# Cmux Pi Orchestration

> Orchestrate audited pi-worker DAGs on cmux using exact-base code worktrees, central-only SKILL.state, phase-pinned models, fresh audit, owner promotion, cleanup, and recovery. Use for cmux orchestration, parallel pi workers, multi-agent DAGs, or renumbered cmux refs.

- Skill: `luw2007/cmux-pi-orchestration` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add luw2007/cmux-pi-orchestration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/luw2007/cmux-pi-orchestration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: luw2007 (https://skillmd.com/u/luw2007)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/luw2007/cmux-pi-orchestration

---


# cmux pi orchestration

Owner controls immutable `SPEC.json`, atomic `STATE.json`, per-attempt exchange, routes, and acceptance under `$HOME/.cmux-pi-orchestration/`. Worktrees contain project code only.

## References

Read [contract](references/audited-task-contract.md), [artifact store](references/artifact-store.md), and [route profile](references/billing-route-profile.md); after selecting cmux, read [runbook](references/cmux-runtime-runbook.md) and live `cmux <group> --help`.

## Gates

Non-trivial work requires accepted `$kickoff`; trivial work needs ledger `skip_reason`. Use SKILL.state: immutable `P`, current `Σt`, latest `ot`. Pin digest/base; reject unresolved, stale, untraceable, or mismatched input. Workers cannot amend `P`; invalidation reopens Kickoff.

`SSH_CONNECTION` or `SSH_TTY` means cmux is client-local while work is remote. Worker tabs MUST SSH to the exact live-derived host and canonical worktree. Failed non-interactive directory/HEAD proof disables cmux dispatch.

Resolve task → project role → user role → allowed default. Require exact alias, auth, and runtime identity. Billing/no-fallback proof applies only when requested. Human approval remains mandatory for permission expansion and destructive, production, or irreversible actions.

## Execute

Invariant: **`P + Σt + ot` → validate → atomic `Σt+1` → archive `ot`**.

1. Prove cmux/cwd; create central run with `SPEC.json` and `STATE.json` recording main worktree.
2. Create worker worktree/tab; atomically add attempt, worktree, route, surface, and cleanup facts to `STATE.json`.
3. Dispatch central `TASK.md`; worker publishes central `REPORT.md` then `DONE`.
4. Fresh-audit central files plus live Git/cmux, required checks, scope, route, base, HEAD, and state version.
5. Create verified `candidate.bundle`; checksum attempt evidence; atomically replace `STATE.json`.
6. Re-evaluate DAG; close/remove exact runtime resources and record cleanup in `STATE.json`.

Never append old observations/reasoning. Central `SPEC.json`/`STATE.json` and live runtime beat prose, titles, refs, and memory. Workers cannot promote or widen scope. Restart from these minimal files plus live Git/cmux—not transcripts.