git:20261029.c32fa3d to git:20261030.a5465a6
34 added, 37 removed. Audit A to A.
---
name: common-subagent-driven-development
description: Execute an approved implementation plan at the context boundary that preserves required independence and review. Use when implementing plans, executing multi-task PRs, choosing between main-loop and dispatched execution, or transitioning from planning to implementation.
metadata:
triggers:
files:
- 'docs/**/plans/*.md'
- '.agent/sdd/**'
- '*plan*.md'
- 'TODO.md'
keywords:
- subagent-driven-development
- subagent
- implement plan
- execute plan
- implement this plan
- implement PR
- implement tasks
- execute tasks
- start implementation
- plan implementation
- subagent driven
- multi-task implementation
- sdd
---
# Subagent-Driven Development (SDD)
## **Priority: P1 (HIGH)**
Execute a multi-task plan with one implementation owner per slice, independent review after each task, and whole-branch review before completion.
## 1. Placement Decision
- Choose placement before any edit. Delegate only when at least one named benefit applies: independent parallel work over disjoint owned paths that are verifiable alone; measured context pressure such as observed truncation, lost constraints, or replay cost; a required independent verification gate that must be a separate owner from the implementer; or real host-enforced permission isolation, meaning the host enforces the boundary because prompt text is not enforcement. A specialist label, another workflow stage, file count, plan length, or "more thorough" fan-out is not a named benefit.
-
- Precedence, first match wins: controlling host authority, then required independence or isolation, then coupling and verifiability, then economical eligible capability (`common-task-complexity-routing`).
+ Choose placement before any edit. Delegate only for a named benefit: independent parallel work over disjoint owned paths verifiable alone; measured context pressure; a required independent verification gate owned by someone other than the implementer; or host-enforced permission isolation, because prompt text is not enforcement. A specialist label, workflow stage, file count, plan length, or "more thorough" fan-out is not a named benefit. Precedence, first match wins: controlling host authority, then required independence or isolation, then coupling and verifiability, then economical eligible capability (`common-task-complexity-routing`).
| Condition | Placement |
| --- | --- |
| Coupled sequential reasoning; host permits main-loop implementation | One implementation context, skills loaded progressively |
| Independent, bounded, verifiable slices with disjoint ownership | Concurrent bounded workers, one owner per component |
| Host requires worker execution | That boundary; keep coupled steps in one bounded worker, not a planner/fixer chain |
- | Isolation or permission needed but unavailable | Report the operation unsupported or blocked; never infer permission |
+ | Isolation or permission needed but unavailable | Report unsupported or blocked; never infer permission |
- One implementation context is not one actor for the lifecycle: main-loop implementation still requires a separate reviewer, and a single worker still requires independent review.
+ Under an active host or orchestration policy requiring an execution confirmation gate before multi-task implementation:
+ 1. **Execution confirmation gate:** Do not edit files directly in the orchestrator session. Offer Subagent-Driven (Recommended) versus Inline (an explicit recorded exception only for small, genuinely low-risk bounded changes; file count alone does not establish low risk).
+ 2. **Vague assent boundary:** "yes", "proceed", "start", or "approve" binds ONLY the presented choice; it authorizes no inline execution, auto-promotion, premium escalation, or scope expansion. Without explicit host permission for inline work, report the operation unsupported or blocked.
+ 3. **Policy-permitted dual placement:** Where the host permits either placement without a mandatory gate, apply the table above; coupled sequential reasoning stays in one implementation context.
+ 4. Record the decision with its named benefit or the forcing host requirement; reuse a recorded approach instead of re-asking.
- - Record the decision with its named benefit, or the host requirement that forced it. Reuse an approach the plan already records; do not re-ask.
- - Missing required approval, packet, standards, or isolation stops only the affected operation. Report the exact missing item; do not infer permission or silently change the execution path.
- - Plan approval authorizes neither merge, deployment, premium spend, nor a different execution mode.
+ One implementation context is not one actor for the lifecycle: main-loop implementation still requires a separate reviewer, so implementer self-review never closes a review gate. Missing approval, packet, standards, or isolation blocks only the affected operation: report the exact missing item, never infer permission or silently change the path. Plan approval authorizes neither merge, deployment, premium spend, nor a different execution mode. Detail: [methodology.md](references/methodology.md#1-placement-decision).
## 2. Lifecycle
- Report current state with read-only `status --state <PATH> --revision <REV> --dirty-identity <ID> --format json|markdown`; it rechecks plan/evidence bytes and never mutates state. Checkpoint completion is not verification, acceptance, or release.
-
- | Operation | Required evidence |
- | --- | --- |
- | prepare | Standalone packet: assignment manifest, task text, authority, invariants, owner, owned paths, required standards with revision, ACs, verification, source/dependency identities |
- | dispatch | One implementation owner per slice; authority and data eligibility checked before any task context is sent |
- | completion | Terminal state reported by the host, not inferred from silence or elapsed time |
- | resume | Same task, same authority, same owned paths; a new task is a fresh dispatch |
- | cancel | Reported as cancelled/stopped; never as completed or verified |
- | receipt | Operation, task/actor/revision, terminal state, evidence, limitations |
- | verify acceptance | Independent reviewer, separate from the implementer, against ACs and evidence |
+ Report current state read-only with `status --state <PATH> --revision <REV> --dirty-identity <ID> --format json|markdown`; it rechecks plan and evidence bytes and never mutates state. Checkpoint completion is neither verification, acceptance, nor release.
- Host instructions bind these operations to native invocation; canonical text names semantics only. If a required operation or permission control is unavailable on the host surface, report the affected operation unsupported; do not claim success. Dispatch, sequencing and recovery detail: [Methodology](references/methodology.md).
+ - **Operations:** prepare -> dispatch -> completion -> resume -> cancel -> receipt -> verify acceptance; host instructions bind each to a native invocation, and canonical text names semantics only. Dispatch one implementation owner per slice after authority and data-eligibility checks; a new task is a fresh dispatch, resume keeps the same task, authority, and owned paths, and cancelled work is reported stopped, never completed or verified. Read terminal state from the host, never from silence or elapsed time; receipts carry operation, task/actor/revision, state, evidence, and limits.
+ - **Worker checks:** implementers own bounded implementation and focused checks on touched files; they do not commit, recursively delegate, or run full suites by default. A denied call is not a total block while an allowed alternative or read-only inspection exists, and sibling requests are forward-only: forward to the orchestrator or human, never approve or bypass permissions for another agent.
+ - **Errors and TDD:** a 429, timeout, or disconnect is not proof the turn ended; acknowledge terminal state before transferring write ownership. Implementers run RED -> GREEN -> REFACTOR inside each brief.
## 3. Task Loop
- 1. **Select placement and prepare:** Apply Section 1 and record the decision. Record `BASE=$(git rev-parse HEAD)`. Generate the packet with `task_brief.py <PLAN_FILE> <TASK_NUMBER> --assignment <ASSIGNMENT_JSON> --out <BRIEF_FILE>`. The assignment manifest is required; never dispatch a bare task section.
- 2. **Execute or dispatch:** One implementer per task when the placement decision requires it; otherwise execute the slice in the recorded single context. The packet, not repeated prose, carries authority and acceptance.
- 3. **Yield:** Wait for a completion notification; never poll status in a loop.
- 4. **Review:** Generate the scoped cumulative package from `$BASE` and the owned paths. Dispatch an independent reviewer with brief, report and package. Implementer self-review never satisfies this gate.
- 5. **Fix:** Re-prompt the same worker with concrete failed ACs; regenerate the cumulative package and re-review against cumulative state.
- 6. **Integrate:** Orchestrator verifies the diff, runs required covering checks, and commits.
+ 1. **Select placement and prepare:** apply Section 1, record the decision, and record `BASE=$(git rev-parse HEAD)`. Generate the brief from the repository root: `python3 skills/common/common-subagent-driven-development/scripts/task_brief.py <PLAN_FILE> <TASK_NUMBER> --assignment <ASSIGNMENT_JSON> [--out <BRIEF_FILE>]`. `--assignment` is required; `task_brief.py` validates the manifest and the selected task section's contract fields (scope/owned write set, inputs, outputs, real ingress, positive/negative invariants, verification owner, explicit handoff/freeze, correction route) before publishing, and rejects missing fields or fields that appear only inside code fences (exit 2).
+ 2. **Dispatch or execute:** one implementer per task when placement requires it, otherwise the recorded single context. Include exact cross-worktree input paths, provenance, and inclusive ranges for conversion tasks; preserve unaffected fields during correction.
+ 3. **Yield (no polling):** request a completion notification via `wait()` and yield control; never poll status or activity in a loop.
+ 4. **Scoped review package:** generate the cumulative package from `$BASE` over the owned paths: `python3 skills/common/common-subagent-driven-development/scripts/review_package.py <PLAN_FILE> $BASE WORKSPACE --paths <OWNED_PATHS...>`. Pass literal file paths or bounded owned directories (no pathspec magic, globs, `.`, or overlapping scopes); same-base/scope packages are cumulative, not fix-only. Dispatch an independent reviewer with `[BRIEF_FILE]`, `[REPORT_FILE]`, `[DIFF_FILE]`.
+ 5. **Fix loop and failure routing:**
+ - **Host policy precedence:** correction counts, retry limits, and eligible routes come from active host/user policy, which overrides generic defaults.
+ - **Quality failure:** send the authorized corrective follow-up naming the failed ACs; if unresolved, escalate that slice to the next authorized route. Re-prompt the same worker, regenerate from the original `$BASE` with identical owned paths, and re-review the latest cumulative state.
+ - **Quota failure:** on observed quota exhaustion (429, usage limit, provider unavailable), advance immediately to the next authorized route; do not burn retries on an exhausted provider.
+ - **Other runtime errors:** confirm terminal state and writer acknowledgement before failover or transferring write ownership. Retry count alone never authorizes premium without explicit human approval.
+ 6. **Integrate:** the orchestrator verifies the diff, runs required covering checks, and commits.
+
## 4. Failure-Specific Recovery
| Observed failure | Route |
| --- | --- |
- | Missing prerequisite/context | `needs_context` or `blocked` with the exact missing item; no fallback |
- | Defective output | One corrective assignment naming the failed AC and expected result |
+ | Missing prerequisite or context | `needs_context` or `blocked` naming the exact missing item; no provider fallback |
+ | Defective output | One corrective assignment naming the failed AC and expected observable result |
| Observed provider exhaustion | Only an eligible, authorized fallback; the receipt records the exhaustion evidence and selected route |
- | Consequential safety/design issue | Human decision |
+ | Consequential safety or design issue | Human decision |
- Retry count alone never authorizes premium. Timeout and cancellation are not completion. Required human approvals remain external to agent verdicts.
+ Retry count alone never authorizes premium, timeout and cancellation are not completion, and required human approvals stay external to agent verdicts. Rules and examples: [methodology.md](references/methodology.md#5-failure-specific-recovery).
## 5. Final Review and Evidence
- Run whole-branch review on a capable host hint, then complete the branch. Before deleting the workspace, archive packets, reports, immutable review snapshots and verification receipts at durable references; cleanup must not invalidate handoff links.
+ Run whole-branch review from the repository root with `python3 skills/common/common-subagent-driven-development/scripts/review_package.py <PLAN_FILE> $MERGE_BASE HEAD`, dispatch an independent senior reviewer, then complete the branch.
+ **Cleanup needs a verified durable archive and ownership authority:** before deleting `<workspace>`, verify every report, diff, receipt, and evidence copy is archived outside the scratch directory. Never erase the only evidence copy; if archive verification fails or authority is missing, retain `<workspace>` and report the unarchived evidence. Once verified and authorized, delete `<workspace>`.
+
## Anti-Patterns
- - **No worker commits**: workers leave changes; the orchestrator commits.
- - **No recursive delegation**: workers do not spawn agents.
- - **No self-approval**: implementer verdicts do not satisfy independent review.
- - **No agent per stage**: a workflow stage, specialist label, or file count never justifies a new agent; no named benefit, no dispatch.
- - **No polling loops**: yield until a completion event.
- - **No fabricated savings or enforcement claims**: prompt text is not a sandbox, and savings need complete measured coverage.
+
+ - **No worker commits, recursive delegation, self-approval, or agent-per-stage**: the orchestrator commits; workers do not spawn agents; implementer self-review never satisfies independent review; a workflow stage, specialist label, or file count is never a named benefit.
+ - **No polling loops, inlined context bloat, or fabricated claims**: yield to a completion event; pass briefs and diffs as file paths; prompt text is not enforcement, and savings need complete measured coverage.
+ - **No unapproved inline edits under confirmation policy and no inferred authority**: vague assent binds only the presented choice; siblings never approve for each other, and a denial needs a safe-alternative check before a total block. Never delete `<workspace>` without verified durable archival and ownership authority.
## References
[Methodology & Gates](references/methodology.md) · [Prompt Templates](references/templates.md) · [Progress Receipts](references/progress-receipts.md) · [Capability & Effort Resolution](../common-task-complexity-routing/references/routing-table.md#capability-and-effort-resolution)