Imported from Cjbuilds/Codex-Orchestration (plugins/codex-orchestration/skills/codex-orchestration/SKILL.md). Install upstream with npx skills add Cjbuilds/Codex-Orchestration --skill codex-orchestration. Copyright stays with the author.

Codex Orchestration

The model selected when this Codex task started is already the orchestrator. Never ask the user to configure another one and never change the root model on this skill's behalf.

This skill adds a model route to Codex's existing multi-agent flow. It does not create another scheduler.

Understand invocation

For explicit invocation, require the literal skill label $codex-orchestration:codex-orchestration at the start of an ordinary Codex prompt. These are prompts handled by this skill, not shell commands or registered slash commands. Codex's built-in /skills discovery may be used to browse and select the installed skill. Support these simple forms:

$codex-orchestration:codex-orchestration setup executor: GPT-5.6 Luna Extra High
$codex-orchestration:codex-orchestration setup executor: GPT-5.6 Luna Extra High, advisor: Claude Fable 5 High
$codex-orchestration:codex-orchestration setup planner: Claude Fable 5 High, advisor: GPT-5.6 Sol High, executor: GPT-5.6 Luna Extra High
$codex-orchestration:codex-orchestration setup advisor: Claude Opus 5 XHigh, executor: GPT-5.6 Luna Extra High
$codex-orchestration:codex-orchestration setup designer: GPT-5.6 Sol High, executor: GPT-5.6 Luna Extra High
$codex-orchestration:codex-orchestration Planner: Claude Fable 5 High, Designer: Kimi K3
$codex-orchestration:codex-orchestration --update
$codex-orchestration:codex-orchestration create project role: researcher
$codex-orchestration:codex-orchestration create personal roles: researcher, writer, reviewer
$codex-orchestration:codex-orchestration configure external role researcher with OpenRouter model moonshotai/kimi-k3 at max
$codex-orchestration:codex-orchestration call researcher at max — <one bounded task>
$codex-orchestration:codex-orchestration status
$codex-orchestration:codex-orchestration repair
$codex-orchestration:codex-orchestration disable
$codex-orchestration:codex-orchestration remove custom roles personally
$codex-orchestration:codex-orchestration executor: GPT-5.6 Terra high — <one task only>
is Kimi available to use as Designer?
can I use Kimi K3 for design?

Implicit invocation is discovery, not mutation authority. A natural-language availability question authorizes only read-only inspection. It never authorizes setup, repair, provider preparation, authentication, Gate 0 spend, role creation, configuration writes, disconnect, or removal.

For a question such as is Kimi available to use as Designer?, enter this skill implicitly and run external status from the installed skill before answering. Never infer External Model availability from the currently exposed MCP or subagent tool list. A visible Fable tool is not an exhaustive provider or role inventory. Report the result in four separate terms:

• supported: the exact display name maps to a bundled audited manifest;
• configured: the exact provider/model/effort and role exist without drift;
• locally ready: status is READY and read-only resolve succeeds for the exact role and effort in the current workspace;
• callable now: a sealed invoke has successfully attested the active binary, required CLI controls and feature catalog, unchanged registry, and accepted the model call. Read-only discovery must report this as unconfirmed rather than make a model call.

Say Kimi K3 is available to use as Designer only when support, configuration, local readiness, and callability are all true. Otherwise, say it is supported but not yet callable, name the exact lifecycle state, and give the next action. Never answer that the plugin does not expose Kimi merely because a Kimi-specific tool is absent; the route is materialized through the External Model lifecycle and a provider-pinned custom agent.

--update securely refreshes this plugin from its canonical Git marketplace. setup installs or updates the personal one-time routing policy. create project role or create personal role creates native Codex custom-agent files. status inspects built-in routing. repair restores only saved managed hint bytes after narrow drift validation. disable restores pre-setup values.

remove custom roles cleans only verified plugin-managed advisor/executor files. Arbitrary native roles are user-owned. An invocation with native seats and work but no control verb is a current-task override and must not rewrite config. Explicit External Model seat labels are the exception: they may perform only the clean preparation, connection, and readiness writes authorized in the External Model lifecycle below.

Explicit seat labels are authoritative. planner: configures only Planner, advisor: configures only Advisor, designer: configures only Designer, and executor: configures only Executor. Never infer or change a seat from a model's historical use, default role, cached description, or provider; in particular, never reinterpret a supplied planner: model as an Advisor or a supplied designer: model as an Executor. Saved defaults may fill only omitted seats and never override a seat supplied in the current invocation.

The executor is required for setup or a task-local override. It is not required for a custom-role creation request. Planner, advisor, and designer are optional: omitted planner means the current root model plans, omitted advisor means advisor: none, and omitted designer means designer: none. Do not ask separate planner or advisor questions, or a separate designer question, unless the user asks for help choosing them.

For both persistent setup and task-local overrides, reject an identical Planner and Advisor route: the same direct model ID, the same custom-agent name, or more than one bundled Claude subscription seat across Fable 5 and Opus 5. Independent critique is required.

If the executor is missing, ask only:

Which executor model and effort should Codex use? You can optionally include a planner, advisor, and designer; omission uses the root as planner and no advisor or designer.

Because explicit skills may not reload from a bare reply, include a ready-to-copy line using the exact label shown by the client and preserve the original work:

<exact-skill-label> setup executor=<model>@<effort-or-auto>, planner=<model>@<effort-or-auto>|root, advisor=<model>@<effort-or-auto>|none, designer=<model>@<effort-or-auto>|none

For a task-local request, append — <original task>. Keep every supplied modifier. Do not lose the user's task while collecting a model choice.

