Spec-Driven Dev

Phase details: See references/phase-*.md for step-by-step instructions per phase.

Drive feature work from idea to implementation through repo-stored specs. Five phases: specify → design → tasks → implement → validate.

Execution Flow

1. Detect state → enter correct phase
2. Specify requirements with user
3. Design architecture (deep only)
4. Break into atomic tasks → confirm
5. Implement tasks sequentially with commits
6. Ask user about validation → validate in fresh session

Mode Detection

Read specs/_current to determine state:

• File missing or empty → New feature (start at Specify)
• Directory exists, no tasks.md → Specify or Design
• tasks.md exists, tasks Pending → Implement (resume)
• All tasks Done, no validation-report.md → Validate
• validation-report.md exists → Complete

If no specs/ directory exists, create it.

Spec Directory Structure

specs/
  _current          # plain text: path to active spec dir, e.g. specs/0001-auth
  0001-auth/
    spec.md         # requirements (Draft → Implementing → Done)
    design.md       # architecture notes (deep depth only)
    tasks.md        # task list with Status fields + progress log
    validation-report.md  # created during Phase 5
  0002-payments/
    ...

Sample specs/_current content:

specs/0001-auth

Sample specs/0001-auth/tasks.md excerpt:

## Task 0001-03 — Add JWT middleware
Status: Pending
Files: src/middleware/auth.ts, src/routes/index.ts

Resuming

When specs/_current points to an active spec:

1. Read the progress log for context from prior sessions
2. Check git status and git log --oneline -5 to see what was last committed
3. Find the first task with Status: Pending or In Progress
4. Summarize to the user: "Resuming spec NNNN, task N: [title]. Last completed: [summary]." Then continue Phase 4.

Phases

See example-spec.md for a complete output example.

Rules

Do:

• One spec directory per feature; 4-digit zero-padded numbering (0001, 0002, …)
• Commit after each task (not at the end); reference the spec and task number
• Keep tasks to one commit, one concern — split if a task needs multiple commits
• Investigate code before asking — read first, ask second
• Log progress after every task for session continuity
• Spec statuses: Draft → Implementing → Done. Spec is frozen once Implementing.
• Spec the why; tasks the what. Quick depth for < 3 files, Standard for features.
• Create feature branches when asked; create and update files in specs/

Do not:

• Skip phase gates or proceed to implementation without user confirmation on spec or tasks
• Modify files outside the current task's boundary
• Delete or overwrite existing specs
• Push without explicit user permission

Common failures:

• Skipping confirmation — building without sign-off leads to building the wrong thing.
• Tasks too large — if a task needs multiple commits, split it.
• No progress log — without log entries, the next session can't resume correctly.