This repository is v2 of the orchestration plugin for Codex and Claude
Code. The default install is the no-Claude Codex host; Claude remains an
explicitly selectable host and optional worker family.
It contains both the design spec (under docs/) and the plugin
implementation that descends from it (under orchestration/:
.claude-plugin/plugin.json, codex-plugin/.codex-plugin/plugin.json, skills/,
codex-skills/, external-skills/, config/, hooks/,
scripts/, schemas/, templates/, tests/). A routing-eval harness
lives in the top-level eval/ directory. See the layout block below.
v1 of the plugin (look-before-you-leap) shipped a working orchestrator but
accumulated too much enforcement machinery: signed Codex receipts, HMAC
sidecars, a digester sub-agent for every artifact, forced plan-mode gates
that blocked routine edits, and a hook surface that mutated state. The good
ideas — conductor mode, persistent plans, discipline skills, Orbit review —
were buried under ceremony.
v2 is a clean rewrite. The design preserves what worked, drops what over-enforced, and trusts the model + bounded prompt contracts in place of receipts and signatures.
- A
conductorskill that orchestrates work via sub-agent dispatch and bounded Codex calls. - Persistent plans on disk (three-file format) that survive compaction.
- Eight discipline skills (
engineering-discipline,persistent-plans,writing-plans,codex-dispatch,refactoring,test-driven-development,systematic-debugging,brainstorming). - Nine auxiliary skills the orchestrator routes to
(
doc-coauthoring,frontend-design,svg-art,immersive-frontend,mcp-builder,react-native-mobile,webapp-testing,skill-review-standard,remote-agent-host), auto-discovered fromskills/<name>/SKILL.md. - Six hook-event registrations: two bounded read-only notice hooks
(
SessionStart,PostCompact) plus four narrowly scoped, fail-open, non-decision Mini lifecycle observers backed by one private labels-only queue bridge. This supersedes the former exactly-two-read-only-hooks design. - Direction-locked Codex wrappers (
run-codex-impl.sh,run-codex-verify.sh) with a fixed Summary / Verdict / Findings prompt contract. - A parallel Grok lane (
run-grok-impl.sh,run-grok-verify.sh) sharing the same direction-locked contract; seedocs/10-grok-integration.md. - Five direction-locked model wrappers: two implementation wrappers and three verification wrappers (Codex, Grok, and the legacy Claude verifier).
- Sixteen plugin-root scripts covering wrappers, plan/routing helpers, the guarded workflow relay, and the Mini-resident registry/mirror/APNs backend.
- Four JSON Schemas for plans, progress, routing, and policy, plus a
masterPlan.mdtemplate.
claude-codex-orchestration/ ← repo root = marketplace root
├── .agents/plugins/
│ └── marketplace.json ← Codex marketplace metadata
├── .claude-plugin/
│ └── marketplace.json ← marketplace metadata (this repo as marketplace)
├── README.md ← you are here
├── AGENTS.md ← the three roles (conductor, sub-agents, Codex)
├── LICENSE ← MIT
├── install.sh ← --host codex|claude|both (Codex default)
├── .claude/
│ └── CLAUDE.md ← context for any Claude session editing this repo
├── docs/ ← the design spec (markdown only)
│ ├── 01-philosophy.md … 12-phone-control-surface.md
│
├── orchestration/ ← shared package + Claude plugin source
│ ├── .claude-plugin/
│ │ └── plugin.json ← minimal plugin manifest (name, description)
│ ├── codex-plugin/ ← Codex marketplace source
│ │ ├── .codex-plugin/plugin.json
│ │ └── skills/ ← conventional entrypoints to canonical bodies
│ ├── skills/ ← 9 core + 9 auxiliary skills
│ ├── codex-skills/ ← 4 Codex-host orchestration skills
│ ├── external-skills/ ← exact 13 portable Codex/Grok work skills
│ ├── config/ ← canonical Codex/Fable routing profiles
│ ├── hooks/ ← manifest + 2 read-only notice handlers +
│ │ 1 fail-open private-queue observer handler
│ ├── scripts/ ← 5 wrappers + 11 plan/routing/Mini helpers
│ ├── schemas/ ← plan, progress, routing, and policy schemas
│ ├── templates/ ← starter templates (e.g. masterPlan)
│ └── tests/ ← hook + script tests
│
└── eval/ ← routing-validation eval harness (non-shipped dev tool)
├── corpus/ ← gold tasks per domain (tracked)
├── scripts/ ← bash helpers: score/judge/aggregate (tracked)
└── results/ ← scorecards + raw run JSON (gitignored)
Prerequisites depend on the selected host:
- Default
--host codex: authenticatedcodexandgrokCLIs. Codex is the Sol xhigh root; Grok 4.5 is the independent planning, review, and verification counterweight. This path never requires or invokesclaude. --host claude: authenticated Claude Code, Codex, and Grok CLIs. Fable is the root; Codex and Grok remain required planning and verification lanes.--host both: all three authenticated CLIs. This is the easiest setup for explicit host switching without reinstalling later.orbit-mcponPATH— the plugin declares anorbitMCP server used to surfacemasterPlan.mdfor human review before execution and to coordinate the plan-mode handoff (EnterPlanMode→ compaction → fresh execution window). On macOS:brew install orbit-mcp(or follow Orbit's own install docs).jqonPATH— used by the plan helpers, the contract parser, and the hooks.
The optional Mac Mini workflow path additionally requires local git, ssh,
and a SHA-256 implementation, plus an already provisioned Mini. The Mini must
expose the matched workflow-registry, supervisor, mirror worker, gateway,
APNs sender, and protocol authority generation on PATH; the MacBook's
remote-agent.sh talks only to workflow-registry. The supervisor launches
the installed claude, codex, or grok subscription TUI. Each TUI must
already be authenticated interactively on the Mini, and real worktrees must
exist at the configured project roots. Configure its SSH
host with --host, REMOTE_AGENT_HOST, or the single-line
${XDG_STATE_HOME:-$HOME/.local/state}/orchestration-remote-host file. The
helper neither installs this backend nor copies SSH keys, API keys, cookies,
browser profiles, shell profiles, harness authentication, or other secrets.
Clone this repo somewhere stable, then run install.sh:
git clone https://github.com/miospotdevteam/claude-codex-orchestration.git \
~/projects/claude-codex-orchestration
cd ~/projects/claude-codex-orchestration
bash install.sh # Codex-primary surface; no Claude invocation
# bash install.sh --host both # prepare both hosts
# bash install.sh --host both # install once for profile switchinginstall.sh is host-aware and idempotent. Every mode installs and validates the
Codex dependency; Claude modes additionally install the Claude plugin. The
selected provider's machine-readable installed artifact—not the invoking
checkout—is canonical. Before cleanup, the installer validates the exact 13
portable work skills, then syncs them into ~/.codex/skills and
~/.grok/skills; host-only conductor/plan/dispatch bodies remain plugin-owned.
--host codex performs this without invoking Claude. Unowned skills are
preserved. Safe to re-run after upgrading.
The effective profile defaults to the shipped codex-primary preset when a
project has no routing file. A project override lives at
.orchestration/routing.json and is managed by orchestration-routing.sh.
Activate either profile atomically:
orchestration/scripts/orchestration-routing.sh activate codex-primary .
# later, if Fable remains available:
orchestration/scripts/orchestration-routing.sh activate fable-primary .codex-primary requires a Sol xhigh Codex host and denies Claude workers.
fable-primary requires a Fable xhigh Claude host and enables the approved
Fable/Codex/Grok lanes. Activation reports the required next host but does not
launch it. Invalid routing fails closed to deny; legacy policy.json remains
a compatibility fallback only when no project routing override exists. The standalone
model routing configurator emits the
same validated, activatable profiles.
Codex model selection remains an authenticated machine preference, not an
installer mutation. For the default lane, configure ~/.codex/config.toml with
model = "gpt-5.6-sol" and model_reasoning_effort = "xhigh". The Grok
wrappers independently pin grok-4.5 with high reasoning effort.
# Codex
codex plugin marketplace add miospotdevteam/claude-codex-orchestration
codex plugin add orchestration@claude-codex-orchestration
# Add this repo as a Claude Code marketplace
claude plugin marketplace add miospotdevteam/claude-codex-orchestration
# Install the plugin from the marketplace
claude plugin install orchestration@claude-codex-orchestrationAfter install, start the selected host in any project. On Claude, the
SessionStart hook injects a one-line notice if an active plan
already exists; otherwise the conductor skill is on standby.
claude plugin marketplace update claude-codex-orchestration
claude plugin update orchestrationOr re-run bash install.sh --host codex|claude|both from the clone. Host
installation and orchestration authority are separate: with both hosts
installed, switch explicitly using orchestration-routing.sh activate codex-primary|fable-primary; no reinstall is required.
Restart Claude Code or run /reload-plugins in an open session after install
or upgrade. Do not edit the plugin cache or user Claude settings by hand; make
changes in this repository, reinstall, and reload.
To remove the current plugin cleanly, run:
claude plugin uninstall orchestration -y
claude plugin marketplace remove claude-codex-orchestrationReinstalling with install.sh always selects the marketplace's current
artifact; it does not pin the invoking checkout. A historical rollback must be
published or registered as a marketplace version and then installed through
the Claude plugin CLI—never copied into Claude's cache manually.
The Mini backend has no fixed installation directory; its supervisor,
workflow registry, mirror worker, gateway, APNs sender, and protocol authority
must be deployed as one matched generation on the Mini's PATH. Retain the
previous matched generation before upgrading. If rollback is needed, stop
active work through the matching guarded helper and restore the generation as
a unit; never mix relay/backend versions or bypass lease, restore-journal, or
recovery-required state.
An unrelated dirty Mini worktree is not an invitation to deploy over it.
Never reset, clean, checkout, overwrite, or raw-rsync it. List, inspect, wait,
sync, and release through the guarded remote-agent protocol only; its lease,
snapshot, divergence, restore-journal, and recovery-required refusals are
authoritative. Mirror verified content and release ownership before changing
host or updating the matched relay/registry generation.
Claude model and effort are authenticated user preferences, not supervisor
launch arguments. For this Mini deployment, select Fable and xhigh once in the
subscription-backed Claude TUI (/model fable, then /effort xhigh) and verify
that ~/.claude/settings.json reports model=fable and
effortLevel=xhigh. The supervisor deliberately continues to launch only
claude --yolo; the helper neither copies authentication nor rewrites those
machine-local preferences.
The plugin is gentle-reminder driven, not gate-enforced. You can make any edit at any time; the discipline lives in the skills.
A typical non-trivial task flows through four phases:
- Discovery. Ask Claude to "look into X" or "figure out how Y
works". The
conductorskill dispatchesExploresub-agents in parallel and collects bounded summaries. - Plan. Once discovery is enough, say "write the plan" (or
similar). The
writing-plansskill produces three files under.temp/plan-mode/active/<planId>/:plan.json— immutable definition (frozen after approval)progress.json— mutable execution statemasterPlan.md— human-facing proposal (review this)
- Execute. On approval,
plan.json.frozenflips totrue. The conductor computes the runnable frontier viascripts/plan-utils.sh compute-frontierand dispatches steps in parallel throughcodex-dispatch. Codex returns a bounded Summary / Verdict / Findings block; the parser writes the verdict intoprogress.json. - Verify. Each step is verified during execution; a final pass
re-runs project-level checks (type-check, lint, tests). The plan
directory moves to
.temp/plan-mode/archive/when done.
A compaction at any point is fine: the post-compact hook re-injects
the active plan path and the runnable frontier, and the conductor
resumes from plan.json + progress.json alone — no source files
re-read, no discovery re-run.
For trivial work — a typo, a one-line config tweak — say "just do it" and the conductor skips the plan. The discipline is gentle on purpose.
The remote-agent-host skill translates natural-language Mini requests into
one stateless guarded relay:
remote-agent.sh [--host HOST] list
remote-agent.sh [--host HOST] inspect WORKFLOW_ID
remote-agent.sh [--host HOST] wait WORKFLOW_ID --cursor CURSOR --timeout SECONDS
remote-agent.sh [--host HOST] start-conductor PROJECT PLAN_ID
remote-agent.sh [--host HOST] send WORKFLOW_ID --prompt-file FILE [--ack-event SEQ]
remote-agent.sh [--host HOST] interrupt|kill|release|reveal WORKFLOW_ID
remote-agent.sh [--host HOST] sync WORKFLOW_ID [--cancel MIRROR_JOB]
remote-agent.sh [--host HOST] diagnostic ACTION PROJECT HARNESS
Ask naturally: “list the Mini workflows”, “resume this workflow”, “check
whether it needs input”, “wait for its next event”, “reveal its Terminal”,
“synchronize and release it”, or “start a Codex diagnostic session”. The relay
never orchestrates locally and stores no workflow state. list discovers
opaque workflow IDs; every later resident-workflow operation uses that ID.
start-conductor creates the durable Mini-resident workflow. The shipped
registry currently launches the Claude subscription harness for this path.
Codex and Grok desktop sessions use the separate full-lease diagnostic
family and must not be described as mobile-resumable workflows.
Prompts travel only through private files. Before every send, inspect and report
at most 40 relevant lines or 4 KiB. Monitoring is event-driven: issue one
blocking wait, retain its restart-aware monotonic cursor, then inspect once.
Never loop on captures, screenshots, or Computer Use.
Synchronization is separate from lifecycle control. Kill makes a workflow
quiescent but does not move files or release ownership. sync WORKFLOW_ID
queues a mirror job whose safe direction is derived at claim time. Only after a
mirror-done event and aligned state may release WORKFLOW_ID clear the
lease last. Divergence, live-writer conflicts, CAS loss, restore failure, or
recovery-required always fail closed. PID, heartbeat, terminal, exit, and
timeout state never infer staleness.
The Mini and MacBook must run matching relay/registry generations. Exit 127 without a registry envelope indicates version skew, not an absent workflow. During an upgrade, use only the previously installed matching guarded helper to quiesce and align the old session; never fall back to raw SSH, rsync, or tmux.
Run all 29 shipped plugin suites against installation, helpers, skills, wrappers, Mini services, and hooks:
cd orchestration
for test_file in tests/scripts/*.test.sh tests/hooks/*.test.sh; do
bash "$test_file"
doneAll 29 suites use shell test harnesses, sandbox under mktemp -d,
and clean up after themselves. Each exits non-zero on any failure.
Syntax / lint checks for the shell scripts:
cd orchestration
bash -n scripts/*.sh hooks/*.sh tests/scripts/*.test.sh tests/hooks/*.test.sh
shellcheck scripts/*.sh hooks/*.sh # optional but recommendedJSON validity (from repo root):
jq -e . .claude-plugin/marketplace.json orchestration/.claude-plugin/plugin.json orchestration/hooks/hooks.json orchestration/schemas/*.jsonThe full design lives under docs/. Read in order:
docs/01-philosophy.md— the bias (what v2 keeps, drops, why).docs/02-conductor.md— the dispatch-only contract.docs/03-plan-format.md— the plan/progress/masterPlan schemas.docs/04-execution-loop.md— the four-phase runtime.docs/05-skills-catalog.md— what each skill triggers on.docs/06-codex-integration.md— wrappers + prompt contract.docs/07-hooks.md— the six hook events, privacy, and event limits.docs/08-plugin-layout.md— target tree + build order.docs/09-routing-matrix.md— model routing, panel planning, and verification lanes.docs/10-grok-integration.md— Grok wrappers + prompt contract.docs/11-routing-eval.md— the routing eval harness that validates the matrix.docs/12-phone-control-surface.md— the evolving private phone-control contract.
When you're working on the plugin, your own session is itself an
exercise of the system: a non-trivial change should produce a plan
under .temp/plan-mode/active/<planId>/. Look at the existing
archives under .temp/plan-mode/archive/ for examples of approved
plans and their progress records.
.claude/CLAUDE.md is the project-local rule set: markdown only under
docs/, no regressions to v1 shape, no lib/ shared between skills, and
exactly the shipped six-event hook surface. The four lifecycle observers are
fail-open, non-decision, and labels-only; they supersede the former two-hook
rule without restoring gates.
- No signed receipts, HMAC sidecars, or
claude-review-*.mdsibling files. - No
lbyl-digestsub-agent. - No forced-plan hard gates. Reminders only.
- No tool-blocking or decision-returning hooks. Lifecycle observers may append sanitized labels to their private queue, but never persist user/model text.
- No
lib/shared between skills. Skills reference each other by name in prose, not by shared imports. - No secret copying, continuous unguarded synchronization, public workflow endpoint, transcript persistence, or raw terminal streaming.
See docs/01-philosophy.md for the full rationale.