Fable Orchestrator
Overview
The orchestrator's context is the scarcest resource. You plan, route, verify,
and report — agents do the work. Every token spent reading files or writing
code in the main loop is a token that should have been delegated.
When not to orchestrate
A wave costs a spec, a spawn, two review rounds, and a merge. Below that bar,
orchestrating is slower and more expensive than doing the work.
| Situation |
Do instead |
| Change fits in files you can already name |
Make the edit. The wave costs more than the work |
| You don't know what's broken yet |
Diagnose first — one Explore agent, or read it yourself. A spec needs a diagnosis |
| Each step needs the previous step's output |
One agent, or inline. Parallelism was the whole payoff |
| Under ~30 minutes of work |
Overhead exceeds the task |
Prerequisites
codex CLI, installed and authenticated on its own OpenAI quota, and the
aetheris plugin for aetheris:second-opinion. Both the mandatory review round
(loop step 5) and the Codex worker role depend on them — without Codex you have
same-model review only, which is the weaker half.
Role routing
| Who |
What |
Not |
| You — Fable / Mythos / Opus 5 |
Decompose, spec, spawn, verify claims, route fixes, git, report |
Reading big files, writing feature code, long investigations |
Opus (model: "opus") |
Complex builds, analysis, debugging, second-round same-model review |
Mechanical work a spec fully determines |
Sonnet (model: "sonnet") |
Well-specified implementation, tests, cleanups, doc merges. Sonnet 5 lands near Opus on coding — route volume here |
Open-ended design or debugging |
Codex reviewer (aetheris:second-opinion) |
Primary review of every nontrivial diff, and plan/spec docs before build (--plan <file>) |
Applying its own fixes — advisory only |
Codex worker (codex exec) |
Tests against Claude-authored code, tie-break patches on disputed findings |
Bulk implementation — separate quota, rate-limits under load |
The spawn contract
Every agent prompt carries the same contract: ownership boundary, no sub-agents,
no git, scope discipline, and a capped FINAL REPORT shape. Copy it from
spawn-contract.md in this directory and fill in the brackets.
Keeping agents off each other's files
| Mechanism |
Use when |
Cost |
| File-ownership matrix in the spec |
Work partitions cleanly by path — the common case |
Free, but documentation-enforced: one rogue sub-agent voids it |
isolation: "worktree" on the spawn |
Writes overlap, or the partition isn't clean |
~200–500ms + disk per agent; you merge the trees back |
The loop
- Spec-as-contract first for multi-agent waves: goals, ground truth
(file:line pointers so agents don't rediscover), acceptance criteria, and
the ownership matrix.
- Parallel agents building against each other get an interface contract
frozen in the spec (exact signature + return keys); each builds blind to it.
- Spawn in one message, in background.
- Verify claims independently before acting on any report: run the suite,
spot-check the DB/output yourself. An agent's own green is not your green —
this is a trust boundary, and it survives however good the agents get.
- Codex reviews first (
aetheris:second-opinion) — different model,
different blind spots, and the load-bearing round now that you and the
agents are the same model. Then an adversarial same-model pass over the
post-fix state, where repo context earns its keep. Budget for one round
only? Run Codex.
- Route findings back to the owning agent via SendMessage (warm context
beats fresh spawns); require fail-before/pass-after evidence per fix.
- You do git: scoped commits (never
-A), PR with verification evidence,
user merges.
Codex as a worker
SCRATCH=$(mktemp -d)
codex exec --sandbox workspace-write --skip-git-repo-check -C <owned-dir> \
-o "$SCRATCH/report.md" "<task prompt>" < /dev/null > "$SCRATCH/run.log" 2>&1
# report.md is its final message; run.log is the event stream, for when it
# dies and you need to see how far it got.
# `< /dev/null` is load-bearing: codex appends piped stdin to the prompt and
# blocks waiting for EOF. Without it this hangs indefinitely under any tool
# runner that holds stdin open.
Its sandbox writes only under -C — point it at the owned directory, never
repo root. It has no mailbox, so -o is the mailbox: read report.md. Best
yield is tests for code a Claude agent wrote, and dueling patches when reviews
disagree — have Codex implement its finding, compare against the Claude
version, pick on evidence.
Failure playbook
| Symptom |
Move |
| Agent idles without reporting |
SendMessage: "send your final report now" |
| Agent dies (rate limit/crash) |
Check tree state, SendMessage resume with "re-read your own diff" |
| Two agents need the same file |
Serialize, or transfer ownership explicitly when one finishes |
| Finding in unowned file |
Fix it yourself only if trivial; else assign ownership |
| Report names files you never assigned |
It spawned sub-agents — re-derive the diff yourself before trusting any of it |
Red flags
- Reading a 2,000-line file in the main loop → spawn an Explore/Opus agent
- About to code a feature inline → write the spec, spawn Sonnet/Opus
- Shipping on an agent's claim you didn't verify → run the check yourself
- Skipping Codex because the same-model pass was clean → backwards. Same-model
shares the author's blind spots; Codex is the round that counts
- You typed "verify your work" into a spawn prompt → delete it
1---2name: fable-orchestrator3description: Use when running on an expensive orchestrator model (Fable, Mythos, or Opus 5) and the task is substantive parallelizable multi-step work — building features, research sweeps, audits, incident fixes — where the user wants the agent team pattern ("spawn the team", "use opus/sonnet/codex", "orchestrate this", "keep my orchestrator context clean") or invokes /fable-orchestrator. Not for single-file changes or undiagnosed bugs.4---56# Fable Orchestrator78## Overview910The orchestrator's context is the scarcest resource. You plan, route, verify,11and report — agents do the work. Every token spent reading files or writing12code in the main loop is a token that should have been delegated.1314## When not to orchestrate1516A wave costs a spec, a spawn, two review rounds, and a merge. Below that bar,17orchestrating is slower and more expensive than doing the work.1819| Situation | Do instead |20|---|---|21| Change fits in files you can already name | Make the edit. The wave costs more than the work |22| You don't know what's broken yet | Diagnose first — one Explore agent, or read it yourself. A spec needs a diagnosis |23| Each step needs the previous step's output | One agent, or inline. Parallelism was the whole payoff |24| Under ~30 minutes of work | Overhead exceeds the task |2526## Prerequisites2728`codex` CLI, installed and authenticated on its own OpenAI quota, and the29`aetheris` plugin for `aetheris:second-opinion`. Both the mandatory review round30(loop step 5) and the Codex worker role depend on them — without Codex you have31same-model review only, which is the weaker half.3233## Role routing3435| Who | What | Not |36|---|---|---|37| **You** — Fable / Mythos / Opus 5 | Decompose, spec, spawn, verify claims, route fixes, git, report | Reading big files, writing feature code, long investigations |38| **Opus** (`model: "opus"`) | Complex builds, analysis, debugging, second-round same-model review | Mechanical work a spec fully determines |39| **Sonnet** (`model: "sonnet"`) | Well-specified implementation, tests, cleanups, doc merges. Sonnet 5 lands near Opus on coding — route volume here | Open-ended design or debugging |40| **Codex reviewer** (`aetheris:second-opinion`) | **Primary** review of every nontrivial diff, and plan/spec docs before build (`--plan <file>`) | Applying its own fixes — advisory only |41| **Codex worker** (`codex exec`) | Tests against Claude-authored code, tie-break patches on disputed findings | Bulk implementation — separate quota, rate-limits under load |4243## The spawn contract4445Every agent prompt carries the same contract: ownership boundary, no sub-agents,46no git, scope discipline, and a capped FINAL REPORT shape. Copy it from47`spawn-contract.md` in this directory and fill in the brackets.4849## Keeping agents off each other's files5051| Mechanism | Use when | Cost |52|---|---|---|53| File-ownership matrix in the spec | Work partitions cleanly by path — the common case | Free, but documentation-enforced: one rogue sub-agent voids it |54| `isolation: "worktree"` on the spawn | Writes overlap, or the partition isn't clean | ~200–500ms + disk per agent; you merge the trees back |5556## The loop57581. **Spec-as-contract first** for multi-agent waves: goals, ground truth59 (file:line pointers so agents don't rediscover), acceptance criteria, and60 the ownership matrix.612. Parallel agents building against each other get an **interface contract**62 frozen in the spec (exact signature + return keys); each builds blind to it.633. Spawn in one message, in background.644. **Verify claims independently** before acting on any report: run the suite,65 spot-check the DB/output yourself. An agent's own green is not your green —66 this is a trust boundary, and it survives however good the agents get.675. **Codex reviews first** (`aetheris:second-opinion`) — different model,68 different blind spots, and the load-bearing round now that you and the69 agents are the same model. Then an adversarial same-model pass over the70 post-fix state, where repo context earns its keep. Budget for one round71 only? Run Codex.726. Route findings back to the **owning** agent via SendMessage (warm context73 beats fresh spawns); require fail-before/pass-after evidence per fix.747. You do git: scoped commits (never `-A`), PR with verification evidence,75 user merges.7677## Codex as a worker7879```bash80SCRATCH=$(mktemp -d)81codex exec --sandbox workspace-write --skip-git-repo-check -C <owned-dir> \82 -o "$SCRATCH/report.md" "<task prompt>" < /dev/null > "$SCRATCH/run.log" 2>&183# report.md is its final message; run.log is the event stream, for when it84# dies and you need to see how far it got.85# `< /dev/null` is load-bearing: codex appends piped stdin to the prompt and86# blocks waiting for EOF. Without it this hangs indefinitely under any tool87# runner that holds stdin open.88```8990Its sandbox writes only under `-C` — point it at the owned directory, never91repo root. It has no mailbox, so `-o` is the mailbox: read `report.md`. Best92yield is tests for code a Claude agent wrote, and dueling patches when reviews93disagree — have Codex implement its finding, compare against the Claude94version, pick on evidence.9596## Failure playbook9798| Symptom | Move |99|---|---|100| Agent idles without reporting | SendMessage: "send your final report now" |101| Agent dies (rate limit/crash) | Check tree state, SendMessage resume with "re-read your own diff" |102| Two agents need the same file | Serialize, or transfer ownership explicitly when one finishes |103| Finding in unowned file | Fix it yourself only if trivial; else assign ownership |104| Report names files you never assigned | It spawned sub-agents — re-derive the diff yourself before trusting any of it |105106## Red flags107108- Reading a 2,000-line file in the main loop → spawn an Explore/Opus agent109- About to code a feature inline → write the spec, spawn Sonnet/Opus110- Shipping on an agent's claim you didn't verify → run the check yourself111- Skipping Codex because the same-model pass was clean → backwards. Same-model112 shares the author's blind spots; Codex is the round that counts113- You typed "verify your work" into a spawn prompt → delete it
Aetheris-Solutions-LLC