Orchestration Skill - Multi-Session Workflows

This skill enables you to orchestrate multiple Claude Code sessions, spawn workers, and coordinate parallel work using TabzChrome.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Vanilla Claude Session (you)                               │
│  ✅ Has Task tool → can spawn subagents                     │
│                                                             │
│  Subagents (via Task tool):                                 │
│    → conductor:skill-picker (haiku) - find/install skills   │
│    → conductor:tui-expert (opus) - spawn TUI tools          │
│    → conductor:code-reviewer (sonnet) - review changes      │
│                                                             │
│  Monitoring (via tmuxplexer):                               │
│    → Background window shows all AI sessions                │
│    → Conductor polls directly, no subagent needed           │
│                                                             │
│  Terminal Workers (via TabzChrome spawn API):               │
│    → Each is a vanilla Claude with full Task tool           │
│    → Can use their own subagents for exploration            │
│    → Assigned tab groups for browser isolation              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Why this works: Skills add knowledge without restricting tools. You keep the Task tool and can spawn lightweight subagents for monitoring while workers run in separate terminals with full capabilities.

Core Capabilities (TabzChrome)

Tabz MCP Tools

mcp-cli info tabz/<tool>  # Check schema before calling

Subagents (via Task Tool)

Since you're running as vanilla Claude (not via --agent), the Task tool is available:

Example - Prepare worktrees for parallel workers:

Task tool:
  subagent_type: "conductor:initializer"
  prompt: "Prepare 3 workers for issues beads-abc, beads-def, beads-ghi in /home/matt/projects/myapp"

Worker Monitoring (via tmuxplexer)

Instead of a watcher subagent, monitor workers directly via tmuxplexer in a background window:

# Spawn tmuxplexer --watcher as background window
plugins/conductor/scripts/monitor-workers.sh --spawn

# Poll worker status every ~2 minutes
plugins/conductor/scripts/monitor-workers.sh --status
# Output: ctt-worker-abc|tool_use|45

# Get summary
plugins/conductor/scripts/monitor-workers.sh --summary
# Output: WORKERS:3 WORKING:2 IDLE:0 AWAITING:1 STALE:0

Note: awaiting_input means worker is at prompt, not necessarily AskUserQuestion. Check actual pane if idle too long.

Terminal Workers

Workers are spawned as separate Claude sessions via TabzChrome API. Each worker:

• Has full Task tool (can spawn their own subagents)
• Runs in isolated worktree with own node_modules
• Gets assigned port for dev server (no conflicts)
• Uses build lock for test/build (serialized)

Worker internal flow:

1. Code the solution (main work)
2. Task(conductor:code-reviewer) → quality gate
   - If passed=false → fix blockers, re-review
   - If passed=true → continue
3. Acquire build lock → npm test && npm build
4. git commit
5. bd close <issue> --reason "..."

Terminal Management

Get auth token:

cat /tmp/tabz-auth-token

Spawn a worker:

TOKEN=$(cat /tmp/tabz-auth-token)
curl -s -X POST http://localhost:8129/api/spawn \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $TOKEN" \
  -d '{"name": "Claude: Task Name", "workingDir": "/path/to/project", "command": "claude --dangerously-skip-permissions"}'

• Always include "Claude:" in name (enables status tracking)
• Always use --dangerously-skip-permissions
• Response includes terminal.sessionName - save for sending prompts

Send prompt to worker:

SESSION="ctt-claude-task-xxxxx"
sleep 4  # Wait for Claude init

# CRITICAL: Validate session exists before sending (prevents crashes)
if ! tmux has-session -t "$SESSION" 2>/dev/null; then
  echo "ERROR: Session $SESSION does not exist"
  exit 1
fi

tmux send-keys -t "$SESSION" -l 'Your prompt here...'
sleep 0.3
tmux send-keys -t "$SESSION" C-m

List active terminals:

curl -s http://localhost:8129/api/agents | jq '.data[] | {id, name, state}'

Kill a terminal:

curl -X DELETE http://localhost:8129/api/agents/{terminal-id}

Worker Prompt Structure

When sending tasks to workers, include relevant capabilities:

## Task
[Clear description of what needs to be done]

## Approach
- Use the xterm-js skill for terminal patterns
- Use subagents in parallel to explore the codebase
- Use tabz MCP tools for browser automation (if worker has tab group)

## Files
@path/to/relevant/file.ts
@path/to/another/file.ts

## Constraints
[What NOT to change, requirements to follow]

## Success Criteria
[How to verify the task is complete]

Capability Triggers

Skills require explicit phrasing. Use "use the ___ skill to..." format:

Tab Group Isolation

When spawning multiple workers that need browser access:

1. Create a unique tab group per worker
2. Pass the groupId to the worker
3. Worker uses explicit tabId - never relies on active tab

# Create isolated tab group for worker
tabz_create_group --title "Worker-1" --color "blue"
# Returns groupId - pass to worker prompt

Workflows

Parallel Workers

# Spawn multiple workers
curl -s -X POST http://localhost:8129/api/spawn ... -d '{"name": "Claude: Frontend", ...}'
curl -s -X POST http://localhost:8129/api/spawn ... -d '{"name": "Claude: Backend", ...}'

# Start monitor in background window
plugins/conductor/scripts/monitor-workers.sh --spawn

# Poll periodically
plugins/conductor/scripts/monitor-workers.sh --summary

Beads Issue Swarm

Use /conductor:bd-swarm command or:

1. bd ready - Get unblocked issues
2. Spawn workers (1 per issue)
3. Send skill-aware prompts with issue context
4. Workers close issues when done: bd close <id> --reason "..."

TUI Tools

Invoke tui-expert subagent for system info:

Task(subagent_type="conductor:tui-expert",
     prompt="Check system resources with btop")

Best Practices

1. Use subagents for monitoring - Haiku watcher is cheap
2. Workers are vanilla Claude - They have full Task tool
3. Tab groups for isolation - Each browser worker gets own group
4. One goal per worker - Keep context focused
5. Capability triggers - Activate skills explicitly
6. Clean up when done - Kill terminals after completion

Error Handling

Backend not running:

curl -s http://localhost:8129/api/health || echo "Start TabzChrome backend"

Auth token missing:

cat /tmp/tabz-auth-token || echo "Token missing - restart backend"

Session not found:

tmux has-session -t "$SESSION" 2>/dev/null || echo "Session does not exist"

Related Commands

• /conductor:bd-swarm - Spawn workers for beads issues
• /conductor:plan-backlog - Sprint planning for parallel work
• /conductor:bd-status - Check beads issue status
• /conductor:bd-work - Work on a single beads issue