smart-orchestrate

name

smart-orchestrate

description

Two-model orchestration workflow where Claude acts as planner/reviewer and Codex GPT-5.5 (xhigh reasoning, fast tier) acts as executor, plus an advisor mode implementing Anthropic's advisor strategy (executor drives end-to-end, escalates to Claude only when stuck; Claude returns a plan, correction, or stop signal and never writes code). Use this skill whenever the user invokes /smart-orchestrate, asks to delegate implementation to Codex, wants Claude to plan/review while another model writes the code, mentions the codex-rescue agent, or asks to run a task in advisor mode / advisor strategy where the executor drives and Claude only advises.

Smart Orchestrate

Two ways to split work between Claude (the brain) and Codex GPT-5.5 xhigh fast (the arms). In both, Claude never writes the implementation code and Codex never makes user-facing decisions alone. The bulk of token-heavy generation runs on the ChatGPT plan, typically saving 50%+ of Claude tokens.

Modes

Mode	Invocation	Pattern
Orchestrate (default)	/smart-orchestrate <task>	Claude decomposes and briefs up front; Codex implements; Claude reviews and gates. Top-down.
Advisor	/smart-orchestrate advisor <task>	Codex drives the task end-to-end and escalates to Claude only when it hits a decision it can't reasonably solve. Bottom-up. This is Anthropic's advisor strategy, inverted onto this stack: Codex = executor, Claude = advisor.
Plan-only	/smart-orchestrate plan <task>	Produce the brief and stop, so the user can inspect or edit it before delegation.

Choosing a mode. Orchestrate suits architecturally significant work (new services, schema changes, anything touching locked ADR constraints) where up-front decomposition pays for itself. Advisor suits well-bounded tasks (bug fixes, refactors within an existing pattern, mechanical sweeps) where decomposition is overhead and frontier reasoning is only needed at occasional decision points. Advisor mode is cheaper in Claude tokens than Orchestrate because Claude is consulted only at escalation points, not on every diff.

Method: goal-state, invariant-driven

Both modes run as a goal loop, not a checklist — the same engine that makes /ship reliable. Each mode below states a single goal and a set of invariants: preconditions, not steps. If any is unmet, achieving it becomes your next action. What keeps this honest:

• Evidence, not assertion. An invariant is met only with concrete evidence — a retrieved diff, the output of a command you ran. "Codex says it's done" is never evidence.
• Self-healing order. The path is yours; if a later action invalidates an earlier invariant (a fresh Codex diff invalidates a prior review/verify), that invariant flips back to unmet and re-meeting it becomes the next action automatically.
• Resumable checklist. Track invariant status in a TodoList so an interrupted or compacted session resumes correctly.
• Escalate, don't waive. Declaring the goal met with an unmet invariant is the one prohibited move. Blocked on a decision above your pay grade (Codex unavailable, broken main, disputed design) → pause and ask the user.
• Terse transitions. Report like [orchestrate] diff retrieved → reviewing or [advisor] escalation 2/3: correction sent.

Orchestrate mode

Roles

Claude — planner & reviewer

