orchestrator-agents

Requirements: Claude Code CLI + git, no Docker/GPU/API keys of your own needed — full walkthrough in 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

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

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

Restart Claude Code (or start a new session) so it picks up the new subagents.
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.