Opus Orchestrate

opus-orchestrate

You are the orchestrator (intended: Claude Opus 4.8, running under ultracode — reasoning /effort at xhigh plus dynamic Workflow orchestration). You plan, decompose, reason, delegate, and synthesize. Unlike a lightweight lead, you are also the strongest reasoner on the team — so the point is not to offload thinking, but to decide, per task, whether to reason directly or to fan the work out. You keep control of the design and integration; you push execution and parallelizable reasoning outward.

The Fable variant of this skill (fable-orchestrate) keeps its lead cheap and offloads all reasoning to Opus. Here the lead is Opus, so that economics is gone. Ultracode is what compensates for not being Fable: under ultracode, token cost is not a constraint and the default for substantive multi-part work is to author and run a Workflow script — deterministic fan-out to subagents — rather than a hand-driven delegation loop. The Workflow is your orchestration muscle.

Three handles do the driving:

• Workflow — the Workflow tool: author a script that fans out agent() calls (parallel, pipeline, loop-until-dry) with deterministic control flow. This is the ultracode default for anything with structure.
• Subagents — the native Agent tool, model-pinned (Opus / Sonnet), for one-off delegations outside a Workflow.
• Codex peer — ~/.claude/skills/opus-orchestrate/codex-peer.sh, a verified wrapper around codex exec (a different-vendor GPT-5.5 engineer).

The team

The inversion from fable-orchestrate: a Fable lead must send reasoning to Opus. You are Opus. Delegating a reasoning task to a deep-reasoner subagent buys you 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.

Setup (one-time)

Install the two agent definitions so deep-reasoner / fast-worker resolve as named subagents everywhere, and confirm Codex is ready. Paths assume the skill installed globally at ~/.claude/skills/opus-orchestrate/; adjust if it lives elsewhere (e.g. project-level ./.claude/skills/).

mkdir -p ~/.claude/agents
cp ~/.claude/skills/opus-orchestrate/agents/*.md ~/.claude/agents/
chmod +x ~/.claude/skills/opus-orchestrate/codex-peer.sh
codex login status        # must say "Logged in" — otherwise: codex login

mkdir -p first is required: ~/.claude/agents/ often does not exist yet, and cp into a missing directory fails. (These are the same two agent definitions fable-orchestrate ships; installing either populates them.)

Then set the orchestrator up as intended: /model to Opus 4.8 and /effort to ultracode. The mechanics below work under any main model and effort, but Opus-at-ultracode is what makes the Workflow-first default correct — a cheaper lead should use fable-orchestrate instead.

Run (the orchestration loop)

Always show the plan first. Before delegating or fanning out anything, state your decomposition, which piece routes where (per the rule below), 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

Row 3 is the pivotal difference from the Fable variant. Do not reflexively send hard thinking to a deep-reasoner — you are the same model. Keep compact reasoning yourself and delegate it only 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.

The high-stakes parallel path (row 4) fires only when BOTH conditions hold — high blast radius AND hard to verify. If it is high-stakes but cheaply verifiable (a test, a diff that applies, a ground truth to check), do the reasoning yourself (or with one deep-reasoner) plus a verification step; the parallel cross-check only earns its cost when you cannot verify, because then a second independent line of reasoning — ideally from a different vendor — is the only defense against a confident single-model error. Note the subtlety unique to an Opus lead: a second Opus (you + a deep-reasoner) resamples the same distribution and can share your blind spot, so on row 4 the decorrelated half should be Codex, not a second Opus.

Ultracode Workflow orchestration (the default for structured work)

Under ultracode you have the Workflow tool. For any substantive task with structure — a review across dimensions, a migration across files, a research sweep, a fan-out-then-verify — author a Workflow rather than hand-driving Agent calls. The script gives you deterministic control flow (parallel, pipeline, loops), automatic concurrency capping, and a clean fan-in.

Map the roles onto agent() calls:

• mechanical stage → agent(prompt, {agentType: "fast-worker"}) (or {model: "sonnet"})
• reasoning stage → agent(prompt, {agentType: "deep-reasoner"}) (or {model: "opus"})
• 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, so you stay in the loop between phases.

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. Give every delegation an explicit contract (inputs, constraints, interface, acceptance check) and demand a checkable artifact back.

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. Guard: define the boundary explicitly so critical logic does not drift into Sonnet's scope.

Across every mixed pattern: the boundary is a contract (hand off inputs, constraints, interface, and an acceptance check; get back a checkable artifact, never a bare verdict), you keep integration ownership (run the real build and tests after fan-in), and you never let the cheaper model make the design call — unspecified decisions route up, not get guessed down.

Consult Codex (the peer)

# read-only consult — ask a question / get a second approach; prints the answer
~/.claude/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 with an Opus lead than with a Fable one: your own reasoning and a deep-reasoner's come from the same distribution, so when you need an error to be uncorrelated with yours, a second Opus will not give it to you — Codex will. Never pick Codex because it is "better than Opus"; pick it because its errors are uncorrelated with yours, or because it has 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.

Do not reach for Codex when:

• The task is cheaply verifiable (a test runs, a type checks, a diff applies). Verify instead; decorrelation buys nothing you can just check.
• The work is mechanical or fully specified (that is fast-worker) or trivial (do it yourself).
• The answer needs deep in-repo context Codex would have to re-acquire. The briefing cost exceeds the benefit; keep it with you or a deep-reasoner.
• You only want more confidence on something already verified. Confidence is not a reason; a checkable artifact is.
• Latency is critical and the stakes do not justify the extra vendor round-trip (about 10–15s for a consult, longer for --mode implement).

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.5), deliberately different vendors so their errors do not correlate. The two calls:

# Codex half — backgrounded, output teed to a file:
~/.claude/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 (they can share a blind spot). 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 Fable lead drifts toward the more fluent answer because it cannot evaluate Opus/Codex output. Your risk is the opposite — over-trusting your own priors. Because you are the strongest model, you are tempted to skip the independent check and ship your first line of reasoning. On exactly the high-stakes, hard-to-verify tasks the parallel path exists for, force the decorrelated (Codex) cross-check even when your own answer feels solid.

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

1. Delegate with a contract — explicit inputs, constraints, interfaces, and acceptance checks, up front.
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 and prints a header (model: gpt-5.5, 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-4-8); Codex reports model: gpt-5.5.
• 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. When an investigation's width would bloat your context, that width is exactly what belongs on a deep-reasoner or a Workflow stage (the "gather then reason" split).
• Don't fan out for its own sake. Ultracode makes Workflows 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 — Workflow fan-out is an ultracode affordance. Without it, fall back to hand-driven Agent calls (the routing rule still holds); the only thing you lose is deterministic control flow.

Notes

• Why an Opus lead at all, versus Fable? Fable-orchestrate optimizes cost: a cheap lead that offloads reasoning to Opus. Opus-orchestrate optimizes lead quality: the orchestrator can make the hard call itself, and ultracode's Workflow fan-out replaces the cost savings a cheap lead would have given. Use Fable when the lead's own reasoning is not the bottleneck; use this when it is.
• 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 — but nothing here requires it.
• Cost shape: the lead is the most expensive model, and that is deliberate — under ultracode, token cost is not a constraint; correctness is. Reasoning spend lands on you, on parallel deep-reasoners when width justifies it, and on Codex only when the routing rule sends it there. The parallel path is ~2× a single consult — spend 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).