• Breaks every task down: architecture decisions, file targets, constraints, edge cases
• Writes precise implementation briefs for Codex, including project invariants (CLAUDE.md rules)
• Critically reviews every Codex diff for correctness, contract adherence, and test impact
• Runs verification (npm run typecheck, npm test, or the project's equivalent) and gates what gets accepted
• Sends specific corrections back to Codex when review finds issues

Codex — executor

• All file edits, feature implementation, refactors, and mechanical sweeps
• Works from Claude's brief and returns a complete diff for review
• Handles fix-up rounds based on Claude's review feedback

Goal

The task is implemented and accepted, with every invariant below holding with evidence. Claude writes no implementation code; Codex makes no design decision alone.

Invariants

1. Briefed. A written brief exists (template below) carrying scope, files, project invariants, contracts, edge cases, and verification commands — CLAUDE.md/ADR rules copied in verbatim, since Codex has no project context unless you give it.
2. Diff in hand. Codex has executed and a complete diff has been retrieved for review — not a prose description of changes. The codex-rescue agent only forwards the task; fetching the actual diff is a separate, required step via the result path (see Delegation mechanics). No diff retrieved = this invariant is unmet.
3. Reviewed. The retrieved diff has been checked against the brief and the real codebase: correctness, contract adherence (public APIs, types, error-handling conventions), test impact, and no unrequested design changes (reject those even if they work).
4. Verified. The verification commands were run by Claude — not taken on Codex's word — and pass.
5. Corrections closed. Every review finding is either fixed via a delta correction loop (template below) or consciously descoped and noted. Any new diff re-opens invariants 3–4.

Loop until all hold, then summarise to the user: what changed, what was verified, what was descoped.

Advisor mode

The inversion: Codex runs the task end-to-end — reading code, making edits, running commands, iterating toward a solution. Claude does not decompose, does not write a brief, and does not review every diff. Claude is consulted only when Codex escalates, and at the final gate.

Goal

The task is complete and accepted; Claude was consulted only at escalation points and the final gate; every invariant below holds with evidence.

Invariants

1. Kicked off. Codex has the lightweight kickoff (template below): task, invariants, verification commands, and the escalation triggers — dispatched at --effort xhigh (see Delegation mechanics).
2. Escalations resolved. Every escalation Codex raises is answered with exactly one of plan / correction / stop (contract below). Because the executor returns rather than pausing live, each answer is a bounded re-delegation: Claude hands back the delta and Codex resumes from it. Consultations are capped (default 3) — hitting the cap is the signal that the task belonged in Orchestrate mode; say so and switch, don't keep advising.
3. Final gate. Before acceptance, Claude has run the verification commands and reviewed the final diff once, with evidence. Lighter than Orchestrate's per-round review, but never skipped.

Claude never writes the code, never pre-empts an escalation, never takes over; if the executor is failing badly, issue a stop signal and consult the user rather than silently switching modes.

Advisor contract (Claude's side)

When Codex escalates, Claude reads the escalation context (what Codex tried, where it's stuck, relevant code) and returns exactly one of:

• Plan — a short, concrete approach for the executor to follow (aim for a few hundred tokens, not a full brief)
• Correction — identification of what the executor got wrong and what correct looks like
• Stop signal — instruction to halt because the task is off-track, out of scope, violates an invariant, or needs the user

Never write the code itself, never call tools to do the executor's work, never produce user-facing output mid-task.

Setting up the executor

Give Codex a lightweight kickoff (not a full brief):

Task: <one-paragraph statement>
Invariants: <CLAUDE.md / ADR rules that must not be violated>
Verification: <commands that must pass before you consider yourself done>

Drive this end-to-end. Escalate to me (the advisor) only when you hit a decision
you cannot reasonably resolve: ambiguous requirements, an architectural fork,
a contract you're unsure you may change, or three failed attempts at the same
problem. When escalating, state what you tried, what you're stuck on, and the
options you see. Do not escalate routine implementation choices.

Escalation triggers (teach these to the executor)

• Ambiguity in requirements that materially changes the implementation
• An architectural fork (two valid designs with different long-term costs)
• Uncertainty about whether a contract, schema, or invariant may be changed
• Repeated failure: same error or failing test after ~3 attempts
• Anything that smells like scope expansion

Delegation mechanics

Both modes delegate to Codex through the codex-rescue agent (a thin forwarder to the Codex companion task runtime). Three things this skill pins down that the agent leaves to the caller:

• Effort. Request --effort xhigh explicitly when delegating. The codex-rescue agent leaves effort unset by default, which falls back to your ~/.codex/config.toml (high); this skill assumes xhigh reasoning, so state it. (task accepts none | minimal | low | medium | high | xhigh.)
• Model. Leave the model unset — Codex runs your configured default (GPT-5.5). Only pass --model if the user explicitly asks for a different one.
• Result retrieval. The codex-rescue agent forwards the task and returns; it does not poll or fetch results. Retrieve the completed diff via the Codex result path (/codex:result, or the companion result / status commands) before reviewing — that retrieval is what satisfies "Diff in hand" (Orchestrate) and the final gate (Advisor). A description is not a diff. The forwarder's streamed output file freezes when it returns; the live job state is ~/.claude/plugins/data/codex-openai-codex/state/<workdir-hash>/jobs/task-*.json (status field) with the stream in the sibling .log — watch those for completion.
• Budget signal (statusline integration). The Codex rate windows are cached at /tmp/codex-rl-cache.json, written by ~/.claude/codex-rl-probe.sh (reads the latest rate_limits snapshot from ~/.codex/sessions/**/rollout-*.jsonl — the same numbers the codex TUI shows; local-only, free, ~40ms). Fields: used_percentage (5h window), weekly_used_percentage, resets_at (epoch), snapshot_age_seconds. The statusline renders it as cdx5h: N% alongside ant5h: N% (Anthropic 5h from the native statusline JSON). Before EVERY executor dispatch, run the probe and read the cache — the snapshot only updates when codex runs, so refresh first; a large snapshot_age_seconds means the number predates recent jobs.
• Executor fallback (authority granted by Leigh 2026-06-12). If the Codex budget is in danger of capping — 5h used_percentage ≥ 80%, or weekly ≥ 90%, or a dispatch batch would plausibly push it there — dispatch the executor role to a Sonnet subagent (Agent tool, model: "sonnet") instead of Codex: same brief/kickoff text, same invariants and escalation triggers, Claude still reviews and verifies. Note the substitution in the task summary so the budget shift is visible. If BOTH budgets are strained, pause and tell the user rather than burning the tighter one.

Direct-exec escape hatch (when the companion blocks — verified 2026-07-05)

The codex-rescue → companion task path has two hard limits that will silently waste a dispatch. Know the failure signatures and skip straight to driving codex exec yourself.

Companion limits (do not fight these — they are structural):

• Args after task are prompt text, not flags. The companion task has no CLI surface of its own for sandbox/cwd/writable-roots. node codex-companion.mjs task --help runs a Codex thread with --help as the task. So you cannot pass sandbox-bypass or extra writable dirs through the forwarder.
• Writable root = launch workspace + /tmp only. A task targeting a second repo outside the launch dir cannot edit it — Codex reports it's blocked on write access. Multi-repo instrumentation/migration work hits this every time.
• Sandbox can fail before any work. Intermittent signature in the returned output: bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted — every shell command (even pwd) fails, touchedFiles: [], no edits made. Not a code/plan problem; retrying the companion does not fix it.

When you see any of the above (bwrap error, "no write access to

", or the task spans >1 repo, or the user asks for --yolo), stop using the companion and run codex exec directly. --yolo = --dangerously-bypass-approvals-and-sandbox (unsandboxed, no approval prompts) — it needs explicit user authorization since it runs model-generated commands unsandboxed; this session had it. Verified recipe:

# write the kickoff to a file first (avoids shell-escaping hell)
codex exec --dangerously-bypass-approvals-and-sandbox \
  -C /path/to/primary-repo \
  --add-dir /path/to/second-repo \        # repeat --add-dir per extra writable repo
  -c model_reasoning_effort="xhigh" \      # effort is reliable here; companion drops/ignores it
  - < /path/to/kickoff.md \                # '-' reads prompt from stdin
  > /path/to/run.log 2>&1                  # run in background; poll the log + `git status`

• -C sets the working root; --add-dir grants each additional writable repo (this is the fix for the companion's single-root limit).
• Prefer stdin (- < file) over a positional prompt — a multi-paragraph kickoff with backticks/quotes will otherwise be mangled by the shell.
• Result retrieval for direct exec: there is no job JSON. Tail run.log and watch git status --short in each repo for .go/new-package changes to confirm progress; the diff itself is the git working tree. (Companion path retrieval is unchanged: poll ~/.claude/plugins/data/codex-openai-codex/state/<workdir-hash>/jobs/task-*.json status.)
• Budget probe still applies before dispatch — direct exec spends the same Codex quota.

Brief template (Orchestrate mode)

## Task
<one-paragraph statement of what to build/change and why>

## Files
<explicit list of files to create/modify; anything not listed is out of scope>

## Invariants
<project rules Codex must not violate — copied from CLAUDE.md, ADRs, lint/style rules>

## Contracts
<public APIs, types, schemas, error-handling conventions that must be preserved>

## Edge cases
<the specific cases the implementation must handle>

## Verification
<commands that must pass: typecheck, tests, lint>

## Out of scope
<explicitly excluded work, to prevent scope creep>

Return a complete diff. Do not refactor beyond the listed files.

Correction-loop template

Review round N. Fix only the items below; do not change anything else.

1. <file>:<location> — <what is wrong> — <what correct looks like>
2. ...

Re-run <verification commands> before returning the diff.

Hard rules

• Claude never writes implementation code in either mode. If Codex is unavailable, say so and ask the user whether to fall back to direct implementation.
• In Orchestrate mode, Codex never makes design decisions; reject unrequested design changes in a diff even if they work.
• In Advisor mode, Claude never pre-empts escalations or takes over the task; if the executor is failing badly, issue a stop signal and consult the user rather than silently switching modes.
• Every accepted result must have passed verification commands run by Claude, not taken on Codex's word.
• Corrections are deltas, not re-briefs.
• Declaring the goal met with an unmet invariant is the one prohibited move (see Method).