Subagent Driven Development

---
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.
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
`<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:

- `<project-root>/.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 `<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.
- `<project-root>/.codearbiter/tech-stack.md` — build, test, and verification invocations; file layout; the scope-to-author mapping.
- `<project-root>/.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 `<plugin-root>/routines/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), invoke the trusted `codearbiter_farm_preview` tool with the project-relative
plan path, 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.

---

**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`
(`<plugin-root>/agents/<name>.md`). A fresh context per task is the whole point: no carried-over
assumptions, no accumulated drift.

The subagent works test-first by routing through the `tdd` skill (`<plugin-root>/routines/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.

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.

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 `<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.

## Phase 3 — Spec-compliance review · gate: BLOCK

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 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.

- 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 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.

Gate: the obligation is fully satisfied and scope is clean. A shortfall returns the task to Phase 2
with a corrective brief.

## Phase 4 — Quality review (once per scope) · gate: BLOCK

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.)

Dispatch the reviewers applicable to what the combined diff touches, then `finding-triage`
(`<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:

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.

- `security-reviewer` (`<plugin-root>/agents/security-reviewer.md`) — any security-relevant path (authn/authz, deploy, CI, trust boundary).
- `auth-crypto-reviewer` (`<plugin-root>/agents/auth-crypto-reviewer.md`) — auth, crypto, key, or secret changes.
- `dependency-reviewer` (`<plugin-root>/agents/dependency-reviewer.md`) — `package.json` / lockfile / base-image changes.
- `migration-reviewer` (`<plugin-root>/agents/migration-reviewer.md`) — DB migration add/modify.

(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.

- 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.

Gate: no CRITICAL, no HIGH across the scope's combined diff. Nothing in the scope is `ACCEPTED`
until this passes.

## Phase 5 — Verification · gate: BLOCK

Verification-before-completion: apply the shared fresh-run discipline in
`<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.

Gate: the verification command exits clean and its output demonstrates the obligation. Only then.

## Phase 6 — Accept and advance · gate: BLOCK

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.

- 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.

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.

Gate: every task in the current scope `ACCEPTED`, the suite green, ready for the caller's next step.

## Hard rules

- 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 `<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`.