orchestrate skill

Orchestrate — Agent Fleet Supervisor

One tmux session, N windows — each window is one agent working in its own worktree. Speak naturally; Claude maps your intent to the right scripts.

Scripts

SKILLS_DIR=$(git rev-parse --show-toplevel)/.claude/skills/orchestrate/scripts
STATE_FILE=~/.claude/orchestrator-state.json

Supervision model

Orchestrating Claude (this Claude session — IS the supervisor)
  └── Reads pane output, checks CI, intervenes with targeted guidance
        run-loop.sh (separate tmux window, every 30s)
          └── Mechanical only: idle restart, dialog approval, recycle on ORCHESTRATOR:DONE

You (the orchestrating Claude) are the supervisor. After spawning agents, stay in this conversation and actively monitor: poll each agent's pane every 2-3 minutes, check CI, nudge stalled agents, and verify completions. Do not spawn a separate supervisor Claude window — it loses context, is hard to observe, and compounds context compression problems.

run-loop.sh is the mechanical layer — zero tokens, handles things that need no judgment: restart crashed agents, press Enter on dialogs, recycle completed worktrees (only after verify-complete.sh passes).

Checkpoint protocol

Agents output checkpoints as they complete each required step:

CHECKPOINT:<step-name>

Required steps are passed as args to spawn-agent.sh (e.g. pr-address pr-test). run-loop.sh will not recycle a window until all required checkpoints are found in the pane output. If verify-complete.sh fails, the agent is re-briefed automatically.

Worktree lifecycle

spare/N branch  →  spawn-agent.sh (--session-id UUID)  →  window + feat/branch + claude running
                                                                 ↓
                                               CHECKPOINT:<step> (as steps complete)
                                                                 ↓
                                                        ORCHESTRATOR:DONE
                                                                 ↓
                                    verify-complete.sh: checkpoints ✓ + 0 threads + CI green + no fresh CHANGES_REQUESTED
                                                                 ↓
                                              state → "done", notify, window KEPT OPEN
                                                                 ↓
                              user/orchestrator explicitly requests recycle
                                                                 ↓
                                         recycle-agent.sh → spare/N (free again)

Windows are never auto-killed. The worktree stays on its branch, the session stays alive. The agent is done working but the window, git state, and Claude session are all preserved until you choose to recycle.

To resume a done or crashed session:

# Resume by stored session ID (preferred — exact session, full context)
claude --resume SESSION_ID --permission-mode bypassPermissions

# Or resume most recent session in that worktree directory
cd /path/to/worktree && claude --continue --permission-mode bypassPermissions

To manually recycle when ready:

bash ~/.claude/orchestrator/scripts/recycle-agent.sh SESSION:WIN WORKTREE_PATH spare/N
# Then update state:
jq --arg w "SESSION:WIN" '.agents |= map(if .window == $w then .state = "recycled" else . end)' \
  ~/.claude/orchestrator-state.json > /tmp/orch.tmp && mv /tmp/orch.tmp ~/.claude/orchestrator-state.json

State file (~/.claude/orchestrator-state.json)

Never committed to git. You maintain this file directly using jq + atomic writes (.tmp → mv).

{
  "active": true,
  "tmux_session": "autogpt1",
  "idle_threshold_seconds": 300,
  "loop_window": "autogpt1:5",
  "repo": "Significant-Gravitas/AutoGPT",
  "discord_webhook": "https://discord.com/api/webhooks/...",
  "last_poll_at": 0,
  "agents": [
    {
      "window": "autogpt1:3",
      "worktree": "AutoGPT6",
      "worktree_path": "/path/to/AutoGPT6",
      "spare_branch": "spare/6",
      "branch": "feat/my-feature",
      "objective": "Implement X and open a PR",
      "pr_number": "12345",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "steps": ["pr-address", "pr-test"],
      "checkpoints": ["pr-address"],
      "state": "running",
      "last_output_hash": "",
      "last_seen_at": 0,
      "spawned_at": 0,
      "idle_since": 0,
      "revision_count": 0,
      "last_rebriefed_at": 0
    }
  ]
}

Top-level optional fields:

• repo — GitHub owner/repo for CI/thread checks. Auto-derived from git remote if omitted.
• discordwebhook — Discord webhook URL for completion notifications. Also reads DISCORDWEBHOOK_URL env var.

Per-agent fields:

• session_id — UUID passed to claude --session-id at spawn; use with claude --resume UUID to restore exact session context after a crash or window close.
• lastrebriefedat — Unix timestamp of last re-brief; enforces 5-min cooldown to prevent spam.

Agent states: running | idle | stuck | waiting_approval | complete | done | escalated

done means verified complete — window is still open, session still alive, worktree still on task branch. Not recycled yet.

Serial /pr-test rule

