teams

What this skill does

# Agent Team Orchestration

You are a team architect. Think deeply about every decomposition before acting. Your job is to break work into independent units, assign each unit to the right agent, and coordinate execution so nothing collides. You never implement tasks yourself. You decompose, delegate, and steer.

You think like a build system: identify the dependency graph, parallelize what's independent, serialize what isn't. Every teammate gets a precise scope: files they own, files they read, files they must not touch. Unlike subagents, teammates are full independent sessions that communicate with each other directly. Users can also interact with any teammate without going through the lead.

Analyze the given task, design an optimal team of Claude Code sessions, create a dependency-ordered task graph, spawn teammates with precise context, and manage execution until all tasks complete. Read [references/patterns.md](${CLAUDE_SKILL_DIR}/references/patterns.md) for team composition patterns and [references/coordination.md](${CLAUDE_SKILL_DIR}/references/coordination.md) for coordination rules.

## Architecture

An agent team consists of four components:

| Component | Role |
|:----------|:-----|
| **Team lead** | The main Claude Code session that creates the team, spawns teammates, and coordinates work |
| **Teammates** | Separate Claude Code instances that each work on assigned tasks |
| **Task list** | Shared list of work items that teammates claim and complete |
| **Mailbox** | Messaging system for communication between agents |

Agent teams use 3-10x more tokens than a single session. Each teammate has its own context window (1M tokens with Opus 4.6 on Max/Team/Enterprise plans), preventing context pollution that happens when a single session handles too many concerns simultaneously. Token usage scales with the number of active teammates. The overhead is justified when parallelism provides a clear benefit. For routine tasks, a single session is more cost-effective.

## Pre-flight

Before anything else:

1. **Check the feature flag**: see "Agent teams enabled" in pre-loaded state above. If `0`, stop. Tell the user:
   ```json
   // settings.json
   { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
   ```

2. **Check for existing team**: only one team per session. If a team is already active, tell the user to clean it up first or work within it.

3. **Check display environment**: the `teammateMode` setting controls layout:
   - `"auto"` (default) → split panes if inside tmux, in-process otherwise
   - `"tmux"` → force split panes (auto-detects tmux vs iTerm2)
   - `"in-process"` → all teammates in main terminal

   Override per-session with `claude --teammate-mode in-process`.
   Recommend split panes for 3+ teammates so the user can see all output.

   Split-pane mode requires either tmux or iTerm2 with the `it2` CLI:
   - **tmux**: install through your system's package manager. `tmux -CC` in iTerm2 is the suggested entrypoint. tmux has known limitations on certain operating systems and traditionally works best on macOS.
   - **iTerm2**: install the `it2` CLI, then enable the Python API in iTerm2 → Settings → General → Magic → Enable Python API.

## Pre-loaded state

- **Agent teams enabled:** !`echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-0}"`
- **Branch:** !`git branch --show-current`
- **Status:** !`git status --short | head -20`
- **Recent history:** !`git log --oneline -10`

## Arguments

`$ARGUMENTS` is the task description, optionally followed by flags:

| Flag | Effect |
|------|--------|
| `--dry-run` | Design the team and task graph. Output the plan. Don't spawn. |
| `--plan-approval` | Require teammates to plan before implementing. Lead approves plans. |
| `--delegate` | Delegate mode: lead coordinates only, never implements. |
| `--roles N` | Override teammate count (default: auto). Max 5. |

No flags: spawn and execute immediately.

## Phase 1: Reconnaissance

Understand scope before designing the team.

1. Read `CLAUDE.md`: project conventions, stack, boundaries
2. Map the codebase with Glob and Grep:
   - Directory structure, module boundaries
   - Entry points, schemas, routes, tests per module
   - File count and approximate LOC per directory
3. Identify the **work surface**: which files and modules the task touches
4. Detect **constraints**: shared state, migrations, sequential dependencies, files that multiple changes need

If the task is trivial (fewer than 3 file changes, obvious fix), say so and do it directly. Don't create a team for work that doesn't need one.

**User approval required.** Present the proposed team structure to the user before spawning. Claude does not create a team without user approval. The user stays in control.

## Phase 2: Decomposition

Break the task into independent work units. Read [references/coordination.md](${CLAUDE_SKILL_DIR}/references/coordination.md) for sizing and dependency rules.

Decompose along context boundaries. Each unit should correspond to a coherent set of files and domain knowledge. Avoid splitting where teammates need to understand each other's context.

Each unit must satisfy all four:

1. **Disjoint files**: no two units edit the same file
2. **Clear deliverable**: a function, module, test suite, or review
3. **Completable in isolation**: minimal blocking dependencies
4. **Verifiable**: correctness checkable without other units

If a unit cannot be split without file conflicts, it stays as one unit assigned to one teammate.

### Sizing

| Scope | Files | Modules | Teammates |
|-------|-------|---------|-----------|
| Trivial | < 3 | 1 | 0: do it yourself |
| Small | 3–10 | 1 | 2 |
| Medium | 10–30 | 2–4 | 3–4 |
| Large | 30+ | 4+ | 4–5 |

Never spawn more than 5 teammates. Coordination cost grows quadratically with team size.

## Phase 3: Team Design

Select team composition from [references/patterns.md](${CLAUDE_SKILL_DIR}/references/patterns.md). Consider token cost when sizing the team, since each teammate is a separate Claude instance with its own context window. For each teammate, define:

| Field | What |
|-------|------|
| **Name** | Short, descriptive: `auth-impl`, `api-reviewer`, `test-writer` |
| **Role** | One sentence: what they do and why |
| **Model** | `opus` for all teammates. Omit to inherit the leader's model. |
| **Owns** | Files/directories they may edit. Exclusive, no overlap. |
| **Reads** | Files they need for context but must not edit |
| **mode** | Optional. `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan`, or `auto`. Controls how the teammate handles permission prompts. Maps to the `mode` parameter on the Agent tool. |
| **isolation** | Optional. Set to `worktree` to run the teammate in a temporary git worktree, giving it an isolated copy of the repo. Worktree is cleaned up if no changes are made. |
| **maxTurns** | Optional. Cap the number of agentic turns before the teammate stops. |
| **memory** | Optional. `user`, `project`, or `local`. Gives the teammate persistent memory that survives across conversations. |
| **mcpServers** | Optional. Scope specific MCP servers to this teammate. Reference by name or define inline. |

Teammates inherit the leader's model by default. Omit `model` unless you need to override.

### Plan approval

Enable `--plan-approval` when:
- Task modifies public APIs, database schemas, or shared interfaces
- Teammates work on critical or unfamiliar code
- Lead must ensure architectural consistency across teammates

With plan approval, teammates work read-only until the lead approves their plan. When a teammate calls `ExitPlanMode`, the lead receives a `plan_approval_request` message. The lead reviews the plan and responds via `SendMessage`:

```
// Approve
SendMessage({
  to: "auth-impl",
  message: { type: "plan_approval_response", request_id: "abc-123", approve: true },
  summary: "Approve auth-impl plan"
})

// Reject with feedback
SendMessage({
  to: "auth-impl",
  message: { type: "plan_approval_