agent-teams

What this skill does

<objective>
Coordinate teams of 2-3 Claude Code agents working in parallel on the same codebase. Each agent runs in its own terminal, its own git worktree, and its own context window. The team lead (you, the orchestrating Claude) decomposes work, spawns agents with focused prompts, monitors progress, and coordinates merges.

**Key principle:** Each agent is a fresh Claude session with zero shared memory. All coordination happens through files (WORKTREE_TASK.md, shared contracts) and git (branches, PRs). There is no runtime communication between agents.
</objective>

<quick_start>
**Set the environment variable (one-time):**
```bash
export AGENT_TEAMS_MAX=3  # M1/8GB safe default
```

**Spawn a 2-agent team:**
```
"Set up a team: Agent 1 builds the API endpoints, Agent 2 builds the React components.
They share this contract: POST /api/tasks returns { id, title, status }."
```

**What happens:**
1. Team lead creates 2 worktrees via worktree-manager
2. Writes WORKTREE_TASK.md with focused prompt + contract to each
3. Launches each agent in its own Ghostty terminal
4. Agents work independently, team lead monitors and merges
</quick_start>

<success_criteria>
A team session is successful when:
- Each agent completes its assigned task in its worktree
- No merge conflicts between agent branches (or conflicts are trivially resolvable)
- Each agent's context stays focused (no bloat, no re-reading unrelated code)
- All agent work passes the project's test suite after merge
- Total wall-clock time is less than sequential execution would take
</success_criteria>

<setup>

## Prerequisites

**Required skill:** [worktree-manager](../worktree-manager-skill/SKILL.md) — agent-teams delegates ALL worktree creation, port allocation, and terminal launching to worktree-manager. Install it first.

**Recommended:** Project has a `.claude/` directory with CLAUDE.md (dev commands, conventions). If the project also has `.claude/agents/` with custom subagents or `.claude/settings.json` with hooks/permissions, these are automatically propagated to each agent's worktree.

**Environment check:**
```bash
# Agent teams config
echo "Max agents: ${AGENT_TEAMS_MAX:-3}"

# Worktree manager available?
ls ~/.claude/skills/worktree-manager/ 2>/dev/null && echo "worktree-manager: OK" || echo "worktree-manager: MISSING"

# Running agents (approximate)
pgrep -f "claude.*--model" | wc -l | xargs echo "Active Claude processes:"

# Memory pressure
vm_stat | grep "Pages free" | awk '{print "Free pages:", $3}'
```

<current_state>
Active agents:
!`pgrep -f "claude.*--model" 2>/dev/null | wc -l | tr -d ' '` Claude processes running

Worktree registry:
!`cat ~/.claude/worktree-registry.json 2>/dev/null | jq -r '.worktrees[] | select(.status == "active") | "\(.project)/\(.branch)"' | head -5`

Memory:
!`memory_pressure 2>/dev/null | head -1 || echo "Unknown"`

Git status:
!`git status --short --branch 2>/dev/null | head -3`
</current_state>

### Hardware Constraints (M1/8GB)

| Resource | Budget | Per Agent | System Reserved |
|----------|--------|-----------|-----------------|
| RAM | 8 GB | ~1.5 GB | 2 GB |
| CPU cores | 8 | Shared | — |
| Max agents | 3 | — | — |

**Rule of thumb:** If `memory_pressure` reports "WARN" or higher, reduce to 2 agents.

</setup>

<when_to_use>

## When to Use Agent Teams

**Use when:**
- Task naturally decomposes into 2-3 independent work streams
- Each stream touches different files (low conflict risk)
- Wall-clock speed matters more than token efficiency
- You have clear contracts between components (API shape, shared types)

**Don't use when:**
- Task is tightly coupled (every change touches the same files)
- You're on battery with <30% charge (agents drain power fast)
- Memory pressure is already high (check `memory_pressure`)
- The codebase has no tests (merging blind is risky)

**Decision heuristic:**
```
Can I describe each agent's task in <50 words?
  YES → Good candidate for agent teams
  NO  → Break it down more, or do it sequentially
```

