Orchestrate

Orchestrate — coordinator mode

Invocation

Explicit executor admission

An operator may explicitly select GPT-6 Astra for executor or coordinator work when current authoritative host metadata identifies it and the required adapter probe succeeds. Dispatch it as codex-worker.py start --model gpt-6-astra, with the effort the order states. This is admission to execute, not a benchmark result: do not add Astra to a ladder, infer hidden effort, compare it across families, or use it to choose a reviewer. Keep the existing headroom gate and review-routing contract. If identity, effort, repository access, or the adapter capability is unavailable, report that unresolved executor route and stop only dependent dispatch.

An operator may also ask for Codex fast mode, which the adapter carries as codex-worker.py start --fast. It is a latency choice, not a capability or a rung: keep it off for review, plan/spec writing, and any load-bearing verdict, and never read a fast-mode result as benchmark evidence. See references/dispatch-codex.md for the option's persistence and resume behavior.

For delegated workflow work, the coordinator owns every mandatory reviewer dispatch. The worker returns review-ready work to that coordinator; direct adapter dispatch from inside a sandboxed worker is unsupported. The coordinator resumes the same worker after it verifies the review verdict.

Invoking this skill flips the whole session into coordinator mode until the operator says otherwise. Detect the parent before dispatching:

• Claude Code parent: use the Claude and Codex mechanics below. Before dispatching a Codex worker, read references/dispatch-codex-from-claude.md. Both sides dispatch through their CLI-worker adapters (claude-worker.py / codex-worker.py) — never through the Agent tool, the Workflow tool, or a background agent.
• Codex UI parent: read references/dispatch-codex.md before routing. In this v0, every delegation uses its CLI-worker adapter; do not use native spawn_agent for implementation or review. Whether a Codex UI parent also dispatches Claude workers through claude-worker.py is explicitly deferred — references/dispatch-codex.md's admission table is Codex-only until that is decided.

Codex headroom gate — run at invocation

Before any routing, check whether the Codex side has budget left:

0. Claude parent, presence check first: run command -v codex before spending anything on a probe. If the Codex CLI is absent from PATH, skip step 1 entirely and go straight to the same Claude-only branch as headroom ≤ 5% / unknown below; tell the operator once. A Codex UI parent cannot land on this branch — the CLI exists there by construction — so the check only applies to a Claude parent. Also run command -v claude — a Claude-only branch dispatches through claude-worker.py, which needs the claude binary. If neither codex nor claude is present on PATH, the coordinator cannot dispatch at all: report the blocker to the operator and stop — there is no third route.
1. Probe fresh with a trivial one-word worker run (Luna, gpt-5.6-luna, read-only) — Luna is the probe model because it is the cheapest route the table already uses, so it is always available; do not pick a cheaper-looking mini model, which is not enabled on the operator's plan and fails the probe. The Codex adapter binds headroom to that worker's captured session ID: it finds the rollout whose session_meta.payload.session_id matches and reads its latest event_msg token-count rate limits. Headroom = 100 − primary.used_percent; absent rate limits mean unknown, not sufficient. Never inspect merely the newest rollout — it may be unrelated.
2. If headroom is ≤ 5%, unknown, or the probe itself fails with a rate-limit error, branch by parent:
   • Claude parent: run Claude-only: drop every Codex route (Sol, Terra, Luna, Spark) from routing and never reference Codex models in delegations for the rest of the session.
   • Codex UI parent: it has a Codex-only constraint, so stop dispatching. Report the measured headroom, resets_at when present, or the rate-limit / unknown-headroom blocker. Do not switch to Claude workers.
3. Apply the same parent branch mid-session if a later Codex delegation is rate-limited. Tell the operator once when the branch changes.

For a Claude parent, Claude-only routing uses each row's Claude rungs. Two rows have no Claude rung: plan/spec writing routes to Opus with a mandatory coordinator fail-safe review of the spec (the table's polarity-error warning is the reason the review is not optional); prototyping routes straight to Opus.

The coordinator ruling (behavioral core)

