Skip to content

docs(agents): state the subagent model split as capability tiers #132

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andybons merged 1 commit into from
Aug 12, 2026
Merged

docs(agents): state the subagent model split as capability tiers #132

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 20 additions & 13 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1363,19 +1363,26 @@ Rules:
## Subagent model strategy

When you spawn subagents, set the model EXPLICITLY on every spawn — never
let an implementation agent inherit the parent model by default.

- **Code-writing / implementation / mechanical work uses Sonnet.** Writing
code, editing docs, changing config, grep/investigation, watching a
deploy — spawn these with the Sonnet model. Sonnet is fast and sufficient.
- **Review, adversarial verification, and judgment gates use Opus.** The
review-to-zero gate and any correctness verdict deserve the stronger
model. Spawn review agents with Opus.

The default pattern for a change: a Sonnet agent writes the PR, an Opus
reviewer drives it to zero. Omitting the model makes a subagent inherit the
parent's model, so an Opus parent silently runs implementation work on Opus
— expensive and backwards. Pass the model on every spawn.
let an implementation agent inherit the parent model by default. The rule
is a capability-tier split, not a vendor or model-name rule; it applies to
whatever frontier family is current.

- **Code-writing / implementation / mechanical work uses the fast
mid-tier.** Writing code, editing docs, changing config,
grep/investigation, watching a deploy — the tier that is fast, cheap,
and sufficient for well-specified work (today: Claude Sonnet; the
equivalent tier elsewhere: GPT mini/frontier-fast class, Gemini Flash).
- **Review, adversarial verification, and judgment gates use the
strongest tier.** The review-to-zero gate and any correctness verdict
deserve the strongest available model (today: Claude Opus; elsewhere:
the full frontier flagship, never a mini/fast variant).

The default pattern for a change: a mid-tier agent writes the PR, a
strongest-tier reviewer drives it to zero. Omitting the model makes a
subagent inherit the parent's model, so a strong parent silently runs
implementation work at flagship price — expensive and backwards. Pass the
model on every spawn. When a model family changes, re-map the two tiers
and keep the split; do not carry a stale model name forward.

## One agent per plan task, not one agent per plan

Expand Down