orchestration

name

orchestration

description

Routing doctrine for the architect-as-orchestrator pattern — how a session running the smartest model delegates implementation to cheaper lanes to minimize cost. USE WHEN delegating implementation work, choosing between the grok/opus/sonnet implementation lanes, picking an Opus reasoning-effort tier, handling a grok rate-limit fallback, writing a spec for a subagent, deciding whether to consult fable-advisor, managing session cost or token spend, or running any multi-task build where the session is the architect.

Orchestration — the architect's routing doctrine

The session is the architect: it owns requirements, architecture, decomposition, specs, routing, and verification. It should almost never type implementation code. Every implementation task gets routed to the cheapest lane that is adequate for it — escalation is deliberate, per task, never a fixed binding.

Cost discipline — the prime directive

The session model is the most expensive lane in the system, on both input and output tokens. The whole economic case for this pattern is keeping its token volume low: spend the architect on judgment, spend the cheap lanes on volume. Three rules follow.

Emit judgment, not volume. The architect's output is decomposition, specs, routing decisions, verdicts on diffs, and short reports. It does not type implementation code, test bodies, boilerplate, or config files. A code block longer than an interface signature or a few illustrative lines is a spec that hasn't been delegated yet — stop and delegate it. Fixing a lane's bug by hand is the same failure in disguise: send a corrected spec back to the cheap lane instead.

Keep the context lean. Everything in the architect's context is re-read at architect prices on every turn. Delegate broad exploration, codebase searches, and log-grepping to a cheap read-only agent and keep only the conclusions; read files yourself only when the decision genuinely depends on the exact code. Don't paste long files, full diffs, or verbose command output into the conversation when a path reference or an excerpt will do.

Reason once, then hand off. Do the hard thinking — the architecture, the interface design, the debugging hypothesis — in one pass, capture it in the spec, and let the cheap lane carry it from there. Re-deriving decisions across turns burns the premium twice.

What stays with the architect regardless of cost: decomposition, interface design, hypothesis selection when debugging, spec writing, lane routing, and judging verification evidence. Those tokens are what the premium is for — everything else is a candidate for delegation.

The lanes

Lane	Producer	Invoke	Route here when
Routine	Grok 4.5	grok-implementer agent	The spec fully determines the outcome: boilerplate, wiring, CRUD, mechanical edits, straightforward features. Default lane — attempt first on every implementation delegation unless the effort table below routes the task to Opus. Requires the Grok CLI.
Fallback	Claude Sonnet	sonnet-implementer agent	ONLY when grok-implementer has just returned STATUS: rate_limited for the current delegation. Never routed to by preference — see "Grok rate-limit fallback" below.
Deep reasoning	Claude Opus (effort per task)	opus-implementer-high / -medium / -low agents	The outcome depends on reasoning the spec can't fully pin down, or mistakes are costly. Pick the effort tier from the decision table below.
Judgment	Fable 5	fable-advisor agent	Not an implementation lane. See "Commitment boundaries" below.

Deciding rule: how much does the outcome depend on judgment the spec can't capture? Little → the default grok lane; you will verify anyway. A lot, and mistakes are costly → the Opus lane at the right effort tier, race grok against opus-implementer-high on the same spec and pick the stronger diff, or keep that piece with the architect.

Vendor honesty: only the grok lane is a non-Anthropic family. The Opus and Sonnet lanes are the architect's own family — they still get fresh-context review from the architect, but not cross-vendor review. Racing grok against opus-implementer-high buys two independent implementations from two families; it is not the three-vendor race the codex era offered.

Opus effort — the decision table

The Opus lane selects reasoning effort per task. The architect MUST pick from this table and state, in one line, which effort it chose and why before delegating — e.g. Effort: HIGH — schema migration, lossy if wrong.

Effort	Invoke	Route here when
HIGH	opus-implementer-high	Correctness-critical: concurrency, security, data migrations, algorithms, or anything costly to revert.
MEDIUM	opus-implementer-medium	Non-trivial logic that isn't safety-critical: standard feature code, moderate refactors.
LOW	opus-implementer-low	Mechanical or boilerplate changes where the spec fully determines the output. (Prefer the grok lane for this class unless you specifically want a Claude producer.)

Why three agents instead of one parameter: Claude Code's per-invocation agent call exposes a model override but no reasoning-effort parameter, so effort ships as distinct agent variants. Each variant carries an effort: frontmatter key (unverified against every Claude Code version — see the TODO in each file) AND enforces its tier through in-body instructions, so the tiers behave differently even where the frontmatter key is ignored.

Grok rate-limit fallback — per delegation, no daemons

At each implementation delegation routed to the Routine lane, attempt grok-implementer FIRST. Then:

• STATUS: rate_limited (the lane's specific quota signal — non-zero CLI exit AND a rate-limit/quota error signature) → transparently re-route the SAME spec, verbatim, to sonnet-implementer, and note in your report to the user that Grok was rate-limited and this task ran on the Sonnet fallback. Never absorb the substitution silently.
• Recovery is per-delegation, not a timer. On the NEXT implementation task, attempt grok first again. There is no polling, no auto-resume daemon, no scheduled retry — Claude Code is stateless between turns, so "try grok again on the next delegation" is the entire recovery mechanism, and it is documented as such.
• Any non-rate-limit failure fails loudly. unavailable (CLI missing, not authenticated), auth errors, or a genuine task failure (bad spec, failing verification) must NOT trigger the Sonnet fallback. Surface the lane's REASON verbatim to the user and stop routing that class of work until the cause is fixed or the user explicitly chooses a different lane. A grok lane that quietly becomes a Claude lane defeats the routing.
• timeout → report it explicitly; re-routing to another lane is allowed only with an explicit note in your report, never silently.

The spec contract

Implementers share none of your conversation context. Every delegation prompt carries all five parts:

1. Objective — what to build or change, one paragraph
2. Files — exact paths to create or modify
3. Interfaces — signatures, types, or API shapes the code must match
4. Constraints — project conventions, things not to touch
5. Verification — the command(s) that prove it works

A spec you can't finish writing is a signal the decision isn't made yet — that's architect work, not a reason to hand the ambiguity to a cheaper model.

Parallelism

Independent specs (no shared files, no ordering dependency) launch as parallel agents in a single message. Sequential chains and single-file surgery stay serial. For high-stakes work, a pick-the-stronger-diff race — grok-implementer and opus-implementer-high on the same spec, architect judges — buys a second independent implementation from a different model family for one extra lane's cost.

Commitment boundaries

Consult fable-advisor (read-only, verdict in under 300 words) at the moments that decide whether the next hour is wasted:

• Before committing to an architecture, data migration, API shape, or refactor strategy
• Whenever the same problem has resisted two distinct attempts
• Once before declaring a multi-step deliverable done

Pass it the decision, the constraints, and the options considered. Act on the verdict or surface the disagreement — never silently ignore it. (If the session itself already runs on Fable, the advisor still earns its keep as a context-clean skeptic reading the actual code.)

Verification

Reports are claims, not evidence. Before accepting any lane's work: read the diff, and re-run the verification command (or spot-check its quoted output against the working tree). "Should work", "tests should pass", or a report with no command output means the task is not done. A lane that reports a spec gap gets a corrected spec, not a "use your judgment".