Before applying setup or starting task-local work, validate the normalized mapping internally against the user's explicit labels. If an exact native seat cannot run, report that seat as unavailable and stop under the required-route rules; never move its model to another seat. For an External Model seat still crossing a valid lifecycle boundary, report its exact lifecycle state and next action, not unavailable. Status and diagnostic commands may show omitted defaults explicitly, including Designer: none and Advisor: none; a successful activation confirmation follows the concise contract below instead.

Activation confirmation

After all requested task-local routes have been validated as callable in the current task, respond with one plain line per explicitly supplied model-bearing seat and preserve the user's seat order. Use this exact shape:

Planner — Fable 5 high: Activated
Designer — Kimi K3: Activated
Executor — GPT-5.6 Sol high: Activated

Keep the role and model recognizable to the user. Normalize stable product punctuation such as GPT-5.6, and render a supplied effort in lower-case readable words; internal values such as xhigh remain routing details. Do not append a defaulted effort that the user omitted; for example, the implicit Kimi K3 max remains part of route validation but not the display line. Do not print omitted, none, or implicit-root seats. On a role-selection-only invocation, the activation lines are the entire successful response: do not add a heading, preamble, route internals, or delegation boilerplate.

Use Activated only after that exact route is locally ready and its sealed invoke preflight succeeds for the active binary in the current task. It means available for this task, not used and confirmed runtime identity. If authentication, qualification, connection, restart, resolution, or another required boundary remains, report the exact lifecycle state and next action instead of Activated. Never mix a false activation line into a blocker response. For a request that also contains task work, print the activation lines first and then continue that work.

If an old prompt contains orchestrator:, explain that the current task model already owns that role. Ignore that seat instead of switching or persisting it.

Normalize Extra High to xhigh. For Claude Fable 5, accept Low, Medium, High, XHigh, Max, or Ultra. Omission or Auto means High; Ultra is a user-facing alias for Claude Code's actual max setting and must be reported as that mapping. Route Fable with --planner-fable --planner-effort <normalized-effort> or --advisor-fable --advisor-effort <normalized-effort>, not through the Codex model catalog. For Claude Opus 5, accept exactly Low, Medium, High, XHigh, or Max; omission or Auto means High, and Ultra is not an alias. Route it with --planner-opus or --advisor-opus plus the normalized effort. Resolve every other display name to an exact ID only through the executing host's model catalog, picker, a loaded custom agent, or official provider documentation. Never invent an ID. For persistent direct routing, resolve auto to the catalog's concrete default.

Persistent Designer accepts only a direct same-provider model, not a bundled Claude MCP or unqualified custom-agent route. Route it with --designer-model plus --designer-effort. A Designer route may share a model with another seat; only Planner and Advisor require independent routes. For a cross-provider Designer, create and invoke a task-local External Model role named designer; resolve must reject matching project agents in the current workspace or any ancestor immediately before returning its route. Codex does not yet expose a scope-qualified agent identity, so persisting an agent name would let a later project's agent shadow it.

Read providers-and-models.md before setup, when clients disagree, when a model is absent, when providers differ, or when custom agents or legacy migration are involved.

Update the plugin

Treat the explicit prompt $codex-orchestration:codex-orchestration --update as a request to update only this plugin. It cannot be combined with setup, status, disable, seat settings, custom role operations, or task work. Resolve the absolute Codex binary used by the active host. First run codex plugin list --json and require exactly one enabled codex-orchestration@codex-orchestration entry whose marketplace source type is git and source is the canonical HTTPS GitHub repository. Refuse local, disabled, missing, duplicate, or unexpected sources without mutation. Then run only:

codex plugin marketplace upgrade codex-orchestration --json
codex plugin add codex-orchestration@codex-orchestration --json
codex plugin list --json

Use that active absolute binary for all commands and let Codex's native plugin manager own transport, process containment, cache writes, and installation. Do not wrap these commands in a custom downloader, Git client, script, or credential-bearing environment. Require the upgrade result to select only this marketplace with no errors, the add result to report a SemVer newer than or equal to the original, and the final inventory to retain the exact canonical source and enabled state at that version. Never run plugin remove, rewrite Codex config, read credentials, or inspect/touch routing, chats, or sessions. If a native command or post-check fails, report the exact phase as failed and do not claim rollback.

On success, report the old and new versions and tell the user to restart Codex Desktop and start a new task. The current task keeps the already loaded skill instructions; no updater can replace those in place. If the plugin is installed from a local or noncanonical marketplace, stop and explain that automatic update is intentionally unavailable for that source.

External Model roles

Use this path when the user wants Codex Orchestration to own a model that should not appear in the Desktop model picker. Read external-models.md completely before preparing, qualifying, creating, resolving, disconnecting, or removing an External Model role.

The root model and its ChatGPT/OpenAI login remain untouched. Never write top-level model or model_provider, never edit the Desktop picker, and never inspect, migrate, archive, or delete a chat or session. An External Model is represented only by a reviewed provider adapter, strict non-secret state, and provider-pinned personal agent variants.

Accept natural-language forms such as:

configure external role researcher with <provider> model <exact-id> at <effort>; job: <purpose>
configure external role designer with <provider> model <exact-id> at <effort>; job: <design purpose>
call researcher at max — <bounded task>
use reviewer@high for <bounded task>
external status
disconnect external role researcher
remove external provider openrouter

Only bundled provider manifests are eligible. Do not turn an arbitrary URL, model name, shell command, project file, or subscription CLI into a provider. Resolve the exact model and supported efforts from the manifest and its cited evidence. Reject all unsupported effort values; never clamp, alias, or silently fall back.

External models supplied as seat labels

