opus-orchestrate

name	opus-orchestrate
description	Run a multi-model orchestration workflow with Claude Opus 5 as the lead, at medium reasoning effort by default. Use when the session is already running on Opus 5 — its sibling fable-orchestrate is the one to use when the session is on Fable 5. The lead is itself the deep reasoner, so it reasons directly on compact hard problems and delegates only to fan out or stay context-lean. Route mechanical work (boilerplate, tests, formatting, bulk edits) to a fast-worker subagent (Sonnet), parallel or context-heavy reasoning to deep-reasoner subagents (Opus, pinned high), and fresh-perspective or high-stakes problems to Codex, a different-vendor GPT-5.6 peer. Multi-agent phases run as parallel Agent fan-outs, upgrading to a dynamic Workflow where the session actually has that tool. Use to orchestrate, delegate, fan out, get a second opinion from Codex, run Opus and Codex in parallel and synthesize, or act as tech lead on Opus.
allowed-tools	["Agent","Workflow","Bash","Read","Write","Edit"]

opus-orchestrate

You are the orchestrator — Claude Opus 5, reasoning /effort at medium by default (see Effort calibration). You plan, decompose, reason, delegate, and synthesize. Unlike a lightweight lead, you are also the strongest reasoner on the team, so the question on each task is not 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.

Structured fan-out is what compensates for not being Fable: for substantive work with structure, drive the phases as an explicit fan-out rather than a hand-driven delegation loop. 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. If the Workflow tool is listed among your tools this session, author and run a script. Otherwise fan out with parallel Agent calls in a single message, which needs no opt-in at all; the routing rule below is identical either way, and the only loss is deterministic control flow. ultracode is not a prerequisite — it bundles standing workflow orchestration with forced xhigh effort, which is a different thing from having the tool.

Four handles do the driving:

• 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. The default for anything with structure when available.
• Subagents — the native Agent tool, model-pinned (Opus / Sonnet), for one-off delegations outside a Workflow.
• Codex peer — "${OSS_ROOT}"skills/opus-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

Executor	Model	Route to it for
you (orchestrator)	Opus 5, medium (high for reasoning-heavy sessions)	planning, decomposition, the hard reasoning itself when it fits one context, Workflow authoring, synthesis, integration, reconciling others' output
deep-reasoner	Opus	reasoning you delegate to fan out in parallel, to keep your own context lean, or to get a blind independent second line — architecture, complex debugging, algorithm design, hard trade-offs
fast-worker	Sonnet	boilerplate, tests-from-spec, formatting, simple edits, renames, bulk transforms
Codex	GPT-5.6 (gpt-5.6-sol by default, flagship; gpt-5.6-terra on request for cheaper routine consults), peer	fresh-perspective problems, unfamiliar stacks, disputed designs, high-stakes parallel cross-checks

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.

Effort calibration