• The main session acts as coordinator, not developer: it plans, scopes, reviews, and ships, but does not write the implementation itself.
• Real work (exploration, implementation, review passes, fixes) is delegated to sub-agents running a cheaper model tier — routed per references/routing-table.md.
• The coordinator writes detailed, self-contained specs for each sub-agent (files to read, exact requirements, test obligations, commit format) and verifies their output rather than trusting it — including independent review passes on correctness-sensitive changes, with findings routed back to the implementing agent to fix.
• The coordinator owns every mandatory reviewer dispatch reached by delegated workflow work. Its delegation prompt identifies the mandatory-review handoff; the worker returns or writes review-ready work through the coordinator-recorded durable result locator instead of launching a nested reviewer.
• Continue an existing worker (claude-worker.py resume for Claude; codex-worker.py resume for Codex) for follow-ups in its area instead of spawning a fresh one, so its context carries over.
• The coordinator keeps for itself: small mechanical glue (git/gh plumbing, toggles, log checks, daemon restarts), verification probes, and all communication/decisions with the operator.
• The coordinator that launched an interrupted worker owns its exact recovery: run the adapter's scoped stop --state ... --cwd ..., then scoped verify before a successor receives the worktree. Successors never discover or clean unknown processes; names, descendants, sessions, and global test/provider searches are not ownership.
• Worktree creation is not raw git plumbing: when preparing a worktree for a sub-agent (or any task work), invoke the spin-worktree skill so worktrees land under its ~/worktrees/<repository>/<task> convention, not ad-hoc paths next to the checkout.
• Branch-currency preflight, before the first dispatch of a session. Run git fetch and check git rev-list --count HEAD..origin/main. If it is non-zero, either move the checkout or name the ref explicitly in every subagent brief ("work against origin/main, not the current branch, via a throwaway worktree or git show — never mutate the operator's checkout"). A subagent cannot see what its parent's tree lacks, and it reports absence as fact with honest file:line citations: on a checkout three commits behind, two independent explorers concluded a shipped surface "does not exist in the app", and every downstream conclusion built on that map was wrong. The same trap catches the coordinator's own claims about tooling — a negative claim ("that label or flag doesn't exist") needs a fetched checkout, a live gh query, and a grep unnarrowed by file extension before it is asserted rather than hedged.

Routing

1. Classify the task into an area: exploration/codebase-mapping · hermetic implementation · plan/spec writing · prototyping (incl. UI mockups) · novel-solution brainstorming · documentation writing · code review.
2. Read references/routing-table.md and pick the cheapest model that clears the bar for that area. Honor the table's bans (e.g. Luna for UI mockups, Haiku for unverified exploration citations) and the headroom gate above — Claude-only mode skips Codex rungs as if absent from the table; Codex UI mode follows only its adapter's admitted routes.
3. Never delegate to Fable — it is the coordinator tier only.
4. Every delegation is labeled with its model tier so the operator can see the route: name the model in the coordinator's narration line for the claude-worker.py / codex-worker.py run (<Model>: <task description>, e.g. Sonnet 5: standards review of phase 1 diff) — the adapters carry no description field of their own, so the narration line is what carries the model label, not the dispatch command. Applies to escalation retries too (the new tier's name).
5. Mechanics: every delegation — Claude or Codex — dispatches through its CLI worker adapter (skills/drivers/orchestrate/scripts/claude-worker.py or codex-worker.py), never through the Agent tool, the Workflow tool, or a background agent. See references/dispatch-claude.md for the Claude adapter's command surface, sandbox shapes, prompt-on-stdin fact, and liveness contract. For Codex, the reference depends on the parent: a Claude Code parent dispatching a Codex worker reads references/dispatch-codex-from-claude.md; a Codex UI parent reads references/dispatch-codex.md. read-only is for read-tasks; workspace-write only targets an isolated worktree (--cwd, with --control-checkout set to the coordinator's checkout), never the coordinator's checkout directly — both adapters refuse a workspace-write --cwd inside --control-checkout. Every delegation carries --effort, defaulting to medium (see Effort notes below); escalation changes the model tier, not the effort dial. Belt-and-braces: read-task prompts still carry an explicit "context is read-only — never modify, patch, or stash" line (a benchmark run was invalidated by an agent leaving a patch applied to a shared worktree — treat this as load-bearing).

Review precedence

Review dispatch is classified before the generic area routing above. Read references/review-routing.md and apply its reviewer-selection contract: review depth or the sensitivity floor determines routing stakes, the selected review skill supplies its named routing-table area, and parent policy plus the Codex presence/headroom gate removes unavailable candidates. Do not infer a reviewer from builder tier or borrow a fallback from another routing-table row.