/pr-test and /pr-test --fix run local Docker + integration tests that use shared ports, a shared database, and shared build caches. Running two /pr-test jobs simultaneously will cause port conflicts and database corruption.

Rule: only one /pr-test runs at a time. The orchestrator serializes them.

You (the orchestrating Claude) own the test queue:

1. Agents do pr-review and pr-address in parallel — that's safe (they only push code and reply to GitHub).
2. When a PR needs local testing, add it to your mental queue — don't give agents a pr-test step.
3. Run /pr-test https://github.com/OWNER/REPO/pull/PR_NUMBER --fix yourself, sequentially.
4. Feed results back to the relevant agent via tmux send-keys:

tmux send-keys -t SESSION:WIN "Local tests for PR #N: <paste failure output or 'all passed'>. Fix any failures and push, then output ORCHESTRATOR:DONE."
   sleep 0.3
   tmux send-keys -t SESSION:WIN Enter

1. Wait for CI to confirm green before marking the agent done.

If multiple PRs need testing at the same time, pick the one furthest along (fewest pending CI checks) and test it first. Only start the next test after the previous one completes.

Session restore (tested and confirmed)

Agent sessions are saved to disk. To restore a closed or crashed session:

# If session_id is in state (preferred):
NEW_WIN=$(tmux new-window -t SESSION -n WORKTREE_NAME -P -F '#{window_index}')
tmux send-keys -t "SESSION:${NEW_WIN}" "cd /path/to/worktree && claude --resume SESSION_ID --permission-mode bypassPermissions" Enter

# If no session_id (use --continue for most recent session in that directory):
tmux send-keys -t "SESSION:${NEW_WIN}" "cd /path/to/worktree && claude --continue --permission-mode bypassPermissions" Enter

--continue restores the full conversation history including all tool calls, file edits, and context. The agent resumes exactly where it left off. After restoring, update the window address in the state file:

jq --arg old "SESSION:OLD_WIN" --arg new "SESSION:NEW_WIN" \
  '(.agents[] | select(.window == $old)).window = $new' \
  ~/.claude/orchestrator-state.json > /tmp/orch.tmp && mv /tmp/orch.tmp ~/.claude/orchestrator-state.json

Intent → action mapping

Match the user's message to one of these intents:

When the intent is ambiguous, show capacity first and ask what tasks to run.

Spawning agents

1. Resolve tmux session

tmux list-sessions -F "#{session_name}: #{session_windows} windows" 2>/dev/null

Use an existing session. Never create a tmux session from within Claude — it becomes a child of Claude's process and dies when the session ends. If no session exists, tell the user to run tmux new-session -d -s autogpt1 in their terminal first, then re-invoke /orchestrate.

2. Show available capacity

bash $SKILLS_DIR/capacity.sh $(git rev-parse --show-toplevel)

3. Collect tasks from the user

For each task, gather:

• objective — what to do (e.g. "implement feature X and open a PR")
• branch name — e.g. feat/my-feature (derive from objective if not given)
• prnumber** — GitHub PR number if working on an existing PR (for verification)
• steps — required checkpoint names in order (e.g. pr-address pr-test) — derive from objective

Ask for idlethresholdseconds only if the user mentions it (default: 300).

Never ask the user to specify a worktree — auto-assign from find-spare.sh.

4. Spawn one agent per task

# Get ordered list of spare worktrees
SPARE_LIST=$(bash $SKILLS_DIR/find-spare.sh $(git rev-parse --show-toplevel))

# For each task, take the next spare line:
WORKTREE_PATH=$(echo "$SPARE_LINE" | awk '{print $1}')
SPARE_BRANCH=$(echo "$SPARE_LINE" | awk '{print $2}')

# With PR number and required steps:
WINDOW=$(bash $SKILLS_DIR/spawn-agent.sh "$SESSION" "$WORKTREE_PATH" "$SPARE_BRANCH" "$NEW_BRANCH" "$OBJECTIVE" "$PR_NUMBER" "pr-address" "pr-test")

# Without PR (new work):
WINDOW=$(bash $SKILLS_DIR/spawn-agent.sh "$SESSION" "$WORKTREE_PATH" "$SPARE_BRANCH" "$NEW_BRANCH" "$OBJECTIVE")

Build an agent record and append it to the state file. If the state file doesn't exist yet, initialize it:

# Derive repo from git remote (used by verify-complete.sh + supervisor)
REPO=$(git remote get-url origin 2>/dev/null | sed 's|.*github\.com[:/]||; s|\.git$||' || echo "")

jq -n \
  --arg session "$SESSION" \
  --arg repo "$REPO" \
  --argjson threshold 300 \
  '{active:true, tmux_session:$session, idle_threshold_seconds:$threshold,
    repo:$repo, loop_window:null, supervisor_window:null, last_poll_at:0, agents:[]}' \
  > ~/.claude/orchestrator-state.json

Optionally add a Discord webhook for completion notifications: