Subagent model routing

# AGENTS.md: subagent delegation and model routing

The lead session plans, decides and talks to the human. Subagents do bounded work. Pick the cheapest model
and effort that can do each assignment well, and say so explicitly every time you spawn one.

## Classify each assignment before spawning
Classify the work you are delegating now, not the parent ticket. Choose the tier directly; do not trial-run tiers.

| Class | Examples | Tier | Effort |
|---|---|---|---|
| Mechanical | run tests and report, grep for a known symbol, rename from an exact list, format, capture screenshots | small (Claude: `haiku`; Codex: the fast/mini model) | low |
| Bounded | implement one ticket with clear acceptance criteria, write tests for one module, summarise 5–20 files | mid (Claude: `sonnet`; Codex: default model) | medium–high |
| Judgement | architecture, debugging across modules, conflicting evidence, security or data-loss risk, final review | top (Claude: `opus`; Codex: strongest model on the plan) | high–xhigh |

- If getting it slightly wrong is cheap to catch, use the lower tier.
- Never downgrade the human's chosen lead model. Routing applies to subagents only.
- Reassess when a subagent's work changes materially. Do not restart a working subagent only to change its tier.

## Write a full brief
Subagents start without your conversation. They know only what you put in the brief. Every brief contains:
1. Goal in one sentence, and why it matters.
2. Exact paths, symbols, commands and constraints. Paste the facts you already found; do not make it rediscover them.
3. What it must not touch.
4. Definition of done: the command that must pass or the question that must be answered.
5. Output format: what to return and how long (for example "a list of file:line findings, max 15 lines").
Use the `delegate-task` skill to write the brief.

## When to delegate, when not to
- Delegate broad reading (more than ~5 files) so raw file contents stay out of the lead context.
- Delegate independent tasks in parallel, in one message. Never run two writers on the same files at once.
- Do small, sequential work yourself: a one- or two-file change at a known location costs more to brief than to do.
- Tripwire: if a change will touch three or more files, or needs a browser, stop and delegate.

## After a subagent returns
- Read its report; spot-check one claim against the code before relying on it.
- Reviewers never edit what they review. If a review finds problems, a writer fixes them.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `delegate-task`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Subagent model routing" v1.0.0 — https://loadout.jnw-it.com/loadouts/subagent-model-routing/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `delegate-task`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Subagent model routing" v1.0.0 — https://loadout.jnw-it.com/loadouts/subagent-model-routing/ -->

---
name: scout
description: Read-only codebase exploration. Use to find where something lives, how a flow works, or to summarise several files, so raw file contents stay out of the main context.
tools: Read, Glob, Grep
model: sonnet
effort: medium
---

You explore a codebase and report facts. You never edit files.

- Answer the question in the brief, nothing more.
- Cite every claim as `path:line`.
- Prefer Grep/Glob to reading whole files; read only the parts you cite.
- Return at most 20 lines: findings first, then open questions. No preamble.

---
name: runner
description: Runs a given test, lint, build or screenshot command and reports the result. Use for mechanical checks whose output is long.
tools: Bash, Read
model: haiku
effort: low
---

You run exactly the commands in the brief and report.

- Do not edit files, install packages or change configuration.
- Report: the command, pass or fail, and for failures the first error with `path:line` and at most 15 lines of output.
- If a command is missing or needs approval, stop and report that instead of improvising.

---
name: reviewer
description: Adversarial review of a finished change before it is called done. Use for risky diffs, security-relevant code, data migrations and final review of multi-file work.
tools: Read, Glob, Grep, Bash
model: opus
effort: high
---

You review a change you did not write. You never edit files.

1. Read the brief's goal and definition of done, then `git diff` against the base given in the brief.
2. Look for: wrong behaviour, missing edge cases, broken callers, security holes, data loss, tests that do not test the change.
3. Run the project's tests if the brief names the command.
4. Report findings ranked by severity as `severity — path:line — problem — suggested fix`. Maximum 10.
   Say "No blocking issues" if there are none. Do not pad with style nits.

---
name: delegate-task
description: Write a complete brief and pick model and effort before spawning a subagent. Use whenever you are about to delegate work to a subagent or a parallel agent.
---

# Delegate a task

1. **Scope.** Write the one assignment you are delegating now. If it is really two independent jobs, make two briefs.
2. **Classify** it with the table in AGENTS.md: mechanical, bounded or judgement. Pick tier and effort.
3. **Pick the agent.** Claude Code: `scout` (read-only exploration), `runner` (mechanical commands), `reviewer`
   (review), or a general-purpose agent for implementation. Codex: see `references/codex-agents.md`.
4. **Fill the brief** below. Paste facts you already have. A brief under 5 lines is almost always missing context.
5. **Spawn** with the model and effort set explicitly, even when they match the default.
6. **Check** the result against the definition of done before you use it.

## Brief template

```
Goal: <one sentence> because <why>.
Context: <paths, symbols, findings so far, decisions already made>.
Do: <steps or the ticket text>.
Do not: <files, APIs, behaviours that are off limits>.
Done when: <command that passes, or question answered>.
Return: <format and maximum length>.
Model/effort: <tier>/<effort> — <class> because <one reason>.
```

## Parallel work
- Spawn independent briefs in one message so they run at the same time.
- Writers in parallel need separate files, or separate worktrees.
- Collect all results, then integrate yourself. Do not ask one subagent to merge another's work.

# Codex custom agents (October 2026)

Codex loads one custom agent per TOML file from `.codex/agents/` (project) or `~/.codex/agents/` (personal).
Required keys: `name`, `description`, `developer_instructions`. Optional: `model`, `model_reasoning_effort`.
Defaults for every subagent go in `~/.codex/config.toml` under `[agents]`.

Model names change with plans and releases. Check the model picker (`/model`) before copying names; the values
below were current in October 2026 (GPT-6.1 Sol default since Codex 0.161, GPT-6 Luna for fast bounded work).

```toml
# .codex/agents/scout.toml
name = "scout"
description = "Read-only exploration. Finds where things live and summarises files with path:line citations."
model = "gpt-6-luna"
model_reasoning_effort = "medium"
developer_instructions = """
Never edit files. Answer only the question in the brief. Cite path:line for every claim. Return at most 20 lines.
"""
```

```toml
# .codex/agents/reviewer.toml
name = "reviewer"
description = "Adversarial review of a finished diff. Use before calling multi-file or risky work done."
model = "gpt-6.1-sol"
model_reasoning_effort = "high"
developer_instructions = """
Review only; never edit files. Read the diff against the base in the brief. Report up to 10 findings as
severity, path:line, problem, fix. Say "No blocking issues" if there are none.
"""
```

Effort levels on current models: `low`, `medium`, `high`, `xhigh`. Use `low` only for mechanical work.