Orchestrate

<p align="center"><img src="assets/architecture.svg" alt="orchestrate (Codex): an active GPT-6 Astra or GPT-6.1 Sol session leads; Astra keeps the hardest reasoning in the lead, Sol escalates unusually difficult units to Astra, and both route bounded work to lower tiers and can reach a Fable cross-vendor peer" width="900"></p>

Preflight the lead runtime first

Before reading the task brief, inspecting the workspace, planning, or delegating, resolve SKILL_DIR as the directory containing this SKILL.md and run:

"$SKILL_DIR/scripts/check-lead-runtime.sh"

This verifies the current thread through CODEX_THREAD_ID, its latest turn_context, and any recorded reroute. Proceed when it reports gpt-6-astra or gpt-6.1-sol and the actual effort. Preserve the user's selected effort; xhigh is not required. Missing runtime metadata, another lead model, or a current-turn reroute blocks the workflow. Report the exact failure and ask the user to select Astra or Sol in /model while keeping their chosen effort. Do not infer the current runtime from configuration defaults, the newest session file, or model self-identification.

Act as the lead orchestrator: own decomposition, coupled decisions, integration, and final verification. Use the mode reported by the gate:

• Astra-lead mode: keep compact hard reasoning and judgment in the lead. Delegate for width, isolation, execution, or an independent line.
• Sol-lead mode: keep planning, coordination, integration, and routine decisions in the lead. Escalate compact hard reasoning or unusually consequential GPT-side judgments to a fresh Astra worker. Use structured fan-out when width, isolation, or context pressure justifies it.

The mode is detected, not claimed. Plain $orchestrate works from either supported session; it cannot change the running model.

Optional Jev routing (--route)

$orchestrate --route <task> asks Jev for an experimental pre-work plan: which lead and effort, and which workstreams go to Luna or Sol workers, Astra reasoners, or a Claude cross-check. Jev is the default and only supported provider (--route jev <task> is equivalent). --effort auto is implicit for routing; a user-specified effort or model pins the lead and takes precedence. Parse --route, --verify, optional provider names, --model, and --effort from the invocation prefix before the task, so $orchestrate --route --verify <task> enables both against the same task. Without --route, follow this skill's normal routing rules and make no Jev route call.

After the lead-runtime preflight, when routing is requested, read ${JEV_VERIFIER_HOME:-$HOME/.local/share/oss-experiments/jev-verifier/current}/ROUTE.md and follow its availability, disclosure, and checkpoint instructions, with harness: codex. Use advisory mode for this explicit route request. One request sends only the task's objective, acceptance criteria, and scope constraints; Jev answers six questions about the task, and the runtime maps them to executors locally, so no model name is sent. Report the lead exactly as the preflight verified it, and mark an executor available only where this session can launch it with the requested permissions — inspect the live spawn_agent schema and the availability of any CLI path. Record your own plan first, then show the proposed plan beside it and let the user change it before dispatch. Apply proposed items; decide review items yourself; never launch an unavailable item under another executor. For NOT_CHECKED, run your own plan and say Jev did not shape it. The recommendation never changes the current lead's model or effort; a different lead requires a new session. Jev routing is an uncalibrated experiment, not proof the plan is optimal.

Optional Jev verification (--verify)

$orchestrate --verify <task> adds Jev completion verification; $orchestrate --verify jev <task> is an explicit equivalent. Jev is the default and only supported provider. Without this option, do not run Jev verification. --route and --verify are independent and composable: route first, execute, then verify. Neither option is a flag to the Codex executable.

After the lead-runtime preflight, when verification is requested, read ${JEV_VERIFIER_HOME:-$HOME/.local/share/oss-experiments/jev-verifier/current}/ORCHESTRATE.md and follow its checkpoint instructions alongside this skill. If the shared verifier is missing or credentials are unavailable, report that verification is blocked; never silently substitute a mock or claim a Jev check passed. This opt-in permits the documented, minimized Jev API requests, not arbitrary data export or automated repair.

Model and effort calibration

Inspect the actual spawn_agent schema and session permissions before selecting a route. If model and reasoning overrides are exposed, use them with a self-contained brief and the supported fork_turns value ("none" where available). Full-history forks may require inheritance. If overrides are unavailable, native workers inherit the lead; use explicit CLI one-shots for other tiers only when the environment permits them.

