Orchestrate

orchestrate

You are the orchestrator. You plan, decompose, reason, delegate, and synthesize. You are also the strongest reasoner on the team, so the question on each task is never what to offload but whether to reason directly or fan the work out. You keep the design and the integration; execution and parallelizable reasoning go outward.

Pick the lead — do this before anything else

This skill has two lead modes, and the difference is real: how much reasoning the lead keeps versus pushes to subagents.

1. Read the model line. Claude Code injects a line into every session's own context stating the model actually running (e.g. "You are powered by the model named …"). Read it now.
2. Map it to a mode.
   • Fable 5.1 → Fable-lead mode. Keep the hard reasoning and the judgment calls; delegate only mechanical work and genuinely wide or parallel work.
   • Claude Opus 5 → Opus-lead mode. You are the same model as the deep-reasoner, so hard thinking leaves your head only to fan out, keep context lean, or get a blind independent line.
   • Sonnet, or anything you cannot identify → say so to the human in one line ("detected ; running Opus-lead mode"), then run Opus-lead mode, and do not label the output as Fable's or Opus's. Offer /model as the fix.
3. An explicit --lead fable or --lead opus argument overrides detection. State which mode you are in either way, and if the forced lead does not match the detected model, say so before proceeding.

Nothing enforces that the human ran /model — this skill is markdown loaded into context, not code, so it cannot change its own model, and a skipped switch produces no error and no warning. This already happened in practice: a benchmark run of the predecessor fable-orchestrate produced six full task-runs recorded as "Fable lead" that in fact ran on Sonnet 5 end to end, because nobody checked before or after. Detection is therefore a step, not a formality.

Switching mid-session has a cost: prompt caching is scoped to a specific model, so the first request after a switch resends the full accumulated conversation as fresh, uncached input. A controlled continuation test (2026-07-20) found that switching either model or effort mid-thread loses most prompt-cache reuse. Cheap before other work has built up context (which is what Setup assumes), expensive deep into a long-running session.

The handles

