Spec-Driven Workflow

The pipeline that turns one ambiguous request into a chain of small, one-shottable steps.

The pipeline

flowchart TD
    A[Idea] --> B{Small?}
    B -- yes --> Q[/quickfix/]
    B -- no --> S[/specify/]
    S --> CL[/clarify/]
    CL --> P[/plan/]
    P --> R[Pre-Task Review]
    R --> T[/tasks/]
    T --> I[/implement/]
    I --> V[/verify/]
    V -- BLOCKER --> I
    V -- PASS --> RE[/retrospective/]
    RE --> EX[/extract-skills/]
    EX --> KF{3+ repeats?}
    KF -- yes --> CON[/constitution/]
    KF -- no --> END[Done]
    Q --> V

Each command is a separate invocation, its own model tier, its own focused context.

Phases

Phase	Model	Purpose
quickfix	sonnet	≤2 files, ≤20 lines. Bypass full pipeline.
specify	opus	Natural language → structured spec
clarify	opus	≤5 questions, answers folded back into spec
plan	opus	Architecture, sketches, data model, contracts; gated review
tasks	sonnet	Decompose plan into dependency-ordered tasks
implement	opus	Orchestrate; dispatch each task to its @model tier
verify	opus	Adversarial review across 5 dimensions
retrospective	sonnet	Post-mortem → constitution amendments + skill candidates
extract-skills	sonnet	Materialise skill YAMLs

Tier rationale: Model Routing: Haiku, Sonnet, Opus.

Phase-by-phase

Specify — produces spec.md (user scenarios, functional requirements, success criteria, edge cases, assumptions). Up to 3 [NEEDS CLARIFICATION] markers; defaults guessed for the rest.

Clarify — at most 5 questions, one at a time, each with a recommended answer + 2-3 alternatives. Answers update the spec in place.

Plan — produces plan.md, research.md, data-model.md, contracts/*, quickstart.md, and preview.md (architecture mermaid + 2-4 code sketches with real signatures). Reviewed before tasks.

Tasks — produces tasks.md. Each task in one strict shape:

- [ ] T012 [P] [deps: T003,T007] [US1] @sonnet [ctx: src/foo.ts:10-40] description

[P] = parallelisable; [deps] = explicit deps; [US1] = user-story trace; @model = tier; [ctx] = pre-fetched ranges.

Tasks are grouped: Setup → Foundational → one phase per user story (P1 first) → Polish. ### Wave N (parallel) groups concurrent tasks with a commit gate between waves.

Implement — walks tasks.md in dep order. For each task: read [ctx] ranges, inline contents into the subagent prompt, dispatch at @model, mark [X]. See Subagents and Context Injection.

Verify — adversarial review of spec + plan + tasks + diff across spec-divergence, missing tasks, security, correctness, contract breaks. Findings tagged BLOCKER / WARN / NOTE. Any BLOCKER → re-enter implement. See Trust but Verify.

Retrospective + Extract — produces CONSTITUTION_AMENDMENTS and SKILLS_TO_EXTRACT blocks. See The Compounding Layer.

Fast-track: quickfix

Hard preconditions, enforced before any edit:

• ≤ 2 files
• ≤ 20 lines
• No new files / deps / public-API changes
• Commit type in {fix, docs, style, chore, typo, refactor}
• No protected paths (configurable)

Trip any of these → escalate to full pipeline. Ceremony for a typo is worse than no process.

Why waterfall

Each phase produces an artefact that gates the next. Unfashionable, intentional. The whole structure exists to defeat The One-Shot Problem: small steps to keep each agent invocation one-shottable, written checkpoints between them.

Trade made explicit: heavy planning and review up front, almost mechanical implementation after. The thing being avoided is the ten-minute agent run that returns the wrong feature. Every hard decision is made and recorded before the implementer starts writing.

The alternative — "give the agent the repo, tell it to do the next thing" — is the one-shot trap with extra steps.