Role	Default	Use
Lead	active gpt-6-astra or gpt-6.1-sol, current session effort	Decomposition, coordination, integration, and final review.
Premier worker	gpt-6-astra, high or xhigh	Compact hard reasoning under a Sol lead, or an unusually difficult independent unit under either lead.
Demanding worker	gpt-6.1-sol, high	Separable difficult reasoning, implementation, and review under an Astra lead; parallel width under a Sol lead.
Bounded worker	gpt-6.1-sol, medium	Independently checkable research, diagnosis, implementation, or verification; raise to high for a difficult unit.
Mechanical worker	gpt-6-luna, high	Fully specified, high-volume tasks with objective checks: extraction, classification, structured summaries. OpenAI's starting effort for Luna is high.
Cross-vendor peer	scripts/claude-peer.sh	A separate Claude review for difficult, consequential judgments. Different vendors can still share errors.

Prefer a native worker when it supports the required model and interaction. Use a self-contained brief with fork_turns="none": choose Astra/high or xhigh for a premier worker, Sol/high for demanding or wide work, Sol/medium for bounded work, and Luna/high for mechanical work. Full-history forks inherit the lead in runtimes that prohibit overrides; do not use them for model routing. Keep routine work local when briefing and integration cost more than execution. Otherwise, a bounded read-only CLI call can use:

codex exec --model gpt-6.1-sol -c model_reasoning_effort=medium \
  --sandbox read-only --skip-git-repo-check "<self-contained brief>" < /dev/null

Close stdin when the prompt is an argument; when supplying a prompt file, redirect that file instead. Use --output-last-message <new-file> for the final response. Use workspace-write only for authorized implementation and assign disjoint paths.

Headless execution and approval never do not by themselves prohibit nested calls. The parent sandbox, network access, authentication, and available tools determine what works. Earlier restricted macOS/Linux runs failed on nested Codex initialization; a child cannot relax its parent's restrictions. Use already authorized permissions, request escalation only if the runtime permits it and the task needs it, and report unavailable delegation without inventing a worker response.

Keep briefs and returned evidence compact. Delegate only when the isolation, parallel work, or lower worker cost justifies briefing and integration. Start with the chosen effort; change it only for a demonstrated need using mechanisms the runtime supports. Do not infer current cache behavior from old CLI experiments.

Delegation gate

Use subagents only when the user explicitly invokes $orchestrate or requests orchestration, delegation, fan-out, parallel agents, or independent agent review. If loaded implicitly without that authorization, work locally.

Show the route

Before spawning work, publish a compact plan that names each workstream, owner role, dependency, expected artifact, and acceptance check. Update it as dependencies or evidence change.

Choose the execution topology

For each workstream, choose both its owner/model/effort and the execution form before dispatch. Normal $orchestrate uses the rules below; --route adds Jev's independent recommendation but does not bypass runtime capability checks or user constraints.

• Keep work in the lead when it is tightly coupled, trivial, or cheaper to complete directly.
• Use native spawn_agent workers for bounded work that benefits from model/effort overrides or parallelism and can safely share the current checkout. Inspect the live tool schema and permissions; only request controls the runtime actually exposes.
• Use a one-shot CLI call for a brief, self-contained task that needs another model but no follow-up, persistent context, or editable worktree. A different model alone does not require a worktree if a native worker or one-shot supports it.
• Work that must outlive this session needs its own session, which this skill does not launch; tell the user rather than pretending a worker will survive.

Never create nested agent cascades solely because a router named more models. Add delegation depth only when the work decomposes into independently contractable units and the coordination cost is justified. If a requested model/effort cannot be applied, do not relabel an inherited-default worker as a routed choice.

Route by first match

Apply the first matching row using the detected lead mode. Use native model overrides where supported; otherwise use permitted CLI one-shots.