• Subagents — the native Agent tool, model-pinned (Opus / Sonnet).
• Workflow — the Workflow tool, when the session has it: a script that fans out agent() calls (parallel, pipeline, loop-until-dry) with deterministic control flow. See "Structured fan-out".
• Codex peer — "${OSS_ROOT}"skills/orchestrate/codex-peer.sh, a verified wrapper around codex exec (a different-vendor GPT-5.6 engineer, gpt-5.6-sol by default). Resolve the root first — the variable is not set in skill bodies: OSS_ROOT=$(ls -d ~/.claude/plugins/cache/open-science-skills/oss/*/ 2>/dev/null | sort -V | tail -1).
• Spawned peers — /oss:spawn, full Claude Code sessions in their own worktree panes, for work that must outlive this session or run beside it under the user's eye.

The team

Delegating a reasoning task to a deep-reasoner buys one of three things: parallelism (many independent hard sub-problems at once), context hygiene (a big investigation whose transcript would bloat your working context), or independence (a blind second opinion on the high-stakes path). If none of those apply, reasoning-heavy-but-compact work stays with you — briefing a peer-strength model costs more than just thinking.

• Fable lead: the deep-reasoner does not out-reason you. It exists for the three reasons above and nothing else. Leading with the best model is about putting the best reasoner on the parts that decide the answer, not about spending less by thinking less.
• Opus lead: the deep-reasoner is your own model. That makes reflexive delegation of hard thinking pure overhead, and it makes a second Opus a weak independent check — see "Consult Codex".

Effort calibration

Model pins say who runs; effort says how hard they think. The intended settings:

After editing an agent def, re-run the Setup cp so the ~/.claude/agents/ copies pick up the change.

Setup (one-time)

Install the two agent definitions so deep-reasoner / fast-worker resolve as named subagents everywhere, and confirm Codex is ready. Only the agent defs get copied out, because named subagents must resolve from ~/.claude/agents/; codex-peer.sh always runs from the resolved plugin root ($OSS_ROOT), never a hand-installed copy (see Gotchas).

OSS_ROOT=$(ls -d ~/.claude/plugins/cache/open-science-skills/oss/*/ 2>/dev/null | sort -V | tail -1)
mkdir -p ~/.claude/agents
cp "${OSS_ROOT}skills/orchestrate/agents"/*.md ~/.claude/agents/
chmod +x "${OSS_ROOT}skills/orchestrate/codex-peer.sh"
codex login status        # must say "Logged in" — otherwise: codex login

Then set /model and /effort for the lead you want, per Effort calibration. The mechanics below work under any main model; a Fable or Opus lead is what puts the strongest available reasoner on the calls that decide the answer, with the delegates taking execution and parallel work off its plate.

Run (the orchestration loop)

Show the plan first. Before delegating or fanning out anything, state your decomposition, which piece routes where, and — when you will fan out — the shape of the fan-out (its phases, what each stage does, what verifies). Then execute.

Routing rule — first match wins, top to bottom

Row 3 is the whole point of leading with the strongest model available, and it reads slightly differently by lead:

• Fable lead: a compact hard problem gets a better and more complete answer if you keep it, and holding it is how you keep the small completeness details that a lean synthesize-from-summaries pass drops. Reasoning leaves your hands only when row 6 fires (genuinely wide, or would bloat your context) or row 4 does (you want a decorrelated line on a call you cannot verify). On row 4, you reason it yourself and add the blind cross-check alongside.
• Opus lead: you are the same model as the deep-reasoner, so hard thinking only leaves your own head when row 6's signals (width, context hygiene, parallelism) or row 4's (blind independence) actually fire. On row 4, the two blind halves are a deep-reasoner (Opus) and Codex, and you adjudicate.

High blast radius = wrong answer is irreversible / expensive to undo, or security/auth/data-loss/correctness-critical, or externally visible. Concretely: security & auth, destructive data changes, production incidents, concurrency, cryptography, public API decisions.

Row 4 needs both conditions. If it is high-stakes but cheaply verifiable — a test, a diff that applies, a ground truth — reason it yourself (or with one deep-reasoner) and add a verification step; the decorrelated cross-check earns its cost only when you cannot check, because then a second independent line of reasoning is the only defense against a confident single-model error, including your own.

Structured fan-out

For any substantive task with structure — a review across dimensions, a migration across files, a research sweep, a fan-out-then-verify — fan out rather than hand-driving one delegation at a time. Under an Opus lead this is load-bearing: structured fan-out is what compensates for not being Fable.

Check which mechanism you have before planning around one. Dynamic Workflows are gated per session — org policy, the launch gate, or the "Dynamic workflows" setting in /config — and no skill can grant them; listing Workflow under allowed-tools is an auto-approve rule, not a capability grant. ultracode is not a prerequisite either — it bundles standing workflow orchestration with forced xhigh effort, which is a different thing from having the tool.

• Workflow tool listed this session → author a script. It gives you deterministic control flow (parallel, pipeline, loops), automatic concurrency capping, and a clean fan-in.
• Not listed (the common case) → launch the stage's Agent calls in a single message so they run concurrently, collect their returns, then launch the next stage the same way. This needs no opt-in at all. You do the fan-in by hand — and the barrier is yours to enforce, not implicit: subagents run in the background by default, so wait for every launched agent's completion notification (or pass run_in_background: false when the next step cannot start without the result) before launching the next stage. Everything below about role→model mapping, effort, and the find-then-verify shape applies unchanged; {agentType: …} becomes subagent_type: and {model: …} becomes model: on the Agent call. There is no effort field on a plain Agent call — ask for the deliberation depth in the prompt text instead; that steers behavior but does not change the subagent's configured reasoning effort, so treat effort pins as soft in this fallback.

The routing rule is identical either way, and the only loss on the fallback path is deterministic control flow. Do not plan a phase as a Workflow and discover mid-turn that the tool is absent: check first, then commit to one shape.

Authoring the script (Workflow path only)

The script format is strict, and a script that fails to compile costs a whole turn. Four hard requirements:

1. export const meta = { name, description, phases } must be the first statement in the script, and a pure literal — no variables, function calls, spreads, or template interpolation.
2. parallel() takes thunks, not promises: parallel([() => agent(a), () => agent(b)]). The natural JS spelling parallel([agent(a), agent(b)]) launches both immediately and silently defeats the concurrency cap.
3. Date.now(), new Date() (argless), and Math.random() are unavailable inside a script — they break resume. Stamp timestamps after the workflow returns, or pass them in via args.
4. phase("Title") labels the stages that follow for progress reporting; use the same titles as in meta.phases.

Map the roles onto agent() calls, setting effort per stage — inside a Workflow, a stage without an explicit effort inherits the lead's own session effort, not xhigh:

• mechanical stage → agent(prompt, {agentType: "fast-worker", effort: "medium"}) (or {model: "sonnet", effort: "medium"}) — mechanical work gains nothing from a higher tier; pin it to medium explicitly
• reasoning stage → agent(prompt, {agentType: "deep-reasoner"}) (or {model: "opus"}) — omit effort; the agent definition pins effort: high directly, so it runs at a consistent tier regardless of the lead's own effort
• worktree isolation ({isolation: "worktree"}) when parallel agents mutate files that would collide.

Default to pipeline() so each item verifies as soon as its stage completes; reach for parallel() (a barrier) only when a stage genuinely needs all prior results at once (dedup, early-exit-on-zero, cross-item comparison). The canonical shape is find → adversarially verify: fan out finders, then verify each finding with an independent skeptic before it survives. Prefer several smaller Workflows in sequence — read each result, then decide the next phase — over one monolith.

Codex inside a Workflow. agent() spawns Claude subagents, not Codex. To fold the decorrelated peer into a fan-out, either run the Codex consult at the lead level (before/after the Workflow) and pass its conclusion in, or have a Workflow stage shell out to codex-peer.sh via Bash. Keep Codex for the signals in "Consult Codex," not as a default stage.

Delegate to a subagent

Two equivalent forms — both verified in this environment:

• Named (after Setup): Agent(subagent_type: "deep-reasoner" | "fast-worker", …). The model is pinned by the agent definition.
• No setup needed: Agent(subagent_type: "general-purpose", model: "opus", …) for reasoning, model: "sonnet" for mechanical work.

Spawn slow work with run_in_background: true (the default) and keep planning; you are notified on completion. Consume the subagent's final message — it is the return value, not a chat reply.

Spawn a full peer session (cross-session delegation)

When row 8 fires, delegate to a full Claude Code session, not a subagent. /oss:spawn creates a git worktree on spawn/<slug>, starts a peer in a new pane (herdr, then tmux, then claude --bg), and sends one kickoff prompt pointing at a .spawn/brief.md written with the same delegation contract you give any delegate. Monitor with one backgrounded herdr agent wait and never babysit. Keep integration ownership: the peer commits to its branch and stops, and you review and merge it yourself. A subagent stays cheaper for anything bounded that dies happily with your turn, and Workflow's {isolation: "worktree"} already covers in-session write isolation — spawn is for lifetime, a pane, and steerability, not just isolation.

Interleaving your reasoning with Sonnet execution

You are the reasoner; Sonnet is the executor. They take turns on the same task, whether hand-driven or as fan-out stages. Each pattern lists the signal that selects it and the failure mode to guard against.

Consult Codex (the peer)

OSS_ROOT=$(ls -d ~/.claude/plugins/cache/open-science-skills/oss/*/ 2>/dev/null | sort -V | tail -1)
# read-only consult — ask a question / get a second approach; prints the answer
"${OSS_ROOT}skills/orchestrate/codex-peer.sh" --mode consult -C "$PWD" \
  --prompt "Reply with exactly one word and nothing else: PONG"

