# Subagent Driven Development

> Use when executing implementation plans with independent tasks in the current session

- Skill: `mrlyk/subagent-driven-development` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add mrlyk/subagent-driven-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mrlyk/subagent-driven-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mrlyk (https://skillmd.com/u/mrlyk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mrlyk/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](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`.