[Feature] Agent tiers: pin model explicitly, add effort per agent, read design docs by section

## Summary Three changes to agent configuration and to brief/skill reading discipline. None of them lowers quality; all three cut token spend. Measured on a downstream project (Godot, ~3 weeks of design-phase work, 39 agents, v1.1.2) where the user exhausted a weekly subscription quota in 3 days. 1. **Replace every `model: inherit` with an explicit tier**, assigned by the *kind of work* the agent does, not left to the session model. 2. **Add `effort:` to every agent's frontmatter.** Today no agent sets it. 3. **Briefs and skills read a design document by section, never in full.** ## Type - [ ] New agent - [ ] New skill (slash command) - [ ] New hook - [x] New rule - [ ] New template - [x] Improvement to existing component - [ ] Other: ## Problem / Motivation ### Why `inherit` is the wrong default `inherit` ties an agent's quality and cost to whatever the session runs, which has nothing to do with the agent's job: | Session model | What the 30 `inherit` agents get | |---|---| | Sonnet | Judgment-heavy agents (game-designer, systems-designer, qa-lead, world-builder…) run on Sonnet — the workload where Sonnet is weakest per dollar (see data below) | | Opus | Fine for judgment agents; execution agents pay Opus for work Sonnet does equally well | | Fable | Every agent, including pure execution, runs at 2.5× Opus price ($10/$50 vs $4/$20 per MTok) | The tier of an agent should be a property of its role, stable across sessions. ### The data behind the tiers (Sonnet 5.5 vs Opus 5.5) The aliases resolve to the latest model of each family, so the table below does not change when a model ships — only the benchmarks that justify it do. - **Well-specified agentic coding: Sonnet ≈ Opus.** Terminal-Bench: Sonnet 5.5 70.6 % vs Opus 5.5 66.4 %; CursorBench: Sonnet second only to Opus; Anthropic: ~30 % faster and up to ~30 % cheaper *per task* (not 50 %: Sonnet emits more tokens). - **Open-ended reasoning / judgment: Opus is cheaper at equal quality.** Artificial Analysis Intelligence Index, score · cost per task: | Effort | Sonnet 5.5 | Opus 5.5 | |---|---|---| | low | 36 · $0.41 | 42 · $0.55 | | medium | 41 · $0.59 | **51 · $1.34** | | high | 47 · $1.08 | 54 · $1.82 | | xhigh | 52 · $2.74 | 56 · $3.46 | | max | 56 · $7.60 | 58 · $5.98 | Opus `medium` beats Sonnet `high` and roughly equals Sonnet `xhigh` at half its cost. Sonnet at max emits ~60 % more output tokens than Opus at max. - **Hardest cases: Opus keeps the edge.** CodeRabbit's 13 hardest known-bug reviews: the gap to Opus is wider than elsewhere (Sonnet: −60 % cost, ½ wall-clock). - **Effort matters more than the model.** Opus `medium` → `xhigh` costs 2.6× for ~5 points. Sonnet on code drops sharply below `high` (CursorBench 39 % medium vs 48 % high). Anthropic's own runs: on research/knowledge work, `medium` matches `high`. Sources: [Artificial Analysis](https://artificialanalysis.ai/models/releases/comparisons/claude-sonnet-5-5-vs-claude-opus-5-5) · [Kingy AI, cost per task](https://kingy.ai/blog/claude-sonnet-5-5-vs-opus-5-5/) · [The Decoder](https://the-decoder.com/anthropics-claude-sonnet-5-5-nearly-matches-opus-5-5-on-benchmarks-while-costing-up-to-30-percent-less-per-task/) · [CodeRabbit](https://coderabbit.ai/blog/sonnet-5-5-model-review) ## Proposed Solution ### Proposal 1 — three profiles, every agent pinned | Profile | `model:` | `effort:` | For | Agents | |---|---|---|---|---| | **A — arbitrate, verify, hard review** | `opus` | `high` | Few calls, highest stakes, the failures that cost a whole review pass | `creative-director`, `technical-director`, `qa-lead`, `world-builder`, `systems-designer`, `lead-programmer`, ` -specialist` (primary: `godot-specialist`, `unity-specialist`, `unreal-specialist`) | | **B — design authoring in volume** | `opus` | `medium` | Best quality/price point of the curve; `medium` ≈ `high` on knowledge work | `game-designer`, `art-director`, `level-designer`, `narrative-director`, `ux-designer`, `audio-director`, `economy-designer` | | **C — execute a written spec** | `sonnet` | `high` | Sonnet ≈ Opus on well-specified work, ~30 % cheaper per task; never below `high` for code | `producer`, all `*-programmer`, all engine sub-specialists (gdscript, shader, gdextension, csharp, ue-*, unity-*), `prototyper`, `devops-engineer`, `technical-artist`, `performance-analyst`, `accessibility-specialist`, `security-engineer`, `qa-tester`, `writer`, `sound-designer`, `localization-lead`, `release-manager`, `analytics-engineer`, `live-ops-designer`, `community-manager` | No `haiku` agent — unchanged rationale: every agent drafts, writes or judges. **Changes against v1.1.2** (`model:` lines): - `producer`: `opus` → `sonnet`. Most of its volume is rule-following execution: delivering debt lines to receiving documents, propagation, dashboards. When it arbitrates scope, the caller passes `model: "opus"` for that one invocation. - `lead-programmer`: `sonnet` → `opus` — code review on hard cases is where Opus keeps its edge. - every `inherit` → `opus` or `sonnet` per the table. - `effort:` added to all. **On `effort:`** — Claude Code parses `effort` in agent frontmatter since 2.1.258 ([issue](https://claudeissues.com/issue/91415-docs-subagent-frontmatter-effort-field-is-implemented-but-undocumented)); the Agent tool's own description says "each agent type's model, reasoning effort, and tools come from its definition". It is not in the subagent docs yet, and whether a subagent inherits the session's effort is undocumented. Claude Code's session default is `xhigh` — the most expensive band of the curve. An explicit value removes the ambiguity. **`model-tiers.md`** to update with it: the agent section (counts, lists, the `effort` column), and the stale line "`sonnet` currently resolves to Sonnet 5". ### Proposal 2 — read by section, never a whole design document On the measuring project, design documents outgrew a context window: the largest GDD is 1.7 MB / 13 029 lines (~450 K tokens), all GDDs together ~11 MB. Every agent that works on one re-reads slices of it; every cross-review does it again. Subagents also load project `CLAUDE.md` and its imports on every spawn ([docs](https://code.claude.com/docs/en/claude-md)), so instruction weight multiplies by the number of agents in a lot. - **Brief rule** (in `coordination-rules.md`): a brief names the sections an agent needs by their heading; the agent locates them with `grep -n "^## "` and reads those ranges. Reading a design document in full is the exception, and the brief says why. - **Skills**: generalise what `/review-all-gdds` already does ("Before reading any full document, use Grep to extract `## Summary` sections") and `/design-review` Step 2a ("no full document read") to every skill that consumes a GDD, ADR or the art bible. ## Alternatives Considered - **Keep `inherit` and document "run the session on Opus".** Rejected: the tier still follows the session, and a Fable session bills execution agents at 2.5× Opus. - **`CLAUDE_CODE_SUBAGENT_MODEL` / `_FORCE` env vars.** A per-user override for one model for every agent; it cannot express "Opus for judgment, Sonnet for execution". - **Move everything to Sonnet because benchmarks look close.** Rejected by the data: on judgment work Sonnet reaches Opus's score only at higher effort, emitting more tokens, so the saving disappears. - **Haiku for status or formatting agents.** None of the agents only reads and formats. ## Additional Context ### What this does not change - No skill `model:` changes (the 5 / 66 / 3 split stays). - Quality bar unchanged: every move to Sonnet is on work where the data shows parity; everything judgment-heavy stays on Opus. ### Suggested verification Run one real task twice (e.g. a `/design-review` section or a lore-verification pass): profile B agent on Opus `medium` vs Sonnet `high`. Compare defects found and cost. The benchmarks are generic; this is the measurement that settles a borderline agent.