/spec-driven-dev-v2

name: spec-driven-dev-v2
description: Use when an agent will work for hours or days across many files and multiple vertical slices. Drives a three-level Project → Sprint → Task hierarchy with isolated per-task execution, a review round-loop, context packs for subagent reviewers, governance-as-code, and orchestrator-readable state. Designed for long-running drivers like /loop, autoresearch:ship, and goal-driven.

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