cmux-orchestration
Control cmux panes and surfaces to coordinate terminal agent workers. Use when a top-level agent needs to launch, prompt, monitor, or manage Claude Opus and Codex GPT-5.5 TUIs in the current cmux workspace, run plan-first delegations (Claude Code plan mode, Codex Plan mode), track worker state, delegate bounded tasks, or verify worker reports.
- License 许可
- MIT
- 最近更新
- 2026-07-16
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- cmux-orchestration
- metadata
- { "author": "Pedro Nauck", "github": "https://github.com/pedronauck", "repository": "https://github.com/pedronauck/skills" }
- description
- Control cmux panes and surfaces to coordinate terminal agent workers. Use when a top-level agent needs to launch, prompt, monitor, or manage Claude Opus and Codex GPT-5.5 TUIs in the current cmux workspace, run plan-first delegations (Claude Code plan mode, Codex Plan mode), track worker state, delegate bounded tasks, or verify worker reports.
02 资源文件 5
- 参考文档agents/openai.yaml218 B
- 资产文件assets/fable-orchestrator-dark.png108.7 KB
- 资产文件assets/fable-orchestrator.excalidraw19.1 KB
- 资产文件assets/fable-orchestrator.png108.6 KB
- 参考文档references/plan-mode.md7.1 KB
03 SKILL.md 正文
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 for panes, surfaces, routing, and health checks.
- cmux-workspace 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, andCMUX_SOCKET_PATHbefore focused-window fallbacks. - Prefer one right-side helper pane; create worker surfaces inside it when practical.
- Send commands and prompts to explicit
surface:Nrefs. - 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:
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:
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:
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 withrtk claude --dangerously-skip-permissions --model opus.codex-gpt-5.5: start Codex withrtk 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:
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 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 theWould 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 viaImplement 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.
Rules:
-
Prefer passing the initial prompt as a CLI argument at launch (
rtk claude --dangerously-skip-permissions "…prompt…",rtk codex "…prompt…"). This avoids the TUI-ready race and the submission problem entirely. Exception: Codex plan-first runs must launch bare — see Plan-First Delegation. -
For any follow-up prompt to an already-running TUI, always send the text and then submit with an explicit Enter:
rtk cmux send --surface surface:<worker> "…follow-up prompt…" rtk cmux send-key --surface surface:<worker> enter -
Confirm submission with
rtk cmux read-screen --surface surface:<worker>: the input line must be empty and the TUI spinner/working indicator active. Treat an unconfirmed send as not delivered.
Delegation Packets
Send worker prompts as standalone contracts. Include:
- repo path and exact objective
- worker role and model
- execution mode: plan-first (plan mode) or direct
- files, packages, or surfaces in scope
- files and behaviors explicitly out of scope
- claimed files or work slice to avoid conflicts
- expected evidence format: files, line refs, commands, diffs, failures, screenshots, and uncertainty
- verification commands or browser flows to run
- stop conditions: unexpected code shape, repeated command failure, auth/model blocker, or need for out-of-scope edits
Prefer small, independent worker slices. Do not assign overlapping file claims unless the controller plans to integrate and resolve conflicts immediately.
State Registry
Maintain a compact registry in the task ledger or handoff:
- controller identity
- worker role and model
workspace:N,pane:N, andsurface:N- prompt/objective sent and start time
- current status: starting, planning, plan-review, plan-accepted, running, waiting, blocked, reported, verified
- claimed files or work slice
- worker-reported commands and results
- controller verification performed
- final disposition: accepted, rejected, superseded, or blocked
For long runs, attach progress to the caller workspace with cmux sidebar state:
rtk cmux set-status orchestration "running" \
--workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"
rtk cmux set-progress 0.4 --label "Workers running" \
--workspace "${CMUX_WORKSPACE_ID:-}"
rtk cmux log --workspace "${CMUX_WORKSPACE_ID:-}" --level info -- \
"Started cmux orchestration"
Clear status/progress when orchestration finishes or is abandoned.
Monitoring and Verification
- Poll or inspect worker surfaces without changing focus.
- Ask a worker for a concise status summary when output is unclear.
- Verify high-impact findings by reopening cited files locally.
- Verify claimed test results with fresh controller-run commands when the result matters for completion.
- Review the final diff before accepting any worker patch.
- If a worker edits outside its claim, pause integration and decide whether to accept, request user-approved cleanup, or supersede with controller edits.
Stop Conditions
Stop and report instead of improvising when:
- cmux rejects a valid workspace, pane, or surface ref
- the requested model or startup flags are rejected
- authentication blocks the TUI
- worker output cannot be observed or controlled reliably
- a plan-mode status line or acceptance menu cannot be confirmed via
read-screen, or a worker's plan stays out of scope after a re-planning round - workers need overlapping edits that the controller cannot integrate safely
- the task requires focus-changing cmux commands and the user has not approved them
Use this skill for orchestration mechanics. Use task/domain skills separately for coding, review, debugging, UI, browser QA, or product-specific judgment.
Diagram
Use assets/fable-orchestrator.excalidraw or the generated PNG variants when
a visual explanation of the controller/worker topology helps.
04 同仓库更多 Skills
to-prompt-opus
Use when preparing or rewriting prompts for Claude Opus 4.8, Anthropic API agents, XML-structured prompts, long-context document work, coding agents, research synthesis, frontend/design tasks, or model-specific prompt optimization. Do not use for GPT/OpenAI prompts or raw context packaging without Opus-specific tuning.
to-prompt-gpt
Use when preparing or rewriting prompts for GPT-5.5, OpenAI API agents, Responses workflows, coding agents, research synthesis, support assistants, or model-specific prompt optimization. Do not use for Claude/Opus prompts or raw context packaging without GPT-specific tuning.
plan-refactor-qa
Plans and runs qa-report before executing Compozy refactor tasks. Use when the user provides a refactor or issue slug and wants Codex to inspect the matching .compozy/tasks directory, related PRD/TechSpec/ADR/task artifacts, affected code, and existing tests, then invoke $qa-report with a repository-grounded prompt. Do not use to run tests, execute qa-execution, implement code, or perform post-refactor verification.
multi-tool-branch-review
Orchestrates a multi-tool branch review of the current git branch against a base branch. By default it runs two independent thermo-nuclear maintainability audits, one on Codex GPT-5.5 xhigh and one on Claude Opus xhigh, then consolidates the findings into a single remediation plan via writing-plans. If the user explicitly asks for native reviews, it can add the Claude native review pass, the Codex native review pass, or both. Use when the user wants a deep cross-model review of a branch or PR before merge, or asks to review this branch with multiple tools or models. Encodes known infra failure modes and their fixes (missing Claude ACP adapter, Codex MCP auth hangs, false-positive report files, long jobs orphaned inside subagents). Do not use for reviewing a single uncommitted snippet, for non-git work, for running only one reviewer, or when the user only wants a quick lint or test run.
create-pr-with-template
Create a GitHub Pull Request with gh CLI and prefer repository PR templates automatically. Use this whenever the user asks to open/create a PR, especially when template compliance is needed. If multiple templates exist, ask the user which template to use.
ui-craft
Provides guardrails for user-facing UI work: usability heuristics, accessibility floors, design-system discipline, component states, microcopy, motion, dark mode, responsive behavior, and human-AI UX. Use when designing, generating, reviewing, or refactoring visible product surfaces such as components, pages, dashboards, forms, dialogs, loading/empty/error states, or AI interfaces. Do not use for backend-only work, infrastructure, CLI/TUI design, or pure documentation editing.