subagent-driven development
current authority
local execution uses peer sessions only, never subagents. preserve the durable ledger and review gates below; one integration owner verifies returned evidence. the upstream subagent mechanism is reference material, not executable local authority.
controller pattern for executing plans: fresh implementer subagent per task, review its diff with another subagent, fix-loop until clean, record everything in a ledger file. the controller coordinates; it never implements.
what it teaches
three mechanisms:
- isolated context per role. each subagent gets a brief it can execute alone — task text, interfaces it touches, global constraints — never the session's history.
- the review loop. each task ends in a spec-compliance and quality review of the diff. findings enter a bounded fix loop (five rounds, escalating to a fresh, more capable implementer at round four); at the cap, the controller adjudicates and parks each finding with a written ruling.
- the ledger. progress lives in a file, not memory — context compaction is assumed. after compaction, the ledger and git log are the truth; recollection is not.
why it exists
controllers that keep context in their head have re-dispatched entire completed task sequences — the most expensive observed failure. implementers that fix their own reviews without a gate ship unreviewed churn. the ledger and the loop are the two brakes.
the rules
- fresh subagent per task; never parallel implementers on shared files.
- model to the task: cheap for transcription, capable for judgment and final review.
- rulings, not stalls — decide, record, continue; stop only for the four named irreversibles.
- every ruling is a ledger entry; silent discards are forbidden.
when to use
executing a plan with independent tasks from a session that can dispatch subagents. replaces executing-plans' human checkpoints with subagent review gates — faster iteration, same fidelity.
good and bad
bad
controller completes task 2, context hits limit, compaction occurs.new controller resumes and redispatches task 2 (unaware it finished).result: duplicate changes, conflicts on merge, lost review record.
without a durable ledger, execution state exists only in memory: it vanishes at compaction, the restarted controller redoes finished tasks, and earlier rulings lose their explanation.
good
ledger entry: task 2, implementer-b, [routes/approval.ts, middleware/logging.ts],verified: POST /approval returned 200 with typed response,review verdict: 1 minor (log format), approved,next: task 3 ready (consumed route interfaces from task 2)new controller compaction resumes from ledger, dispatches task 3 only,and can audit the complete trace of decisions and evidence.
the ledger makes execution restartable by construction: a fresh controller resumes exactly where work stands, and every ruling carries its evidence forward. context limits become a routine event, not a threat to correctness.