git:20260728.ab5edc5 to git:20261013.fbe187d

- description: "Cross-runtime Orchestrator/Executor — Fable/Opus writes a goal file, GPT-5.6 Sol (codex) or a Sonnet subagent executes it, Fable/Opus verifies against acceptance criteria before reporting done."

- - Workflow

- ---

-

- # $ccc-orchestrate — Cross-Runtime Orchestrator/Executor

-

- Orchestrate splits work across **two different model runtimes**, not just two tiers of the same one. A capable model (**Fable 5** or **Opus 5** — the calling session, i.e. "you") compresses a fuzzy request into a tight, testable **goal file**. Execution then happens **outside this runtime entirely** — on **GPT-5.6 Sol via the `codex` CLI**, or on a **Sonnet subagent** if codex isn't available. The orchestrator never writes production code itself.

-

- **CC Commander** · Cross-Runtime Orchestrate · [Docs](https://commanderplugin.com)

-

- > This is `$ccc-plan-exec` generalized past Claude-only: instead of plan (cheap Claude) → execute (capable Claude), it's plan (Fable/Opus) → execute (a *different runtime* — GPT-5.6 or Sonnet). The goal file is the interface between the two systems, so it has to have real teeth.

-

- ---

-

- ## Why cross-runtime

-

- Fable/Opus is expensive per token but excellent at compressing a fuzzy request into a tight, unambiguous spec. GPT-5.6 Sol at high/xhigh reasoning is a strong, comparatively cheaper implementer for well-specified work. The split only pays for itself if the goal file is genuinely load-bearing — vague or hand-wavy acceptance criteria collapse the whole advantage, because the orchestrator ends up re-explaining the task on every re-dispatch anyway. Write the goal file as if the executor has zero conversational context, because on the codex path it does.

-

- **Model guidance (GPT-5.6 family, `commander/adapters/codex/models.js`):** default the executor to **Sol** for real implementation work (deep dev — flagship reasoning). Drop to **Terra** for balanced, well-specified tasks where Sol's extra reasoning wouldn't change the output. Reserve **Luna** for cheap, mechanical steps (renames, boilerplate, formatting) inside a larger loop — never for the primary executor role.

-

- ## The two roles

-

- 1. **Orchestrator (Fable 5, effort high, or Opus 5 — this session)** — reads the request, asks clarifying questions if the scope is fuzzy, and writes a structured **goal file** to disk. Never edits production code in this mode.

- 2. **Executor (GPT-5.6 Sol via codex, or Sonnet subagent)** — reads the goal file verbatim as its entire brief and implements it. Does not re-plan, re-scope, or renegotiate the acceptance criteria.

-

- The orchestrator resumes after execution to **verify against the goal file's done-when checklist**, not to re-review the diff from scratch.

- ---

- ## The goal file

- A Skill.md-shaped markdown spec saved to a scratch path — use the session's scratchpad directory if available, else `/tmp/ccc-orchestrate/<slug>.md`.

- ```markdown

- ---

- goal: <slug>

- created: <ISO date>

- orchestrator: fable-5 | opus-5

- executor: codex-gpt-5.6-sol | codex-gpt-5.6-terra | codex-gpt-5.6-luna | sonnet-subagent

- ---

- # Goal: <one-line outcome>

- ## Context

- <the minimum the executor needs — no more>

- ## Steps

- 1. <concrete, ordered step>

- 2. <concrete, ordered step>

- ...

- ## Files in scope

- - path/to/file.ts — <what changes>

- ## Files explicitly out of scope

- - path/to/other.ts — <why it must not change>

- ## Done-when (acceptance criteria)

- - [ ] <testable, verifiable condition>

- - [ ] <testable, verifiable condition>

- - [ ] `npx tsc --noEmit` passes (if TS project)

- - [ ] Tests green: `<exact command>`

- ## Explicitly NOT required

- - <anything that might look tempting but is out of scope>

- ```

- Each acceptance-criteria line must be checkable by reading a diff or running a command — not a vibe. "Code is cleaner" is not a criterion. "`grep -c 'TODO' src/foo.ts` returns 0" is.

- ---

- ## Executor picker

- Check codex availability before offering it:

- ```bash

- which codex

- ```

- Call `AskUserQuestion`:

- ```

- question: "Who should execute the goal file?"

- header: "Orchestrate Executor"

- multiSelect: false

- options:

- - label: "🤖 GPT-5.6 Sol via codex (recommended if installed)"

- description: "Shells out to the codex CLI with model=gpt-5.6-sol — flagship deep-reasoning tier. Different runtime, different failure modes than Claude — good adversarial diversity."

- preview: "Only offered when `which codex` succeeds. Terra/Luna available for lighter steps — see model guidance above."

- - label: "🎯 Sonnet subagent"

- description: "Stays in-Claude. Use when codex isn't installed, or you want a single-vendor audit trail."

- preview: "Dispatched via Workflow/Agent, model=sonnet, goal file as its full prompt."

- ```

- If `which codex` fails, don't show the codex option — just note in your response: "codex CLI not found (`which codex` failed) — executing via Sonnet subagent instead."

- ---

- ## Isolation (MANDATORY before any executor dispatch)

- The executor never touches the main tree directly (Fable Pillar 5). Before dispatching codex or the Sonnet subagent:

- ```bash

- git worktree add .claude/worktrees/<goal-slug> -b goal/<goal-slug>

- ```

- - Run the executor with **cwd = that worktree** (codex: spawn with the worktree as working directory; Sonnet: state the worktree path as the only edit root in the prompt).

- - The goal file's first step for the executor is always: `git rev-parse --show-toplevel` must equal the worktree path — **abort if not**. Relative paths only from there.

- - Never hand the executor the main repo's absolute path as an edit target.

- ---

- ## Execute phase

- **Codex path** — build args via the real adapter interface in `commander/adapters/codex.js` (`adapter.buildArgs(prompt, opts)`), do not invent flags it doesn't expose:

- ```js

- const codex = require('./commander/adapters/codex.js');

- const args = codex.buildArgs(goalFileContents, { model: 'gpt-5.6-sol', approval: 'full-auto' });

- ```

- `buildArgs` currently supports `model`, `approval`, `allowedTools`, `quiet` — there is **no documented reasoning-effort flag** in this adapter today. If xhigh reasoning on codex is needed, that's a TODO to add to `commander/adapters/codex.js`, not a flag to guess at. Pass the goal file's full contents as `prompt`.

- **Sonnet path** — dispatch through the Workflow tool's agent equivalent, `model: sonnet`, with the goal file's contents as the entire prompt. No additional framing — the goal file already has context, steps, and scope.

- ---

- ## Verify phase (mandatory)

- Back in the orchestrator session, read the executor's diff/output and check it line-by-line against the goal file's done-when checklist:

- - ✅ All boxes checkable and true → report done.

- - ❌ Any box unmet → **re-dispatch the executor with the specific gap only** ("criterion 3 unmet: tests still fail on X — fix that, do not touch anything else"). Do not re-plan the whole goal file and do not let the executor decide what "close enough" means.

- - 🧹 **Isolation check (always):** `git -C <main-repo> status --porcelain | grep -v '^??'` must be EMPTY — the executor's work lives only in its worktree branch. Any tracked change in the main tree is a leak; stop and reconcile before reporting done.

- If the goal needs repeated re-dispatch until criteria hold (a convergence loop, not a one-shot), run the verify cycle as a `/goal` loop from the ccc-loop taxonomy — it gives you the gate + iteration cap for free instead of hand-rolled retries.

- Report back:

- > 🧭 **Orchestrate: goal file at `<path>`, executed by `<codex-gpt-5.6-sol|codex-gpt-5.6-terra|codex-gpt-5.6-luna|sonnet-subagent>`.**

- > Done-when: N/M criteria met.

- > <if gaps: re-dispatching with the specific gap · if clean: ✅ all criteria verified>

- ---

- - `$ccc-plan-exec` — same idea, Claude-only (cheap Claude plans, capable Claude executes). Use that when you want to stay in one vendor.

- - `$ccc-handoff` — use if the orchestration spans enough turns that context grows large; write a handoff doc before compacting rather than losing the goal file's state.

-

- ---

-

- ## Anti-patterns — DO NOT

-

- - ❌ Let the executor re-plan or renegotiate the goal file — it executes the steps as written; scope changes go back through the orchestrator

- - ❌ Skip the acceptance-criteria verification step — "the executor said it's done" is not verification; read the diff against the checklist yourself

- - ❌ Invent a codex CLI flag (like a reasoning-effort flag) that isn't in `commander/adapters/codex.js` — check the adapter first, file a TODO if it's missing

- - ❌ Use this for a single trivial edit — the goal-file overhead only pays off when there's real ambiguity to compress; for a one-liner, just do it inline

- - ❌ Re-plan from scratch on a failed verification — re-dispatch with the specific unmet criterion, not a fresh goal file

- - ❌ Offer the codex executor option without confirming `which codex` succeeds first

-

- ---

-

- **Bottom line:** orchestrator (Fable/Opus) compresses fuzzy intent into a goal file with teeth; executor (GPT-5.6 Sol via codex, or Sonnet) implements it in a different runtime; orchestrator verifies against the checklist before calling it done. Pay for Fable/Opus on the thinking, not the typing — and don't let the typing runtime decide what "done" means.

-

- ---