michelhelsdingen/ensemble/skill

Collab: Autonomous AI Team Collaboration

Language rule: ALWAYS respond in the same language the user used to invoke /collab. If the user writes in English, all your output (status updates, summaries, everything) must be in English. If Dutch, respond in Dutch. Never mix languages.

For a single review, a team is often overkill; use single-agent delegation if available.

Launch a Codex + Claude team. Runtime files are namespaced under /tmp/ensemble/<TEAM_ID>/.

Script Paths

Every script lives in __ENSEMBLE_DIR__/scripts/ and MUST be called with its full path and .sh extension. They are not on $PATH, and the permission allowlist installed by setup-claude-code.sh only covers the full paths. Calling a bare collab-launch fails.

Set this once per session and reuse it:

ES="__ENSEMBLE_DIR__/scripts"

Path Convention

All collab artifacts live in /tmp/ensemble/<TEAM_ID>/:

• messages.jsonl — agent + ensemble message log
• summary.txt — written on disband by ensemble-service
• bridge.pid, bridge.log — bridge process
• poller.pid, feed.txt — background poller
• postcheck.log: output of the automatic post-spawn health check
• prompts/, delivery/ — agent prompt/delivery files
• .finished — written by ensemble-service AFTER summary.txt
• team-id — team ID marker
• sessions: this team's tmux session names, one per line, written by ensemble-service on

every successful agent spawn; what postcheck and rescue use to only touch this team's panes

Workflow

Step 0: Detect environment

if [ "${HERDR_ENV:-}" = "1" ]; then
  echo "HERDR"
elif [ -n "$TMUX" ]; then
  echo "TMUX_YES"
elif [ "$(uname)" = "Darwin" ] && [ "${TERM_PROGRAM:-}" = "iTerm.app" ]; then
  echo "ITERM_NATIVE"
else
  echo "TMUX_NO"
fi

Four monitor modes:

• HERDR — inside a herdr workspace; collab-launch.sh asks herdr for the split
• TMUX_YES — already inside tmux; collab-launch.sh opens a split pane right
• ITERM_NATIVE — macOS iTerm2 without tmux; collab-launch.sh uses osascript to open a native iTerm split pane (no tmux attach needed)
• TMUX_NO — fallback: detached tmux session the user must attach to

Check `HERDR_ENV` first, and never conclude "iTerm" from `TERM_PROGRAM` alone. herdr owns the terminal and draws its own panes inside a host session, but passes TERM_PROGRAM=iTerm.app straight through. An AppleScript split then opens a real iTerm pane outside the layout the user is watching: it succeeds, reports success, and is never seen. HERDR_ENV=1 is the reliable signal (HERDR_PANE_ID, HERDR_TAB_ID and HERDR_WORKSPACE_ID name the exact pane).

Force a specific mode with COLLAB_MONITOR=herdr|tmux|iterm|none, change the herdr layout with COLLAB_HERDR_MODE=split|tab, or the iTerm layout with COLLAB_ITERM_MODE=split|tab|window (both default split).

Step 1: Launch the team

"$ES/collab-launch.sh" "$(pwd)" "$TASK_DESCRIPTION" [AGENTS] [TEMPLATE]

Agent selection (3rd argument, optional). Comma-separated keys from agents.json; the first one becomes lead. Default when omitted: codex (lead) + claude code (worker). Available keys: codex, claude, grok, agy, gemini, glm, opencode (all defined in agents.json). When configured, healthCommand checks which agents are currently usable and catches an unavailable CLI before launch. An unknown key is not an error: resolveAgentProgram() falls back to claude, so a typo silently spawns a second claude instead of failing. Only pass this when the user explicitly names agents in the task (for example, "use agy and claude"). Preflight checks only the CLIs you name here, so a codex quota wall does not block a grok,claude run. Naming agents explicitly also disables the auto-fallback: a dead agent becomes a hard failure instead of a silent swap.

Also settable via COLLAB_AGENTS, for a preferred line-up you do not want to retype (export COLLAB_AGENTS="codex,claude,grok"). Precedence: 3rd argument > COLLAB_AGENTS > the default pair. Only the argument counts as naming your agents; COLLAB_AGENTS is a standing preference and keeps the auto-fallback, with every swap printed as a warning.

Template selection (4th argument, optional). A key from collab-templates.json that gives each agent an explicit role instead of the generic lead/worker prompt. Also settable via COLLAB_TEMPLATE. Pick one when the task clearly matches:

Leave it empty if the task does not fit cleanly. A wrong template is worse than none.

Extract TEAM_ID from the launch output (last line is TEAM_ID=<id>):

TEAM_ID=$(printf '%s\n' "$LAUNCH_OUTPUT" | sed -n 's/^TEAM_ID=//p' | tail -1)

Do not read /tmp/collab-team-id.txt unless you have no launch output: it is a single global file that a concurrent collab overwrites.

Check that the launch actually succeeded before doing Step 2. collab-launch.sh can fail after the team already exists: exit 3 means a team was created but no message was exchanged within the wait window, exit 4 means the bridge or poller died right after starting. Both print a TEAM_ID= trailer anyway, but neither one printed Team is live!. Only tell the user the team is live when that exact line is in the output. On exit 3, run "$ES/collab-rescue.sh" "$TEAM_ID" before saying anything is running.