Treat a supplied built-in seat whose model unambiguously matches a bundled external model as an explicit External Model seat assignment. In particular, normalize Designer: Kimi K3, case-insensitively, to role designer, provider openrouter, model moonshotai/kimi-k3, and effort max; an omitted or auto effort also means max. Reject every other explicit Kimi K3 effort. This is a manifest-backed display name mapping, not permission to guess model IDs or accept fuzzy, dated, or latest aliases.

An external Designer is not a native direct-model Designer: never pass it to --designer-model, the root-provider model catalog, or the persistent routing schema; always inspect external status first and compare the requested role, provider, model, and effort with the strict registry result. Then follow exactly one state:

• If the exact role is READY, invoke it only with the configurator's sealed invoke subcommand and an absolute active-host --codex-bin; pass the bounded packet on stdin. Never execute an External Model role with agents.spawn_agent (or any native spawn-agent namespace). resolve remains a read-only diagnostic.
• If the exact role is RESTART_REQUIRED, tell the user to fully quit and reopen Codex and start a new task. In that new task, preview and apply ready; then use sealed invoke only after readiness succeeds.
• If the provider is exact, authenticated, and CAPABILITY_VERIFIED or READY, but role designer is absent, the explicit seat assignment authorizes clean role creation: preview and apply connect with the bounded purpose "Produce a design handoff for the root; do not edit implementation code, direct other roles, or spawn descendants." Report the resulting RESTART_REQUIRED boundary. It does not authorize replacing or disconnecting an existing role.
• If the provider is absent, treat the explicit seat assignment like a literal configure request: preview and apply only clean provider preparation, then follow the existing hidden authentication flow. Preparation may add the exact audited OpenRouter provider entry when absent, but never modifies or removes a pre-existing provider entry. If authentication is missing, print the required no-paste message and enrollment command, then stop.
• If the exact tuple is not qualified, request separate explicit billing approval immediately before Gate 0. A seat assignment never authorizes Gate 0 billing, credential entry, retries after a failed probe, or any other spend.
• If the role exists with another provider/model, any file or helper drifts, a project agent shadows it, or status is ambiguous, stop with the exact collision or integrity blocker. Never overwrite, repair, disconnect, or substitute a route.

At every non-ready state, describe the next exact action; do not report the requested external seat as unavailable merely because its personal agent has not been created or loaded yet; preserve the original task and every supplied seat while crossing an authentication, qualification, or restart boundary. A seat-only invocation is a role-provisioning request only when it contains only External Model seat labels; that form does not require Executor. If the invocation also supplies any native seat or contains task work, preserve every supplied seat and that work, then collect a missing Executor using the existing question and ready-to-copy invocation after reporting or progressing the external role state.

External seat assignments remain task-local. The returned custom-agent name must not be persisted in native routing state because a project agent could shadow that unqualified name in a later workspace. This rule does not change native same-provider Designer setup or Claude Fable 5 Planner/Advisor routing.

Native setup is preview-first and uses scripts/external_configurator.py from this skill's real installed directory. Its stages are prepare, external authentication, explicitly authorized billable gate0, connect, a new Codex task, and ready. A literal configure request authorizes clean preview and preparation, but not entering a key or spending on Gate 0. Obtain separate explicit approval for --acknowledge-billing immediately before that probe. Apply role creation only after Gate 0 succeeds for the exact provider/model/effort tuple.

When authentication is missing, say exactly this before stopping:

External provider authentication is required. Do not paste the API key into this chat. Run the displayed enrollment command in a trusted local terminal; its hidden local prompt stores the key in your operating-system credential store. Tell me when that command succeeds.

Never ask the user to paste, upload, dictate, or save a provider key in chat. Never place one in a command argument, environment file, TOML, registry, journal, prompt, test, log, Git file, issue, or pull request. Do not run the enrollment command for the user: they must enter the value through the OS prompt outside chat. The durable provider table may contain only documented command-backed auth fields pointing to the stable helper under CODEX_HOME or an explicitly trusted absolute user helper.

gate0 runs one fixed, ephemeral, read-only request in a temporary CODEX_HOME and may incur provider cost. Treat success as CAPABILITY_VERIFIED and route acceptance, not runtime model confirmation. OpenRouter officially lists the exact Kimi K3 tuple moonshotai/kimi-k3 with only max reasoning. For this model, auto resolves to max; reject every other explicit effort instead of clamping it. The bundled adapter is no longer experimental, but each installation remains unqualified until that exact tuple passes its explicitly authorized Gate 0. Never substitute a dated or latest Kimi alias.

connect creates one personal provider-pinned custom-agent variant for every manifest-validated effort. After a new task and exact integrity check, resolve maps the requested role and effort for diagnostics. Execute only with sealed invoke, never a native spawn-agent tool. Report route accepted when the direct CLI accepts it. Report used and confirmed only from mechanical host/provider/rollout metadata; model self-identification is never evidence.

For an unavailable provider, effort, auth helper, role file, or readiness state, stop and report the exact blocker. CLI_CHANGED, CONFIG_DRIFT, ROLE_COLLISION, and RECOVERY_REQUIRED are not best-effort states. Preview disconnect and removal, then apply only exact plugin-owned bytes and exact provider config. Preserve edited or ambiguous data for manual recovery. An intentionally replaced user helper may be accepted only through preview/apply trust-helper at the same absolute path, which clears qualification and requires authentication plus Gate 0 again.

Claude Fable 5 and Claude Opus 5 are the sealed first-party subscription adapters. They use only the Planner/Advisor MCP operations and existing first-party login, no-tools, no-session-persistence, runtime-model-metadata contract. Do not route them through the native External Model provider configurator and do not generalize their adapter to arbitrary CLIs.