**Lightweight alternative:** For tasks where agents DON'T need file isolation (different files, read-only, reviews), use [subagent-teams](../subagent-teams-skill/SKILL.md) instead. It uses Claude's native Task tool for in-session parallel agents — faster startup, no worktrees needed. See also the **Native Teams API** section below.

</when_to_use>

<architecture>

## Architecture

```
┌──────────────────────────────────────────────────┐
│                   TEAM LEAD                       │
│            (this Claude session)                  │
│                                                   │
│  Responsibilities:                                │
│  • Decompose task into agent assignments          │
│  • Create worktrees (via worktree-manager)        │
│  • Write WORKTREE_TASK.md for each agent          │
│  • Monitor progress (git log, file checks)        │
│  • Coordinate merges back to main                 │
└─────────┬───────────────┬───────────────┬────────┘
          │               │               │
    ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
    │  AGENT 1  │   │  AGENT 2  │   │  AGENT 3  │
    │           │   │           │   │           │
    │ Worktree: │   │ Worktree: │   │ Worktree: │
    │ ~/tmp/wt/ │   │ ~/tmp/wt/ │   │ ~/tmp/wt/ │
    │ proj/br-1 │   │ proj/br-2 │   │ proj/br-3 │
    │           │   │           │   │           │
    │ Terminal: │   │ Terminal: │   │ Terminal: │
    │ Ghostty 1 │   │ Ghostty 2 │   │ Ghostty 3 │
    └───────────┘   └───────────┘   └───────────┘
         │               │               │
         └───── git branches ─────────────┘
                     │
               [main branch]
```

### Context Isolation

Each agent is a **completely separate Claude session**. Agents:
- Cannot read each other's context windows
- Cannot send messages to each other
- Share state ONLY through the filesystem and git
- Read their task from `WORKTREE_TASK.md` on startup

### Coordination Through Files

| File | Purpose | Written By | Read By |
|------|---------|------------|---------|
| `WORKTREE_TASK.md` | Agent's assignment + context | Team lead | Agent |
| `CONTRACT.md` | Shared API/interface definitions | Team lead | All agents |
| `.agent-status` | Agent self-reports progress | Agent | Team lead |
| `.claude/CLAUDE.md` | Project conventions, dev commands | Project | Agent (auto-loaded) |
| `.claude/settings.json` | Hooks (auto-format), permissions | Project | Agent (auto-loaded) |
| `.claude/agents/*.md` | Custom subagent definitions | Project | Agent (on dispatch) |
| Git commits | Work product | Agent | Team lead at merge |

</architecture>

<display_modes>

## Display Modes

| Mode | Terminal | How |
|------|----------|-----|
| `in-process` | Any terminal | All teammates in main terminal. `Shift+Down` to cycle, `Ctrl+T` for task list. |
| `split-pane` | tmux or iTerm2 only | Each teammate gets own pane. Click pane to interact. |

Config: `"teammateMode": "auto"` in `~/.claude/settings.json`. CLI: `claude --teammate-mode in-process`. Ghostty requires tmux wrapper for split-pane.

### Split Pane Setup

**tmux:** Auto-detected when `$TMUX` is set. Each teammate gets a split pane. Navigate with `Ctrl+B` + arrow keys.

**iTerm2:** Uses AppleScript automation. Teammates open in split panes within the current tab.

**Limitations:** Ghostty lacks programmatic pane splitting — use tmux wrapper: `ghostty -e "tmux new-session"`. Max 4 panes recommended (leader + 3 teammates). Each pane needs ~120 columns.

</display_modes>

<team_hooks>

## Team Hooks

### TeammateIdle Hook

Fires when a teammate finishes its current turn and goes idle. Configure in `settings.json`:

```json
{
  "hooks": {
    "TeammateIdle": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'echo \"Teammate idle — check TaskList for unassigned work\" >&2'"
      }]
    }]
  }
}
```

**Use cases:** Auto-assign next task, log idle time, trigger cleanup. Exit code 2 blocks the idle transition (kee