Step 1b: Health checks (automatic, do not re-run)

• Preflight runs inside collab-launch.sh before the team is created. It checks the

service, agent CLI auth, and DNS. Non-zero exit means launch aborted with the fix command printed. Do not paper over it with COLLAB_SKIP_PREFLIGHT=1 unless the user asks. Exit codes: 1 service down, 2 service started in an unauthenticated shell (restart it), 3 claude CLI broken, 4 codex CLI broken, 5 DNS/network, 6 grok CLI broken, 7 health hook reports an unavailable requested agent or no healthy fallback. Exit 7 is also returned by the launcher; its message lists healthy alternatives.

• Postcheck is armed automatically and fires ~25s after spawn. It only ever looks at this

team's own tmux sessions. If an agent is stuck in an error state, or zero messages were exchanged in its wait window, it kills the team and writes the diagnosis to /tmp/ensemble/<TEAM_ID>/postcheck.log. If a team dies within the first minute, read that file before guessing.

Step 2: Tell the user where the monitor is

• HERDR: "Team is live in the new herdr pane on the right."
• TMUX_YES: "Team is live in the right tmux pane."
• ITERM_NATIVE: "Team is live in the new iTerm pane on the right."
• TMUX_NO: "tmux attach -t ensemble-$TEAM_ID — live TUI monitor (steer, disband, scroll)"

Step 3: Monitoring — the user MUST see the conversation

CRITICAL RULE: The user wants to SEE the team's conversation as it happens. Every poll result must be presented clearly and formatted as a readable conversation. Do NOT just dump raw output — format it as a proper dialogue.

If TMUX_NO: poll and PRESENT messages inline

Use collab-poll.sh — a single-shot poller that tracks state automatically and gives clean output.

Poll command:

"$ES/collab-poll.sh" "$TEAM_ID" --sleep <seconds>

Output format: sender\tcontent lines, ending with one of:

• ---STATUS:ACTIVE — new messages were found
• ---STATUS:QUIET — no new messages (agents in deep work)
• ---STATUS:DONE — team finished, followed by summary.txt content
• ---STATUS:WAITING — messages file not yet created

Presentation rules — THIS IS THE KEY PART: After each poll, present the new messages to the user like this:

codex-1: [message content]

claude-2: [message content]

Use markdown bold for agent names. Show the FULL message content (up to 500 chars), not truncated summaries. Between polls, add a brief status line like "Team is working... next check in 15s."

Polling cadence:

• First poll: --sleep 10
• Normal: --sleep 15 to --sleep 20
• If 3+ polls QUIET: --sleep 30 (agents in deep work)
• On ---STATUS:DONE: stop polling, present final summary

When done, present structured summary + clean up:

TEAM_ID="<id>" && RD="/tmp/ensemble/$TEAM_ID" && kill "$(cat "$RD/poller.pid" 2>/dev/null)" 2>/dev/null || true; kill "$(cat "$RD/bridge.pid" 2>/dev/null)" 2>/dev/null || true; tmux kill-session -t "ensemble-$TEAM_ID" 2>/dev/null || true

If HERDR: background summary watcher

Same as TMUX_YES: the monitor pane is visible to the user, so don't inline-poll. Wait for completion in the background and present the final summary. The monitor closes its own herdr pane on exit (pane id in /tmp/ensemble/<TEAM_ID>/herdr-pane-id), so no tmux kill-session.

If ITERM_NATIVE: background summary watcher

Same as TMUX_YES: the monitor pane is visible to the user, so don't inline-poll. Wait for completion in the background (same snippet as below) and present the final summary when done. On cleanup, the iTerm pane lives on — the user closes it with q or Cmd+W. Do NOT try to tmux kill-session (no tmux session exists in this mode).

If TMUX_YES: background summary watcher

Monitor visible in right pane. Wait in background:

TEAM_ID="<id>" && RD="/tmp/ensemble/$TEAM_ID" && while [ ! -f "$RD/.finished" ] && [ ! -f "$RD/summary.txt" ]; do sleep 8; done && echo "COLLAB_COMPLETE" && cat "$RD/summary.txt" 2>/dev/null

Run with run_in_background: true, timeout: 600000.

When done: summarize + cleanup poller/bridge PIDs.

How a team ends

Auto-disband triggers on one of two paths:

1. Explicit sentinel (preferred). EVERY active agent sends a team-say whose entire content

is <<COLLAB_DONE>>. This bypasses the message-count minimum and the idle wait. The agent prompts already instruct this. The bar is every agent, not two, so a third agent is never cut off while its teammates close up.

1. Idle + completion signals. A safety net for teams that go quiet without sending the

sentinel: it needs a minimum number of exchanged messages AND at least 60s of silence.

Ordinary words like "done" or "klaar" in a status update do not kill a team while the conversation is running. Do not warn agents to avoid those words.

Troubleshooting

Work through these in order before reporting a failure to the user.