subagent-driven-development

name	subagent-driven-development
description	Consult before delegating implementation when an approved plan benefits from worker context isolation and durable coordination.

Subagent-Driven Development

Purpose

The core value of subagents is context isolation: bounded implementation work can proceed without loading the main session's accumulated history, while the main agent keeps the long-horizon picture coherent. Use this workflow for a plan whose deliverables benefit from that separation, not as a mandatory wrapper around every edit.

Controller and worker ownership

The main agent owns long-horizon continuity, overall construction progress, dependency and integration state, semantic acceptance ownership, and high-level architecture communication with the user. It normally coordinates rather than performing the worker's detailed implementation itself.

Workers own their bounded construction, focused validation, and durable report. The main agent should not duplicate worker implementation merely to stay busy. Direct main-agent investigation is appropriate only when separate verification is required, a worker report cannot serve as ground truth, or repeated failure on the same problem calls for deeper diagnosis.

Choose or resume a worker

Before each dispatch, ask whether the harness supports resuming a relevant prior worker and whether that worker's context still materially helps the next deliverable. When available, resume a relevant prior worker when it retains useful task-specific knowledge, unresolved evidence, or local implementation state.

Use a fresh worker when clean context isolation, an independent perspective, or unrelated work makes the earlier context a liability. Do not hardcode a single harness API: express the resume-or-dispatch decision, then use the active harness's supported worker mechanism.

Durable handoffs

Keep the controller context small and the work recoverable through files:

• Create a task brief with scripts/task-brief PLAN_FILE N; it is the worker's authoritative requirement source.
• Give the worker a report path beside the brief. The report preserves project meaning, architecture impact, semantic evidence, concerns, commit_authority, and commits when authorized or working-tree diff, changed files, and evidence without commit authority.
• Create a review package only when independent review is warranted. For committed work use scripts/review-package BASE HEAD; without commit authority use scripts/review-package --worktree BASE [OUTPUT]. Pass the resulting DIFF_FILE, brief, and report paths to the reviewer instead of requiring a SHA or pasting bulk history.
• Maintain .superpowers/sdd/progress.md as the progress ledger. Record each accepted deliverable, commit_authority, commits when authorized or its working-tree diff/files/evidence, acceptance evidence, open concerns, and next dependency. After context compaction, resume from the ledger and git log, not recollection.

The brief, report, review package, and progress ledger are continuity tools, not ceremony: each preserves information a new controller or worker would otherwise need to reconstruct.

Review placement

Place independent review at a meaningful semantic or risk boundary: a behavior that changes user-visible outcomes, crosses module ownership, introduces a security or data-integrity concern, alters permissions, affects concurrency, or creates a compatibility boundary. Substantive work receives a final whole-change review that checks integration and semantic acceptance across deliverables.

Repeated low-risk mechanical work following an already-reviewed pattern may use a grouped review. Short changes still receive independent review when they are security-sensitive, data-integrity, permission, concurrency, or cross-module changes. A reviewer evaluates semantic behavior and integration, not a hunt for style findings or an excuse to add process.

If a review finds an issue, decide whether a fix needs independent verification: request it for material semantic, risk, or integration findings; record a low-risk mechanical correction and verify it through the appropriate acceptance evidence when another review would not change confidence.

Execution loop

1. Read the plan, stable references, repository-operation preferences, and any progress ledger. Resolve only blockers that change construction.
2. Identify the next meaningful deliverable and its dependencies. Select a resumed or isolated worker using the rule above.
3. Dispatch with the task brief, any non-inferable interface decisions, the report path, and the required semantic acceptance evidence. Choose model capability proportional to the task's ambiguity, risk, and integration load.
4. Read the worker status and report. Preserve its evidence in the ledger; do not treat a summary as proof when separate verification is required.
5. Place review at the meaningful semantic or risk boundary. Resolve material findings through a worker or direct investigation only under the ownership rule above.
6. Update the ledger with accepted state, commit_authority, commits when authorized or working-tree diff/files/evidence without commit authority, concerns, and the next dependency. At the end of substantive work, request a final whole-change review before closeout.

Worker status

• DONE: Confirm the report contains project meaning, architecture impact, semantic evidence, and concerns; then select the appropriate acceptance or review path.
• DONE_WITH_CONCERNS: Read and record the concern before deciding whether it requires independent verification or a follow-up worker.
• NEEDS_CONTEXT: Supply the missing decision or stable reference and resume the relevant worker when that context remains useful.
• BLOCKED: Change the task context, worker capability, decomposition, or escalate the real blocker. Do not repeat the same dispatch without new information.

Model selection

Use the least costly worker that can safely handle the task: inexpensive models for determined isolated edits, stronger models for cross-module integration or debugging, and the strongest available judgment for substantive whole-change review. Explicitly choose a model where the harness allows it; do not inherit a high-cost default accidentally.

Red flags

• Treating a worker report as ground truth when the task needs independent semantic evidence.
• Discarding useful prior-worker context solely to reset every task.
• Resuming a worker whose old context is unrelated or biases an independent judgment.
• Having the main agent redo bounded worker implementation without a verification need or repeated failure signal.
• Reviewing every trivial repetition while missing a real security, permission, data-integrity, concurrency, or cross-module boundary.
• Letting a final review replace the progress ledger or semantic acceptance evidence accumulated through construction.

Templates

• implementer-prompt.md — bounded worker contract
• task-reviewer-prompt.md — independent semantic and integration review
• code-reviewer.md — final whole-change review when substantive work warrants it