/spec-driven-dev

name: spec-driven-dev
description: Use when starting any non-trivial feature, refactor, or new project that will touch more than one file. Drives an AI coding agent through a gated Spec → Plan → Build → Test → Review → Ship lifecycle so work is specified before it is built, verified before it is reviewed, and reviewed before it ships.

Spec-Driven Development

A gated, six-phase workflow for shipping real software with an AI coding agent. Each phase has a goal, exit criteria, and a rationalization table for the excuses an agent will invent to skip it. Do not advance until the current gate is closed.

When to Use

• Starting a new project, service, or significant feature
• Requirements arrive as a paragraph, screenshot, or vague idea
• The change touches more than one file or subsystem
• You are about to make an architectural decision
• An agent is about to write more than ~100 lines without a plan
• Picking up half-finished work from another session

When NOT to Use

• One-line typo or copy fix
• Renaming a single local variable
• Changes fully scoped by a one-line request where "done" is unambiguous
• Pure dependency bumps with no behavior change
• Throwaway spikes clearly marked as experiments and never merged

If unsure, do the spec phase anyway. A 10-minute spec is cheap insurance.

The Gated Workflow

  SPEC  ──▶  PLAN  ──▶  BUILD  ──▶  TEST  ──▶  REVIEW  ──▶  SHIP
   │          │          │          │          │           │
   ▼          ▼          ▼          ▼          ▼           ▼
 What &     Tasks &    Thin       Prove it   Five-axis   Deploy,
  why       order      slices     works      quality     observe,
                                   by test    gate       roll back
   │          │          │          │          │           │
   └──────────┴──────────┴──────────┴──────────┴───────────┘
            human or reviewer approves each gate

Rules of the gate:

1. You may loop backward (Test reveals a broken spec — return to Spec). 2. You may not skip forward. No building without a plan. No shipping without review. 3. Each gate produces a named artifact committed to the repo: `SPEC.md`, `PLAN.md`, code + tests, a review note / PR description, a launch + rollback note.

Phase 1: SPEC

**Goal.** Turn a vague request into a written contract that answers *what*, *why*, *for whom*, and *how we know it is done*. Surface assumptions before they become bugs.

**Inputs.** User request, existing codebase, any prior specs, constraints.

**Steps.**

1. Restate the request in one sentence. Confirm with the human. 2. List assumptions explicitly. Example: `ASSUMPTIONS: web app, Postgres, session cookies. Correct me or I proceed.` 3. Reframe vague requirements as measurable success criteria. "Make it fast" becomes "dashboard LCP < 2.5s on 4G, initial data < 500ms". 4. Write the spec using `templates/spec.md` and save it in the repo. 5. Define Always / Ask First / Never boundaries. 6. Log open questions. Do not guess answers.

**Exit criteria.**

• [ ] Spec file saved in the repository
• [ ] Human has read and approved it
• [ ] Success criteria are specific and testable
• [ ] Boundaries are explicit
• [ ] No unanswered blocking questions

**Common Rationalizations**

| Excuse | Reality | |---|---| | "It's obvious what to build" | If it were, two engineers would write the same code. They won't. | | "I'll write the spec after the code works" | That's documentation, not specification. It can no longer change the design. | | "The user told me what they want" | Users describe symptoms, not contracts. Extract the contract. | | "Requirements will change anyway" | That's exactly why you write them down — so the change is visible. |

Phase 2: PLAN

**Goal.** Convert the spec into an ordered list of small, verifiable tasks with an explicit dependency graph. No code is written in this phase.

**Inputs.** Approved spec, relevant source files, existing conventions.

**Steps.**

1. Enter read-only mode. Read the spec and the code it will touch. 2. Draw the dependency graph: what must exist before what. 3. Slice vertically. Thin end-to-end slices beat horizontal layers (schema → all APIs → all UI is the wrong shape). 4. Write tasks using `templates/plan.md`. Each task fits one focused session and touches ~5 files or fewer. 5. Insert verification checkpoints between task groups. 6. Call out risks and parallelization coordination (e.g. agree an API contract before splitting frontend/backend).

**Task sizing.**

| Size | Files | Example | |---|---|---| | XS | 1 | Add a validation rule | | S | 1–2 | One endpoint, one component | | M | 3–5 | One vertical feature slice | | L | 5–8 | Multi-component feature (split if possible) | | XL | 8+ | **Too big. Break it down.** |

**Exit criteria.**

• [ ] Plan file saved in the repository
• [ ] Every task has acceptance criteria and a verify step
• [ ] Dependencies are ordered correctly
• [ ] No task is XL
• [ ] Checkpoints exist between phases
• [ ] Human approved the plan

**Common Rationalizations**

| Excuse | Reality | |---|---| | "I'll figure it out as I go" | That's how tangled diffs are born. Ten minutes planning saves hours untangling. | | "Planning is overhead" | Planning *is* the work. Implementation without a plan is just typing. | | "I can hold it in my head" | Context windows are finite. Compaction will eat it. |

Phase 3: BUILD

**Goal.** Implement the plan in thin, compilable, revertible increments. Every increment leaves the tree green.

**Inputs.** Approved plan, the current task.

**The increment cycle:** `implement → test → verify → commit → next slice`

**Rules.**

0. **Simplicity first.** What is the simplest thing that could work? Three similar lines beat a premature abstraction. Do not generalize before the third use case demands it. 1. **Scope discipline.** Touch only what the task requires. Note unrelated issues; do not fix them. No "while I'm here" refactors. 2. **One thing per comm