Subagent driven development

Subagent-Driven Development

Execute a written plan with fresh, narrowly briefed subagents where delegation pays for itself. Scale review to risk: low-risk tasks use focused tests and self-review, medium-risk work gets one independent boundary review, and high-risk work gets review at each risky boundary plus final independent verification. The default process executes tasks sequentially on one branch. Recursive coordinator mode is an explicit exception for independent tasks with disjoint ownership.

Why subagents: each task gets deliberately fresh context that you construct. Some harnesses can inherit or fork parent history, so request a fresh context explicitly for implementers and reviewers. Hand each one exactly what its task needs, which keeps it focused and preserves your own context for coordination.

Git authorization: selecting SDD never grants permission to commit, push, merge, or open a pull request. Preserve the user's and repository's existing authorization. When commits are authorized, the ledger records their ranges. Otherwise the ledger and working tree are the recovery mechanism. Recursive children never perform Git index or ref operations.

Continuous execution: do not check in with your human partner between tasks. Stop only for a BLOCKED status you cannot resolve, ambiguity that prevents progress, or completion of all tasks. Narrate at most one short line between tool calls; the ledger and tool results carry the record.

When to Use

Use this skill when a written plan exists, its tasks are mostly independent, and subagents are available. Use the ordinary sequential process when per-task commits are acceptable. Select recursive coordinator mode only when the harness supports nested subagents and every concurrent writer can receive disjoint ownership. With no plan, tightly coupled tasks, or no safe ownership split, execute manually or use megapowers:executing-plans.

For deterministic mechanical changes that share one oracle, use bulk mechanical mode: one owner, one bounded batch, one focused verification set, and one proportional review. Do not create an implementer and reviewer loop per file.

Recursive Coordinator Mode

Recursive coordinator mode is guidance for native Codex and Claude Code subagents, not an execution runtime. Select it explicitly when a plan has several independent roots and coordinators can assign exclusive paths before dispatch. The ordinary sequential process below remains the fallback.

All writers share the current checkout; recursive mode creates no worktrees. Each child receives exclusive ownership of exact files or non-overlapping directory roots. A coordinator may subdivide only the ownership it inherited. Overlapping ownership, shared interface changes, and dependencies stay sequential. If independence cannot be stated in one concise ownership sentence, keep the work under one writer.

Before any recursive dispatch, run scripts/ownership-preflight PLAN_FILE. Do not dispatch if it reports missing, ambiguous, globbed, duplicated, or parent-child-overlapping ownership among parallel tasks. Correct the plan or execute the affected work sequentially. The executable parser contract is scripts/tests/ownership-preflight.test.sh.

The lead launches one native coordinator per independent root. A coordinator may launch native children for independent pieces of its own scope. It waits for every required child, reviews the combined diff, resolves integration issues within its ownership, runs the required verification, and returns one synthesized result to its parent. The lead coordinates only its direct children. Descendants report to the coordinator that spawned them.

In Codex, use native nested subagents with fork_turns = "none" for independent children. In Claude Code, use nested Agent calls; do not use agent teams because teams cannot nest. Respect the harness capacity and depth visible in the session. When capacity is unavailable, continue inline or serially.

Each child brief contains the assignment, done criteria, owned paths, relevant interfaces and constraints, required verification, whether it may subdivide, and the requirement to wait for its direct children and return one synthesized subtree result. Do not copy the parent transcript, full plan, repository tests, or descendant chatter into the brief.

Separate top-level sessions may share the checkout only when their exclusive ownership was partitioned before launch. There is no cross-session lock or automatic conflict resolution. Concurrent children do not run Git index or ref mutations. They do not commit, merge, rebase, reset, switch branches, update refs, push, or clean the checkout. Only the top-level lead performs any authorized Git action, after its direct children return and repository policy permits it.

Use native done, blocked, and needs-context results. The parent decides whether to add context, retry with a fresh child, reduce the task, continue inline, or surface the blocker. Recursive mode adds no separate recovery machinery.

The Process

Setup once: read the plan and existing progress ledger. Use those as the one progress surface rather than duplicating every task into a second todo list. Then scan the plan for conflicts before dispatching Task 1: tasks that contradict each other or the Global Constraints, and anything the plan explicitly mandates that the review rubric treats as a defect. Present everything you find as one batched question. Under an autonomous or on-the-loop charter, resolve non-blocking conflicts with the least-surprise reading and journal them.