Create arbitrary custom roles

Use native Codex custom-agent files for roles beyond the built-in planner, advisor, designer, and executor seats. Examples include researcher, reviewer, writer, supervisor, security auditor, browser debugger, or domain expert.

Use project scope when the user says project, repo, workspace, or current project. Write to <trusted-project>/.codex/agents/<role-name>.toml. Use personal scope only when explicitly requested and write to ~/.codex/agents/<role-name>.toml.

Before writing:

1. Normalize the role name to lowercase snake case and validate ^[a-z][a-z0-9_]{0,62}$.
2. Require a clear purpose and developer_instructions that keep the role bounded.
3. Resolve the model and effort from the active catalog or a user-confirmed exact ID.
4. If model_provider is supplied, require an existing configured and authenticated compatible provider. Never create provider access or collect credentials.
5. Use the current task permission mode by default. Add sandbox_mode only when the user requests it. A role may request a narrower sandbox; it never bypasses the parent task's authority.
6. Keep agents.max_depth = 1 behavior unless the user explicitly asks for nested agents. A custom role should not create descendants by default.
7. Refuse symlinked paths, duplicate agent names, malformed TOML, and overwriting an existing file without explicit replacement approval.

A custom agent file must define name, description, and developer_instructions. It may also define model, model_reasoning_effort, model_provider, sandbox_mode, mcp_servers, and skills.config when supported.

Preview the path and complete TOML before writing. A literal create request authorizes a clean new file after preview. Replacing or deleting an existing user-owned role requires a separate explicit decision.

Do not add the plugin ownership marker to arbitrary roles. Do not claim disable or remove custom roles will remove them. Tell the user to start a new task after creation so Codex loads the new roles.

When the user supplies a sequence such as researcher -> reviewer -> writer, preserve it as task-level workflow instructions. The root orchestrator owns every handoff, resolves conflicting feedback, verifies the result, and may skip only optional steps.

If the user combines a workflow with a Codex Goal, leave Goal lifecycle and limits under Codex's normal Goal controls. The orchestration policy operates inside the Goal; this skill does not silently create, pause, resume, or clear it.

One-time native setup

Use this path for a current same-provider setup such as Sol root to Luna or Terra children. Claude Fable 5 and Claude Opus 5 are the built-in cross-provider Planner or Advisor exceptions because they run through the bundled read-only MCP bridge and the user's authenticated Claude Code CLI.

1. Identify the Codex binary used by the active host. Do not assume the shell codex is the Desktop binary.
2. Resolve the exact executor and optional Planner, Advisor, and Designer IDs and efforts from that host.
3. Run the bundled native configurator from this skill's real directory with Python 3.11 or newer. Use python3 on typical macOS/Linux hosts; on Windows select an available py -3.11 or python launcher after checking its version. Never use a repository-relative copy from the user's workspace.
4. Inspect the dry-run output. A literal setup request authorizes applying a clean, non-replacement personal policy after that preview.
5. Start a new task after apply. The user chooses the orchestrator in the normal model picker and no longer needs to invoke this skill for ordinary work.

Typical dry run and apply:

python3 <skill-dir>/scripts/configure_native_routing.py \
  --codex-bin <active-codex-binary> \
  --executor-model gpt-5.6-luna \
  --executor-effort xhigh

python3 <skill-dir>/scripts/configure_native_routing.py \
  --codex-bin <active-codex-binary> \
  --executor-model gpt-5.6-luna \
  --executor-effort xhigh \
  --apply

Add --advisor-model and --advisor-effort for a same-provider Codex advisor. For Claude Fable 5, use --advisor-fable; add --advisor-effort low|medium|high|xhigh|max when the user chooses one. Omitting Fable effort defaults to high, while user-facing ultra is normalized to Claude Code's max. The configurator verifies that the installed Claude Code CLI advertises the selected effective effort. It also requires Claude Code to be logged in through a first-party Pro, Max, or Team account, chooses an available Python 3.11+ MCP launcher, and performs only an auth/capability check during setup. It never extracts a token, writes a credential, or makes a model call during setup or status. Omission persists advisor: none.

For Claude Opus 5 Advisor, use --advisor-opus with an optional exact --advisor-effort low|medium|high|xhigh|max. The default is high. Setup also requires Claude Code 2.1.219 or newer. It checks version, first-party login, required flags, and that the installed CLI advertises the selected effort; extra future CLI efforts remain unselectable.

Add --planner-model and --planner-effort for a same-provider Planner. For Claude Fable 5, use --planner-fable; add --planner-effort low|medium|high|xhigh|max when the user chooses one. For Claude Opus 5, use --planner-opus with the same exact five values and the same 2.1.219 minimum. Planner omission persists no Planner route and means the root plans. A configured Planner and Advisor must not resolve to the same model or agent route; independent review is required.

Add --designer-model and --designer-effort for a persistent same-provider Designer. Designer omission persists designer: none. Designer cannot use the bundled Claude MCP route or a persistent custom-agent name. Use a task-local External Model role named designer for cross-provider design work so the root can validate its personal file and reject project shadowing immediately before the bounded call.

The configurator capability-tests the complete four-field preset on the active target, codex on PATH when different, the known macOS Desktop binary when present, and every explicit --compat-bin. A successful isolated config probe means that client can parse the preset; it is not a live child-model confirmation. Report route accepted or used and confirmed only from the exact live spawn evidence defined below. Ask about other Codex/IDE installations that share this config only when the environment suggests they exist, and pass their binaries explicitly. If the request or active host indicates a named --profile, explain that normal setup manages the default user layer and is not verified for that profile; do not add a routine question for users with no profile signal. If a checked client rejects any managed field, stop before apply. Recommend updating it or using the task-local fallback. --allow-incompatible-client requires a separate explicit user decision because it can make the shared config unreadable to that client.

