Subagent-Driven Development
You are the controller. Fresh workers build and review one task, or one approved wave, at a time; you hold the plan, the ledger, and every decision they may not take. This skill never decides what happens to the branch.
When to use
- An approved plan is about to be built by dispatched workers rather than here: the user asked for workers, or approved the plan with a delegated mode.
- Skip building the tasks in this session (
executing-plansowns that) and a lone task with no plan directory. - Skip a plan whose index holds phases or shards: its queues, leases, and
capacity envelope run inline through
executing-plans, never through a slim brief. If its row says delegated, go to Step 1.5 first.
Available scripts
scripts/plan-version.sh— prints the plan's version, or with--check-contractand--verifychecks task-contract invariants and the decision ledger.scripts/plan-files.sh— checks each task'sFilespaths against a base revision. Read-only.scripts/sdd-workspace.sh— opens the plan-scoped ledger and re-checks that it still binds to the plan.scripts/task-brief.sh— renders a role brief from a task file, and refuses one with a script slot left unfilled.scripts/review-package.sh— assembles one task's diff and file list for a reviewer.
Step 1: Verify approval and mode
- Run
bash scripts/plan-version.sh --verifyon the plan directory to verify the plan's version against theExternal decision ledger(a ledger: add to it, never rewrite it) and task-contract invariants. The index cannot approve itself; the last decision row (Sectionempty) for the printed version must record theApproval ruleowner's approval and not be closed by a later row. - If
--verifyfails, stop and name the missing version, the row that closed it, or the script's error; never substitute a version read from the index. - If
mode=unset, askassets/mode-question.mdbefore any workspace action, and stop. A request for workers made before approval is not the answer; rendering the question collects it. - If
mode=inline, stop;executing-plansowns it, and only theApproval ruleowner's direct answer changes the mode. - If
mode=delegatedandphases_or_shards=yes, neither this skill norexecuting-planscan run it: ask theApproval ruleowner for a direct inline answer, append it as a new approved row for this version in the shapewriting-plansStep 4.5 gives, withmode: inline, and stop.
Step 2: Open the run
Record the approved plan directory by absolute path; read the plan only there.
REQUIRED SUB-SKILL: invoke
using-git-worktrees. One worktree holds the whole plan; a worker writes inside it, or inside the wave worktree the controller cut for it from that worktree's HEAD. Never hand a worker the shared checkout. Before the first dispatch, confirm that the workspace record'sLocal commit authorityholds a yes; if it holds none, ask the checkpoint questionusing-git-worktreesgives and record the answer. On a no, stop: review packages need commits, so this mode cannot run; hand the mode back to theApproval ruleowner.Open the ledger:
bash scripts/sdd-workspace.sh --plan {{plan-dir}}Line 1 is the plan's identity. After a compaction, read the ledger before anything else and re-check it with
--check: the run resumes from the ledger, not from memory. It lives at.sdlc-skills/evidence/{{plan directory name}}/sdd-ledger.mdand holds this run's dispatches, rulings, and findings. Task states go to the index'sExternal execution ledger, one row per state asusing-sdlc-skills'artifact-layout.mdmaps an execution row; the decision ledger stays where the index points.Confirm the plan contract before the first dispatch from Step 1's
--verifyoutput (Consumes,Depends on,Implementation disciplines, andoverlap=lines): write everyoverlap=pair claiming the same file into the ledger as an ordering; confirm no task edits its own judge unless its approvedEvaluator identity/ownerpermits the exact change; and for a UI task, confirmApplicable visual referencesmatch the index'sSelected visual referencesfield for field and run each freshness evaluator now. If any check fails, report the field and task; dispatch nothing under an invalid contract.A high-risk task is blocked until its migration and assurance contracts are approved and their entry gates have passed. Report it; dispatch nothing for it. A prerequisite task that only builds an entry gate and touches no target is not blocked by that gate.
Read
Integration cadence:plan end(default) orper task. It decides Step 5.6.
Step 3: Rule, don't stall
A worker that asks a question gets an answer and a ledger row, not a pause. Stop and ask the user only when the next act would be:
- irreversible — data, history, or something already published;
- security-sensitive — secrets, credentials, permissions, a trust boundary;
- effective outside the worktree;
- settling a requirement clause with two readings, or a product or architecture choice the approved artifacts do not settle;
- or the plan is broken on every path you can see, not merely the first one.
Everything else is a ruling: a ledger row carried into the next brief. A
task that cannot be built as written gets one when every requirement it
traces still holds: another signature, a file outside its Files, a changed
owner, a new way to run its Evaluator. Never edit plan files.
Write and bound it as executing-plans' Rulings items 1 and 2 say:
the task ID in Task, the requirement it keeps, its cost if wrong, each
later task it touches, and an Evaluator change only to how the check
runs, RED first, never loosening an assertion or a judge its Evaluator identity/owner or the spec keeps from the task.
A change to the Goal, a traced requirement, Acceptance, Constraints,
or an approved migration or assurance contract is never a ruling, nor, on a
high-risk route, a change writing-plans' scalable-transformation.md
calls normative. Write its proposed successor (on a high-risk route,
REQUIRED SUB-SKILL: reviewing-plans first), ask for reapproval, end
the turn. A mode change is neither: Step 1.4 owns it.
On the second ruling caused by a plan claim the code disproves,
dispatch nothing until writing-plans Step 3.6 and 3.7 have walked every
remaining task against the current base once. A gap every traced
requirement survives gets a ruling; every other gap goes into one
successor, its Bound inputs naming that base revision. A claim that fails
Step 3.7 is a finding for the owner of the document that made it; invoke
nothing from here.
Step 4: Dispatch one task
- Take the next task whose dependencies are done. If the approval row says
waves: yes, take every ready task that passes the independence test ofdispatching-parallel-agentsStep 1. Before each dispatch row, cut that task a branch and worktree from the plan worktree's HEAD yourself under the plan worktree's commit authority;using-git-worktreesrun by the worker would reuse yours. The brief grants the worker local commit authority on that branch, and no push. Dispatch them together throughdispatching-parallel-agentsStep 2; sequence a failing pair. - Batch tasks into one dispatch only when they are small and the same shape: same kind of file, same act.
- Fill
assets/implementer.mdwhen dispatching an implementer, rendering it withbash scripts/task-brief.sh, which pastes the task contract and insertsassets/implementer-report.mdbefore dispatch. Pass with--inputeach path the worker would otherwise search for: the plan index, whoseConstraintsevery task inherits; the task'sContext; the instructions file and the nearest test of the module it edits where they exist; and a file, written beside the report, of the ledger rulings that touch this task. Paths the worker opens for itself; never pasted history. - Set the tier explicitly, from the task's
Suggested tierchecked against the Model selection table indispatching-parallel-agents. - Bind the role to a runtime: where the harness exposes a named agent whose contract covers the role, dispatch that agent with the role brief; otherwise dispatch a general subagent with the role prompt. Name mappings belong in the adapters, never here.
- Write the dispatch row before dispatching: task ID, attempt, base
revision, evaluator identity, tier. Then dispatch per
dispatching-parallel-agentsStep 2. It owns the dispatch receipt, the not-dispatched rule, and cancellation. When an implementer cannot be dispatched, its question omits option 1: the controller never edits, and building a task inline is a mode change only theApproval ruleowner's direct answer makes (Step 1.4). Until a worker's report arrives, run only read-only git in its worktree; an add, commit, or reset there races its writes.
Step 5: Review the diff, then fix
If a worker ends without its report file and can still be reached, ask it once for the report before the frozen deadline; with none by then, apply
dispatching-parallel-agentsStep 2.4. Before packaging, confirm the implementer and everything it started have stopped andgit statusshows nothing changed after the reported revision; otherwise stop the stragglers and rebuild the range. Rungit statusas well in every other checkout the brief named a path in: a change there that is neither yours nor the report is ablockingfinding the package cannot show.Build the package with
bash scripts/review-package.sh, then fillassets/task-reviewer.mdwhen the implementer reports, rendering it withbash scripts/task-brief.sh, which insertsassets/task-reviewer-report.mdbefore dispatch, and pass the plan index with--inputfor itsReview focus.Verify each finding on its merits first, as
receiving-code-reviewStep 2 says; one that fails the check goes to the ledger with its evidence and opens no round. Then sort the findings before any round opens, first by what each one touches, whatever the reviewer rated it:- an edit the diff makes outside the contract, the implementer report's
Done beyond the contractline included, isblocking: a fix round removes it, unless a ruling names the contract clause that needs it. - a defect or gap outside the contract, in code the diff does not touch,
in the review or under the implementer report's
Defects noticed and not editedline and## Gaps outside this task, goes to Findings outside the task. It never enters a round. - a
blockingfinding opens a fix round. - an
advisoryfinding gets one recorded decision in the ledger: accepted as it stands, folded into a round a blocking finding opened, or ruled blocking with the failure it causes. It never opens a round or a task by itself. - a
## Declined to judgeor## Limitationsentry gets one recorded decision before the task isdone. On a main user flow, run the check or remove the dependency on the unrun environment; "check at deploy" is no decision. - a
## Discoveries for later tasksentry is copied into the ledger as a ruling naming the later task, unless Step 3 says it needs a successor.
The rounds are the task's repair budget from
receiving-code-review: five unless the user or the plan sets another number, and theper taskreview rounds of 5.6 count against the same budget. All but the last two rounds go back to the same implementer, which still holds the task. The last two go to a fresh implementer one tier up, or atlargewhen it is already there, briefed from the findings file; it has read nothing. Every round gets its findings by file path, never pasted; when the harness reports the same implementer's context near its limit, a fresh one at its tier takes the round from that file. A round may answer a finding with no change and evidence that the claim is false: the re-review weighs it once and withdraws or upholds the finding; an upheld one stays in the loop and counts against the budget.- an edit the diff makes outside the contract, the implementer report's
Fill
assets/re-reviewer.mdwhen a fix round returns, so the second look judges the fix and its blast radius rather than the task again, rendering it withbash scripts/task-brief.sh, which insertsassets/re-reviewer-report.mdbefore dispatch.When the budget is spent without convergence, stop dispatching, write the adjudication in the ledger (the finding, what each round changed, why it did not converge), record the task
blockedasunconverged, and hand the user that row. Never open a round past the budget.Read the diff yourself against the task, then REQUIRED SUB-SKILL: invoke
verification-before-completionon the result revision, with the task'sEvaluator, everyVCONFrow, andvisual-ui-verificationfor a visible UI change.For a wave: once every unblocked wave diff has passed 5.1 to 5.4, merge those branches into the plan worktree (a blocked task's branch stays out) and run this check on the merged HEAD before any wave task is
done. If a merge conflicts, abort it and open a fix round for the task whose branch was being merged: its implementer rebuilds that branch on the plan worktree's HEAD. If the check is red, open a fix round in the plan worktree on the task it names, or on the task merged last when it names none. Each round counts against that task's repair budget and ends in 5.4's adjudication; then merge and check again. The wave worktrees and branches are task-owned resources in the workspace record forfinishing-a-branch.Then append the task's state to the index's
External execution ledger: done, done with concerns, blocked, or needs context. Mirror only the task row's checkbox and adjacent label. Do not change the index'sStatusheader or normalize it out of the plan's identity.Under
per taskcadence only, REQUIRED SUB-SKILLS: invokerequesting-code-reviewon this task's revision, thenfinishing-a-branch. Return after it records its decision.Go to Step 4 with the next ready task. Do not report, ask, or pause at
done. When every task isdone, orcancelled/supersededwith its approved ledger decision, go to Step 6. If no ready task can advance, or a high-risk entry gate has not passed and no ready task can advance without it, report the unresolved states and their blockers and end the turn.
Step 6: Finish the plan
In the worktree from Step 2, in order:
- REQUIRED SUB-SKILL: invoke
verification-before-completionon the integrated revision (per task: the base after the last integration): the index'sAcceptancecheck plus every done task's evaluator. Worker reports are claims; this is the evidence. - REQUIRED SUB-SKILL: invoke
requesting-code-reviewon the whole branch. Its fix rounds run underreceiving-code-review's convergence check and plan-end budget. You run only the triage and the budget: write each fix set to a file beside the review report and pass it as--task; it and every round go to a fresh implementer through the Step 4 brief and the Step 5 review loop, counted against the plan-end budget, not a task's. When that budget is spent, write the adjudication in the ledger and hand the user that row; no task is recordedblocked. - REQUIRED SUB-SKILL: invoke
finishing-a-branchwith the workspace record from Step 2. It asks the integration question and executes the answer. Run no push, PR, merge, or delete here. - Close with "Rulings I made": every ruling in the ledger with its cost if
wrong, one line each,
then "Findings not built": every
findingrow with noadmittedrow, with its evidence, one line each. The user decides which become work. If the index'sPlan setnames a next slice, name it and ask theApproval ruleowner whetherwriting-plansruns on it now; start nothing from here.
| Thought | Reality |
|---|---|
| "Every worker returned DONE, so the plan is done" | DONE is a claim per task. The plan is done after Acceptance, review, and the integration decision — three skills you have not invoked yet. |
| "The reviewer subagent passed it, so review is covered" | That reviewed one task's diff against its contract. The branch review is a separate check on the integrated state. |
Findings outside the task
A defect or gap outside the current task's contract is never an edit in this
task. One a later listed task's contract covers is left to that task. Any
other, whoever reports it, is a finding row in the ledger: where, what,
the evidence. It is never a task because someone wrote it down.
- If the index's
Out-of-task findingsfield sayslog and report, or is absent, every finding waits for Step 6.4. - Read
references/admitted-findings.mdwhen the index'sOut-of-task findingsfield saysfix when admitted.
Gotchas
- A gap found mid-task, written as a successor, stops the run for reapproval: one run wrote fifteen this way. Write a ruling wherever Step 3 allows one.
- A worker's status is not a verdict on the task — reproduced whenever a
DONEarrives with a diff that edits a file the brief never named. Read the diff yourself (Step 5.5). - Every brief here prohibits subdispatch; keep it. A worker's own workers return a diff nobody reconciled and receipts you never held.
- The controller never edits, so
test-driven-developmentandyagniload in the implementer, where the brief requires them; loading them here proves nothing about the worker.
Stopping and resuming
- If the remaining work will not fit this session, finish the current ledger
row, then invoke
handoff. - On resume, rerun
bash scripts/plan-version.shand re-read the latest decision row (emptySection) for the printed version before--checkon the run ledger: the run ledger detects an amended plan, not a row that closed the version. - For a dispatch row with no result row, confirm that worker has stopped, as
dispatching-parallel-agentsStep 2.4 says, then rungit logfrom the row's base in its worktree. If commits exist, build their review package and dispatch only the reviewer. If none exist, set any uncommitted output aside and reassign the task underdispatching-parallel-agentsStep 2.5: the lost session is the cause and the resumed one the changed intervention; outside the caller's bound, return it as blocked.