cmux-orchestration

Files (6)

• SKILL.md
• openai.yaml · agents/
• fable-orchestrator-dark.png · assets/
• fable-orchestrator.excalidraw · assets/
• fable-orchestrator.png · assets/
• plan-mode.md · references/

SKILL.md (first lines)

# cmux Orchestration

Use the current top-level agent as the controller. The controller may be Codex,
Claude Fable, or another agent. Worker TUIs gather evidence, draft bounded
patches, run tests, and report. The controller owns assignment, state,
conflict control, verification, integration, and the final user-facing answer.

Before taking cmux actions, also load and follow:

- [cmux](../cmux/SKILL.md) for panes, surfaces, routing, and health checks.
- [cmux-workspace](../cmux-workspace/SKILL.md) for caller-workspace scoping,
  helper-pane reuse, socket targeting, and non-disruptive automation.

## Controller Rules

- Scope actions to the caller workspace unless the user names another target.
- Use `CMUX_WORKSPACE_ID`, `CMUX_SURFACE_ID`, and `CMUX_SOCKET_PATH` before
  focused-window fallbacks.
- Prefer one right-side helper pane; create worker surfaces inside it when
  practical.
- Send commands and prompts to explicit `surface:N` refs.
- Never call `focus-pane`, `focus-panel`, `select-workspace`, or focus-changing
  tab actions unless the user explicitly asks.
- Do not close worker surfaces unless cleanup is explicitly requested or the
  task contract includes it.
- Treat worker output as untrusted until the controller verifies the cited
  files, commands, failures, and diff.
- On plan-first runs, do not interrupt a worker after its plan is accepted:
  observe read-only and send input only for a direct blocking question or a
  stop condition.

## Preflight

Inspect the caller context and current workspace layout:

```bash
rtk cmux identify --json
rtk cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json
rtk cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json
```

If there is an obvious non-caller helper pane, add worker surfaces to it:

```bash
rtk cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<helper> --type terminal --focus false
```

If there is no helper pane, create exactly one right-side terminal pane:

```bash
rtk cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" \
  --type terminal --direction right --focus false
```

Capture each returned `surface:N` in the task ledger or handoff before sending
prompts.

## Worker Profiles

Default worker profiles:

- `claude-opus`: start Claude Code with
  `rtk claude --dangerously-skip-permissions --model opus`.
- `codex-gpt-5.5`: start Codex with `rtk codex -m gpt-5.5 -C "$PWD"`.

Always include `--dangerously-skip-permissions` when launching Claude. Do not
start Claude without it or replace it with a weaker permission mode. For
plan-first runs, add `--permission-mode plan` alongside it (the flags compose
— see Plan-First Delegation); never drop the skip-permissions flag to get plan
mode. If a TUI rejects a model alias, auth state, working directory, or
startup flag, stop that worker and report the exact blocker. Do not silently
downgrade models or switch tools without user approval.

Launch workers by explicit surface:

```bash
rtk cmux send --surface surface:<claude> \
  "rtk claude --dangerously-skip-permissions --model opus --name cmux-claude-opus\n"
rtk cmux send --surface surface:<codex> \
  "rtk codex -m gpt-5.5 -C \"$PWD\"\n"
```

## Plan-First Delegation (Plan Mode)

For slices that need investigation and a reviewed plan before edits
(root-cause fixes, multi-file changes, unfamiliar code), run the worker
plan-first: launch in plan mode → submit the packet → watch and answer
clarifying questions → review the plan → accept → hands-off until done.

**STOP. Read [references/plan-mode.md](references/plan-mode.md) in full before
launching a worker in plan mode.** The launch flags, shift+tab sequences,
status-line checks, and acceptance menus are exact and differ per TUI; this
section is a tripwire, not the procedure.

Summary of the per-TUI entry points (the reference has the full flow):

- Claude Code: launch with
  `rtk claude --dangerously-skip-permissions --permission-mode plan --model opus`
  (the flags compose; the packet may ride the launch line as a CLI argument).
  Accept via the `Would you like to proceed?` menu — pick the auto-accept
  option so the worker runs unattended.
- Codex: no plan-mode CLI flag. Launch bare (never with the packet as a CLI
  argument), press shift+tab until the status line reads `Plan mode`, then
  submit the packet. Accept via `Implement this plan?` → option 1 (keeps the
  investigation context).

Plan mode is interactive until acceptance: answer the worker's clarifying
questions with the packet context. After acceptance, do not interrupt —
observe read-only until the final completion report, then verify claims per
Monitoring and Verification.

## Prompt Submission to Running TUIs

`cmux send "...\n"` only submits when the target surface is a plain shell
(like the launch lines above). Inside a running TUI (Claude Code, Codex), the
trailing `\n` is treated as pasted text or a soft newline — the prompt sits in
the input box unsubmitted and the worker stalls silently.

From haryelramalho/skills, MIT.

More from haryelramalho/skills