For the current validated v2 direct route, set tool_namespace = "agents". Live testing on Desktop 0.144.0-alpha.4 showed that the default reserved collaboration.spawn_agent schema rejected expanded model/effort metadata, while agents accepted the same request and spawned Luna at xhigh. Treat this as a required control-surface setting for that tested path, not as the executor selection. usage_hint_text carries the actual Planner, Advisor, Designer, and Executor routes.

Do not add enabled = true for a Sol or Terra root. Their current model metadata selects v2. The configurator intentionally manages these routing fields:

• features.multi_agent_v2.hide_spawn_agent_metadata;
• features.multi_agent_v2.tool_namespace;
• features.multi_agent_v2.multi_agent_mode_hint_text;
• features.multi_agent_v2.usage_hint_text.

When Claude Fable 5 or Claude Opus 5 is selected, it additionally manages only the plugin-scoped enabled override for the chosen bundled MCP launcher and any launcher variant already overridden by the user. The historical fable-advisor-* launcher IDs are retained as compatibility identifiers for both sealed models. All bundled variants are disabled by default. The original override values are stored and restored by disable. Codex's TOML editor may retain an inert empty table header after deleting the last override; never rewrite the file merely to remove that cosmetic header.

It uses Codex App Server's config/read and config/batchWrite APIs, not a home-grown TOML rewrite. It preserves unrelated settings and comments, validates the whole effective config, and uses the user-layer version to detect races. Restore snapshots cover the four routing fields plus the narrowly scoped MCP overrides only when either bundled Claude model is selected; the namespaced state also records schema/version markers, config path, selected seats, and scalar-conversion metadata when needed. If the user explicitly replaces existing hint text, the exact prior text is stored for restoration; warn them never to place credentials in routing hints.

If a user-authored mode or usage hint already exists, do not replace it automatically. Show the conflict. Use --replace-existing-policy only after the user explicitly approves replacing and later restoring those exact values.

Status, repair, change, and disable

For status:

python3 <skill-dir>/scripts/configure_native_routing.py \
  --codex-bin <active-codex-binary> \
  --status

python3 <skill-dir>/scripts/configure_native_routing.py \
  --codex-bin <active-codex-binary> \
  --status --require-effective

Run status from the target project. The first form is descriptive. Use --require-effective for automation and release gates; it returns nonzero for incompatible clients, conflicts, overrides, incomplete controls, an unavailable bundled Claude or custom-agent route, or orphaned v0.4+ personal roles. Report the current task model as the orchestrator, Planner (root when omitted), configured Advisor, Designer, and Executor, whether the personal policy is installed and effective in that workspace, whether effective spawn controls are visible, whether the effective tool namespace is agents, the target config path, and checked-client compatibility. State that neither status form proves a live route or infers v2 activation for the model selected in a task; current Sol or Terra is the intended root.

When status reports managed fields conflict with local restore state, do not run setup or disable over the conflict and do not assume authentication failed. A literal repair request makes the valid saved plugin state authoritative only for the following narrow recovery. Dry-run first, then apply only after the preview says the drift is limited to saved managed mode/usage hints:

python3 <skill-dir>/scripts/configure_native_routing.py \
  --codex-bin <active-codex-binary> \
  --repair

python3 <skill-dir>/scripts/configure_native_routing.py \
  --codex-bin <active-codex-binary> \
  --repair --apply

Repair must require valid saved state and both live hints to retain the plugin ownership marker. It must refuse namespace, spawn-metadata, drift in the historical Fable launcher IDs shared by both bundled Claude models, scalar-shape, missing/unmarked hint, or other managed drift. It writes only the different mode/usage fields through App Server compare-and-swap, leaves the original restore snapshot and seat records byte-for-byte unchanged, checks user and effective readback, rolls the two fields back when a higher layer overrides them, and preserves a concurrent config or saved-state edit instead of overwriting it. It never reads or changes authentication, credentials, chats, or sessions. After apply, run status with --require-effective and fully quit and reopen Codex before starting a new task.

To change ordinary seats, run normal setup again. The configurator keeps the original restore snapshot rather than treating its own managed values as user settings. An Opus route may update effort in place only on the same seat. Replacing Fable with Opus, replacing Opus with Fable, moving Opus between planning seats, or removing Opus through setup must fail before writes and instruct the user to run the existing full-policy --disable --apply, then one fresh complete setup.

For disable, dry-run and then apply. A literal disable request authorizes a clean restore:

python3 <skill-dir>/scripts/configure_native_routing.py \
  --codex-bin <active-codex-binary> \
  --disable

python3 <skill-dir>/scripts/configure_native_routing.py \
  --codex-bin <active-codex-binary> \
  --disable --apply

Disable must remain available even if an older client is incompatible with the active policy. Refuse to erase managed fields that the user edited after setup; explain the conflict instead.

For personal v0.4 custom roles, preview and apply removal with configure_orchestration.py --scope personal --personal-route-names --remove-saved-roles. For older fixed-name personal roles, run a separate preview without --personal-route-names. Project removal uses --scope project --root <trusted-project> --remove-saved-roles. Delete only files that the configurator fully validates as managed; edited or user-owned files require manual review.

Claude Fable 5 or Claude Opus 5 Planner or Advisor

Use this built-in route when the user names Claude Fable 5. Do not create a custom provider or custom-agent file for it. Claude Fable 5 remains a built-in cross-provider Planner or Advisor exception.