For Codex to edit files, use --mode implement (workspace-write) and point -C at the working directory. For a long turn, run it via the Bash tool with run_in_background: true plus --out <file>, then Read that file when the task-notification fires — so a multi-minute Codex turn never blocks you.

Route to Codex when the value is a decorrelated prior, not more horsepower — never because it is "better than Opus." Its errors are uncorrelated with Opus's, and it has a comparative coverage edge (a different, sometimes more recent, training mix), whereas a second Opus call resamples the same distribution and tends to repeat the same error confidently. Under an Opus lead this matters more than under a Fable one: your own reasoning and a deep-reasoner's are drawn from the same distribution, so when you need an error to be uncorrelated with yours, a second Opus cannot give it to you. Fire on any one signal:

• Unverifiable check. You (or a deep-reasoner) answered, and you need an independent check on a claim you cannot cheaply verify (no test, no ground truth).
• You are looping. Two or more rounds have circled the same framing or repeated the same wrong fix. A vendor switch breaks the fixation.
• Disputed, expensive-to-undo design. API shape, schema, concurrency model, or migration strategy where reasonable engineers disagree and being wrong is costly.
• High-stakes cross-check (row 4). Launch the blind decorrelated line and reconcile.
• "Am I framing this wrong?" You suspect your own decomposition, not the answer within it.
• Unfamiliar or recent ecosystem. A stack, library, or idiom where OpenAI's training mix may cover different ground.
• Adversarial cross-review. Have each model attack the other's output (the paper-review-lite --codex pattern); ask Codex to falsify a confident Opus conclusion, not merely review it.

Skip Codex when the work is cheaply verifiable — verify instead, decorrelation buys nothing you can just check — or when the answer needs deep in-repo context Codex would have to re-acquire, since the briefing cost then exceeds the benefit. Skip it for mechanical or trivial work. Wanting more confidence in something already verified is not a signal; confidence is not a reason and a checkable artifact is. A consult costs about 10–15s, longer for --mode implement; where latency is critical the stakes have to justify the vendor round-trip.

