| name | subagents |
| description | Framework for dispatching one-shot Subagents that complete a Task and return. Covers Prompting (WHAT/WHY, never HOW), the Story/Business/Goal/Verification/Process Prompt Template, Verification, Evidence, and Orchestrator-side ranking. |
Subagents
One-shot Subagents complete a Task and return; SendMessage by name resumes one for iteration.
Every line of code is written by a Subagent during Orchestration; the Orchestrator preserves Context for coordination.
The Orchestrator holds the big picture; Subagents ask it at decisions and report to it when done.
1. Prompt WHAT and WHY, never HOW
Strip implementation detail from the Prompt
A fresh-Context Subagent finds the right solution from the Goal. Implementation detail in the Prompt biases it toward the Orchestrator's assumptions, does the Subagent's research for it, and breaks when the code changes. State the User pain, the capability wanted, and observable success.
Never: files, symbols, read order, library calls, "do not touch X", src/foo.py, _extractMethod, "read X first then Y", "use lizard.analyze", or "DO NOT modify main".
IF the Task is mechanical:
Give exact mechanical steps
A bulk rename or format conversion is not Architectural, so specific Task steps are correct.
2. Scope the Subagent to its reasoning unit
Give the full module or feature
An Architect given one method cannot judge encapsulation; a reviewer given one hunk cannot find caller regressions. The Subagent narrows itself after reading.
Example: Architect gets the module; reviewer gets the full diff plus surrounding code; backend-engineer gets the service boundary.
Split disconnected Tasks into separate Subagents
One Subagent, one Task. Quality falls as a Subagent's Task list grows.
Never: "do A, then also B, then also C" in one dispatch when the Tasks share no reasoning unit.
Dispatch one owner per system, not one Subagent per symptom
Symptoms cluster to the system that owns them. Two Subagents touching the same file collide; give the owning system's Subagent the symptom cluster instead.
Keep a dispatched Task singular and unchanging
The Orchestrator re-scopes by resuming the agent or dispatching anew; the Subagent never widens its own Task.
3. Write the Prompt Template
A dispatch Prompt has Story, Business, Goal, Verification, Architecture, and Process.
Story says what the User experiences and needs.
Business says WHY it matters, the boundaries, and the limitations.
Goal says what the Subagent delivers.
Verification says how the Subagent proves its work before returning.
Architecture orients the Subagent before the Process and marks files to change with *.
Process is the operating procedure the Subagent runs first and last.
Weave findings into the section they belong to
A prior finding about User impact belongs in Story; a prior finding about a boundary belongs in Business. A trailing notes section is a dump the Subagent reads too late.
Make Verification observable, specific, and complete
Verification is input → output, or command + expected status and body.
Example: "npm test --grep payment passes"; "timeout after 30s shows 'Payment timed out'".
Never: "code works", "tests added", "no errors".
Template:
Story:
Business:
<WHY it matters, boundaries, limitations>
Goal:
Verification:
Architecture:
- path/to/file.ext — why it is in scope
Process:
- Read every file marked * in the Architecture block
- One file at a time — read it, then edit it. No bulk-rewrite scripts, no shortcuts
- Implement against the Goal
- For EACH Verification item: exercise it; record the input, the observed output, and
a screenshot (agent-browser) when the behavior is visible in a browser
- If a Verification item fails → fix and re-verify (loop step 4)
- Write your Evidence to the directory the dispatch named — report.md plus screenshots.
A claim without output or a screenshot behind it does not go in report.md
- Post a completion summary: what changed, what was verified, what was tricky, where the Evidence is
4. Dispatch independent Subagents at once
Run independent Tasks in parallel
One message, multiple Agent calls, each with name and run_in_background: true, each
naming its Evidence directory (docs/agents/-/). Sequence only when
one Task's output feeds the next.
Template:
Agent(subagent_type: "backend-engineer", name: "worker",
prompt: "<Story/Business/Goal/Verification + Architecture + Process>",
run_in_background: true)
Resume the agent you have
SendMessage by name resumes an agent from its transcript, even after it returned.
Never: a fresh dispatch for work an existing agent owns.
Check on agents; never put them on a timer
On the coordination cadence, read a running agent's Evidence directory; when nothing moved,
SendMessage it for status. Only when resume fails — including an agent whose Context is
exhausted and resumes into silence — dispatch a replacement implementing Subagent with the original
Prompt, the current diff, and the Evidence directory.
Never: kill or time out a working agent — that leaves incomplete work and an unresumable agent.
5. Verify, hold the Goal, and orchestrate
Preserve Context for coordination
Do not use Edit, Write, or NotebookEdit while coordinating. Reading a wide diff yourself burns Context: you lose Orchestration Context and miss things.
Judge the Evidence yourself
Read the report.md against the dispatch's Verification criteria; open only the screenshot
that settles a criterion the text cannot. Thin Evidence goes back to the same Subagent by
name, naming the failed item. For a reported symptom, Evidence must show the symptom's own
surface — the reporter's page, not a stand-in fixture.
Never: dispatch any Subagent to re-verify a completed work item — "the screenshots look
thin, let me have the tester confirm it". Validation runs once, against the whole
changeset, at the end.
Restore by hand
Destructive-git restore is banned because Subagents nuke without checking and destroy real work. The Hooks enforce this.
Never: git reset, git restore, git checkout --, or a script.
Take the long hard way
Repetitive work is still read then edit, file by file. A bulk-rewrite script or clever one-liner that skirts the work and hides errors is AI Slop.
6. Treat Subagent output as a claim until proved
Repo behavior outranks the summary
The Subagent summary describes what it believes it did. The repo, common sense grounded in User, Architecture, and Business, and the Architect's reported outcome outrank the summary.
Re-dispatch contradictions deeper
When a finding contradicts what the Architect reported, the finding is incomplete. Re-dispatch deeper until a Subagent reproduces the reported outcome.
Reject effort arguments
"Done", "tests pass", and "no change needed" earn belief only after a repo check. "Out of scope", "too many files", and "too slow" are effort arguments, not scope. "It was broken before" is false until a clean baseline run proves it. "I'm blocked" is usually a skipped simple step: retry, restart the server, clear the cache, re-run.
7. Verify behavior, not guesses
Require concrete input and observed output
Before accepting "done", the Subagent answers in writing: what concrete input ran and what exact output came back, which Critical Path was exercised start to finish, what was not exercised, and what breaks if production hits it.
Treat compile checks as necessary but incomplete
Compiling, type-checking, linting, "logic is sound", and "looks correct" prove nothing about behavior. A confidence percentage is a guess wearing a number.
Example: "POSTed {email: a@b.co} to /api/v1/form-submit; got 200; redirect to /thanks; happy path exercised; editor variant not exercised."
Never: "build succeeds, types check, confidence 80%."
8. Record Evidence
Evidence lands on disk
Evidence goes in docs/agents/<YYYYMMDD>-<task-slug>/: report.md plus screenshots beside it. Later Agents reference the Evidence instead of trusting the claim.
Advance a status only with its Evidence
A work item moves to fixed or closed only with the Evidence path that proves it; a status that moves backward gets a one-line written cause.
9. Rank returned options yourself
Strip the recommendation and keep the facts
A Subagent saw a Slice; the Orchestrator holds the project, its Rules, the Architect's prior calls, and sibling code. Its recommendation is one finding, not a verdict.
Finish the research before ranking
Re-dispatch every gap in parallel and re-run Subagents that came back thin. Stop when nothing is left to investigate, never when the batch returns. Every surviving claim comes from a read.
Eliminate before ranking
Drop every option that breaks a standard, convention, or Rule. The Orchestrator does this, not the Subagent.
Rank in your own voice
Rank survivors with /pcc, then recommend one in your own voice.
Never: "the Agent recommends", "per the research", "based on the findings X is best", "Architect recommended Option N", "following the analysis Option N".
Template:
Close every research gap. Dispatch as much in parallel as is independent. Do not stop to ask, do not deliver half-finished work, run the loop until nothing is left to investigate. Every code claim must come from a read, not a guess. Findings only — no scope changes, no ranking, no recommendation.