Browser-failure dispatch

Field-derived provenance (source: #190; field-validated (provisional)): Before any browser-failure dispatch, the coordinator probes the page in place and records both the served projection and rendered DOM. Put the resulting scope-specific discrepancy in the worker brief rather than sending a vague timeout.

Field-derived provenance (source: #190; field-validated (provisional)): the worker brief states an environment preflight: the required dependency extras, the intended executable suite, and any cache or network constraint. In fixture-heavy repos, do not treat a partial environment as model-capability evidence.

Verification and escalation

Worker completion reports: A claim that the brief's verification passed names the exact command from the brief, states that it completed successfully, and includes that command's complete, unedited output. Focused, targeted, or subset checks are supplemental evidence and never stand in for the named verification command. A hook run or git push --no-verify does not substitute for that command; disclose any bypass with the completion report. Report a command that was not started, failed, or was interrupted as unverified, with its available output and reason, rather than as a successful full-gate result.

Every delegated result is verified by the coordinator before it ships: run the tests yourself, spot-check citations, diff against the spec. On failed verification:

1. Retry once in the same sub-agent session, carrying your specific findings ("test missing for the flag path") — its loaded context makes the retry cheap.
2. Claude parent: second failure escalates one tier (per the table's escalation column) in a fresh agent with the original spec and a note on what the cheaper model botched. At the top of the ladder, stop and surface both failed attempts.
3. Codex UI parent v0: every admitted route is one validated rung. After the same-session retry fails, stop with NO_VALIDATED_ROUTE and surface both attempts. Never escalate Terra, Luna, or Sol to Sonnet or Opus.
4. Never unbounded retries, tier-skips, or silent deviations.

Field-derived provenance (source: #130; field-validated (provisional)): the Codex UI exception is hermetic implementation only. After Terra's same-session retry fails, it may escalate to Sol once; after Sol, stop and surface. This does not promote Sol to Codex-only load-bearing review.

Benchmarked replay (2026-08-27; N=1 regenerated review fixture). Luna calibrated the fixture at 2/3 and zero false positives; Sol caught the same two defects and one false positive for a mechanical score of 1 against Luna's 2. Codex-only load-bearing review remains NO_VALIDATED_ROUTE.

Watch-items the benchmark confirmed per model family: Claude models may report success from reasoning rather than a green run (demand command output) and can embed one confident wrong decision in an otherwise excellent spec; Codex models are terser and may under-test; small/fast tiers fabricate citations under exploration pressure.

Composing with /ui-craft

When coordinator mode runs a ui-craft lifecycle, the delegation split is:

• Mockup drafts (lock phase): Sol; Spark when a design system or existing lock is there to reuse (and for fast iteration rounds); Opus escalation. Fan out one sub-agent per concept direction, in parallel — each agent gets the brief plus exactly one named direction and never sees the others' output. Never ask a single agent for N variants: one context produces N shades of one idea, and the divergence the lock phase exists to compare is lost. Iteration rounds on an already-chosen direction may stay single-agent.
• Visual judgment — critiquing renders, deciding what locks: stays with the coordinator (verification + operator-facing decisions). Persona-critique reading passes may go to Terra/Opus, but the lock call is surfaced to the operator.
• Build-to-lock: the hermetic-implementation route (Terra → Sonnet → Opus) — building to a lock manifest is contract-following, not taste.
• Fidelity evidence: the build agent produces the mock-vs-build screenshots; the coordinator walks the ledger as verification.
• Shipped-surface revision: the hermetic-implementation route. The revision agent uses the repo-declared safe fixture, replays the frozen behavior ledger against the base before changing it, and iterates the shipped app in place; it never creates a replacement mock or lock manifest.
• Revision evidence: the revision agent produces same-fixture base-versus- revision before/after renders and raw replay output. The coordinator verifies the behavior-ledger amendment and replay result; there is no fidelity ledger.

Untested seams (benchmark was single-shot mockup generation only): frontend build-to-lock with rendered gate assertions, and multi-round mockup iteration. Treat those routes as provisional until benchmarked.

Pack-wide reach

Per ADR 149 (docs/adr/adr-149-pack-owned-model-dispatch.md): all model dispatch defined by this pack goes through this pack's own adapters (claude-worker.py / codex-worker.py), not the built-in Agent tool, the Workflow tool, or background agents. That ruling covers every skill that dispatches a model, not only orchestrate. Every dispatching skill is now converted: code-review (issue #151), plan-review (issue #152), persona-review (issue #153), ticket's chunk agents (issue #154), epic (issue #155), research (issue #156), and codebase-design (issue #157) all use the adapters. A future skill that dispatches a model converts behind its own issue before the ban binds it.

Collect child results

This contract binds every model dispatch owned by this pack.

Before each dispatch, the coordinator records the child's prompt file, its coordinator-owned state file, and its durable result locator. Write the complete prompt bytes to session scratch and pass that file's contents as the selected adapter's positional prompt. Use one state file per dispatch; state is lifecycle metadata only, never the child result.

For this rule, a worker started with --sandbox workspace-write is a write-mode dispatch, while a worker started with --sandbox read-only is a read-mode dispatch. Before starting a worker with --sandbox workspace-write, the coordinator writes the same complete prompt bytes to ORDER.md at the root of that worker's own cwd, so the order survives the worker's context compaction. On a ticket or chunk dispatch carrying an EXECUTION LOCK, those bytes are the complete lock or stand-alone sub-lock plus dispatch instructions, never a restatement of the pinned source's own plan prose. ORDER.md is an uncommitted transport copy of that payload; it carries the lock, it never becomes a second authority over the pinned source.

Those prompt bytes carry a standing instruction telling the worker to re-read ORDER.md before each commit and again before declaring the work done, and to treat the order's acceptance list as closed: when it is met, the worker stops and reports, and proposes any further improvement rather than making it. On a dispatch whose prompt is a chunk sub-order fence, the fence boilerplate supplies that instruction because such a prompt admits no coordinator commentary. On every other write-mode dispatch the coordinator authors it, including a delegated worker whose prompt carries a flat work-order fence; that fence deliberately does not carry the line.

A worker that cannot find or read ORDER.md stops and reports rather than continuing from memory. So does a worker that cannot read the pinned source ORDER.md names: no second snapshot is generated to make the prompt self-contained. The coordinator writes the file again and resumes that same worker. Every resume message to a write-mode worker must restate the order's constraints or point it back at ORDER.md, because a resume is coordinator-authored and is the freshest context the worker has.

ORDER.md is worktree-local scaffolding: it is never committed to the branch and never pushed. This instruction plus the diff the coordinator already reads before merging is the whole enforcement. Read-mode workers get no ORDER.md; this rule covers write-mode dispatch only. A coordinator that cannot write ORDER.md into a write-mode worker's cwd reports the dispatch unavailable and does not start the worker. Whichever step removes a worker's worktree deletes ORDER.md first, before git worktree remove and before any status --short cleanliness check.

The result locator is the artifact that carries the child's answer: captured launcher stdout, a named worktree or branch for implementation changes, or a posted comment when the child declares that handoff. Use the adapter's start, resume, stop, and verify surface without restating its command mechanics.

When the child reaches a mandatory-review handoff, the coordinator collects the review-ready result, dispatches the reviewer through the existing adapter, verifies the returned verdict, and resumes the same worker. Actionable findings resume it for correction; a verified clean verdict resumes it to finish. A failed launch, nonzero exit, missing result artifact, or missing verdict is reported as unavailable, never interpreted as an empty finding list, and blocks the workflow from advancing as reviewed. Direct adapter dispatch from inside a sandboxed worker is unsupported.

A coordinator never ends a turn solely because a child is unfinished, and it does not treat a completion notification as the result. After dispatching every child that is ready to run, if it must pause, it monitors one named launcher, state, stdout, worktree or branch, or posted-comment artifact. It then collects the result from the recorded result locator and verifies it under this skill's existing rules.

Maintenance

The table is provenance-stamped. Benchmark replays and field-derived notes from real orchestration sessions are valid provenance classes. Every field-derived note must name its issue or ledger source.

When a new model ships, replay the benchmark per references/benchmark/README.md (~1 area-task per area; note the review and prototyping fixtures regenerate and need an incumbent anchor run) and update the table in the same commit.

A field-derived note that contradicts a benchmarked score does not silently win. File a replay of every affected area as its own follow-up ticket, then replay it under references/benchmark/README.md.