# orchestrator-agents

**Requirements:** Claude Code CLI + git, no Docker/GPU/API keys of your own needed — full walkthrough in [SETUP.md](SETUP.md)

Three Claude Code subagent definitions that implement a simple pattern: **one expensive model plans and verifies, cheap models execute.**

## Why this matters

Running every step of a task through your most capable (and most expensive) model wastes money and time on work that doesn't need judgment — renaming a variable across files, looking up a value, running a command and reporting the result. Those are mechanical. Planning what needs to happen, deciding how to split it up, and checking that the result is actually correct — that's where you want your strongest model spending its budget.

This pattern splits the work across three roles:

- **`orchestrator`** — the planner. Scouts the codebase just enough to build a concrete work-list, decomposes the job into fully-specified subtasks, fans them out to `worker` subagents in parallel, and — critically — re-verifies every result from raw data (reads the file, runs the command, diffs the output) instead of trusting the worker's self-reported summary. Runs on a stronger model at high effort, because planning and verification are exactly where that reasoning budget pays off.
- **`worker`** — the executor. Takes a task that has already been fully decided (exact file, exact change, exact expected result) and does it, reporting back in 1-3 lines. If a task isn't fully specified, it stops and says what's missing rather than guessing. Runs on a cheaper model at low effort — it doesn't need to be smart, it needs to be fast and correct on well-defined work.
- **`advisor`** — a read-only second opinion. Called when the executor hits a genuine judgment call — an architecture fork, "is this the right approach" — and wants a stronger model to weigh in without taking over. It reads what it needs, gives a direct recommendation with the reasons that actually drive it, and hands control back. It never edits or runs anything.

The rule that makes this safe: **never trust an executor's prose.** A worker (or any cheaper model) can report success when it isn't — always re-derive the result from the raw file or raw command output before treating a subtask as done. The orchestrator's job description encodes this explicitly as a verification step, not an afterthought.

## What's in this repo

```
agents/
  orchestrator.md   # planner + fan-out + verification
  worker.md          # fully-specified execution
  advisor.md         # read-only second opinion
```

Each file is a Claude Code subagent definition: YAML frontmatter (`name`, `description`, `tools`, `model`, `effort`) followed by the agent's operating instructions.

## Quickstart

1. Copy the three `.md` files into your Claude Code global agents directory:

```bash
cp agents/*.md ~/.claude/agents/
```

2. Restart Claude Code (or start a new session) so it picks up the new subagents.

3. Invoke them by name once you're in a session, e.g.:
   - `@worker` — hand it a single, fully-specified edit or lookup.
   - `@orchestrator` — hand it a job that splits into independent pieces (a sweep across many files, a batch of similar edits, a broad audit).
   - `@advisor` — ask it for a second opinion on a plan or a decision fork. It won't touch files.

## Make it your own

- **Swap the models.** The frontmatter sets `model: sonnet` for the worker and `model: fable` (Anthropic's largest model tier at time of writing) for orchestrator/advisor. Point these at whatever your cheap/expensive tiers are — the pattern is model-agnostic.
- **Adjust `tools:`.** Each agent's frontmatter lists exactly the tools it's allowed to use. `worker` has edit access; `advisor` is intentionally read-only (`Read, Grep, Glob`) so it can never quietly make a change. Keep that boundary if you adopt the pattern — it's what makes "advisor never takes over the work" actually true instead of just asserted.
- **Add more executor tiers.** Nothing about this pattern caps you at three agents. If you have work that needs deep domain judgment but isn't worth the top model's full attention, add a mid-tier specialist agent alongside these.
- **Tighten or loosen the verification rule.** The orchestrator's "Verify" step (re-read the file, re-run the command, diff — don't trust the report) is the load-bearing part of this pattern. If you relax it, you lose the reason the split is trustworthy in the first place.

## What this is not

This is not a framework, library, or runtime — it's three prompt files. There's no code to install beyond copying them into place. The value is in the division of labor they encode, not in any tooling.