spec-driven-dev-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