Subagent driven development

Subagent-Driven Development

Execute a plan in ONE session: dispatch a fresh implementer subagent per task → task review (spec + quality) after each → broad whole-branch review at the end. Upstream: https://github.com/obra/superpowers.

Fresh-context briefs, fan-out width, and the per-task economy are governed by [[parallel-subagent-economy]]; when to decompose-and-fan-out at all by [[monitor-orchestration]]. This file covers only what is SDD-specific: the per-task implementer + two-stage review loop.

Contents

1. When to use vs. alternatives
2. The per-task loop
3. Model selection
4. Handling implementer status
5. Constructing reviewer prompts
6. File handoffs + durable ledger
7. Red flags

When to Use

• Have a plan + tasks mostly independent + staying in THIS session → this skill.
• Want a parallel session with human checkpoints → superpowers:executing-plans instead.
• Tightly-coupled tasks or no plan → brainstorm/manual first.
• Continuous execution: do not check in between tasks. Stop only on unresolvable BLOCKED, genuine ambiguity, or all-done. Narrate ≤1 line between tool calls — the ledger and tool results are the record.

The Per-Task Loop

1. Read plan once; note global constraints; create todos + check the ledger (§6).
2. Pre-flight: scan the plan for tasks that contradict each other/the constraints, or that mandate something the rubric treats as a defect (test asserting nothing, verbatim-duplicated logic). Batch all findings to the human as one question before Task 1; if clean, proceed silently.
3. Per task: scripts/task-brief PLAN N → dispatch implementer (implementer-prompt.md). Answer its questions before it proceeds.
4. On DONE: scripts/review-package BASE HEAD → dispatch task reviewer (task-reviewer-prompt.md) with the printed path.
5. Reviewer returns two verdicts (spec + quality). Critical/Important findings → fix subagent → re-review. Loop until both clean.
6. Mark complete in todos + ledger. Next task.
7. After all tasks: final whole-branch review via ../requesting-code-review/code-reviewer.md, then superpowers:finishing-a-development-branch.

Model Selection

Least-powerful model that handles the role. Always specify model explicitly — an omitted model inherits the session's (most expensive) model and defeats this.

• Plan text contains the complete code → transcription → cheapest tier.
• Single-file mechanical fix, complete spec → cheap.
• Multi-file integration / pattern-matching / debugging → standard (mid-tier is the floor for reviewers and prose-spec implementers).
• Design judgment / broad codebase understanding → most capable. The final whole-branch review is always this tier.
• Reviewer model scales to the diff's size/risk, not the session default.
• Turn count beats token price: cheapest models take 2-3× the turns on multi-step work, costing more overall.

Handling Implementer Status

• DONE → generate review package, dispatch reviewer.
• DONE_WITH_CONCERNS → read concerns first. Correctness/scope → resolve before review; observations → note and proceed.
• NEEDS_CONTEXT → provide the missing info, re-dispatch.
• BLOCKED → diagnose: context gap → re-dispatch same model with more context; needs reasoning → more capable model; too large → split; plan is wrong → escalate to human. Never retry the same model unchanged; never ignore an escalation.

Reviewer ⚠️ "cannot verify from diff" items — requirements in unchanged code or spanning tasks. Non-blocking for the rest of the review, but YOU resolve each before marking complete (you hold the cross-task context the reviewer lacks). A confirmed gap = failed spec review → back to implementer.

Constructing Reviewer Prompts

Per-task reviews are task-scoped gates; the broad review runs once at the end.

1. Never pre-judge. No "do not flag X", "at most Minor", "the plan chose this". If you're tempted to spare yourself a loop, stop — let the reviewer raise it and adjudicate in the loop. The plan's example code is a starting point, not proof its weaknesses were chosen.
2. BASE is the commit recorded before dispatching the implementer — never HEAD~1 (drops all but the last commit of a multi-commit task).
3. Global-constraints block = the reviewer's attention lens. Copy binding requirements verbatim from the plan: exact values, formats, stated relationships ("same layout as X"). Process rules (YAGNI, test hygiene) are already in the template.
4. No open-ended directives ("check all uses", "run race tests if useful") without a concrete task-specific reason. Don't ask it to re-run tests the implementer already ran on the same code.
5. Plan-mandated findings (or any finding conflicting with plan text) → the human decides: present finding + plan text, ask which governs. Don't dismiss it; don't dispatch a contradicting fix without asking.
6. Fix dispatches carry the implementer contract: re-run the covering tests (name them — a one-line fix doesn't need the full suite), report command + output. Confirm all three present before re-review.
7. Critical/Important → fix subagents. Minor → ledger, fed to the final review for triage. Final-review findings → ONE fix subagent with the full list, not one fixer per finding (each rebuilds context + re-runs suites).
8. Final review gets its own package: scripts/review-package $(git merge-base main HEAD) HEAD.

File Handoffs + Durable Ledger

Everything pasted into a dispatch — and everything a subagent prints back — stays resident in your context and is re-read every later turn. Move artifacts as files.

• Brief — scripts/task-brief PLAN N extracts the task to a file. Dispatch = (1) one line on where the task fits; (2) brief path ("read first — your requirements, exact values verbatim"); (3) interfaces/decisions from earlier tasks the brief can't know; (4) your resolution of any ambiguity you spotted; (5) report-file path + contract. Exact values live ONLY in the brief.
• Report — name it after the brief (task-N-brief.md → task-N-report.md). Implementer writes full detail there, returns only status + commits + one-line test summary + concerns.
• Reviewer gets three paths — brief, report, review-package — plus the binding global constraints.
• Never paste accumulated prior-task summaries into later dispatches (a real session hit 42k chars, 99% pasted history). A fresh subagent needs its task, the interfaces it touches, the constraints. Nothing else.

Ledger — conversation memory dies at compaction; controllers have re-dispatched entire completed sequences (most expensive failure observed). Track in $(git rev-parse --show-toplevel)/.superpowers/sdd/progress.md:

• At start, cat it — tasks marked complete are DONE, resume at the first unmarked one.
• On a clean review, append (same message as other bookkeeping): Task N: complete (commits <base7>..<head7>, review clean).
• After compaction, trust the ledger + git log over recollection. git clean -fdx destroys it (git-ignored scratch) → recover from git log.

Red Flags — Never

• Implement on main/master without explicit consent.
• Skip task review, or accept a report missing either verdict (spec AND quality both required).
• Dispatch multiple implementers in parallel (conflicts).
• Make a subagent read the whole plan (hand it the brief).
• Dispatch a task reviewer without a diff file — generate it first.
• Move to the next task with open Critical/Important findings, or accept "close enough" on spec.
• Let implementer self-review replace actual review (both needed).
• Re-dispatch a task the ledger already marks complete.

Prompt Templates + Integration

• implementer-prompt.md · task-reviewer-prompt.md · final review: ../requesting-code-review/code-reviewer.md.
• Workflow skills: superpowers:using-git-worktrees (isolated workspace), superpowers:writing-plans (creates the plan), superpowers:finishing-a-development-branch (completion). Subagents follow superpowers:test-driven-development per task.

Rationalizations — stop, these skip review

Excuse	Reality
"One more task, then review"	Stacked unreviewed tasks compound bugs. Review each before next.
"Reviewer flagged it Minor"	Minor findings cascade. Fix or ledger-feed, don't ignore.
"Close enough on spec"	"Close enough" is a gap. Let the reviewer adjudicate.

Red Flags — STOP: skipping task review · accepting a report missing either verdict · moving to next task with open Critical/Important · "just this once" · re-dispatching unchanged.

<!-- budget: ~101 -->