agent-team-orchestrator

# Agent Team Orchestrator ## Overview Enforce the full agent teams infrastructure before any parallel work begins: TMUX for visibility, git worktrees for file isolation, TeamCreate for coordination. **Core principle:** 6 sequential hard gates. Each gate MUST pass before the next begins. No shortcuts. No exceptions. **Announce at start:** "I'm using the agent-team-orchestrator skill to set up a proper agent team with TMUX and git worktrees." ## When to Use ```dot digraph when_to_use { "2+ independent tasks?" [shape=diamond]; "Need parallel execution?" [shape=diamond]; "Single session is fine" [shape=box]; "Run 6-gate checklist" [shape=box style=filled fillcolor=lightgreen]; "2+ independent tasks?" -> "Need parallel execution?" [label="yes"]; "2+ independent tasks?" -> "Single session is fine" [label="no"]; "Need parallel execution?" -> "Run 6-gate checklist" [label="yes"]; "Need parallel execution?" -> "Single session is fine" [label="no - sequential"]; } ``` **Use when:** - User says "parallel", "team", "agent team", "swarm", "in parallel" - Implementation plan has 3+ independent tasks across different files/modules - Multiple subsystems to build, review, or debug simultaneously - Research/review tasks that benefit from competing perspectives **Do NOT use when:** - Tasks are sequential and depend on each other - Only 1 task (use single session) - Tasks edit the same files (conflicts inevitable regardless of worktrees) ## The 6 Hard Gates <HARD-GATE> You MUST complete each gate in order. You MUST verify each gate passed before proceeding to the next. NEVER skip a gate. NEVER reorder gates. If a gate fails, fix it before continuing. </HARD-GATE> ### Gate 1: Verify Git Repository ```bash git rev-parse --git-dir ``` **Pass:** Command succeeds — proceed to Gate 2. **Fail:** Not in a git repo. Tell the user: "Agent teams require a git repository for worktree isolation. Please navigate to a git repo and re-invoke." STOP. Do not proceed without a git repo. ### Gate 2: Verify TMUX Session ```bash echo $TMUX ``` **Pass:** `$TMUX` is set (non-empty) — proceed to Gate 3. **Fail:** Not in tmux. Tell the user: > Agent teams need TMUX for split-pane monitoring. Please start a tmux session and re-launch Claude inside it: > ``` > tmux new-session -s claude-team > claude > ``` STOP. Do not proceed without TMUX. Do not fall back to in-process mode. **Why this gate exists:** Without TMUX, teammates run invisibly in-process mode. You cannot monitor them, you cannot see their output, and you lose the primary benefit of agent teams. ### Gate 3: Create Git Worktrees For EACH planned teammate: 1. **Verify `.worktrees` is gitignored:** ```bash git check-ignore -q .worktrees 2>/dev/null ``` If NOT ignored: add `.worktrees/` to `.gitignore` and commit immediately. 2. **Create worktree:** ```bash git worktree add .worktrees/<teammate-name> -b worktree-<teammate-name> ``` 3. **Run project setup in each worktree** (auto-detect): ```bash cd .worktrees/<teammate-name> [ -f package.json ] && npm install [ -f requirements.txt ] && pip install -r requirements.txt [ -f pyproject.toml ] && pip install -e . [ -f Cargo.toml ] && cargo build [ -f go.mod ] && go mod download ``` 4. **Verify worktrees exist:** ```bash git worktree list ``` **Pass:** All worktrees created and dependencies installed — proceed to Gate 4. **Fail:** Fix the issue (gitignore, branch conflicts, etc.) before proceeding. ### Gate 4: Create Team (TeamCreate) ``` TeamCreate with team_name based on the task (e.g., "feature-auth-team", "refactor-team") ``` **Pass:** Team created successfully — proceed to Gate 5. **Fail:** Investigate error. Common issues: team already exists (clean up first), agent teams not enabled. ### Gate 5: Create & Structure Tasks (TaskCreate) Create one task per work item. EACH task description MUST include: 1. **Scope:** What exactly to build/fix/review 2. **Constraints:** What NOT to touch, boundaries 3. **Worktree path:** The absolute path to their worktree 4. **Expected output:** What "done" looks like 5. **Communication protocol:** "Use SendMessage to contact the lead if blocked" Set up dependencies with `addBlockedBy`/`addBlocks` where tasks depend on each other. **Pass:** All tasks created with full descriptions — proceed to Gate 6. ### Gate 6: Spawn Teammates For EACH teammate, use the Task tool with these REQUIRED parameters: ``` Task tool call: - team_name: "<team-name-from-gate-4>" - mode: "bypassPermissions" - subagent_type: "general-purpose" - name: "<teammate-name>" - prompt: <USE MANDATORY TEMPLATE BELOW> ``` **Mandatory Teammate Prompt Template:** Every teammate spawn prompt MUST include ALL of these sections: ``` You are teammate "<name>" on team "<team-name>". ## Your Worktree Your isolated workspace is at: <absolute-path-to-worktree> IMPORTANT: cd to this directory FIRST before doing any work. All your file edits happen here, not in the main repo. ## Your Tasks <paste full task descriptions from Gate 5> ## When Done 1. Mark each task complete with TaskUpdate (status: "completed") 2. Send a message to the lead summarizing what you did: SendMessage with type "message", recipient "<lead-name>" 3. Check TaskList for any remaining unblocked tasks you can claim ## If Blocked Send a message to the lead describing what's blocking you. Do NOT wait silently — communicate immediately. ## Rules - ONLY work in your worktree directory - Do NOT edit files in the main repo directory - Commit your work to your worktree branch ``` After spawning, assign tasks via `TaskUpdate` with `owner` set to each teammate's name. **Pass:** All teammates spawned and tasks assigned. ## Post-Launch: Monitor & Coordinate After all 6 gates pass: - **Cycle teammates:** Use `Shift+Down` to move between teammate panes in TMUX - **Check progress:** Periodically read TaskList to see task status - **Communicate:** Use SendMessage to direct teammates, answer questions, redirect approaches - **Synthesize:** When teammates finish, review their work across worktrees - **Merge:** Cherry-pick or merge worktree branches into main branch - **Cleanup:** Use `git worktree remove` for each worktree, then TeamDelete ## Red Flags — STOP Immediately These thoughts mean you are about to violate the skill. STOP and follow the gates: | Rationalization | Reality | |----------------|---------| | "I'll just use subagents (Task tool) instead" | NO. User wants agent teams. Use TeamCreate. | | "TMUX isn't available, I'll use in-process mode" | NO. Tell user to start tmux. Do not proceed. | | "Worktrees are overkill for this" | NO. File conflicts are the #1 agent team failure. Always use worktrees. | | "I'll set up worktrees later" | NO. Gate 3 comes before Gate 4. Follow the order. | | "I can skip the teammate prompt template" | NO. Missing worktree path = teammate edits main repo = conflicts. | | "bypassPermissions isn't needed" | YES IT IS. Without it, teammates stall on permission prompts and go silent. | | "I'll create the team first, then figure out tasks" | NO. Gates 4 and 5 exist in that order for a reason. Plan tasks before spawning. | | "This is just 2 tasks, a full team is overkill" | If user wants parallel execution, use the full stack. Period. | | "I already know how to do agent teams" | Follow the gates anyway. The skill exists because ad-hoc teams fail. | ## Common Mistakes ### Teammates edit main repo instead of worktree - **Cause:** Worktree path missing from teammate prompt - **Fix:** ALWAYS include absolute worktree path and "cd to this directory FIRST" ### Teammates go silent / seem stuck - **Cause:** Permission prompts blocking them - **Fix:** ALWAYS spawn with `mode: "bypassPermissions"` ### Can't see teammate output - **Cause:** Running in-process mode instead of TMUX split panes - **Fix:** Gate 2 prevents this — verify TMUX before creating team ### Teammates overwrite each other's work - **Cause:** No worktree isolation — all editing same directory - **Fix:** Gate 3 prevents this — one worktree per teammate ### Team creation fails silently - **Cause:** `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` not set - **Fix:** Verify env var is set in `~/.claude/settings.json` ## Quick Reference | Gate | Check | Fail Action | |------|-------|-------------| | 1. Git repo | `git rev-parse --git-dir` | Tell user to navigate to repo | | 2. TMUX | `echo $TMUX` non-empty | Tell user to start tmux | | 3. Worktrees | `git worktree add` per teammate | Fix gitignore, create worktrees | | 4. Team | `TeamCreate` succeeds | Debug team creation error | | 5. Tasks | `TaskCreate` with full descriptions | Add missing scope/constraints/path | | 6. Teammates | `Task` with mandatory template | Include all template sections | ## Integration **Pairs with:** - **superpowers:using-git-worktrees** — Gate 3 follows its directory selection and safety patterns - **superpowers:finishing-a-development-branch** — Use after team work complete to merge/PR - **superpowers:writing-plans** — Plans feed into Gate 5 task creation **Replaces:** Ad-hoc agent team creation that skips infrastructure setup. ## Cleanup Checklist When team work is complete: 1. Review all teammate branches 2. Merge or cherry-pick desired changes into main branch 3. Remove worktrees: `git worktree remove .worktrees/<name>` for each 4. Send shutdown requests to teammates: `SendMessage` with `type: "shutdown_request"` 5. After all teammates shut down: `TeamDelete` 6. Verify clean state: `git worktree list` shows only main worktree