Use the same sealed bridge when the user names Claude Opus 5. Its exact model ID is claude-opus-5, and Claude Code 2.1.219 or newer is required. In user-facing diagnostics use the exact name Claude Opus 5.

In user-facing diagnostic status or operation results, use the exact name Claude Fable 5. The concise activation confirmation preserves the supplied Fable 5 label when that is what the user wrote, as shown in its exact example. Report authentication as first-party login ready; do not expose or restate Claude account-plan metadata.

Prerequisites:

• the official claude CLI is installed;
• claude auth status --json reports a first-party Pro, Max, or Team login;
• a Python 3.11+ launcher is available.

The plugin packages three disabled MCP launcher variants for macOS, Linux, and Windows. Setup enables exactly one compatible variant through the plugin's namespaced config when either bundled Claude model is selected. At planning or review time the MCP server gives authentication and model subprocesses only a minimal platform environment. It preserves HOME plus canonical operating-system USER and LOGNAME on POSIX, or USERPROFILE on Windows, for first-party login discovery. It does not trust ambient POSIX identity values and does not inherit credential, config-redirection, provider/model/effort, endpoint/gateway, proxy/CA/mTLS, or telemetry override families. It invokes claude --print --model <sealed-model-id> with --safe-mode, no tools, no session persistence, prompt suggestions disabled, and JSON output. Advisor review additionally requires Claude Code's --json-schema capability. Each saved seat pins its model and effort; the root cannot replace them through tool arguments.

Fable effort is configurable per setup. The default is high; supported Claude Code values are low, medium, high, xhigh, and max. Accept ultra as an alias for max, save the effective Claude Code value, and disclose the alias mapping in setup output. Existing saved max routes remain valid.

Opus effort is also configurable and defaults to high. Its sealed set is exactly low, medium, high, xhigh, and max; no alias is accepted. Setup requires only that the selected sealed effort appear in the installed CLI's advertised set. Extra advertised values do not expand the sealed set.

The bridge exposes only bounded, read-only planning operations. create_plan accepts one self-contained packet and requires PLAN_DRAFT. revise_plan requires the task, canonical current plan, latest critique, and compact findings history, then requires PLAN_REVISION plus a findings ledger and revised plan. review_plan remains the Advisor operation and requires a locally revalidated JSON Schema object containing exactly PLAN_APPROVED or PLAN_REVISE plus a non-empty body; raw prose never counts as a decision. Every call uses the same full saved-state validator as native status/repair/disable, then requires runtime modelUsage to contain a reviewed Fable primary identity (claude-fable-5 or claude-opus-4-8) or the exact Opus primary, plus only that model's explicit exact helper allowlist. Fable permits its independently observed claude-haiku-4-5-20251001 helper. No Opus helper identity is independently established, so Opus currently permits only claude-opus-5 and fails closed if any additional runtime model appears. Return every observed ID in used_models; an unknown additional or missing primary model makes the seat unavailable. Any auth, transport, state, format, or model-confirmation failure makes that seat unavailable; it never counts as approval. The bridge returns no account identifier or credential. Local mocked verification does not prove a positive live Opus invocation.

The configured Fable route remains claude-fable-5, while runtime modelUsage may confirm either reviewed Fable primary identity. This does not make claude-opus-4-8 an Opus route alias. Opus still requires the exact claude-opus-5 primary.

Plugin and policy updates cannot replace the MCP process already loaded into the current task. If a bundled Claude call fails after an update or repair, run fresh native status. When status reports that configured bundled Claude seat ready — first-party login, classify the current tool failure as a stale loaded bridge, not an authentication failure. Do not request re-authentication. Fully quit and reopen Codex, then start a new task so the installed bridge, policy, and saved state load together. Ask for login only when the fresh status check itself reports authentication unavailable.

The managed workflow reserves these MCP calls for the root Codex model. Current MCP requests do not carry caller identity, so the bridge cannot independently authenticate root versus child; caller isolation is instruction-enforced. The bridge still mechanically prevents tools, edits, permission prompts, and session persistence. Never describe the caller boundary as engine-enforced.

Durable or cross-provider custom agents

Direct model routing is same-provider. The audited External Model path above may prepare one bundled provider safely. Every unbundled provider still needs an already authenticated Codex-compatible provider and a loaded custom agent that pins model_provider.

For a cross-provider Planner, create a bounded personal custom role through the arbitrary-role or audited External Model flow, start a new task so it loads, and pass its exact name with --planner-agent. For a cross-provider Designer, create a task-local External Model role named designer and invoke it only after current-project validation; do not persist its unqualified agent name. The older standalone managed-role helper below continues to own only its existing Advisor and Executor files.

Use the existing standalone-agent configurator for an unbundled provider path. Personal scope is required for machine-local provider IDs and affects all projects, so the user's explicit cross-provider setup request must name or confirm the existing provider ID. Never create an unreviewed provider definition, collect keys in chat, or write credentials.

First preview and apply the namespaced custom agents:

python3 <skill-dir>/scripts/configure_orchestration.py \
  --scope personal \
  --personal-route-names \
  --codex-bin <active-codex-binary> \
  --executor-model <exact-id> \
  --executor-effort <effort> \
  --executor-provider <existing-provider-id> \
  --advisor-model <exact-id> \
  --advisor-effort <effort> \
  --advisor-provider <existing-provider-id>

When this cross-provider/custom-agent setup omits an advisor, pass --remove-advisor so a previously managed advisor is not left as a misleading saved seat. Apply only after a clean preview. Then point the native policy at the loaded role names:

python3 <skill-dir>/scripts/configure_native_routing.py \
  --codex-bin <active-codex-binary> \
  --executor-agent <reported-executor-agent-name> \
  --advisor-agent <reported-advisor-agent-name> \
  --apply

Omit --advisor-agent when none is configured. --personal-route-names generates stable CODEX_HOME-specific names and prints them for the native command. The native configurator verifies exactly one matching personal file and refuses a same-name project role in the current workspace. A custom-agent file is a stronger durable model/provider pin than a direct tool hint, but runtime identity is confirmed only when the host exposes it. Start a new task so Codex loads the role files.

These are two separate storage transactions. If the native command fails after the role transaction applied, immediately preview and then apply:

python3 <skill-dir>/scripts/configure_orchestration.py \
  --scope personal \
  --personal-route-names \
  --codex-bin <active-codex-binary> \
  --remove-saved-roles

Remove only files the configurator validates as managed. If cleanup fails or the operation was interrupted, stop and run native --status --require-effective; report each orphaned managed role for manual review. Never claim the two stores changed atomically. On Windows, new managed roles can be created, but updating or removing an existing role fails closed; explain that limitation before choosing the custom-agent path.

The standalone configurator also retains project-scoped saved roles, safe removal, and opt-in migration for releases 0.1–0.3. It must never change the root model, permissions, credentials, or global agent limits.

Preserve Codex's decisions

The current task model remains the root. It owns intent, planning, architecture, decomposition, delegation, integration, review, final verification, and the final answer.

Codex decides whether a plan helps, whether any work is safely delegable, how many independent slices exist, and whether parallelism is worth its context and integration cost. Keep simple, tightly coupled, context-heavy, and root-owned work with the root.

This skill and its saved policy must never:

• create a second orchestrator;
• force a spawn or fixed worker count;
• create or change Goal state;
• weaken approvals or permissions;
• create nested executor teams;
• let a Planner or Advisor contact the other role directly;
• let Designer contact Planner, Advisor, or Executor directly;
• let an advisor direct executors;
• parallelize overlapping writes;
• silently substitute the root model for an unavailable child route.

An explicit no subagents instruction always wins. A current-task seat override wins over the saved default for that task only.

Spawn routed children correctly

Inspect the callable subagent interface. A saved current preset should expose the routed tool under agents; if only collaboration is exposed, do not assume the expanded direct route works. For a task-local fallback, use whichever callable namespace is actually present and pass exact route controls only when its schema exposes them.

Every spawn that supplies model, reasoning_effort, or agent_type through this skill must use:

fork_turns = "none"

A small positive partial fork is technically valid in Codex, but this skill deliberately requires none: it minimizes duplicated context and makes the root send a deliberate self-contained packet. Never use the default all with a different route. Full-history forks inherit the root model and Codex rejects the override.

For a direct Planner, Advisor, Designer, or Executor route, pass the exact configured model and concrete effort. For a custom route, pass the exact namespaced agent_type. Do not force a service tier; supported children may inherit Fast/priority from the parent, so tell users who prioritize allowance savings not to run the root in Fast mode.

Direct model overrides keep the root's provider. Before a direct spawn, establish that the target model is on the same provider. If it differs or cannot be established, mark the route unavailable and require a custom agent that pins model_provider.

After spawning, use the tool result or client metadata to confirm the accepted route. Distinguish:

• native policy installed: the managed user policy exists; v2 activation still depends on the selected root and effective workspace config;
• pinned custom agent available: a matching role is loaded, but has not run;
• route accepted: the current tool accepted and validated the requested route controls;
• used and confirmed: use only when the client explicitly exposes effective runtime model/provider/effort metadata;
• inherited root — requested child model was not used;
• unavailable: the requested route cannot run here;
• root: no Planner route is configured, so the root plans;
• none: no Advisor or Designer is configured for that seat.

Tool acceptance proves the requested route was valid and accepted, not necessarily that the client exposes post-start runtime identity. Child prose claiming a model name is not proof. If an exact route fails, report it to the root. An unavailable configured Planner or Advisor halts before Executor work unless the user explicitly made that seat best-effort for the current task; apply the bounded degradation rules below and disclose it. A configured Designer failure blocks work that explicitly requires its design handoff, but does not block unrelated Executor work; the root owns design when Designer was omitted. An unavailable Executor may leave work with the root only when the user did not require delegation or that Executor route. Never describe an unavailable route as successful.

Planner and Advisor workflow

Planner is optional. When no Planner route is configured, the root creates and revises the plan. When configured, send the Planner one self-contained packet containing user intent, acceptance criteria, repository facts, constraints, proposed executor slices, risks, and verification. Require PLAN_DRAFT. Planner and Advisor report only to the root. They never edit, execute, spawn, contact one another, contact Executors, or release Executor work.

Advisor is optional. If none is configured, the root validates the Planner's draft and may continue. For a non-trivial plan with an Advisor, use this bounded approval loop:

1. Number the canonical plan version and send it to a fresh, stateless Advisor call.
2. Require PLAN_APPROVED or PLAN_REVISE as the first-line signal.
3. PLAN_APPROVED makes that exact version the approved plan. Stop reviewing immediately.
4. For PLAN_REVISE, assign stable IDs to material findings and send the canonical current version, latest critique, and compact cumulative findings ledger back to the same Planner route. If Planner is omitted, the root revises.
5. Require PLAN_REVISION, a complete FINDINGS_LEDGER, and the revised plan. Every latest finding must be INCORPORATED or REJECTED with a concrete reason. Reject stale source versions, missing or duplicated findings, and empty rationales.
6. Increment the version and send the new current plan plus compact ledger to a fresh Advisor call. Ask it to confirm or contest prior dispositions rather than repeat accepted findings.
7. Stop early on approval. Never exceed eight total Advisor reviews.

