--- name: multi-orchestrator description: > Use when executing an implementation plan (waves/tasks) at lowest cost without compromising the quality floor — invoked by /multi-orchestrator, by bs-multi after planning, or when the user asks to "build this the cheap-but-safe way", "orchestrate with risk-routed review", "sonnet orchestrator + codex only on risky diffs". The cost-optimal merge of cursor-orchestrator and north-orchestrator: sonnet coordinates, cursor/composer implements, a deterministic router sends only money/auth/cross-file diffs to codex, advisor gates composed-topology. --- # Multi Orchestrator audience: AI coding agents first. Imperative, BLUF. Execute a plan wave-by-wave at the **lowest cost that preserves the quality floor**. Cheap everywhere; **codex only where a miss is catastrophic** (money/auth/cross-file correctness). Anchored in measured results, not theory. **The objective is not "minimize cost" — it is minimize the Anthropic pool (sonnet/advisor) while pushing volume onto free (north), separate-quota (cursor), and Codex (OpenAI) budgets, with the quality floor fixed.** Four budgets, not one ladder. ## Multi-wave gate — check FIRST before any inline work Handed a PLAN_SLUG or JSONL? Classify shape before executing anything: - **Multi-wave/multi-phase** (>1 wave/phase OR any wave has parallel tasks) → **STOP. Invoke `Skill("run-plan")` with the slug.** Do NOT proceed inline. - **Single-wave single-phase** → proceed below. Multi-wave inline = context saturation across sessions → **$5.13/task** (measured). run-plan Workflow = **$1.985/task** + resumable + parallel. Break-even = first task. Inline orchestrators are single-wave engines only. --- ## Seat map | seat | who | budget | why this tier | |------|-----|--------|---------------| | orchestrator (main loop) | **sonnet** | Anthropic (cheap) | Coordinating waves, dispatching, reading STATUS lines, running Gate 0 is MECHANICAL — not where quality lives. opus-as-orchestrator was the single biggest cost driver. | | implementer (critical path) | **cursor/composer via `ca.sh`** | Cursor quota | Reliable (delivered where north failed 2/2); flat-sub; tokens land OFF the orchestrator's cached context. | | implementer (opt-in $0 only) | **north** (`cohere/north-mini-code:free`) | free | ONLY on its proven-strong classes (mechanical refactor, small described-add) at SHORT paths. NEVER on the critical path, NEVER the money play — it is a ~4% line needing a supervisor that costs more than it saves. | | risk router | **`risk-router.sh`** (deterministic) | $0 | The one decision that gates codex spend — kept deterministic so the cheap orchestrator cannot mis-route it. | | reviewer (HIGH risk) | **codex** (`Skill("ask-codex")`, `gpt-5.5/low`) (+`security-guard` on trust boundaries) | Codex (OpenAI) quota | The quality floor. composer surfaces P0s only 1/3 → unsafe as sole gate here. | | reviewer (LOW risk) | **composer x1** | Cursor quota | Gate 0 already caught the clerical layer; composer is 3/3 on surface/spec. codex never spent here. | | process gate | **`advisor()`** | Anthropic (cheap — conversation only) | Composed-topology + spec-divergence judgment sonnet cannot own. | **opus is NEVER the main loop and NEVER the review gate.** HIGH-risk review is a dispatched `Skill("ask-codex")` call (`gpt-5.5/low`) on Codex's own quota, plus `advisor()` for process gate. Run this orchestration with the session on sonnet (`/model sonnet`); if the session is on opus, the cost model is defeated — switch first. ## IRON LAW — active every turn, survives compaction **The orchestrator never writes, edits, or verifies implementation code. north/composer write the body; codex reviews; advisor gates.** Canonical statement + the sole LOC≤LOP carve-out live in `cursor-orchestrator` — re-read after any compaction. **Plans are contract-level (see `plan`):** a task tagged `apply inline (LOC≤LOP), no dispatch` → the orchestrator applies it directly; every other task gives a Contract, not a body → dispatch the implementer. A plan handing a full body for a dispatched task is a planning defect — dispatch the contract, do not transcribe. The orchestrator likewise NEVER authors a body the plan omitted: expanding a contract bullet into source while building the dispatch prompt is the same defect. Pass the contract slice + file-path pointers; the implementer writes the body. See `cursor-orchestrator` › Implementer prompt template. ## The gate ladder — run in order, risk-routed, single reviewer, NEVER stacked Per wave, after the implementer produces a diff: 1. **Gate 0 — deterministic, FIRST, $0.** Run the repo's own checks against the diff: `tsc`/typecheck, lint, **build** (not just typecheck — `typecheck ≠ bundle`), and the package's tests. Catches the entire clerical failure class for free. RED → composer fixer with exact failure output → re-run Gate 0 → loop until green. Never pay an LLM to find what the build finds. 2. **Risk route — deterministic.** After Gate 0 green, classify the wave diff: ```bash ~/.claude/skills/multi-orchestrator/risk-router.sh .. ``` `RISK=HIGH` (sink in changed lines incl. REMOVED, or sensitive reverse-dep) → step 3a. `RISK=LOW` → step 3b. `RISK=ERROR` (exit 2) → treat as HIGH; never read an erroring router as LOW. 3. **Review — ONE reviewer, chosen by risk. NEVER run composer-then-codex** (codex re-reads the whole file regardless — a composer pre-pass is wasted Cursor quota). - **3a. HIGH → codex review, single pass.** Invoke `Skill("ask-codex")` (`gpt-5.5/low`) over the bounded wave diff + constraint files. If the router printed `TRUST_BOUNDARY: yes`, ALSO run the `security-guard` agent. Findings → composer fixer → re-run Gate 0 → re-invoke codex. Loop until codex CLEAN. No iteration cap. - **3b. LOW → composer x1 first-pass only.** Dispatch composer in AUDIT mode once. Gate 0 already caught clerical; composer is 3/3 on surface/spec. codex is NEVER spent on a LOW diff. 4. **LOC≤LOP inline fixes.** Whoever HOLDS the code fixes a sub-threshold finding inline instead of emitting a report-only finding (the codex reviewer holds the file → it fixes ≤LOP findings + commits, then `advisor()`-checks in-session). See `cursor-orchestrator`. 5. **Process gate — `advisor()`** between waves and before merge. Owns composed-topology and spec-wrong-vs-code-wrong judgment — exactly the class single-unit gates measurably miss. **Never skip it: it is the only high-reasoning eyes on integration/big-picture under a sonnet orchestrator.** advisor flags → fixer loop → advisor again → until clean. ## composer runs x1 — NOT k≥3 (quota discipline) k≥3 rolls lift composer's latent recall (measured: 3/3 on the clawback-uuid shape) but **deplete Cursor limits fast**. Run composer **x1** and take the residual-miss hit. This is bounded by design: HIGH-risk diffs ALWAYS go to codex (step 3a), so x1-composer's lower recall only ever lands on LOW-risk diffs — where a miss is non-catastrophic BY the router's definition. Spend the rolls only where they are free (deterministic Gate 0) or irreplaceable (codex on HIGH). ## codex-authored checklist → composer executes x1 (amortize recurring HIGH shapes) Where codex repeatedly reviews the SAME high-risk shape, have codex author a sharp MUST-verify checklist ONCE, then let composer execute it x1 on later instances of that shape — replaces "codex every time" with "codex once + composer runs it". **Only AFTER codex has identified the suspects** — for a first-of-kind HIGH diff no checklist exists, so codex must run. **Rot guard:** a checklist is valid only for a STABLE shape. When that shape's signature/contract changes, the checklist is stale and composer will pass a diff the old list no longer covers → **re-run codex to re-author when the high-risk shape's contract changes.** Never trust a checklist across a contract change. ## Cache discipline — the dominant cost line under a sonnet loop - **One short scoped session per task.** Don't let a single session accumulate days of context at cache-resident rates. - **Dispatch the heavy build to cursor** so verbose build/test output never re-caches in the orchestrator's context. Keep orchestrator context to **plan + diff + findings**, never whole codebases. - **Keep north bounded** (`timeout -k 5 360`). A long north dispatch between orchestrator turns can evict the 5-min prompt cache → the next sonnet turn pays a full-context cache-miss. "Free" north can bill the Anthropic pool via eviction. ## Implementer routing — net-turn-cost, not raw price - **mechanical refactor / small described-add** → north opt-in (free, first-pass-clean) at a short path, bounded. On non-completion (rc=124/429) retry once, else hand to composer. - **structural / multi-import / anything north is measured-weak on** → composer DIRECT, skip north. One composer dispatch beats free-north-plus-fix-loop on TURNS and wall-clock. - **composer billing 403** (`spending-limit`/Grok) → the `ca.sh` composer-2.5/grok channel is exhausted; switch to `cursor-agent --model gpt-5.2-codex` (Cursor quota), do NOT re-dispatch verbatim. Distinguish billing-403 (switch model) from a real BLOCKED (rewrite prompt) by reading the error body. ## Quality floor — does NOT move regardless of cost - Gate 0 = **real build**, not just `tsc` (`typecheck ≠ bundle`). - **≥1 bounded codex pass** (+`security-guard` on trust boundaries) on EVERY HIGH-risk diff before merge. - **`advisor()` on every composed-topology / integration claim** — single-unit gates have demonstrably missed these. - The **contract/seam stays orchestrator-authored** in planning (`plan`) — the irreducible judgment not delegated down. ## The binding correctness dependency — the risk router must be COMPLETE The whole model rests on the router never under-flagging a money/auth sink. A false-positive costs one extra codex pass (cheap); a **false-negative ships a bug**. The router is conservative by construction (greps added AND removed lines; flags sensitive reverse-deps; errors rather than passes on bad input). **Audit and extend `risk-router.sh`'s sink lexicon for the project before first use; never trim it silently.** When in doubt, it must err HIGH. ## Shared mechanics — point, do NOT re-inline - **`cursor-orchestrator`**: `ca.sh` dispatch rig, foreground-only (bg = failure), return-size discipline, worktree setup, code-review-prompt.md, fixer-loop SHAPE, spec-is-source-of-truth + who-judges, dispatch timeouts/quota. Follow verbatim. - **`north-orchestrator`**: the north dispatch rig (`[[openrouter-via-claude-code-harness]]`) and north operational failure modes — used only for the opt-in north seat. - **`plan`**: contract-level task format the diffs are gated against. ## Common mistakes — stop immediately - Orchestrating on opus → switch to sonnet; codex enters only as review subagent + advisor. - Running composer-then-codex on a HIGH diff → codex re-reads regardless; the pre-pass is wasted quota. - Running codex on a LOW diff, or composer-x1 as the SOLE gate on a HIGH diff → both break the risk routing. - Skipping `advisor()` because sonnet "looked fine" → that is the only high-reasoning eyes on composed-topology. - Running composer k≥3 → depletes Cursor quota; x1 + accept the bounded low-risk hit. - Trusting a stale codex checklist across a contract change → re-author with codex. - north on the critical path, or as the money play → opt-in $0 bonus only. - Reading `RISK=ERROR` as LOW, or trimming the sink lexicon → false-negative ships a bug. - Gate 0 on `tsc` only, no build → typecheck ≠ bundle.