Orchestration layer for AI agents in cmux panes. Low-level pane operations (splits, reads, sends) use cmux MCP tools — this skill handles the workflow on top.

STOP — Before Anything Else

1. Source agent-functions.sh:

source ~/.claude/commands/cmux-agents/scripts/agent-functions.sh

This gives you spawn-agent, agent-status, agent-nudge, agent-kill. 99% failure rate when hand-rolling cmux commands — these are NOT optional.

2. You WILL use spawn-agent for every agent. No exceptions. No hand-rolled cmux send + cd + claude.

3. AGENT_REGISTRY — maintain after CLAUDE_COUNTER in every response with active agents:

AGENT_REGISTRY:
| Surface | Tab | Task | Status | Last Check |
|---------|-----|------|--------|------------|
| surface:153 | cmux-analysis | Digest failures | WORKING | 12:35 |

Add on spawn. Update on check. Remove on kill.

MCP Primitives (use these for low-level ops)

Use MCP tools directly for ad-hoc pane interaction. Use spawn-agent for full agent lifecycle.

Spawning Agents (MANDATORY: use spawn-agent)

source ~/.claude/commands/cmux-agents/scripts/agent-functions.sh
 
# Create surface via MCP, then spawn
spawn-agent <repo> <surface> '<tab-name>' '<task prompt>' [options]

Options: --model sonnet|opus, --launcher <func>, --cli gemini|codex|cursor-audit|cursor-work|kiro

Examples:

spawn-agent golems surface:114 'T1 search-fix' 'Fix search ranking' --model sonnet
spawn-agent golems surface:115 'T2 audit' 'Audit code quality' --cli cursor-audit
spawn-agent orchestrator surface:116 'T3 research' 'Survey patterns' --cli gemini
spawn-agent golems surface:117 'T4 refactor' 'Refactor retry' --cli codex

Multiple agents: Create ALL splits first (3s between for Touch ID), verify $ prompt on each via read_screen, THEN spawn sequentially.

Task Routing

Full CLI syntax and capabilities: adapters/ directory + adapters/capabilities.yaml.

Pre-Spawn Prompt Checklist

Every agent task prompt MUST include:

• Max output length ("2-3 sentences" / "under 200 words")
• Output format ("use this template: ...")
• Audience — internal or client-facing (agents leak investigation details if not told)
• What NOT to include — internal deliberation, false alarms
• Done signal ("end with DONE_SIGNAL_NAME on its own line, right before CLAUDE_COUNTER")

Full audit: workflows/prompt-audit.md

Monitoring Protocol

"I'll monitor them" is NOT monitoring. Monitoring = code on a schedule.

After spawning:

1. Update AGENT_REGISTRY
2. Run agent-status surface:N for each to verify boot (within 15s)
3. For >2 agents or AFK: set up polling every 3-5 min
4. Check agents at natural milestones in YOUR work, or every ~5 min idle
5. When agent finishes, read output IMMEDIATELY — don't wait for user to ask

Anti-patterns:

• Fire and forget — spawning without checking. You WILL miss failures.
• Checking only when user asks — agent may have been stuck 20 min.
• Not reading output files — agent finished, you never read results.
• Using Task tool when user says "cmux agents" — Task agents are invisible. cmux agents are VISIBLE. The user wants to SEE them.

Done Signals

Instruct agents to put the signal as the very last line before CLAUDE_COUNTER — not buried above a summary. Otherwise read_screen won't catch it.

Collab Pattern

Copy ~/Gits/orchestrator/collab/TEMPLATE.md first — never write a collab from scratch. The collab-guard.py hook WILL block you.

# 1. Write collab file from template
# 2. Spawn agents with collab instructions
for entry in "search:Agent1" "perf:Agent2" "security:Agent3"; do
  angle="${entry%%:*}"; name="${entry#*:}"
  # Create split via MCP, get surface ID
  spawn-agent TARGET_REPO "$SURFACE" "$name" \
    "Read collab/FILE.md — you are $name. Claim $angle. Update collab when done." --model sonnet
  sleep 3
done

Log every action in collab: spawns, completions, blockers. No silent work.

Git Worktree Isolation

Parallel agents MUST use separate worktrees — without them, agents clobber each other's git state.

• Claude subagents: Agent(isolation="worktree") (built-in)
• cmux agents: Create worktrees manually before spawning, then spawn-agent into the worktree dir. See worktrees skill for details.

Essential Rules

1. spawn-agent for every agent — no hand-rolled cmux commands
2. Discover surfaces before acting — use list_surfaces MCP tool
3. NEVER read_screen your own surface — recursive output
4. Verify after launch — read_screen within 15s
5. Workers = right splits, audits = down splits
6. Sequential launch — 3s between spawns for biometric
7. Cross-workspace: always pass workspace ref — surfaces are workspace-scoped
8. Name everything — rename_tab on every surface
9. Update collab after every action — spawns, completions, blockers
10. AGENT_REGISTRY is mandatory — maintains state across compaction
11. BrainLayer agents are sequential — stagger by 10s+ (SQLite = single writer)
12. Polling on spawn, not on request — set up monitoring immediately
13. Don't give hour-scale estimates for <500-line tasks — parallel agents are 8-10x faster