Subagent Driven Development

Subagent-Driven Development

Execute an approved Full plan by dispatching implement subagents in one shared task worktree. You are the controller: you decide what runs in parallel, you own verification between waves, and the CLI only records facts.

Setup

Read task.json, prd.md, contract.md, plan.md, and project instructions. Resolve the task-level worktree_path; when it is empty, run superharness task worktree create {task-id} --json and use the returned path. All implementers work in this one worktree on branch superharness/{task-id}. Run superharness task validate {task-id} --json once before dispatching.

Execution Loop

1. Ready tasks are pending tasks whose depends_on are all completed.
2. Run superharness task item {task-id} {n} start for every task you are about to dispatch.
3. Dispatch ready tasks in parallel in a single message. How many to run concurrently, whether to parallelize at all, and how to handle file conflicts are your judgment calls — the plan's Files/Modules and Interfaces sections are your evidence. Do not put tasks with overlapping planned files in the same wave.
4. Each dispatch prompt must carry enough context: task directory, plan task number, worktree path, planned files, interface contracts, public seams, and the focused verification command. Tell the agent the worktree is shared and other tasks may be changing in parallel.
5. Each implementer follows superharness:test-driven-development and ends with exactly one commit, staged and committed with an exact literal pathspec: git add -- <exact files> then git commit --only -- <exact files> (no directories, no globs). An index.lock or ref-lock race is an explicit error — reread HEAD and retry.
6. When an implementer returns, record it: superharness task item {task-id} {n} complete --commit {full-sha}.
7. After each wave, run typecheck only — each task's focused verification already passed inside its implementer, and the finishing gate reruns the deduplicated focused/verified set once at the end. On typecheck failure, dispatch a fix agent whose repair also lands as a commit.
8. Repeat until every task is completed.

See implementer-prompt.md for the dispatch template.

Results and Recovery

• DONE: validate the five-field result and complete the item. A non-empty CONCERNS field is weighed by the controller before moving on.
• NEEDS_CONTEXT: record with superharness task item {task-id} {n} context, supply the missing information, dispatch a fresh implementer.
• BLOCKED: record with superharness task item {task-id} {n} block, then add context, split the task, or ask the user.
• An in_progress task with a dirty worktree gets a recovery agent that first reads the diff and runs the focused test, then continues. Never reset or stash. Ask the user when ownership is unclear.
• On resume, continue from task.json. Do not rerun completed tasks' focused verifications — the finishing gate covers the whole set once at the end.

Final Check

When every task is completed, run the lightweight two-axis review directly — there is no review CLI:

1. Run superharness task transition {task-id} check once.
2. Shell preflight (deterministic, before any agent): git rev-parse must resolve implementation.base_sha; git diff {base}...HEAD --numstat must be non-empty and its total changed lines must stay within 12000. Over the limit: stop and ask the user, suggesting a manual per-task-item review — do not start the review. Keep the changed-path list for the axis agents.
3. In one message, dispatch the Spec axis and the Standards axis check agents in parallel, each report capped at 400 words:
   • Spec axis: reads prd.md, plan.md (Lite falls back to contract.md plus tasks[].seams and behavior_slices), contract.md, the diff, and the commit list. Reports missing requirements, scope the diff exceeds, and implementation errors against the approved plan, quoting the requirement source for each finding. Do not re-litigate design the plan already settled.
   • Standards axis: reads AGENTS.md, the relevant .superharness/spec/ conventions, and the diff, plus this smell baseline pasted into the dispatch prompt — Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Repeated Switches, Shotgun Surgery, Divergent Change, Speculative Generality, Message Chains, Middle Man, Refused Bequest. A documented repo standard overrides the baseline, every smell is a judgement call, and anything tooling already enforces is skipped. Reports concrete violations, distinguishing hard convention breaks from judgement calls.
4. Present the two reports separately — never merge, rerank, or let one axis mask the other.
5. Findings grade Critical/Major/Minor. Any Critical or Major is blocking: run superharness task transition {task-id} implement, then project the blocking findings into a task-local JSON — {"findings":[{"id":"SPEC/F1","affectedTaskIds":[1]}]}, attributing each finding to task items by matching its files against tasks[].changed_paths; the axis reports themselves stay in the conversation — and group repairs through superharness task group-findings {task-id} --input {task-dir}/findings.json --json (Lite skips the CLI and uses one conservative serial group). Land each group's fix as a commit, then superharness task transition {task-id} check again.
6. The HEAD that passes both axes is the reviewed HEAD. From then until the evidence commit, every code commit (blocking repairs, Minor fixes, verification-failure fixes, QA fixes) gets a fix-diff recheck: one axis agent or the controller reads only that fix diff against the original findings and its blast radius. A recheck that still finds Critical/Major stops the automatic loop for the user. Record the reviewed HEAD, each post-review fix commit with its recheck verdict, and the final effective HEAD in verification.md.
7. With no blocking findings, hand off to superharness:finishing-a-development-branch while phase is still check.