Per task, in order:

1. Record the BASE commit in the ledger, generate the task's brief with scripts/task-brief PLAN_FILE N, and dispatch an implementer using implementer-prompt.md. The brief explicitly states whether pre-existing commit authorization exists. The implementer tests and self-reviews, and commits only when that authorization is present.
2. Apply the declared risk tier. Low-risk tasks proceed on focused evidence and self-review. Medium-risk tasks get one independent review at the most useful boundary. High-risk tasks get a fresh task reviewer for each risky boundary. A requested review reports specification compliance and engineering quality as separate verdicts.
3. Send all actionable findings for an artifact in one fix wave, then re-review. Cap fix and re-review at three cycles per artifact. After the third unresolved verdict, mark the task blocked and surface the remaining findings. Never loop until clean without a stopping rule.
4. Mark the task complete in the plan or ledger, whichever is the declared progress surface.

After all tasks, run the branch-boundary verification. Medium and high-risk branches get one whole-branch review. High-risk billing, auth, concurrency, security, schema, data, or external-side-effect changes also get an author-vendor-excluded pass through the structured delegate launcher. Do not repeat a review already performed on the identical complete diff.

Model Selection

When the dispatch surface exposes a per-worker model selector, use the least capable model that can handle each role and specify it explicitly. Transcribing a complete spec and single-file mechanical fixes take the cheapest tier; multi-file integration takes a standard model; design judgment and the final whole-branch review take the most capable. Turn count beats token price: the cheapest models routinely take two to three times the turns on multi-step work, so hold a mid-tier floor for reviewers and for implementers working from prose descriptions.

Codex v2 inherits the session model and effort even with fresh context; fork_turns = "none" controls transcript inheritance, not model selection. Omit the model field on that surface. If a task requires a different Codex model or effort, use a separate role-aware surface or bounded codex exec run. Use delegate-resolve when the role requires another provider.

Handling Implementer Status