Carry only the original constraints, current plan, and compact ledger between fresh calls; do not duplicate complete transcripts. The root owns the canonical plan, versions, ledger, round count, semantic validation, and Executor release. Planner and Advisor never contact one another directly.

If review eight still returns PLAN_REVISE, halt before Executor work. Give the user the latest plan and version, complete ledger, latest unresolved findings, and choices to override, re-scope, or change a route. Never label it approved.

A configured Planner or Advisor is required by default. Route failure, malformed output, missing context, stale version, or invalid ledger halts before Executor work. Only an explicit current-task best-effort instruction permits degradation:

• if the configured Planner fails, disclose it and let the root assume Planner duties for the remaining rounds without resetting the eight-review budget;
• if the Advisor fails, disclose it, end the loop, and label the latest validated plan NOT_ADVISOR_APPROVED before any allowed continuation.

Do not persist a best-effort flag. An explicit task override applies only to that task.

Reject persistent setup or task-local activation when configured Planner and Advisor routes are identical: the same direct model ID, same custom-agent name, or more than one bundled Claude subscription seat. Independent critique is the reason for the Advisor role.

Bundled Claude Planner routes use create_plan and revise_plan; bundled Claude Advisor routes use review_plan. These operations are seat-bound: never send a supplied Planner route to review_plan, and never use an Advisor route to create or revise the plan. The policy authorizes only the root to make these read-only calls; Executors must never use or direct them.

For compatibility with the established seat contract: Fable Planner uses create_plan and revise_plan; Fable Advisor uses review_plan. Opus uses the same operation-to-seat mapping.

Designer handoff

Designer is optional and root-directed. Use it after any required plan approval when visual design, UX, interaction flow, information architecture, or a design system would materially improve the result. Give it one bounded packet containing:

• approved requirements and the exact design question;
• target users, platform, constraints, and acceptance criteria;
• required deliverables and handoff format;
• explicit ownership of any design artifacts it may edit;
• implementation boundaries and known dependencies.

Designer may edit only explicitly delegated design artifacts. Otherwise it returns a design specification or handoff. It never revises the canonical plan, changes implementation code, releases Executor, contacts Planner, Advisor, or Executor, or spawns descendants. The root validates the design handoff, resolves conflicts with the approved plan, and decides what implementation packet Executor receives. A Designer may use the same model as another seat because independent critique is not its purpose; the Planner/Advisor route-separation rule remains unchanged.

Executor handoff

Give each executor one bounded packet with:

• objective and boundaries;
• only the context and repository facts it needs;
• owned files or explicit read-only scope;
• dependencies and stop conditions;
• acceptance criteria and smallest useful verification;
• required handoff format.

Require it to preserve unrelated work, stay inside the slice, avoid the advisor, avoid descendants, and report blockers rather than guess. The handoff includes status, work completed, files or evidence, checks run, and remaining risks.

Parallelize only genuinely independent slices with non-overlapping write ownership. The root inspects, integrates, and verifies every handoff. Executor completion is never final acceptance.

Task-local and older-client fallback

When the persistent policy is unavailable, apply the supplied seats only to the work in the same invocation. Do not claim that a mutable team was saved.

Use the strongest exact control the current client exposes:

1. a matching loaded namespaced custom agent;
2. accepted direct model and reasoning_effort inputs with fork_turns = "none";
3. a clearly labeled prompt preference when exact routing is unavailable;
4. unavailable when the provider or model cannot be reached.

For task-local auto, omit the reasoning-effort input. Never pass the literal string auto to a spawn tool; the effective inherited or host-chosen effort remains unverified unless the client exposes it.

When every supplied fallback route is ready, use the same concise activation confirmation contract above and continue the included task. When any route is not ready, report only the affected seat's exact route state, blocker, and next action; do not label it Activated.

Never report a prompt preference or saved file as a model that actually ran. Report an exact tool call as route accepted; reserve runtime confirmation for explicit effective metadata.

Keep savings language honest

The purpose is to spend high-end capacity where judgment matters and use an efficient coding model for eligible execution volume. Do not create agents solely to hit a percentage.

The “about 65%” example is a model-weighted credit calculation: at the published Luna rate of 20% of Sol, a comparable token mix with 20% on Sol and 80% on Luna costs 0.20 + (0.80 × 0.20) = 0.36, about 64% fewer credits before orchestration overhead.

Never call that 65% fewer raw tokens, a guaranteed five-hour or weekly-limit saving, a fixed monetary saving, or five times more completed work. Advisor calls, duplicated context, retries, tools, Fast service tier, and unnecessary workers can reduce or erase the benefit.

Resources

• scripts/configure_native_routing.py: one-time native setup, status, seat changes, and disable.
• scripts/fable_advisor_mcp.py: fail-closed Fable 5 and Opus 5 planning and review bridge; the filename is retained for compatibility.
• scripts/configure_orchestration.py: namespaced custom agents, provider pins, safe removal, and legacy migration.
• scripts/inspect_models.py: fallible host-catalog diagnostics.
• scripts/external_configurator.py: preview-first External Model provider, Gate 0, role, status, recovery, and removal lifecycle.
• scripts/external_auth_helper.py: stable OS credential-store reader for documented command-backed provider auth.
• scripts/external_subscription.py: sealed dispatch through the bundled Claude subscription bridge.
• providers-and-models.md: detailed capability, provider, compatibility, persistence, and usage boundaries.
• external-models.md: External Model trust lanes, lifecycle, commands, secret handling, Kimi status, and adapter-extension contract.