Idea

The user has a new product or project idea. Follow the Spec-Driven Development Workflow below to turn it into a structured set of artefacts, working through each phase in order with explicit user approval at each gate.

## The Idea

$ARGUMENTS

## Spec-Driven Development Workflow

### Folder Structure

specs/ architecture.md # High-level technical architecture roadmap.md # Sequenced delivery plan {feature-name}/ requirements.md # User stories and acceptance criteria design.md # Technical design for this feature tasks.md # Actionable implementation checklist

### Phase 1: Technical Architecture

1. Ask clarifying questions if the idea is ambiguous (target platform,
   users, scale, constraints, etc.).
2. Propose a high-level technical architecture in `specs/architecture.md`:
   - **Overview**: What the system is and who it serves.
   - **Tech Stack**: Languages, frameworks, infrastructure, and services.
     Justify each choice briefly.
   - **System Components**: Major subsystems/modules and their
     responsibilities. Use a Mermaid diagram if helpful.
   - **Data Architecture**: High-level data stores, key entities, and
     how data flows between components.
   - **Infrastructure & Deployment**: How the system is hosted, built,
     and deployed.
   - **Key Constraints & Assumptions**: Performance targets, platform
     limits, third-party dependencies, or anything the user stated.
   - **Open Questions**: Anything that needs user input before
     proceeding.
3. Present the architecture and ask for approval.
   - Iterate until the user explicitly approves.

### Phase 2: Feature Discovery

**Trigger**: User approves Phase 1.

1. Based on the approved architecture and the original idea, propose a
   set of features. Present them as a numbered list, each with:
   - **Feature name**: Short, descriptive.
   - **Summary**: One or two sentences on what it does and why it
     matters.
   - **Scope**: What is included and excluded.
2. Ask the user to approve, add, remove, or modify features.
   - Iterate until the user explicitly approves the feature set.

### Phase 3: Roadmap

**Trigger**: User approves Phase 2.

1. Organise the approved features into a sequenced delivery plan in
   `specs/roadmap.md`:
   - Group features into phases or milestones (e.g. "Phase 1: Core",
     "Phase 2: Polish", etc.).
   - Order by dependency -- foundational features before those that
     build on them.
   - For each feature entry, include: name, summary, and which other
     features it depends on (if any).
   - Identify any architecture setup work (project scaffolding, CI/CD,
     base infrastructure) as its own roadmap item if needed.
2. Present the roadmap and ask for approval.
   - Iterate until the user explicitly approves.

### Phase 4: Spec Generation

**Trigger**: User approves Phase 3.

For each item on the approved roadmap, in roadmap order, generate the
full spec folder (`specs/{feature-name}/`) containing all three files:

**requirements.md**:
- **Overview**: One-paragraph summary.
- **User Stories**: Numbered, in the format:
  `As a [role], I want [capability], so that [benefit]`.
- **Acceptance Criteria**: For each story, testable criteria in EARS
  format:
  - `WHEN [trigger] THEN the system SHALL [behaviour]`
  - `WHILE [state] THE system SHALL [behaviour]`
  - `WHERE [condition] THE system SHALL [behaviour]`
- **Out of Scope**: Anything explicitly excluded.

**design.md**:
- **Overview**: How this feature fits into the approved architecture.
- **Components / Modules**: What will be created or modified.
- **Data Model / Interfaces**: Schemas, types, API contracts, or config
  structures as relevant.
- **Key Flows**: Step-by-step primary flows. Mermaid diagrams where
  they add clarity.
- **Error Handling**: How failures are surfaced and recovered from.
- **Testing Strategy**: What will be tested and how.
- **Security Considerations**: Auth, secrets, input validation if
  relevant.

**tasks.md**:
- Numbered task groups (1, 2, 3...) representing logical milestones.
- Sub-tasks as a checklist:
  `- [ ] 1.1 Description (Ref: US-1, AC-1.1)`
- Each task must be a concrete coding activity.
- Tasks build incrementally -- no forward dependencies.
- Each task references the requirement(s) and/or design section it
  implements.

After generating specs for a feature, present a summary and ask if
the user wants to review or adjust before moving to the next feature.
If the user says "generate all" or similar, produce all specs in
roadmap order without pausing between features, then present the
full set for review.

### Phase 5: Implementation

**Trigger**: User asks to start building, or approves the generated
specs.

1. Read the roadmap and all spec files for the target feature.
2. Load the task list into TodoWrite for tracking.
3. Work through tasks one at a time, in order.
4. After completing each task:
   - Mark the checkbox in `tasks.md` (`- [x]`).
   - Mark the todo as completed in TodoWrite.
   - Briefly summarise what was done.
   - Wait for user confirmation before the next task, unless the user
     has said "continue without stopping" or similar.
5. If a task is blocked or needs clarification, stop and ask.
6. When all tasks for a feature are complete, move to the next feature
   on the roadmap.

### Resuming Work

If spec files already exist:
- Read `specs/architecture.md` and `specs/roadmap.md` first.
- Check which features have specs and which tasks are complete.
- Offer to continue from where work left off.

### Rules

- Never skip phases. Architecture before features, features before
  roadmap, roadmap before specs, specs before code.
- Never modify approved documents without asking first.
- Keep all documents concise -- favour clarity over length.
- Requirement traceability must flow through: requirements -> design
  -> tasks. Every task must trace back to a requirement.
- If the user says "just build it",