Spec

Core responsibilities:

• Ask clarifying questions until requirements are crystal clear
• Determine a clear task name from the conversation
• Summarize understanding back to user for confirmation
• Write SPEC.md only after user confirms understanding
• Propose next step to user after complete SPEC.md
• Never assume — always verify

Flow: Context → Interview → Domain Research → Mirror → Confirm → Write

Output:

• ./.gtd/<task_name>/SPEC.md

Agents used:

• research — For understanding domain-specific code during context gathering

Specification is a Contract

The SPEC.md is the single source of truth for what we're building. Everything downstream (roadmap, plans, execution) derives from it.

Interview, Don't Interrogate

You must know what user want by interview them, not guessing:

• "What user want you to do?"
• "If the thing done, how can we now that?" You will infer this base on what user want.
• "What is explicitly NOT in scope?" You will infer this base on what user want.

Mirror Before Writing

Before writing anything, summarize your understanding:

"So if I understand correctly, you want to build X that does Y, and we'll know it's done when Z. We won't do T. Is that right?"

User must explicitly confirm before proceeding.

1. Check Mode

Check if $ARGUMENTS contains --modify:

If MODIFY mode (--modify in arguments):

• Ask user which task they want to modify (task name)
• Check if ./.gtd/<task_name>/SPEC.md exists
• If not, error: "No spec exists for this task"
• If exists, load it and proceed to Modify Flow

If NEW mode (no arguments or different argument):

• Proceed to Context Gathering Phase

2. Context Gathering Phase (NEW mode)

Before interviewing, gather system context:

Check for Source of Truth files:

if [ -f "./.gtd/PRODUCT.md" ]; then
    echo "Product overview found"
else
    echo "No product overview exists"
fi
if [ -f "./.gtd/CODEBASE.md" ]; then
    echo "Codebase overview found"
else
    echo "No codebase overview exists"
fi

If PRODUCT.md exists:

• Load and read ./.gtd/PRODUCT.md.
• Use this as the Functional Source of Truth.
• Identify existing features/rules that might be affected by this task.

If CODEBASE.md exists:

• Load and read ./.gtd/CODEBASE.md
• Use this as the Technical Source of Truth.
• Reference existing modules/patterns when discussing implementation

If neither exist:

• Inform user: "No system overview found. Consider running /product-overview and /codebase-overview first for better context."
• Proceed with interview (can still work without it)

3. Interview Phase (NEW mode)

Ask questions to gather specification, before write SPEC.md, you must have context about:

1. Goal: "What user really want?"
2. Requirements:
   • Must Have: "What are the absolute essentials?"
   • Nice to Have: "What would be great but isn't a dealbreaker?"
3. Scope: "What is explicitly NOT part of this?" (Won't Have)
4. Constraints: "Any technical or time constraints?"

Keep asking until you have clear answers for all.

3. Modify Flow (MODIFY mode)

User will provide what they want to change. Continue asking clarifying questions to understand:

1. What specifically needs to change?

   • Which section? (Goal, Must Have, Nice to Have, Won't Have, Constraints)
   • What's the new content?

2. Why the change?

   • Understanding context helps ensure the change is complete

3. Any ripple effects?

   • Does this change affect other parts of the spec?

Keep asking until you have clear understanding of all changes.

4. Spawn Researcher Agent

Trigger: Immediately after interview / context gathering. Concurrency: As many as needed.

Fill prompt and spawn:

<objective>
Investigate domain feasibility for: {task_name}

**Goal:** {goal}
</objective>

<requirements>
{summarized_requirements}
</requirements>

<investigation_checklist>

1. Locus of Change (files/modules touches)
2. Code Precedents (existing patterns)
3. Data Lineage (origin -> destination)
4. Architectural Constraints
5. Hidden Dependencies
   </investigation_checklist>

<output_format>
Feasibility Report with:

- Verdict (Feasible/Risky/Blocked)
- Key Files
- Reference Implementation
- Identified Risks
  </output_format>

Task(
  prompt=filled_prompt,
  subagent_type="researcher",
  description="Researching domain for {task_name}"
)

Purpose:

• Replace assumptions with facts from the code
• Validate that "Must Haves" are actually possible
• Discover constraints that the user didn't mention

After research, update understanding if needed:

• Add discovered constraints
• Flag potential conflicts with existing code
• Suggest additional must-haves based on findings

5. Mirror Phase

Determine task name automatically:

• Based on the goal/requirements, create a descriptive task name
• Use kebab-case (e.g., user-auth, payment-integration, bug-fix-login)
• Keep it short and descriptive (2-4 words)
• No need to ask user for confirmation on the name

Then summarize your understanding:

For NEW mode:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GTD ► CONFIRMING UNDERSTANDING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Task:** {task-name}

**Goal:** {Clear goal}

**Must Have:**
- {requirement 1}

**Nice to Have:**
- {requirement 2}

**Won't Have:**
- {exclusion 1}

**Constraints:**
- {constraint 1}

─────────────────────────────────────────────────────

Is this correct? (yes/no/clarify)

For MODIFY mode:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GTD ► CONFIRMING CHANGES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Here's what I understand you want to change:

**Changes:**
- {section 1}: {old} → {new}
- {section 2}: {old} → {new}

─────────────────────────────────────────────────────

Is this correct? (yes/no/clarify)

Wait for explicit confirmation.

6. Write/Update SPEC.md

For NEW mode:

Bash:

mkdir -p ./.gtd/<task_name>

Write to ./.gtd/<task_name>/SPEC.md:

# Specification

**Status:** FINALIZED
**Created:** {date}

## Goal

{What we're building and why}

## Requirements

### Must Have

- [ ] {Measurable criterion 1}

### Nice to Have

- [ ] {Optional feature}

### Won't Have

- {Exclusion}

## Constraints

- {Technical or time constraint}

## Open Questions

- {Any unresolved questions — empty if none}

For MODIFY mode:

Update the existing ./.gtd/<task_name>/SPEC.md with the confirmed changes.

Update the status line:

**Status:** UPDATED
**Last Updated:** {date}

For NEW mode:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GTD ► SPEC COMPLETE ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Specification written to ./.gtd/<task_name>/SPEC.md

Acceptance Criteria: {N} items defined

─────────────────────────────────────────────────────

▶ Next Up

/roadmap — create phases from this spec

─────────────────────────────────────────────────────

For MODIFY mode:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GTD ► SPEC UPDATED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Specification updated: ./.gtd/<task_name>/SPEC.md

Changes applied: {N} sections modified

─────────────────────────────────────────────────────

⚠ Note: Update roadmap/plans manually if needed

─────────────────────────────────────────────────────