Claude Code Orchestrator
Architecture — cluster diagram
Dispatcher
main thread · pure dispatcher, human-facing · never grinds, never blocks
orchestrator-o4.8-h
Opus · high
responsibility
Triage, decompose, dispatch, steer, integrate. Inline work limited to one-touch actions.
tools
all tools
turn loop
event→ integrate→ advance graph→ yield
mid-flight steering
orthogonal → dispatch alongside refines → SendMessage delta invalidates → TaskStop + redispatch replans → fork
fork
background Opus
responsibility
Background clone of the dispatcher with full context — deep reasoning that outgrows a fast turn (plan synthesis, risky-diff judgment, root-cause analysis).
tools
all tools (inherited from dispatcher)
routes
Routes here: deep reasoning beyond a fast turn — delivers conclusions, not diffs.
↓ Agent: dispatch (parallel, disjoint files)↑ completion notifications
spec carries: files · pattern · acceptance criteria — reply carries: summary / verdict
enforce-agent-tiering.sh Agent-call edge — denies untyped/general-purpose/claude dispatch, opus/default/inherit model overrides, non-allowlisted Plan (fork exempt)
Workers
background fleet · dispatched in parallel on disjoint files
Custom — our role-coded workers
executor-s5-m
Sonnet 5 · medium
responsibility
Applying edits across files, running tests & fixing straightforward failures.
tools
ReadEditWriteBashGrepGlobWebFetchNotebookEditTodoWrite
routes
Routes here: implementation from an approved spec/plan.
chores-h4.5-l
Haiku 4.5 · low
responsibility
Renames, formatting sweeps, verbatim-text boilerplate.
tools
ReadEditWriteBashGrepGlob
routes
Routes here: mechanical, fully-specified edits.
researcher-s5-m
Sonnet 5 · medium
responsibility
Libraries, vendor docs, prior art, trade-offs; source-cited briefs, read-only, not codebase.
tools
ReadWebFetchWebSearch
routes
Routes here: web research.
Default — harness built-in agent types
Explore
Haiku · built-in
responsibility
Never done inline, even when it feels quick.
tools
read-only (all tools except Edit/Write/Agent)
routes
Routes here: any codebase investigation.
claude-code-guide
Haiku · built-in
responsibility
Verify, don't recall.
tools
BashReadWebFetchWebSearch
routes
Routes here: Claude Code / Agent SDK / Claude API questions.
general-purpose
why disabled
Untyped volume work at orchestrator (opus) cost.
claude
why disabled
Catch-all, every tool, no tier.
Plan (bare/default/inherit)
why disabled
Runs opus without your context; fork is strictly better.
Heavy multi-source research escalates to the deep-research skill.
Review
first-pass gate before delivery
reviewer-s5-h
Sonnet 5 · high
responsibility
Spec, correctness, tests. No edit tools; Bash is read-only/tests only. Escalates risky/design-sensitive diffs to the opus fork.
tools
ReadBashGrepGlob
routes
Routes here: first-pass review of worker diffs.
tool-call rail — every worker & reviewer's Bash / Edit|Write passes through here
enforce-git-ownership.sh Bash gate — denies push, revert, cherry-pick, am, gh pr create|merge; allows a commit only to conclude an in-progress merge/rebase/cherry-pick/revert
enforce-conflict-dispatch.sh Edit|Write gate — denies main-thread/orchestrator-* edits on conflict-marker files, workers pass
JOB BOARD — plans/<slug>.md: spec + workstream table, updated every tick. Fleet reconstructible after crash or /clear.
ONE-TOUCH LIMIT — inline only when a worker roundtrip costs more than the act AND the full cost is knowable before starting; merge/rebase and any conflict-capable git op are never one-touch. Escalation-abort: an inline action that turns multi-step or slow gets stopped and the remainder dispatched — sunk cost never finishes inline.
The full cycle — every project, sized to fit
A loop, not a line — every phase feeds the next, and verify can hand work backward instead of forward.
↩ verify → build — implementation bug; the finding is the spec
↩ verify → plan — spec gap or new requirement (brainstorm with you first if scope changes)
↩ verify → research — missing knowledge
Small tasks collapse phases (a bugfix = build+verify), but verify is never skipped on code, and research is never skipped when the plan rests on external facts. Reopened work gets a new workstream entry — iterations stay visible, never overwritten.
pure-dispatcher cluster