launching-agent-teams

STARTER_CHARACTER = 🚀👥

Setup

Update reference docs to get the latest from Anthropic:

python ${CLAUDE_SKILL_DIR}/scripts/update-docs.py

Prerequisites

Agent teams are experimental. The user must have this in their settings (~/.claude/settings.json or .claude/settings.json):

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

If the flag isn't set, tell the user and offer to add it before proceeding.

Teams vs Subagents — Pick the Right Tool

Before launching a team, confirm it's the right approach:

Use agent teams when:

• Teammates need to communicate with each other
• Work benefits from debate, challenge, or cross-pollination
• Tasks span multiple independent areas (frontend/backend/tests)
• Investigation needs competing hypotheses

Use subagents instead when:

• Workers just report results back (no inter-agent communication)
• Tasks are focused and self-contained
• You want lower token cost
• Sequential dependency between steps

Use git worktrees when:

• You want manual parallel sessions without automated coordination

If the task fits subagents better, say so and offer that instead.

Launching a Team

1. Clarify the Work

Before spawning anything, understand:

• What's the goal?
• What are the independent pieces?
• What would each teammate own?

2. Decompose Into Roles

Each teammate should own a distinct, non-overlapping area. Overlap causes file conflicts and wasted tokens.

Aim for 3-5 teammates. More than that creates coordination overhead that rarely pays off. Each teammate should have 5-6 tasks to stay productive.

Anti-patterns:

• Two teammates editing the same file
• A teammate with only one small task (just do it yourself)
• Roles so broad they inevitably overlap

3. Size Tasks Appropriately

• Too small: coordination overhead exceeds the benefit
• Too large: teammates work too long without check-ins
• Right size: self-contained units with a clear deliverable (a function, a test file, a review document)

4. Write Rich Spawn Prompts

Teammates do NOT inherit the lead's conversation history. They only get:

• CLAUDE.md and project context
• The spawn prompt you write

Include in each spawn prompt:

• Specific files/modules they own
• Relevant context they need (architecture decisions, constraints)
• What "done" looks like
• Technologies, patterns, or conventions to follow

5. Configure Display Mode

• in-process (default): all teammates in one terminal, cycle with Shift+Down
• tmux/auto: split panes, each teammate visible (requires tmux or iTerm2)

For monitoring multiple teammates, split panes are better. Suggest tmux if available.

6. Create the Team

Present the proposed team structure to the user for approval before spawning. The structure should cover:

• Team goal
• Number of teammates and their roles
• What each teammate owns (specific files/modules)
• Model choice (default: inherit from lead, or Sonnet for cost efficiency)
• Whether plan approval is needed (recommend for risky/destructive work)

Team Management

• Plan approval: For risky work, require teammates to plan before implementing. The lead reviews and approves/rejects plans.
• Direct messaging: Users can message individual teammates via Shift+Down (in-process) or clicking panes (split mode).
• Task dependencies: Tasks can depend on other tasks. Blocked tasks auto-unblock when dependencies complete.
• Hooks: TeammateIdle (exit code 2 sends feedback, keeps teammate working) and TaskCompleted (exit code 2 prevents completion).

Key Constraints

• One team per session — clean up before starting a new one
• No nested teams — teammates cannot spawn their own teams
• Lead is fixed — can't transfer leadership
• No session resumption for in-process teammates — after resume, spawn new ones
• All teammates start with the lead's permission mode
• Shutdown can be slow — teammates finish current tool call first

Parallel Work Principles

From large-scale multi-agent projects:

• Decompose for true parallelism: if all agents converge on the same bug/file, parallelization fails regardless of team size
• Design for agent orientation: teammates entering fresh need rich context in their spawn prompts and CLAUDE.md — documentation is their primary interface
• Lightweight coordination: file-based task lists + git conflict resolution work better than complex orchestration
• Acknowledge hard limits: autonomous agents have ceilings — plan for human verification of critical outcomes

Cleanup

Always clean up through the lead:

Clean up the team

Shut down teammates first, then clean up. If orphaned tmux sessions persist:

tmux ls
tmux kill-session -t <session-name>

Reference

• [references/anthropic-agent-teams.md](references/anthropic-agent-teams.md) - Complete agent teams documentation
• [references/anthropic-sub-agents.md](references/anthropic-sub-agents.md) - Subagents documentation (for comparison and configuration)