Priority	Work type	Owner
1	decomposition, architecture ownership, integration, conflict resolution, user communication	lead
2	trivial, single-step work where briefing costs more than execution	lead
3	high blast radius and hard to verify	two blind lines: Claude plus Sol under an Astra lead; Claude plus Astra under a Sol lead; then the lead adjudicates the evidence (see the high-stakes path)
4	compact hard reasoning — one architecture call, gnarly debug, or hard trade-off	Astra lead: keep it; Sol lead: send a self-contained premier-worker brief to Astra, then integrate and verify
5	bounded research, inventory, or diagnosis with no overlapping writes	Sol/medium worker; Sol/high for a difficult unit
5a	difficult reasoning that separates into independent units	Astra lead: Sol/high workers; Sol lead: Sol/high workers for width and Astra for the hardest unit; Sol/medium for ordinary units
6	fully specified implementation with objective acceptance checks	Sol/medium worker; Luna only if the work is purely mechanical and carries no material judgment
7	verification, tests, review, or adversarial challenge of an existing artifact	Sol/medium for routine verification; Sol/high for demanding or adversarial review
8	ambiguous or tightly coupled work that cannot be cleanly contracted	lead until separable

High blast radius includes security/authentication, destructive data operations, public API compatibility, concurrency, cryptography, production incidents, privacy, and externally visible irreversible changes. "Hard to verify" means no cheap test, authoritative lookup, reversible experiment, or inspectable artifact can settle the answer.

Parallelize independent work or genuinely independent judgments. Account for briefing and integration overhead as well as the worker model’s cost.

Consult the Claude peer

# read-only consult — ask a question / get a second, cross-vendor opinion; prints the answer
scripts/claude-peer.sh -C "$PWD" \
  --prompt "Reply with exactly one word and nothing else: PONG"

The path is relative to this skill's own directory, the same convention codex/advisor uses for scripts/sol-advisor.sh — Codex resolves it when the skill is loaded, and there is no Codex-side equivalent of Claude Code's ${CLAUDE_PLUGIN_ROOT}. For a long turn, run it via a backgrounded shell call plus --out <file> and read that file when it returns, the same discipline as a CLI worker, so a multi-minute Claude turn never blocks the lead.

Spawn subagents correctly

Use task_name for a stable identifier and message for the complete brief. Pass the minimum context the task needs through fork_turns; choose "none" for an independent review when supported. Set model and effort only through fields actually exposed by the tool. If the tool only supports inheritance, state that the child uses the lead's model and effort.

Role	Behavior	fork_turns
analyst / verifier	inspect, inventory, diagnose, adversarially review, or high-stakes cross-check without editing	minimal — pass only the artifact path and the specific question, not the lead's full history
implementer	make bounded, fully-specified edits with objective acceptance checks and run them	minimal — a complete delegation contract (below) should make full history unnecessary
high-stakes independent check	two agents spawned in the same round on the identical prompt, blind to each other's reasoning	minimal, identical for both, so neither is anchored by the other

All agents share the same container, filesystem, and working directory as the lead — edits by one are immediately visible to all others, including the lead. This makes the write-collision discipline below load-bearing, not optional.

Respect the concurrency limit reported by the current runtime; batch additional work after earlier agents finish.

Use wait_agent to block on a spawned agent's result, send_message to pass it a message without triggering a new turn, followup_task to give an existing agent a new task and wake it if idle, list_agents to check what's active, and interrupt_agent to reclaim a stalled one.

Write a delegation contract

Every subagent brief (the message passed to spawn_agent) must specify:

Objective:
Inputs and authoritative paths:
In scope:
Out of scope:
Constraints and invariants:
Write ownership:
Expected artifact:
Acceptance checks:
Return format: conclusion, evidence, changed files, residual risk

Give each worker the minimum task-local context required. Do not leak another worker's conclusions into an independent round. Demand a checkable artifact, not a verdict — a test that runs, a diff that applies, a cited line, a reproduction — plus the worker's confidence and an explicit "what would make this wrong" note. A task that cannot produce a checkable artifact is the signal that it belongs on the high-stakes path instead of with a single worker. Unspecified design decisions route back up to the lead; they are never guessed down by a cheaper tier.

Prevent write collisions

• Assign disjoint files or directories to concurrent implementers; never let two agents edit the same file concurrently.
• Use read-only agents for overlapping analysis or review.
• State that the shared workspace may change while an agent runs; require rereading before edits.
• Out-of-band CLI one-shots that run --sandbox workspace-write edit the shared tree too; give them disjoint paths like any implementer.
• Preserve user changes and unrelated worktree modifications.
• Keep commits, pushes, deployments, destructive operations, and external messages under the same authorization rules as the lead.

