Subagent Driven Change

Subagent-Driven Change

Preconditions

Use this workflow only when the task has a clear spec, acceptance criteria, and file ownership. Keep tightly coupled or architectural decisions in the parent session unless the user explicitly asks for delegation.

Required subagents: implementer, spec-reviewer, code-quality-reviewer, and change-risk-reviewer.

Fresh Context

Each subagent prompt must include the full task text, relevant spec excerpts, non-goals, acceptance criteria, file ownership, constraints, expected tests, and any command limits. Do not rely on hidden chat history or a previous subagent's memory.

Flow

1. Dispatch implementer with one bounded task and the complete context it needs.
2. If implementer returns BLOCKED or NEEDS_CONTEXT, resolve that before continuing.
3. If implementer returns DONE_WITH_CONCERNS, read the concerns before review and decide whether to fix, narrow scope, or continue.
4. Dispatch spec-reviewer with the original task, relevant spec excerpts, changed files, and implementer report.
5. Fix or escalate every spec-review issue before requesting code-quality review.
6. Dispatch code-quality-reviewer only after spec review reports compliance; keep its existing maintainability objective unchanged.
7. Fix Critical and Important code-quality issues before handoff, or document why a finding is intentionally deferred.
8. This surface alone owns the change-risk/v2 state machine. Invoke change-risk-reviewer only after code-quality review, keep its closed ChangeRiskOrchestrationStateV1 handoff snapshot-bound, and never let a nested surface invoke it again for an unchanged snapshot.
9. Initial review is clean-room; remediation supplies prior fingerprints and searches the complete updated snapshot; required final confirmation is clean-room again. Any code change invalidates the preceding clean result. Files under docs/review-learning/ are excluded from snapshot identity and do not invalidate a terminal result. An initial or remediation review is never repeated against an unchanged snapshot; a required final confirmation is the exception.
10. Apply these bounded owner rules and preserve counters, actual snapshot IDs, and completed-round fingerprint and remediated-cluster-key history across resume:

• at most 3 fix rounds, 6 completed logical reviews, and 2 transient retries per logical invocation.
• Run at most 2 confirmation invocations; a confirmation must be a distinct later clean-room review and cannot be claimed by the initial review.
• Preserve missingInputs from NEEDS_CONTEXT; unavailable or forbidden context escalates immediately instead of consuming retries.
• After CLEAN, only a validated external blocker or a changed snapshot may reopen orchestration.
• Reset transient retries before final confirmation so prior malformed attempts do not consume its retry allowance.
• The initial review is not a fix round.
• One logical invocation may retry a transient failure, an invalid envelope, or a NEEDS_CONTEXT result at most 2 times.
• Failed or incomplete attempts are recorded separately and never become findings or fix rounds.
• Before starting a fix round, reserve a remediation review plus any required final confirmation in the remaining invocation budget.
• The same unresolved fingerprint appearing twice without progress transitions to NO_PROGRESS.
• Failure to reduce the blocking-finding count across two consecutive remediation reviews transitions to NO_PROGRESS.
• A fix round that leaves the reviewed snapshot unchanged while open blockers remain consumes no invocation and transitions to NO_PROGRESS.
• Three or more open findings sharing a cluster key are remediated as one shared cause in one fix round.
• For a within-change cluster recurrence, add a mechanical guard or record impracticality with rationale and evidence before escalating to NEEDS_HUMAN_REVIEW.
• A completed FINDINGS_FOUND result whose P1 and P2 findings are all verified fixed, obsolete, or evidenced false-positive, and whose every P3 carries a valid disposition, contains no blocker.
• It reaches terminal clean exactly as a CLEAN result would, without relabeling the reviewer envelope.
• There is no additional review of the unchanged snapshot; the same required-confirmation triggers still apply.
• A validated external P1 or P2 reopens the local loop when fix-round and logical-invocation budget remains.
• When that budget is exhausted the workflow escalates to NEEDS_HUMAN_REVIEW rather than retaining a clean terminal state.
• External findings enter only through the orchestration owner's validation handoff; an unreproduced report is never trusted automatically and never silently discarded.
• Require final clean-room confirmation: after-any-p1.
• Require final clean-room confirmation: after-two-or-more-fix-rounds.
• Require final clean-room confirmation: high-risk-surface-touched.
• Remaining open P1 or P2 findings after the last allowed fix round.
• Open blockers remain but the invocation budget cannot cover another fix round's remediation review plus the confirmation that would then be required.
• Exhausted attempt retries; they are never converted to a clean result.
• An unsatisfiable missing input escalates immediately.
• NEEDS_HUMAN_REVIEW takes precedence over NO_PROGRESS when both apply.

