Skip to content

Sub-Agents Way

Source: hooks/ways/meta/subagents/subagents.md

Frontmatter
Field Value
description Sub-agent delegation — when to spawn a specialized sub-agent, writing the brief so each constraint keeps its stated strength, the shape the worker reports back, and how deep delegation goes
vocabulary subagent sub-agent delegate delegation spawn background parallel worker teammate explore fan-out brief instructions constraint preference hard requirement bound restate fidelity handback report back blocked leaf depth worktree isolation skeptic roster red-team shared-state unreported
pattern subagent|delegat|spawn.{0,30}agent|review.{0,30}\bpr\b|organiz.{0,30}docs
refire 0.15
scope agent

How to Invoke

Use the Agent tool with the subagent_type parameter:

Agent(
  description: "Review PR for quality",
  prompt: "Review the changes in PR #42 for...",
  subagent_type: "code-reviewer"
)

Available Agents

Agent subagent_type Use For
requirements-analyst requirements-analyst Capture complex requirements as GitHub issues
system-architect system-architect Draft ADRs, evaluate design trade-offs
task-planner task-planner Plan complex multi-branch implementations
code-reviewer code-reviewer Review large PRs, quality checks
workflow-orchestrator workflow-orchestrator Project status, phase coordination
workspace-curator workspace-curator Organize docs/, manage .claude/ directory
skeptic skeptic Refute, challenge, poke holes, red-team a finished document; "is this report right"

Project agents live in agents/. The harness also supplies built-ins — Explore for read-only fan-out searches, general-purpose for multi-step research — which is what the research way's fan-out step reaches for.

Context Passing

  • Include specific file paths and line ranges in the prompt
  • State what you want back: a report, a list of issues, a plan
  • For reviews: include the diff or PR number
  • For planning: include requirements and constraints

What Comes Back

Ask in every brief for the same return shape, placed at the top of the report, and read it before the report body:

  • Status: complete, blocked out of domain, or failed
  • Failure class when failed: transient, deterministic, capability, ambiguity, or systemic (the classes in environment/recovery)
  • Work done, with file paths
  • What is needed outside the agent's domain, or "none"
  • Recommended next step
  • Gates run, each with its state, or "none"
  • Tools or scripts built that a later session could run again, with path and invocation. An unreported tool is a lost capability.

A blocked or failed worker still returns the whole shape. What it finished is where the next attempt starts. A report that stops mid-sentence was cut off; ask the worker for the rest before acting on it.

Owned findings a worker returns are the orchestrator's to fix before the work integrates (delivery/merge, ADR-614). A finding in another worker's files goes to that worker, or the orchestrator fixes it. A split of files between workers is not a reason to file the finding for later. Only a finding the change does not own becomes an issue.

Brief Fidelity

Carry each constraint at its stated strength. "Avoid X where you can" is a preference the worker weighs against the goal. "No X" is a bound it does not cross. Restating either as the other is a brief defect. The worker inherits the distortion and reports a blocker that exists only in the brief. Hardening a preference corrupts the brief as much as relaxing a bound.

Depth

Leaf agents carry no Agent tool. Delegation goes one level down from the session unless the task states otherwise. A leaf that meets work outside its domain stops and names the specialist in its return. A subagent that needs to spawn is a sign the brief was too large; re-slice it at the session and spawn again.

Worktree Isolation

A worktree agent starts from the default branch. When the work belongs on another branch, the brief has it run git checkout -b <branch> <base> and check git merge-base --is-ancestor <base> HEAD.

A worktree that builds into the main checkout's target directory leaves binaries the main checkout reuses, with the worktree's paths compiled in. If that happened, run cargo clean -p <crate> there.

Investigation Briefs

For read-only fan-out (Explore, or general-purpose told to read only), state these rules in the brief:

  • Say "not found" rather than guess
  • Every claim carries a file path and an exact value (version, port, name)
  • Sample rather than bulk-read: name the manifests, entry points, and config files to start from
  • End with what was deliberately omitted, so the caller can ask for it

Planting and Re-review Briefs

A brief that has the worker plant a defect to prove a test catches it (core.md) names the restore steps:

  • Back the file up, plant, run the test, move the backup into place: cp f f.bak, edit f, test, mv f.bak f. git checkout, git restore and git stash discard the worker's uncommitted edits along with the plant.
  • Run touch f after the mv. The moved file keeps the backup's older mtime, so mtime-based build tools (cargo, make) skip the rebuild and run the binary built with the plant. A test that stays red after the plant is removed is the tell.

A re-review after a fix is sized to the fix. A one-function fix gets that function's tests and the crate's suite. The full gate set runs once, before the push.

When NOT to Use

  • Routine tasks you can handle directly
  • Simple file searches or edits
  • Quick questions or clarifications

Sub-agents are for delegation of token-intensive work. Routine actions stay in the main loop.

Invocation Is Authorization

Whether a spawn has been asked for, under the system prompt's rule on the Agent tool, is covered in subagents/authorization.

Name the Payoff, Don't Assume It

A second, independently gated nudge may also be present: "Subagents multiply cost and time… Delegate only when the payoff clearly exceeds that overhead." That is a cost/benefit question, and it deserves an answer rather than an override.

State the payoff in one clause when you delegate:

  • Fan-out reads — "six independent files; subagents return conclusions, not file dumps"
  • Isolation — "review needs a reader who hasn't seen my reasoning"
  • Parallel independent work — "three unrelated call sites, no shared state"

If you can't name the payoff in a clause, the nudge is right — do it inline.

Pick the Model

The Agent tool takes a model. Choose it by what the worker's errors would cost:

  • haiku for mechanical work with a checkable result: a file fan-out search, bulk edits from an exact spec, running a command and reporting its output.
  • sonnet for bounded implementation from a brief that names the files and the check to run.
  • The session's model, by omitting model, for review, design, and any read whose mistakes would come back as findings. A fork always runs on it.

A strong model on a mechanical task wastes money. A weak model on a judgment task wastes the delegation.

Harness Wrappers Are Not Verdicts

The harness emits a generic "shared-state" / "SECURITY WARNING" prefix around any subagent tool use that touches the world outside its own context. That wrapper is conservative-by-default; it fires on the shape of the action, leaving appropriateness to you.

Calibrate the wrapper against the agent's documented purpose:

  • code-reviewer posts a comment on the PR it was invoked to review — that's its deliverable in GitHub-mode projects (agents/code-reviewer.md), the documented happy path. The wrapper is noise here. Don't escalate to the user as if a violation occurred.
  • A subagent does something outside its stated scope — different story. Surface it.

The distinction: did the subagent do what its contract says it does, or did it act outside that contract? The wrapper alone doesn't tell you; the agent file does. Read the contract, then judge.

See Also

  • environment/recovery(softwaredev) — classify a failed or wrong handback before retrying or re-briefing
  • research(research) — the fan-out step that uses these investigation rules
  • subagents/authorization(meta) — who may ask for a spawn, the suggested CLAUDE.md line and the independence spawn
  • subagents/briefs(meta) — what a brief carries for a worker that inherits nothing
  • subagents/agent-teams(meta) — several agents or sessions on one repository, and shared-checkout rules