Spec-Driven Development v2

Spec-Driven Development v2

v1 assumed one agent shipping one feature in one session. v2 assumes an orchestrator (or a human) driving the agent across many sessions — possibly for days — and keeps work correct the entire time.

v2 adds:

1. Three-layer hierarchy — Project → Sprint → Task
2. Per-task state — JSON files an orchestrator can read to resume cold
3. Review round-loop — review → feedback → modify → re-review until clean
4. Worktree isolation — every task runs in a clean checkout, revertable alone
5. Context pack — the briefing a reasoning-blind subagent reviewer needs
6. Mechanical task gate — sizing/acceptance/rollback checks enforced by script
7. Governance-as-code — boundary rules live in lint/CI, not markdown
8. Artifact registry — new rules captured from reviews graduate to lint

When to use v2 over v1

Use v2 if any of:

• Expected agent time > 4 hours
• More than ~8 tasks, or more than one vertical slice
• A subagent (/critic, Agent subagent_type=critic, etc.) reviews each task
• An orchestrator (/loop, autoresearch:ship, goal-driven) drives iteration
• Architectural boundaries (layering, dependency direction) must hold mechanically

For one-session features, use spec-driven-dev (v1) — v2 is overhead for them.

The Hierarchy

context/
  dev/
    projects-001-<slug>/                # one project = one RFC
      RFC.md                            # the contract: what & why
      PLAN.md                           # sprint list + dependency graph
      STATE.json                        # {current_sprint, status}
      sprints-001-<slug>/               # one sprint = one checkpoint
        SPRINT.md                       # goal, scope, exit criteria
        TASKS.md                        # task status tracker
        REVIEWS.md                      # review round log
        STATE.json                      # {current_task, current_round, next_action}
        tasks/
          TK-001-<slug>.md              # one task = one worktree
          TK-002-<slug>.md
        reviews/
          RV-001-round1.md              # round 1 for TK-001
          RV-001-round2.md              # after modify, round 2
          RV-001-round3.md              # …until verdict=approve
      sprints-002-<slug>/
        …
  artifact-registry/
    rules/
      RULE-001-<slug>.md                # captured pattern → lint rule
scripts/
  governance-check.sh                   # boundary + state validator
  task-lint.sh                          # mechanical task gate

All state is on disk. No in-memory plan. This is the contract with the orchestrator: it can read STATE.json, pick up where the last session left off, and advance one step.

Roles

• Planner — writes RFC, PLAN, SPRINT, TASK specs. No code.
• Builder — implements one task in an isolated worktree.
• Reviewer (subagent) — reasoning-blind. Sees only the Context Pack.
• Orchestrator — reads STATE.json, dispatches the next role.

Planner and Builder may be the same model. Reviewer must be a fresh subagent with no access to Builder's conversation — that is what makes review work.

Phase 0: PROJECT (one-time per project)

Goal. Produce the RFC and sprint plan. No code.

1. Draft RFC.md from templates/project/RFC.md — restate request, list assumptions, define measurable success, set Always/Ask/Never boundaries.
2. Draft PLAN.md from templates/project/PLAN.md — decompose into sprints. Each sprint must have a shippable checkpoint (even if behind a flag).
3. Initialize STATE.json with current_sprint: "sprints-001-<slug>".
4. Human approves RFC and PLAN before any sprint opens.

Exit criteria.

• RFC.md committed and approved
• PLAN.md committed with ≥ 2 sprints (or 1 if scope is truly small)
• No sprint is XL (> ~10 tasks); split if it is
• STATE.json present and valid

Phase 1: SPRINT (one-time per sprint)

Goal. Expand one sprint into atomic, independently-reviewable tasks.

1. Write SPRINT.md from templates/sprint/SPRINT.md — goal, scope, exit criteria, what's deferred.
2. Write one tasks/TK-NNN-<slug>.md per task, from templates/task/TASK.md.
3. Write TASKS.md from templates/sprint/TASKS.md — flat status table.
4. Run scripts/task-lint.sh <sprint-dir> — every task must pass:
   • Has acceptance criteria as a bullet list
   • Has an executable verify command
   • Files list ≤ 5 (else size must be L with justification; XL forbidden)
   • Has a rollback: line
   • Title contains no "and"
5. Initialize sprint STATE.json with current_task: "TK-001", current_round: 0.
6. Human approves the sprint.

Exit criteria.

• SPRINT.md + all TK files + TASKS.md committed
• task-lint.sh exits 0
• No XL tasks
• STATE.json valid

Phase 2: BUILD — per task, in isolation

Every task runs in a fresh git worktree (or branch on a clean tree). This is non-negotiable — it is what makes review and rollback possible.

Steps.

1. Orchestrator reads sprint STATE.json, picks current_task.
2. Create worktree: git worktree add ../wt-TK-NNN -b tk-NNN-<slug>.
3. Builder reads only the task file + files it lists. No sprint-wide browsing.
4. Implement. Commit in thin slices. Every commit leaves tree green.
5. Run the task's verify: command. If red, fix. Do not claim done on red.
6. Update TASKS.md: status built, link commit range.
7. Update STATE.json: next_action: "review", current_round: 1.

Scope discipline. Touch only files listed in the task. If you need a file that isn't listed, stop, update the task spec, get re-approval. "While I'm here" refactors are a phase violation.

Exit criteria (per task).

• All commits on tk-NNN-<slug> branch, tree green
• Verify command exits 0
• No files changed outside task's declared set
• TASKS.md + STATE.json updated

Phase 3: REVIEW — the round loop

Review is a state machine, not a one-shot.

  built ──▶ round1 ──┬──▶ approve ──▶ merged
                     │
                     └──▶ request_changes ──▶ modify ──▶ roundN+1

A task may not advance to merged until a review with verdict: approve exists. Every round creates its own reviews/RV-NNN-roundN.md.

Each round:

1. Builder (or orchestrator) constructs a Context Pack — see templates/review/REVIEW.md "Context Pack" section. This is the brief the reviewer subagent will see. It includes:
   • Task file (TK-NNN) and relevant RFC/SPRINT anchors
   • git diff <base>..HEAD scoped to declared files
   • git log --oneline on the branch
   • Verify command output (actual stdout, not "passed")
   • Prior rounds' unresolved findings (round N-1 marked [unresolved])
   • Relevant lint/governance script output
2. Spawn a reasoning-blind reviewer subagent (e.g. Agent subagent_type=critic) with the Context Pack as its only input.
3. Reviewer writes RV-NNN-roundN.md using the 5-axis template. Verdict is one of: approve / approve_with_nits / request_changes / reject.
4. Append a one-line entry to REVIEWS.md.
5. If approve or approve_with_nits: mark task merged in TASKS.md, merge branch, advance STATE.json.
6. Otherwise: Builder addresses every Critical: and (required) finding in new commits on the same branch. Set current_round += 1. Go to 1.

Round budget. If current_round > 5, escalate to human — the task is either mis-specified or too large. Do not grind past round 5 silently.

Context Pack is the skill. A reasoning-blind reviewer with bad context rubber-stamps. The only leverage you have is the pack.