The lead owns shared configuration, interfaces between workstreams, and final integration unless one bounded owner is explicitly assigned.

Run the orchestration loop

1. Inspect authoritative workspace state.
2. Decompose work and identify dependencies.
3. Publish the route and acceptance checks.
4. Start all ready, independent workstreams concurrently using the detected mode — Astra when a Sol lead needs a premier reasoning shot, plus Sol/high, Sol/medium, or Luna/high workers as the task warrants — and a backgrounded claude-peer.sh call for any high-stakes line needing a cross-vendor check. Use CLI one-shots only when native routing is unavailable.
5. Continue useful lead work while agents run; do not duplicate delegated work.
6. Use wait_agent to consume each agent's final response and inspect its artifact directly.
7. Send a focused followup_task to the same agent when its artifact is incomplete, rather than spawning a fresh one that repeats the briefing cost.
8. Integrate in dependency order.
9. Run end-to-end checks at the lead level.
10. Report the outcome, verification evidence, and unresolved risk.

Send concise progress updates during long work so the user is not left without visibility.

Use the high-stakes path

For work that is both high blast radius and hard to verify:

1. Launch two blind lines on the identical prompt in the same round: claude-peer.sh plus a Sol worker under an Astra lead, or claude-peer.sh plus an Astra worker under a Sol lead. The pairing crosses vendor and model tier. Two workers from one model provide separate samples, not independent model families. If claude is unavailable, use the designated GPT worker alone and say plainly that the cross-vendor check could not run.
2. Keep every line blind to the others' reasoning — do not relay one's output into another's task.
3. Compare assumptions, evidence, and failure modes, not tone or confidence. Resolve disagreements through evidence, not model tier or provider.
4. Accept agreement only when the lines point to the same checkable evidence.
5. On substantive disagreement, run one targeted reconciliation round where each can see the competing reasoning.
6. If disagreement survives or evidence remains insufficient, stop and ask the user; do not break the tie by confidence.

If the environment cannot run a separate reviewer, report that limitation; do not present a lead-only answer as independently checked. Use one worker plus a direct verification step when the task is high impact but cheaply verifiable.

Integrate rigorously

Treat subagent results as untrusted until inspected. Check:

• the artifact exists at the claimed path;
• the diff matches the assigned scope;
• interfaces agree across workstreams;
• tests cover the requested behavior rather than a narrower substitute;
• no unrelated user changes were overwritten; and
• any assumption presented as fact has authoritative support.

Read each deliverable as the domain expert the lead is, not just as a checklist. A cheaper tier 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 rather than shipping the worker's summary as-is.

Two named failure modes bracket this step. Fragmentation: locally correct pieces conflict once stitched together — revise the contracts or the integration layer, and do not paper over incompatible assumptions. Over-trusting the lead's own line: an Astra lead can skip the independent check because it expects to be strongest; a Sol lead can rubber-stamp an Astra worker because it expects the higher tier to be right. On a high blast radius call the lead cannot cheaply verify, run the decorrelated line and weigh the evidence — do not decide by model rank, fluency, or agreement alone.

Completion rule

Complete only when every requested deliverable has authoritative evidence, integrated behavior passes proportionate checks, and remaining risks are disclosed. Agent completion messages are not proof of overall completion.

Failure handling

• If an agent stalls, use interrupt_agent to reclaim it, then send one narrower followup_task or reassign.
• If an agent fails after editing, inspect the shared worktree before retrying.
• If the runtime’s concurrency capacity is exhausted, queue dependent work rather than spawning redundant agents.
• If a spawn fails outright, report the exact error rather than silently falling back to doing the work in the lead context — a silent fallback is what causes runaway lead-context token growth. If the failure is environmental, use an available authorized route or report the limitation and continue useful local work.
• If claude-peer.sh fails with "claude CLI not found," the cross-vendor peer is unavailable here — report that and use the mode's designated GPT worker alone, stating explicitly that the fallback is same-vendor and weaker. Do not silently skip the second line.
• claude-peer.sh needs no < /dev/null redirect the way codex exec does (claude -p reads its prompt from the argument and exits after one turn), but it does need claude authenticated in the environment the lead's shell can see; if the peer call errors immediately, check auth before assuming a task-brief problem.