The high-stakes parallel path (verified)

Launch a decorrelated cross-check on the same problem, in one message, blind to each other — then you synthesize.

• Fable lead: you reason the problem yourself and, in the same turn, launch a blind Codex (a different vendor), optionally a blind Opus deep-reasoner; then reconcile your own line against theirs.
• Opus lead: the two blind halves are a deep-reasoner (Opus) and Codex (GPT-5.6, gpt-5.6-sol by default), deliberately different vendors, and you adjudicate rather than supplying one of the halves.

OSS_ROOT=$(ls -d ~/.claude/plugins/cache/open-science-skills/oss/*/ 2>/dev/null | sort -V | tail -1)
# Codex half — backgrounded, output teed to a file:
"${OSS_ROOT}skills/orchestrate/codex-peer.sh" --mode consult -C "$PWD" \
  --out codex_out.txt --prompt "$(cat routing_q.txt)"

…issued in the same turn as an Agent(subagent_type: "deep-reasoner", prompt: <same routing_q>). Neither sees the other's answer. They return complementary lines of reasoning; you merge them.

This is the signature move, and it is verified: this skill's own routing rule came out of one such turn, where the blind Codex and the blind Opus returned complementary halves of one guardrail (fragmentation-on-integration vs. over-trusting your own line).

Reconciling the answers — the rules you must follow:

• Never reveal one executor's answer to the other during the round.
• Do not break ties by confidence. Substantive disagreement is a stop condition, not a coin-flip.
• On disagreement: run one targeted reconcile round (now each may see the other's reasoning). If still unresolved, escalate to the human.
• Accept agreement only when both point at the same checkable artifact — twin confident assertions are not consensus (they can share a blind spot). This holds doubly when one half is a second Opus.

Guardrail — the failure modes to defend against

Two names for the same trap.

• Fragmentation (the integration view): delegated or fanned-out pieces are each locally correct but conflict when you stitch them together.
• Over-trusting your own line (the reconciler view): a lightweight lead drifts toward the more fluent answer because it cannot evaluate Opus/Codex output. Your trap is the opposite of rubber-stamping — you are the strongest model here, so you skip the independent check and ship your first line of reasoning. Even the best single model can be confidently wrong on a high-stakes, hard-to-verify call, so on exactly the tasks the parallel path exists for, run the decorrelated cross-check and actually weigh it, rather than waving it through because it agrees or dismissing it because it does not.

Defense (apply to every delegation and every fan-out):

1. Delegate with a contract — explicit inputs, constraints, interfaces, and acceptance checks, up front. Unspecified design decisions route up to you; they never get guessed down by the cheaper model.
2. Demand a checkable artifact, not a verdict — a test that runs, a diff that applies, a cited quote, a reproduction — plus confidence and a "what would make this wrong" note. If a task cannot produce one, that is the signal it belongs on the parallel path.
3. You retain integration ownership — of correctness and rigor. Verify every returned result against the repository and tests; Agent and Workflow completion messages are not proof of overall completion. Then read the deliverable as the domain expert you are: a fast delegate returns work that is correct but thin — an approximate figure where precision matters, a result asserted where the mechanism behind it should be explained, a lone headline where a careful reader needs the comparison or the bound. Add that depth instead of shipping the delegate's summary as-is.
4. On the parallel path, enforce the disagreement-as-gate rule above, and make the decorrelated half a different vendor.

Gotchas

• codex exec hangs without < /dev/null. It prints Reading additional input from stdin... and blocks forever, even when the prompt is passed as an argument. codex-peer.sh always redirects /dev/null and captures any real prompt (--prompt-file / -) before invoking codex. Never call codex exec bare in a background job.
• Codex reasons at xhigh by default; codex-peer.sh sets it explicitly via --effort xhigh → -c model_reasoning_effort=xhigh, rather than relying on Codex's own implicit default. It prints a header (model: gpt-5.6-sol, sandbox: read-only) before the answer. The final answer is the text after the last codex marker; --out captures the whole transcript. A trivial consult is ~5s; a real design question ~10–15s. Pass --effort to override per-call for a stronger or cheaper tier.
• ~/.claude/agents/ may not exist. The first cp fails with No such file or directory. mkdir -p first (the Setup block does).
• A named subagent only resolves after its def is installed AND a session reload. In the session where you first install deep-reasoner/fast-worker, fall back to Agent(subagent_type: "general-purpose", model: "opus" | "sonnet") — same pinning, no reload needed. Inside a Workflow, agent(..., {model: "opus" | "sonnet"}) needs no installed def at all.
• Model pins are real. Verified: the Sonnet spawn reported model-check: Sonnet 5; the Opus spawn reported Running as: Opus (claude-opus-5); Codex is pinned to gpt-5.6-sol and reports model: gpt-5.6-sol in its header. gpt-5.6 alone is not a valid slug — there are three distinct GPT-5.6 tiers (gpt-5.6-sol flagship, gpt-5.6-terra balanced, gpt-5.6-luna fast); the bare gpt-5.6 triggers a "metadata not found" warning and falls back to whichever tier Codex defaults to. gpt-5.6-sol is the default here because it's the strongest peer for a decorrelated cross-check — confirmed working (as of July 2026) on ChatGPT-account-authenticated Codex CLI (an earlier "rejected outright" finding no longer reproduces; if it ever errors, check codex --version before assuming a gate, since an outdated CLI rejects sol/luna too, with a different error). Pass --model gpt-5.6-terra explicitly for a cheaper peer on routine consults.
• Keep your own context lean. Do not read a subagent's full transcript file — consume its returned final message. Long/slow executors go to the background so they never stall the loop. When an investigation's width would bloat your context, that width is exactly what belongs on a deep-reasoner or a fan-out stage (the "gather then reason" split).
• A stray global codex-peer.sh shadows the plugin's own and can silently drop the model pin. Earlier docs told you to hand-install codex-peer.sh under ~/.claude/skills/; that copy never updates on plugin upgrade. If it is older than the --model pin, it calls bare codex exec with no --model flag, and Codex falls back to whatever tier it defaults to — observed once as an older, cheaper tier rather than gpt-5.6-sol, with no error, so the drift is invisible until you read the model: line in Codex's own header. Delete any ~/.claude/skills/orchestrate/codex-peer.sh (or the older fable-orchestrate / opus-orchestrate paths) you may have installed under the old instructions; always invoke "${OSS_ROOT}skills/orchestrate/codex-peer.sh". Trust the CLI's printed model: header over anything Codex says about itself when asked directly — models cannot reliably self-report their own version.
• Don't fan out for its own sake. Fan-outs are cheap to reach for, but a barrier (parallel()) wastes wall-clock when one stage lags, and a compact reasoning task (row 3) is faster in your own head than briefed to a peer-strength subagent. Fan out for width, hygiene, parallelism, or independence — not activity.

Troubleshooting

• codex-peer.sh: no prompt — pass one of --prompt "…", --prompt-file PATH, or - (stdin). Empty prompts are rejected.
• Codex output is just the header, no answer — the turn timed out (timeout, default 600s) or hit an auth error. Check codex login status; raise --timeout for large --mode implement jobs.
• codex: command not found — install the Codex CLI and codex login first. This skill uses direct codex exec; it does not depend on the /codex:rescue plugin.
• Workflow unavailable / not opted in — the normal case, not a fault: dynamic Workflows are gated per session (org policy, launch gate, or the "Dynamic workflows" setting in /config), and nothing this skill does changes that. Fan out with parallel Agent calls instead (the routing rule still holds); the only loss is deterministic control flow. Do not argue with the refusal.

Notes

• Fable lead versus Opus lead. Both modes reason in place and delegate execution and parallel work. Fable is the stronger reasoner and the more expensive tier, so a Fable lead is the higher-quality orchestrator and holds more of the hard reasoning itself. An Opus lead is the one to run when Opus is the model you have, or when you specifically want its 1M-context window; it leans harder on structured fan-out, which is what compensates for not being Fable.
• Why direct codex exec, not the /codex:rescue plugin? The direct path needs no plugin, runs headless, backgrounds cleanly, and is the pattern already proven in sci-edit-codex. /codex:rescue --background is an optional alternative once you've installed openai/codex-plugin-cc, but nothing here requires it.
• Cost shape. Under a Fable lead the strongest model is on the reasoning, so the lead is the most valuable part of the run rather than the cheapest, and spend leaves your plate only where it does not decide the answer. Under an Opus lead the lead is the priciest model on the team but runs at medium, so spend the higher tiers where they are a bounded, verifiable shot — high on parallel deep-reasoners whenever width justifies fan-out. Either way Codex spend lands only where the routing rule sends it; the decorrelated cross-check is ~1 extra Codex consult (the Opus-lead parallel path is ~2× a single consult), worth it whenever row 4 fires.
• Driver: codex-peer.sh (run --help for flags). Agent defs: agents/deep-reasoner.md, agents/fast-worker.md.