subagent-driven-development · diff
git:20261004.4a578c5 to git:20261015.cffd553
55 added, 202 removed. Audit A to A.
---
name: subagent-driven-development
- description: The implementation engine. Routed to by /sprint (full plan, autonomous) and by executing-plans (scoped batch, checkpoint-gated). One fresh subagent per task — test-first via tdd — followed by spec-compliance review, quality review, and fresh-run verification. No single context accumulates drift, and nothing is accepted on a subagent's word.
+ description: Assistive implementation engine for /sprint and scoped executing-plans work. Follow actual dependencies, implement or delegate coherently, run relevant checks, preserve honest evidence, and advance without artifact approval codes or compulsory reviewer cascades.
disable-model-invocation: true
---
# subagent-driven-development
- ## Structured-artifact format boundary
-
- New full-lane workflows default to HTML through the installed engine. Existing
- HTML pairs use the same path. Load
- `${CLAUDE_PLUGIN_ROOT}/includes/artifacts.md` before HTML artifact I/O;
- its typed identity, binding, receipt, contextual-read, and scope-state rules
- replace rendered-document parsing and direct status-cell edits. Existing
- authoritative Markdown pairs stay on their exact legacy path without conversion.
- A missing, invalid, or unqualified HTML capability must fail closed rather than
- fall back to new Markdown authority. HTML `--farm` dispatch remains disabled.
- Keep every other workflow gate, including human checkpoints, unchanged.
-
-
- One task, one fresh subagent, two reviews, proof on a fresh run. Routed to by `/sprint` (full plan,
- autonomous) and by `executing-plans` (one batch at a time, with human checkpoints between batches).
- The loop processes tasks in dependency order and never trusts a self-report.
-
- ## Pre-flight
-
- Read these, or STOP and surface the gap — never guess scope, command, or obligation:
-
- - `${CLAUDE_PROJECT_DIR}/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value) and project context.
- - The discovered authoritative spec/plan pair. Existing Markdown pairs retain
- their current ledger. For HTML, load `${CLAUDE_PLUGIN_ROOT}/includes/artifacts.md`,
- retain the exact artifact identities and engine-written receipts, and read
- the approved spec binding, obligations, paths, verification definitions,
- dependencies, and state only through `identity`, `index`, `outline`,
- symbol-scoped `read`, and `eligible`. The engine `eligible` response is authoritative;
- the workflow must not infer authority from rendered text, checkboxes, status
- words, digests, or caller-supplied labels, and must not read or write a shadow
- Markdown ledger.
- - `${CLAUDE_PROJECT_DIR}/.codearbiter/tech-stack.md` — build, test, and verification invocations; file layout; the scope-to-author mapping.
- - `${CLAUDE_PROJECT_DIR}/.codearbiter/security-controls.md` — only when a task touches a security boundary (auth, crypto, secrets, a trust boundary).
-
- **Optional `scope` parameter:** when invoked by `executing-plans`, a list of task IDs is passed. The
- loop processes only those tasks (in their internal dependency order). When `scope` is absent (the
- `/sprint` path), the loop processes the full plan from first unblocked task to last.
-
- ## Phase 1 — Task selection · gate: BLOCK
-
- Pull the next unblocked task from the plan in dependency order. When a `scope` was passed, restrict
- selection to tasks in that list. For Markdown, select only a task whose status is `PENDING` and whose
- dependencies are `ACCEPTED`; `BLOCKED` tasks are not selectable until the owning plan workflow
- records a supported transition. For HTML, accept only tasks returned by `eligible` for the exact
- selected plan identity. A task is one verifiable unit of work with a path set, a spec obligation,
- and a verification command.
-
- For HTML, select only a task returned as eligible for the exact selected plan
- identity. Follow contextual `read` pages to completion, retain their context
- ticket, and use `task-start` before author dispatch. Do not translate a displayed
- status or a copied task label into a transition.
-
- After process recreation, rediscover the same authoritative pair and query
- `identity` and `eligible` again. Reconcile an interrupted `IN_PROGRESS` task only
- through an authority-backed `task-reconcile`, then redispatch with `task-start`
- and a fresh complete context ticket. A task in `REVIEW` is not accepted on
- resume; obtain fresh evidence when required and finish the current combined
- scope review before `accept-scope`.
-
- - For Markdown, confirm every dependency task is `ACCEPTED` before selecting.
- - For HTML, use the engine's eligibility and current evidence; do not replace its same-checkpoint `REVIEW` rule
- with the legacy `ACCEPTED` sentence or infer eligibility from a displayed status.
- - Confirm no unresolved `[CONFIRM-NN]` blocks the task. One that does halts the loop — see Hard rules.
-
- Gate: exactly one task selected, dependency-clean, with its spec obligation and verification command in hand.
-
- ## Phase 2 — Implementation dispatch · gate: BLOCK
-
- **Farm path (when `<slug>.plan.json` exists alongside the `.md` plan):** skip the subagent dispatch
- loop below and follow `${CLAUDE_PLUGIN_ROOT}/skills/subagent-driven-development/references/farm-dispatch.md`.
- The farm path replaces only the *authoring* step for the plan's tasks (cheap Zen workers under hard
- gates instead of premium subagents); it does **not** replace review — every task the farm reports green
- is still routed through Phases 3–5 before acceptance. The cost arbitrage is in who *writes* the code,
- never in whether it is *reviewed*. In brief: select a model (canary-probe with a cache→websearch
- fallback ladder), dispatch `${CLAUDE_PLUGIN_ROOT}/tools/farm.js`, honor a circuit-breaker abort as a hard-gate STOP, then for
- each result either accept-after-Phases-3–5 (green) or re-dispatch via premium Phase 2 (escalate).
- Results stream to `.farm/farm-results.jsonl` and are consumed in completion order — Phase 3 + Phase 5
- per green task as it lands, Phase 4 still the once-per-scope barrier (reconcile against `farm-report.json`
- on abort). The reference has the full step-by-step.
+ Execute an existing plan. The plan helps the agent remember the intended result; it is not a second permission system. Run meaningful work, correct defects, update progress, and tell the truth about unfinished checks. The active host, user instructions, and independently applicable security/commit controls still govern real actions.
- ---
+ ## Format and capability boundary
- **Normal path (no `plan.json`):** dispatch ONE fresh subagent for the selected task — `backend-author`, `frontend-author`, or
- `infra-author` by the scope mapping in `tech-stack.md`
- (`${CLAUDE_PLUGIN_ROOT}/agents/<name>.md`). A fresh context per task is the whole point: no carried-over
- assumptions, no accumulated drift.
+ New full-lane workflows default to HTML through the installed engine. Existing authoritative Markdown pairs remain in their original format without automatic conversion. Load `${CLAUDE_PLUGIN_ROOT}/includes/artifacts.md` before HTML I/O; use the pinned native writer, typed operations, and symbol-bound records. Do not scrape HTML or maintain a shadow Markdown ledger. If the HTML writer is unavailable or an artifact write fails, say precisely what was not saved; do not invent a fallback artifact or report success. Safe authorized inspection and repair can continue where the missing artifact is not needed.
- The subagent works test-first by routing through the `tdd` skill (`${CLAUDE_PLUGIN_ROOT}/skills/tdd/SKILL.md`) — no implementation code before
- `tdd` Phase 1. Brief it with the task's path set, its spec obligation, and its verification command.
- Nothing else from prior tasks leaks in.
+ HTML `--farm` is disabled. An explicitly selected, existing Markdown `plan.json` farm workflow retains its separate dispatch procedure in `${CLAUDE_PLUGIN_ROOT}/skills/subagent-driven-development/references/farm-dispatch.md`, including its real provider/budget/circuit-breaker protections. This assistive default does not silently switch backends or imply farm qualification.
- Before dispatch, obtain current bounded inputs for the selected task paths:
- existing code-map text if available, assessed provenance, scoped command
- records and collector observations, applicable constraint references, and
- host-effective native instructions in precedence order. Call the private
- `_artifactpromptlib.compose_feature_actor_input` with the chosen author name,
- brief, exact approved spec and plan IDs, task ID, task paths, and those inputs.
- Send its returned `input` as the fresh child's actual input. The returned
- packet never grants task start, source-snapshot admission, or permission to
- mutate or execute a discovered command. Resolve an applicable critical
- unresolved constraint before that material action. An unavailable optional
- map permits bounded read-only orientation, not an invented complete map.
- For each author or reviewer dispatch, call `_contextselectlib.prepare_actor_delivery`
- on that actor's freshly selected packet with the actual actor/task, absolute
- worktree, current source identity, and host epoch when observable. Send its
- bounded `delivery_text` to that child on `deliver` and retain the counted
- attempt. Treat `observed` only as caller-reported load/input evidence; do not
- use a shared session or persona/read marker as a receipt. On `blocked`, stop
- the material action and report the delivery gap. Re-select after resume,
- compaction, scope expansion, or worktree switch; missing epochs get at most
- two counted deliveries for the same binding.
+ **Scope:** with an explicit `scope` from `executing-plans`, work only on the named tasks; without it, `/sprint` works across the plan. A checkpoint is an organizing group, not independent permission to do the next task.
- Gate: all six `tdd` phases must be green before acceptance. Never redispatch merely to evade a failing gate.
- Under an approved `/sprint`, an ordinary implementation/test failure routes to **Recovery within the approved sprint** in `${CLAUDE_PLUGIN_ROOT}/SPRINT.md`; rerun the original gate after an evidence-led correction.
- An attended invocation returns the blocked prerequisite to its caller. A real authority or security block
- halts the affected work and is surfaced under the hard rules, in either mode.
+ ## 1. Orient and select actual work
- ## Phase 3 — Spec-compliance review · gate: BLOCK
+ Read the selected spec/plan, relevant `.codearbiter/CONTEXT.md`, and the needed build/check commands from `.codearbiter/tech-stack.md`, when present. Read `security-controls.md` for work affecting its rules. Missing optional orientation is a diagnostic, not a blanket STOP; never guess an essential requirement or execute an unknown command.
- Did the change satisfy the task's obligation? Measure the result against the spec line the task
- traces to — not against whether tests merely pass.
+ For HTML, use `identity`, `index`, `outline`, exact or batched symbol-scoped `read`, and `eligible`. The engine `eligible` response is **advisory scheduling**, not permission or evidence of a passing test. Read actual task dependencies and `waiting_prerequisites`; do not treat a checkpoint number or an unscoped legacy prerequisite as a universal dependency.
- For an independent spec reviewer, freshly compose the same task-scoped input
- with actor `spec-reviewer` and the exact artifact/task IDs, then send the
- returned `input` to that reviewer before its substantive verdict. Do not
- substitute the author's packet or the coordinator's summary for reviewer
- delivery; the reviewer independently checks source identity and constraints.
+ **Low-token task context:** after `eligible` identifies a task, prefer the
+ native read-only `task-context` request with that plan's current
+ `model_sha256` and the selected task ID. It returns only the task,
+ its referenced spec criteria, relevant dependency states, scoped factual
+ prerequisites, and explicitly unknown legacy scope. It does not collect a
+ verification snapshot, invoke tools, mint receipts, or authorize execution.
+ A `binding_current: false` response means review affected requirements and
+ reconcile the source, not assume the old plan is approved. The packet marks
+ `context_complete: false` because unrelated spec material is deliberately
+ omitted; expand exact symbols for material constraints. A stale model identity
+ needs a fresh `identity` read. When an older installed engine lacks
+ `task-context`, use existing bounded exact/`read-batch` symbol reads without
+ claiming the new capability exists. On `RECORD_TOO_LARGE`, read complete
+ needed records at a larger supported budget; never accept silent truncation.
- - Every acceptance claim in the task's obligation is met by the change.
- - Scope is clean: nothing implemented beyond the task; nothing required by it omitted.
- - Out-of-scope work the subagent noticed is recorded with an inline `[NEEDS-TRIAGE]` marker — never
- acted on inside this task.
+ For a `fact` prerequisite, check it with ordinary authorized tools and record the actual `prerequisite` observation (satisfied/unsatisfied/unknown, source, outcome and reported origin). For a `decision`, apply the user's already-stated choice where it is actually supported; otherwise ask the consequential question in ordinary language. An agent report is not an authenticated user decision. An unresolved prerequisite affects only the tasks that depend on it; continue independent work.
- For HTML, capture the actual spec-review event against the exact task and
- artifact identities. After the governed verification runner has produced its
- separate receipt, use `task-review` with those two engine-written receipts. A
- digest or the reviewer/subagent's label is not evidence by itself.
+ Record `task-start` when beginning a pending HTML task using the current revision/model hash and a durable operation ID. `task-start` does not need approval receipts, a complete context ticket, a source snapshot, or a reviewer. It cannot clear a recorded stop or start already-running work again.
- Gate: the obligation is fully satisfied and scope is clean. A shortfall returns the task to Phase 2
- with a corrective brief.
+ **After process recreation**, rediscover the same authoritative pair and query `identity` and `eligible` again. Inspect the current worktree, outstanding tool runs, and task results before deciding whether an `IN_PROGRESS` task is still active, partly finished, or ready. Use a reasoned `task-reconcile` to reflect known progress; do not duplicate execution or manufacture evidence. Resume a `BLOCKED` task only after its actual blocker or user's stop has been resolved. CAS/replay remain mandatory: on a lost response, check the journal or retry the same operation ID and identical request rather than reissuing a mutation under a new identity.
- ## Phase 4 — Quality review (once per scope) · gate: BLOCK
+ ## 2. Implement or delegate the useful unit
- Runs ONCE per scope — after every task in the current scope has cleared Phase 3 and Phase 5 — over
- the **combined diff** of the scope, not per 2–5-minute task. Per-task review at that granularity
- costs more context than the work and catches nothing the batch diff doesn't; the batch boundary is
- where review pays. (A scope of one task reviews that task's diff — same rule, degenerate case.)
+ Work directly when a focused change is clearer and cheaper. Delegate when genuinely useful for isolation, independent parallel work, or specialist expertise. A **fresh subagent per task is not mandatory**; do not spawn reviewer agents solely because task status or a receipt changed.
- Dispatch the reviewers applicable to what the combined diff touches, then `finding-triage`
- (`${CLAUDE_PLUGIN_ROOT}/agents/finding-triage.md`) to classify every finding by severity. Select
- reviewers by the diff, not blanket — dispatching an irrelevant reviewer wastes a context:
+ Choose a relevant author (backend/front-end/infrastructure) when delegated. Supply the objective, paths, criterion IDs, actual constraints, known current state, and observable checks in a **bounded context packet**. Reuse `_artifactpromptlib.compose_feature_actor_input` and `_contextselectlib.prepare_actor_delivery` when useful to deliver relevant context; neither returns execution permission, and an absent delivery receipt is not grounds to forbid already-authorized work. Respect the host's real subagent permissions and applicable security constraints. Do not pass source-discovered commands to a tool without ordinary host-governed authorization.
- For each dispatched reviewer, compose and send a fresh actor input with the
- union of paths in the combined scope, the current bounded context inputs,
- exact approved spec/plan IDs, and the scope task binding. Preserve independent
- review judgment and all existing review gates. A packet read only by the
- coordinator is not reviewer delivery; unresolved critical constraints block a
- substantive verdict while bounded source inspection remains possible.
+ Prefer the test-first approach in `${CLAUDE_PLUGIN_ROOT}/skills/tdd/SKILL.md` for behavior changes, using evidence that distinguishes RED, GREEN, regression, and skipped/unrun checks. Documentation-only or other work without a runnable test uses a concrete relevant validation instead. Never weaken or delete a failing test to create a pass.
- - `security-reviewer` (`${CLAUDE_PLUGIN_ROOT}/agents/security-reviewer.md`) — any security-relevant path (authn/authz, deploy, CI, trust boundary).
- - `auth-crypto-reviewer` (`${CLAUDE_PLUGIN_ROOT}/agents/auth-crypto-reviewer.md`) — auth, crypto, key, or secret changes.
- - `dependency-reviewer` (`${CLAUDE_PLUGIN_ROOT}/agents/dependency-reviewer.md`) — `package.json` / lockfile / base-image changes.
- - `migration-reviewer` (`${CLAUDE_PLUGIN_ROOT}/agents/migration-reviewer.md`) — DB migration add/modify.
+ If implementation reveals a better in-scope method, update task steps, runner, or decomposition through typed `apply` with a short reason. Do not reset other tasks or reapprove the entire plan. A changed outcome or consequential unresolved choice goes to its real owner.
- (Do NOT dispatch `grader` or `scout` — they are INTERNAL to `decision-variance` and must never be
- dispatched here.) If the change touches none of the above domains, the quality bar is `tdd`'s own gates
- plus `coverage-auditor` (already run in `tdd` Phase 4) — record that and proceed.
+ ## 3. Verify truthfully and assess only relevant risks
- - A security CRITICAL finding halts the loop — see Hard rules.
- - A HIGH finding returns the offending task(s) — attributed by file — to Phase 2; the scope's
- quality review re-runs over the corrected combined diff.
- - MEDIUM and LOW findings are recorded; the active caller owns their disposition. Under an approved
- `/sprint`, use its existing delegated decision rules rather than adding a per-finding user checkpoint.
- In attended execution the user retains that decision; mandatory project policy still applies.
+ Compare the implementation to the source criteria: what is required, what changed, what is missing, and what behavior a passing test actually covers. Run the planned applicable test or a narrower verified equivalent through the existing **host-governed execution tool**. Record the command, working directory, outcome, and limitations. A command-level pass is not invented named-test proof. A new failure or a skipped/unknown result cannot be masked by an earlier pass.
- Gate: no CRITICAL, no HIGH across the scope's combined diff. Nothing in the scope is `ACCEPTED`
- until this passes.
+ A failing check is a reason to repair, investigate, or mark verification pending, **not permission to claim it passed** and not a ban on unrelated implementation. Rerun affected checks after a correction. If the same approach fails repeatedly without new information, diagnose differently or record a bounded blocked task and continue unrelated work.
- ## Phase 5 — Verification · gate: BLOCK
+ Review the combined relevant diff when risk or change size warrants it. Use a specialist reviewer only for an actual security/dependency/migration concern or an explicit policy requirement. Avoid duplicate security reviews and blanket per-task spec/quality fleets. Retain useful findings; revisit affected conclusions only when relevant code, requirements, supporting evidence, or the previously reviewed subject changes. A new receipt ID by itself is not an impact.
- Verification-before-completion: apply the shared fresh-run discipline in
- `${CLAUDE_PLUGIN_ROOT}/includes/fresh-verification.md`, with **the task's verification command from the
- plan** as the target. Run it yourself in a clean invocation; do not accept a logged result from Phase 2.
- A non-zero exit, or output that does not demonstrate the obligation, returns the task to Phase 2.
+ An explicit receipt-backed review/verification claim remains available under the historical attestation section of `includes/artifacts.md` **only when an actual caller requires such proof**. Never create, auto-approve, relabel, or simulate a receipt to move ordinary progress. Host security controls, actual deny/stop instructions, and policy-required reviews are independent of the artifact status engine.
- Gate: the verification command exits clean and its output demonstrates the obligation. Only then.
+ For a real verification command that the host already ran, record its
+ ordinary result via native `task-check` with `command_index` only when
+ the exact declared command ran, or without it for a useful ad-hoc check.
+ Pass along the observed exit code, summary and bounded source/output; never
+ invent a named-test result because a collector could not parse it. The
+ result stays `caller_reported`, with source/worktree freshness **unassessed**,
+ not an independent test or reviewer certificate. A failed/skipped/unknown
+ report does not become successful because the task was marked `DONE`.
+ The latest reported failure remains visible even after an older pass; fix
+ only relevant work and record another actual result as appropriate. Avoid
+ turning this bookkeeping into an extra testing or approval phase.
- ## Phase 6 — Accept and advance · gate: BLOCK
+ ## 4. Persist honest progress and return
- Mark a task accepted only when its spec-compliance review and fresh verification
- passed AND the scope's Phase 4 quality review passed. For Markdown, record the
- existing status-cell transition in the plan. For HTML, capture the actual
- combined quality-review event and call `accept-scope` once for the whole scope;
- the resulting engine state and acceptance receipts are the resume ledger. Never
- edit an HTML status cell or create a Markdown counterpart. In either format, an
- acceptance that lives only in conversation context is lost to interruption.
+ For HTML use `task-review` without receipts to record implementation ready for review; this is **not** a claim that an independent review or tests passed. For a completed implementation batch use `accept-scope` with its authored scope ID and a real reason, **without a receipt**, to record `DONE` (implementation complete; checks not assessed). It must not clear a pending/blocked member. Keep failures, outstanding checks, and uncertainty in the report or appropriate typed records. Do not upgrade `DONE` to `ACCEPTED` without genuine independent evidence.
- - Tasks remain in the current scope → return to Phase 1.
- - **Scoped invocation** (`scope` was passed by `executing-plans`): all scoped tasks `ACCEPTED` → signal
- batch complete and return to `executing-plans`. Do NOT hand to `commit-gate`; the caller owns that decision.
- - **Full-plan invocation** (no `scope`, i.e. `/sprint`): plan complete → hand the branch to
- `commit-gate`, then to the caller's finishing step. The loop does not commit on its own authority.
+ For Markdown preserve its canonical ledger and meaningful statuses. Do not equate an old Markdown `ACCEPTED` status with a new native receipt, or change representation as a shortcut.
- When either path claims the entire HTML plan is currently accepted, invoke the
- installed bridge's `_preflight_current_acceptance` with the exact
- `_resolve_workflow_pair` result, repository-bound client, and engine-returned
- spec/plan IDs. Do not pass or derive authority from a caller label, digest,
- status, or receipt. A refusal means the plan is not complete; return to the
- appropriate execution/reconciliation phase instead of handing off.
+ - **Scoped invocation:** return completed tasks, checks actually run, unresolved issues, and next work to `executing-plans`. Do not call `commit-gate` yourself.
+ - **Full-plan invocation:** provide the same honest summary to `/sprint`; it owns the authorized commit and PR handoff. A completed implementation batch with failing or unrun required checks is not release-ready.
- Gate: every task in the current scope `ACCEPTED`, the suite green, ready for the caller's next step.
+ ## Hard boundaries
- ## Hard rules
+ Do not invent a test result, user choice, reviewer finding, credential, approval, or installed-host qualification. Do not clear a user stop, skip actual host permissions, run an irreversible or unapproved out-of-scope operation, or bypass independently applicable security controls. Do not silently modify a requirement to claim completion. Mark unrelated discoveries `[NEEDS-TRIAGE]`, not automatic scope expansion.
- - MUST dispatch a fresh subagent per task — never reuse one context across tasks.
- - MUST NOT write implementation code before the task's `tdd` Phase 1 completes.
- - MUST accept a task only when both reviews pass AND verification passes on a fresh run.
- - MUST NOT accept a task on a subagent's self-report — run the verification command and read its exit code.
- - MUST halt and surface a real authority or security block, including security CRITICAL findings and
- unresolved `[CONFIRM-NN]` decisions. Ordinary TDD/verification failures and finish-time stale proof
- under an approved sprint take Recovery within the approved sprint in `${CLAUDE_PLUGIN_ROOT}/SPRINT.md`.
- A failed gate never auto-passes, and recovery never grants missing commit authority.
- - MUST NOT commit — hand the accepted branch to `commit-gate`.
- - MUST mark out-of-scope findings with an inline `[NEEDS-TRIAGE]` marker and never act on them inside the task.
- - MUST NOT invoke `farm.js` before writing `meta.model` into `plan.json` (or setting `FARM_MODEL`) — the dispatcher fails loudly otherwise.
- - MUST NOT skip model selection (Step 1) when `FARM_MODEL` is not set — exhaust the canary→cache→websearch fallback ladder before BLOCKing; never blind-invoke with an unknown model id.
- - MUST route every green farm task through Phases 3–5 before acceptance — the farm replaces authoring, never review. A cheap model gets the same scrutiny as a premium subagent, not less.
- - MUST treat a single task's drift/gaming/tampered-test escalation as model incapacity (re-dispatch via premium Phase 2); raise `[CONFIRM-NN]` and HALT only when multiple tasks drift onto the same out-of-scope path (a real spec gap).
- - MUST treat a `farm.js` circuit-breaker abort (`aborted: true`) as a hard-gate STOP — surface to the user; do not silently re-dispatch the whole slice to premium.
- - MUST NOT dispatch `grader` or `scout` in Phase 4 — they are INTERNAL to `decision-variance`.
+ A reported `DONE` is useful progress, not fresh verification. `eligible` is useful scheduling, not authority. Treat actual failures as failures; do not compensate by adding approval ceremonies or dispatching unrelated reviewers. Do not commit from this skill; use the real `commit-gate` owner when committing is authorized.