spec-driven-dev-v2
/spec-driven-dev-v2
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.
- Author
- lichamnesia ↗
- Repository
- lich-skills ↗
- Licence
- MIT
- Last repository change
- 09.06.2026
Assessment and security
- Files in this package
- 13
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 09.06.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/governance-check.sh, scripts/task-lint.sh
What it does and when to use it
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.
Original author 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.
How it works
- When to use v2 over v1
- The Hierarchy
- Roles
- Phase 0: PROJECT (one-time per project)
- Phase 1: SPRINT (one-time per sprint)
- Phase 2: BUILD — per task, in isolation
- Phase 3: REVIEW — the round loop
- Phase 4: SHIP — per sprint
- Governance — gap 6 made real
- Artifact Registry — gap 7
SKILL.md preview
---
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 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.
## Phase 4: SHIP — per sprint
After every task in the sprint is `merged`:
1. Run sprint-level verify (integration suite, not just per-task tests).
2. Run `scripts/governance-check.sh` — must exit 0 (boundary rules, unresolved
findings, orphan branches, stale STATE).
3. Update sprint `STATE.json` to `status: closed`.
4. Advance project `STATE.json` to `current_sprint: sprints-NNN+1`.
5. If this is the last sprint, follow `spec-driven-dev` v1 SHIP phase for
rollout, feature flags, monitoring, and rollback.
## Governance — gap #6 made real
Boundary rules (e.g. "L2 may call L1 and L0, L0 must not call L2") must be
enforced by script, not prose. The skill ships two runners:
- `scripts/task-lint.sh` — validates task-file frontmatter, sizing, verify
command presence. Run at sprint open and in CI.
- `scripts/governance-check.sh` — project-wide invariants: every merged task
has an approved review, every sprint STATE is consistent, every
`artifact-registry/rules/RULE-*.md` that is marked `enforcement: lint` has a
matching lint rule file.
Add project-specific checks as the project grows. New rule discovered in
review? It goes through the artifact-registry.
## Artifact Registry — gap #7
When a reviewer finds a pattern that should apply to *all future tasks* (not
just this one), capture it:
1. Write `context/artifact-registry/rules/RULE-NNN-<slug>.md` from
`templates/artifact-registry/RULE.md`.
2. Decide `enforcement`:
- `doc` — humans follow it (weakest)
- `review_checklist` — added to `templates/review/REVIEW.md`
- `lint` — automated rule (eslint, custom script, ast-grep, etc.)
3. If `lint`, also land the lint rule in the same commit as the RULE file.
4. `governance-check.sh` verifies that every `enforcement: lint` rule has a
concrete implementation pointer.
Rules that stay at `doc` for more than 2 sprints should graduate or be
deleted. Dormant rules rot.
## Orchestrator contract — gap #8
Any `STATE.json` file is the single source of truth for "what's next". An
orchestrator's turn looks like:
```
1. Read project STATE.json → current_sprint
2. Read sprint STATE.json → current_task, current_round, next_action
3. Dispatch:
- next_action=build → spawn Builder in worktree for current_task
- next_action=review → construct Context Pack, spawn Reviewer
- next_action=modify → Builder addresses unresolved findings
- next_action=merge → merge branch, advance STATE
- next_action=close_sprint → run governance-check, advance project STATE
4. Exit. Next loop iteration re-reads STATE.
```
STATE.json schemas are in `templates/project/STATE.json` and
`templates/sprint/STATE.json`. Keep them small. Do not put history in them —
history lives in `TASKS.md` and `REVIEWS.md`.
## Red flags
- Any task with no verify command, or verify that just echoes "ok"
- Builder touching files outside the task's declared file list
- A review file that references `round1` only — real tasks take 2–4 rounds
- `current_round > 5` with no human in the loop
- `RULE.md` with `enforcement: lint` but no lint rule in the repo
- Two sprints open at once
- Merged task with no approved review file
- STATE.json last-modified older than the most recent commit on the branch
Any of these → `governance-check.sh` should fail. If it doesn't, add the check.
## Templates
- `templates/project/RFC.md` — project contract
- `templates/project/PLAN.md` — sprint decomposition
- `templates/project/STATE.json` — project-level orchestrator state
- `templates/sprint/SPRINT.md` — sprint goal + exit criteria
- `templates/sprint/TASKS.md` — task status table
- `templates/sprint/REVIEWS.md` — round log
- `templates/sprint/STATE.json` — sprint-level orchestrator state
- `templates/task/TASK.md` — one task spec
- `templates/review/REVIEW.md` — 5-axis review with Context Pack
- `templates/artifact-registry/RULE.md` — captured rule
- `scripts/task-lint.sh` — mechanical task gate
- `scripts/governance-check.sh` — project-wide invariant checker
## Relation to v1
v1's five-axis review, rationalization tables, and scope discipline are
unchanged and assumed. v2 wraps them in structure that survives multi-day,
multi-session execution. If a v2 project collapses back to one session with
one sprint and one task, it should read like v1 with extra files — that is
acceptable; the overhead is the insurance.
Files in this package (13)
- SKILL.md 12 KB
- scripts/governance-check.sh 7 KB
- scripts/task-lint.sh 3 KB
- templates/artifact-registry/RULE.md 2 KB
- templates/project/PLAN.md 3 KB
- templates/project/RFC.md 2 KB
- templates/project/STATE.json 1 KB
- templates/review/REVIEW.md 5 KB
- templates/sprint/REVIEWS.md 1 KB
- templates/sprint/SPRINT.md 2 KB
- templates/sprint/STATE.json 1 KB
- templates/sprint/TASKS.md 2 KB
- templates/task/TASK.md 2 KB
Versions
The database has no other skills named spec-driven-dev-v2.
Database snapshot: 13.11.2026 · package version 347b4ef091f2 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100bmad-sprint-run
This skill should be used when the user says "run the sprint", "autonomous sprint", "run all stories", "execute sprint plan", "complete all epics", or asks to autonomously execute all stories in the current sprint. Drives Claude Code through create-story, dev-story, quality… - 100spec-loop
Goal-driven autonomous round loop. Give it a goal + acceptance checklist + round budget (touchpoint 1), then it researches, implements, self-checks, and retrospects round after round — driven by a Stop-event hook, not by prompt discipline — until the final acceptance audit… - 100spec-driven-dev
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… - 100cc-dev-agent
Use when starting Claude Code projects, writing CLAUDE.md/spec.md, dispatching subagents, or requesting Agent Teams parallel development. Covers Spec-Driven Development, Context Engineering, and post-dev workflow. - 100inline-plan-dev
You MUST use this when executing an existing implementation plan directly in the current agent session, including resuming interrupted execution. Covers task-by-task implementation, plan drift, and verification. Not for subagent-driven execution. - 100amoa-orchestration-loop
Use when running the orchestrator loop or managing stop hook behavior. Trigger with loop, stop hook, or state file requests. Loaded by ai-maestro-orchestrator-agent-main-agent