• DONE: proceed to review, using the BASE you recorded before dispatch, never HEAD~1, which silently drops all but the last commit of a multi-commit task.
• DONE_WITH_CONCERNS: read the concerns first. Correctness or scope concerns get addressed before review; observations get noted and carried forward.
• NEEDS_CONTEXT: on a harness with resumable subagents (Claude Code's SendMessage), resume the same implementer with the missing context; it keeps its full history. A fix after review still gets a fresh subagent, never the spent implementer.
• BLOCKED: something must change before retry: more context, a more capable model, a smaller task, or escalation to the human if the plan itself is wrong. Never ignore the escalation or force the same model to retry unchanged.

Handling Reviewer Cannot-Verify Items

The reviewer may report items it cannot verify from the diff, requirements that live in unchanged code or span tasks. These do not block the rest of the review, but resolve each one yourself before marking the task complete; you hold the plan and cross-task context the reviewer lacks. A confirmed gap is a failed spec review: back to a fix subagent, then re-review.

Constructing Dispatch Prompts

A dispatch describes one task, not the session's history. A fresh subagent needs its task, the interfaces it touches, and the global constraints. Do not paste prior-task summaries.

For reviewers:

• Copy the binding requirements verbatim from the plan's Global Constraints section or the spec: exact values, exact formats, and the stated relationships between components. The reviewer's template already carries the process rules; the constraints block is for what this project's spec demands.
• Never pre-judge findings. Do not tell a reviewer to ignore, downgrade, or not flag anything; if you expect a false positive, let the reviewer raise it and adjudicate it in the loop. Likewise skip open-ended directives ("check all uses") without a concrete task-specific reason, and do not ask the reviewer to re-run tests the implementer already ran on the same code.
• A finding the plan itself mandates is the human's decision, like any plan contradiction: present the finding beside the plan text and ask which governs. Do not dismiss it because the plan mandates it, and do not dispatch a fix that contradicts the plan without asking.

For fixes:

• Dispatch fix subagents for every Specification Compliance Fail and for Critical and Important engineering findings. A failed specification verdict with only locally Minor findings still requires correction or explicit requirement-owner authorization and re-review; never record it as deferred Minor work. Record Engineering Standards Minor findings in the ledger and point the final whole-branch review at that list so it can triage what must be fixed before merge; a roll-up nobody reads is a silent discard.
• A Specification Compliance Fail requires correction or explicit approval and must never be treated as Minor.
• Every fix dispatch carries the implementer contract: the fixer re-runs the tests covering its change and reports the covering test files, the command run, and the output. Name the covering tests in the dispatch; a one-line fix does not need the whole suite. Dispatch the re-review only once all three pieces of evidence are present.
• If the final whole-branch review returns findings, dispatch one fix subagent with the complete findings list, not one fixer per finding. Per-finding fixers each rebuild context and re-run the suites.

File Handoffs

Everything you paste into a dispatch, and everything a subagent prints back, stays resident in your context for the rest of the session. Hand artifacts over as files: senior-engineer register (see using-megapowers, Communication), conclusion first, self-contained. scripts/sdd-workspace resolves the working-tree directory all of these artifacts live in.

Each delegate has one report channel. For small reports, return the report directly. For bulky reports, write the report file and return only status plus its path. Do not duplicate claims and evidence across chat and file.

• Task brief: scripts/task-brief PLAN_FILE N extracts the task's full text to a file and prints the path. The brief is the single source of requirements; exact values (numbers, magic strings, signatures, test cases) appear only there. The dispatch adds where the task fits in the project, the brief path introduced as the requirements to follow verbatim, interfaces and decisions from earlier tasks the brief cannot know, your resolution of any ambiguity you noticed in it, and the report path with its contract. Never hand a subagent the whole plan file.
• Report file: named after the brief (task-N-brief.md pairs with task-N-report.md). For a bulky report, the implementer writes the full report there and returns only status plus the path. Fixes append to the same file.
• Reviewer inputs: the brief, the report, and the review package as three paths, plus the binding constraints. scripts/review-package BASE HEAD writes the commit list, stat summary, and full diff with context to one file and prints its path, so the reviewer reads everything in one call. The final review gets the same treatment with the branch's merge base (for example git merge-base main HEAD) as BASE.

Durable Progress

Conversation memory does not survive compaction, and a controller that loses its place re-dispatches completed tasks. The ledger at .megapowers/sdd/progress.md under the repo root is the recovery map.

Roll the controller into a fresh context after 8 to 10 completed tasks, or earlier when another task would cross 80 percent of the context or cache budget. Persist the ledger first. Reserve the final 20 percent for integration, review, verification, and synthesis.

• At skill start, read the ledger. Tasks marked complete there are done; never re-dispatch them. Resume at the first task not marked complete.
• Before each dispatch, append Task N: base <sha7> (in progress) with the current short HEAD. The review step needs this exact BASE, and it otherwise lives only in volatile conversation memory.
• On a clean review, append Task N: complete (commits <base7>..<head7>, review clean), superseding the in-progress line.
• On resume, an in-progress line with no matching complete line marks the task to re-check against git log. After compaction, trust the ledger and git history over your own recollection. git clean -fdx destroys the ledger (it is git-ignored scratch); if that happens, recover from git log.

Prompt Templates

• implementer-prompt.md for the implementer subagent
• task-reviewer-prompt.md for the task reviewer (spec compliance + code quality)
• Final whole-branch review: megapowers:requesting-code-review's code-reviewer.md

Example Workflow

One task's full loop, compressed:

[task-brief for Task 2; dispatch implementer with brief + report paths + context]
Implementer: Added verify/repair modes, 8/8 tests passing, committed.
[review-package BASE HEAD; dispatch task reviewer with the printed path]
Reviewer: Missing progress reporting (spec: "report every 100 items");
  unrequested JSON output flag; Important: magic number.
[Dispatch fix subagent with all findings]
Fixer: Removed the flag, added progress reporting, extracted constant.
[Regenerate package; re-review]
Reviewer: Spec compliant. Quality: Approved. Mark Task 2 complete, ledger line.

Integration

Required workflow skills: for the ordinary sequential process, megapowers:using-git-worktrees ensures an isolated workspace. Recursive coordinator mode is the shared-checkout exception and creates no worktrees. megapowers:writing-plans creates the plan this skill executes; megapowers:requesting-code-review supplies the final whole-branch review template; megapowers:finishing-a-development-branch completes the branch after all tasks.

Subagents should use megapowers:test-driven-development for each task.

Alternative workflow: megapowers:executing-plans for inline single-writer execution when subagents are unavailable or per-task commits do not fit.

Origin: Derived from Superpowers (MIT, (c) 2025 Jesse Vincent), https://github.com/obra/superpowers.