agent-team-orchestrator

name	agent-team-orchestrator
description	Use when facing 2+ independent parallelizable tasks, when user asks for agent teams, parallel work, swarm, or team-based execution, or when an implementation plan has 3+ independent tasks that would benefit from separate Claude Code sessions

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

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

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.

Gate 1: Verify Git Repository

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

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:

git check-ignore -q .worktrees 2>/dev/null

If NOT ignored: add .worktrees/ to .gitignore and commit immediately.

2. Create worktree:

git worktree add .worktrees/<teammate-name> -b worktree-<teammate-name>

3. Run project setup in each worktree (auto-detect):

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:

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