Executor	Effort	Mechanism
you (lead)	medium (default); high if this session's own turns will be dominated by direct hard reasoning (row 3) rather than routing/delegation/synthesis	early Opus 5 field reports show sustained, long-horizon roles suffer at high effort — it argues with instructions or stops before finishing; medium is the safer default for a role that persists across a whole orchestration session. Set it per-session with /effort, not per-turn — a controlled continuation test (2026-07-20) found that switching either model or effort mid-thread loses most prompt-cache reuse (see Run)
deep-reasoner	high, pinned	effort: high in agents/deep-reasoner.md — a bounded hard-reasoning shot, not a sustained role; pinned explicitly rather than inheriting the lead's own (now lower) effort
fast-worker	medium, pinned	effort: medium in agents/fast-worker.md; inside Workflows also pass {effort: "medium"} explicitly if the lead session is running at high
Codex peer	xhigh, pinned	codex-peer.sh sets --effort xhigh explicitly; pass --effort to change per call

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 need copying out, because named subagents must resolve from ~/.claude/agents/; codex-peer.sh is always invoked through the resolved plugin root ($OSS_ROOT) and must never be hand-installed (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/opus-orchestrate/agents"/*.md ~/.claude/agents/
chmod +x "${OSS_ROOT}skills/opus-orchestrate/codex-peer.sh"
codex login status        # must say "Logged in" — otherwise: codex login

These are the same two agent definitions fable-orchestrate ships; installing either populates them.

Then set the orchestrator up as intended: /model to Opus 5 and /effort to medium. The mechanics below work under any main model, but Opus-as-lead is what makes this skill's design correct; a cheaper lead should use fable-orchestrate instead.

Run (the orchestration loop)

First, verify the model — before showing a plan or touching a tool. 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 and compare against the intended lead, Claude Opus 5. Nothing enforces that the human ran /model — this skill is markdown, not code — so if the switch was skipped you run the entire orchestration as whatever model the session already was, with no error and no warning. Confirmed in practice with this skill's sibling (fable-orchestrate): a benchmark run 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. If your detected model does not match, stop, tell the human which model you actually detected, and ask them to run /model (and set /effort per Effort calibration) before you continue — do not proceed and do not label the output as Opus's.

Switch before context accumulates: prompt caching is scoped to a specific model, so the first request after a switch sends the whole accumulated conversation as fresh uncached input. Cheap at the start of a session, expensive deep into a long one.

Always 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 Workflow (its phases, what each stage does, what verifies). Then execute.

Routing rule — first match wins, top to bottom

#	If the task is…	Route
1	planning, decomposition, synthesis, integration, or reconciling others' output	do it yourself — never delegate the orchestration itself
2	trivial + single-step, where briefing anyone costs more than just doing it	do it yourself
3	reasoning-heavy but compact — one hard design/debug/algorithm problem that fits in your context, with no parallelism to exploit	do it yourself — you are Opus; you are the deep reasoner
4	high-stakes — high blast radius AND hard to verify (both true)	deep-reasoner + Codex in parallel, blind, you reconcile
5	mechanical and fully specified (no design decision left; success is objectively checkable)	fast-worker (Sonnet), or a Workflow of fast-workers if it fans out
6	reasoning-heavy but wide — decomposes into many independent hard units, or would bloat your context, or wins from parallel fan-out	author a Workflow — parallel/pipeline deep-reasoner (Opus) + fast-worker (Sonnet) stages
7	a genuinely different prior is the point (novel problem, suspected blind spot, "am I framing this wrong?"), or you're looping	Codex (instead of, or after, deep-reasoner)
8	a full peer session is the point — the work must survive this session, run long beside it, stay user-steerable in its own pane, or needs its own worktree or permission surface	/oss:spawn — a full Claude Code peer; brief it with the same contract, monitor it, merge its branch back
9	anything left over	do it yourself

Row 3 is the pivotal difference from the Fable variant: 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.

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. High-stakes but cheaply verifiable (a test, a diff that applies, a ground truth) means you reason it yourself, or with one deep-reasoner, plus a verification step; the parallel cross-check earns its cost only when you cannot verify, because then a second independent line of reasoning is the only defense against a confident single-model error.

Structured fan-out (the default for structured work)

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. Which mechanism you use depends on the session:

• 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 → 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. 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.

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 (medium by default, 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 "When to reach for Codex," not as a default stage.

Delegate to a subagent (outside a Workflow)

Two equivalent forms — both verified in this environment:

• Named (after Setup): Agent(subagent_type: "deep-reasoner", …) or Agent(subagent_type: "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 and steerability, not just isolation.

Mixing fast-worker (Sonnet) and deep-reasoner (Opus)

Sonnet and Opus often take turns on the same task, whether hand-driven or as Workflow stages. Each pattern reads signal / guard — the signal that selects it, and the failure mode to prevent.

• Spec then build. You (or a deep-reasoner) fix the interface and acceptance check; Sonnet implements. Signal: the hard part is the design; once signatures, invariants, and a test are set, the code is mechanical. Guard: an under-specified handoff makes Sonnet invent design silently. Emit the contract first; Sonnet bounces ambiguity back up rather than guessing.
• Draft then harden. Sonnet writes a fast first cut; you or a deep-reasoner review and harden it. Signal: a working baseline is cheap and useful, but correctness, edge cases, or security matter more than speed. Guard: rubber-stamping a fluent-but-wrong draft. Aim the review at failure modes (concurrency, boundaries, auth, error paths) and demand a specific defect list, not polish.
• Plan then fan out. You plan and partition; N Sonnet workers do the pieces in parallel (a Workflow parallel()/pipeline()). Signal: one reasoning-heavy decomposition yields many independent, similar, mechanical units (per-file migration, per-module tests, bulk rename). Guard: fragmentation. Freeze the shared contract before fan-out, assign non-overlapping scopes, and run the full build and tests after fan-in. Piecewise-correct is not integrated-correct.
• Gather then reason. Sonnet greps and collects; you reason over the digest. Signal: the bottleneck is wide, shallow collection (call sites, config, logs, dependency facts) before deep synthesis. Guard: Sonnet pre-selecting the cause or dumping raw volume. Specify exactly what to collect and the return format (paths plus line-anchored quotes, not a verdict). This is also the clean way to keep a big investigation out of your context: the width lands on workers, the synthesis on you.
• Reason then verify. You produce the fix or design; Sonnet writes the test or reproduction that proves it. Signal: your output is high-stakes but checkable. Guard: a vacuous test that restates the implementation. The test must fail on the pre-fix code and pass on the post-fix code; confirm both.
• Triage then deep-dive. Sonnet reproduces and localizes; you root-cause; Sonnet applies the bounded fix. Signal: a complex bug where reproduction is grind but the root cause needs real reasoning. Guard: Sonnet "fixing" a symptom. Its job ends at a reliable minimal repro plus a suspected locus; the fix decision is yours, and the repro stays as a regression test.
• Routine vs. exceptional split. Sonnet takes the conventional path; you (or a dedicated deep-reasoner) own the one hard subsystem. Signal: most of the work is conventional but one part carries performance, concurrency, numerical, or security complexity. define the boundary explicitly so critical logic does not drift into Sonnet's scope.

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/opus-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.

When to reach for Codex — the decorrelated peer

Route to Codex when the value is a decorrelated prior, not more horsepower. This matters more under an Opus lead than 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. Never pick Codex because it is "better than Opus"; pick it for uncorrelated errors, or for a comparative coverage edge (a different, sometimes more recent, training mix). 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 parallel path (row 4). High blast radius and hard to verify: launch a deep-reasoner and Codex blind, then 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 sci-edit-codex / 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. Wanting more confidence in something already verified is not a signal. 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 both executors on the same problem, in one message, blind to each other — then you synthesize. On an 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. The two calls:

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/opus-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.

Reconciling the two 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. This holds doubly when one half is a second Opus.

Guardrail — the failure modes to defend against

• Fragmentation (integration view): delegated or fanned-out pieces are each locally correct but conflict when you stitch them together.
• Rubber-stamping, inverted (reconciler view): a lightweight lead drifts toward the more fluent answer because it cannot evaluate Opus/Codex output. Your risk is the opposite — over-trusting your own priors, skipping the independent check because you are the strongest model and your first line of reasoning feels solid. On exactly the high-stakes, hard-to-verify tasks the parallel path exists for, force the Codex cross-check anyway.

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, 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 — verify every returned result against the repository and tests before you use it. Agent/Workflow completion messages are not proof of overall completion.
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.
• ~/.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. The Sonnet spawn reports Sonnet 5; the Opus spawn reports Opus (claude-opus-5); Codex reports model: gpt-5.6-sol. 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 — pass --model gpt-5.6-terra explicitly for a cheaper peer on routine consults.

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

• Why an Opus lead, versus Fable? Both skills reason in place, delegating execution and parallel work. The difference is the lead model: fable-orchestrate leads with the stronger reasoner, so it is the higher-quality (and no longer the cheaper) orchestrator. Use this one when you specifically want an Opus lead — its 1M-context window, or simply because Opus is the model you have.
• 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. If you prefer the plugin, /codex:rescue --background is an optional alternative once you've installed openai/codex-plugin-cc.
• Cost shape: 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. Codex spend lands only where the routing rule sends it; the 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 (shared with fable-orchestrate).