11. Run the relevant tests, golden tests, and doctor/check commands required by the spec before final response.
12. When orchestration reaches any terminal status, persist exactly one normalized review-learning/v1 record for this change under docs/review-learning/, carrying sourcePolicy: change-risk/v2 with its execution counters, per-round and per-finding source markers, cluster events, and the terminal status. Write the normalized record only: Raw prompts, transcripts, hidden reasoning, and unfiltered tool output stay in a local ignored location and are never committed. Secret-shaped values are described by shape and never copied verbatim. Reference commits, paths, symbols, contracts, and tests instead of reproducing source or full reviewer explanations. Unknown provider or model versions are recorded as unknown, never guessed. Historical records feed promotion and evaluation only; never load them into initial or final clean-room reviewer context.
13. Then apply the promotion table to each validated finding, keyed on its canonical category with alias normalization - never on raw wording, and never on a cluster key, which is mechanism-keyed and may span categories. The occurrence unit is one reviewed change; repeated rounds and fingerprints inside the same change collapse to at most one occurrence per canonical category. A finding counts only when its recorded resolution is one of fixed, or when it is open and an open finding counts only when the persisted record carries dispositionConfirmed: true together with the owner's decision evidence in dispositionEvidence. A finding resolved false-positive or obsolete never counts, and a finding whose category is uncategorized is excluded from recurrence and earns no rule until a human assigns a canonical category. A P1 is systemic when: The affected contract is a hard safety, permission, ownership, redaction, or no-upload contract. Or the unsafe condition demonstrably reaches two or more independent consumers or surfaces beyond the single reviewed path. When the predicate is uncertain the finding is non-systemic and the recorded reason says why. First systemic P1: Immediately add a regression test and a scoped review rule where practical. First non-systemic P1: Record and categorize like a first ordinary finding and add a regression test where practical. First ordinary P2/P3: Record and categorize the finding. Second occurrence: Add a reviewer regression case plus a scoped Code Review Rules rule, unless an existing mechanical guard already provides equivalent or stronger protection, in which case cite the guard instead. Third occurrence: Add a test, lint, validator, or shared helper where practical; the prompt rule alone has proven insufficient. Before adding a prose rule, determine whether the failure can be prevented by a schema, interface, type, test, validator, lint rule, ownership check, or shared helper. A mechanical or interface-level guard may be introduced before the third occurrence when it is clearly practical and proportionate. A prompt rule is added only when model judgement remains part of the safe decision. Any promoted prose rule is: Concise. Consequential. Scoped to the narrowest applicable path. States the unsafe condition. States the safe path or a counterexample. Never silently modify a compiler-generated instruction region. Within the reviewed change, promotion writes only a proposed-patch artifact under docs/review-learning/proposals/ and never edits a human-owned rule surface. Applying a proposal to AGENTS.md or another human-owned rule surface is a separate later change through the normal write boundary, reviewed and invalidating as usual. When a deterministic guard gives equivalent or stronger protection the redundant prompt rule is removed, retired, or reduced to navigation guidance, and a retired rule is never rendered into generated context.
14. After change-risk orchestration reaches terminal CLEAN and the required tests complete, invoke final-review against the validated handoff and current snapshot. Fix or escalate its findings before handoff.

Status Values

Implementation worker status values: DONE, DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT.

Spec reviewer status values: COMPLIANT, ISSUES_FOUND, NEEDS_CONTEXT.

Code-quality reviewer status values: ACCEPTABLE, ISSUES_FOUND, NEEDS_CONTEXT.

Safety

• Do not ask subagents to commit, push, create branches, install dependencies, read secrets, contact production systems, or upload source unless the user explicitly requested that action.
• Do not accept an implementation report without reading reviewer findings.
• Do not run code-quality review before spec-compliance review passes.
• Keep generated files deterministic and lockfile-tracked.

Output

Final handoff must list what changed, tests run, contract impact, security impact, remaining risks or TODOs, and whether the spec acceptance criteria are fully met.