agent-teams

What this skill does

# Agent Teams

> **Experimental**: Agent teams require the `--enable-teams` flag and may change between Claude Code versions.

## When to Use This Skill

| Use agent teams when... | Use subagents instead when... |
|------------------------|------------------------------|
| Multiple agents need to work in parallel | Tasks are sequential and interdependent |
| Ongoing communication between agents is needed | One focused task produces one result |
| Background tasks need progress reporting | Agent output feeds directly into next step |
| Complex workflows benefit from task coordination | Simple, bounded, isolated execution |
| Independent changes to the same codebase (with worktrees) | Context sharing is fine and efficient |

## Sub-Agent Caveat: Spawn Teams from the Main Thread

`TeamCreate`, `Agent`, and the related parallel-spawn tools may not be present in a **sub-agent's** tool surface, even if the parent conversation has them. A sub-agent designed to orchestrate its own team can silently degrade to sequential single-thread execution — same content, much longer wall-clock — without surfacing the failure until its post-completion summary.

**Authoring guidance:**

| Situation | Recommended pattern |
|-----------|---------------------|
| Fan-out from the main conversation | Spawn the team / parallel `Agent` calls directly — full tool surface available |
| Sub-agent orchestrating its own team | Avoid by design when possible: split the work so the main thread does the fan-out |
| Sub-agent must orchestrate a team | Detect tool availability up front; report sequential fallback as a first-class outcome |

**Detection contract for coordinating sub-agents:**

Brief the orchestrating sub-agent to verify before dispatching:

```
1. Confirm Agent / TeamCreate are callable. If unavailable (e.g. ToolSearch
   does not surface them, or invocation returns "tool not found"), do NOT
   silently fall back.
2. Report the constraint as the first line of the final summary:
   "Parallel fan-out unavailable in this sandbox; executed sequentially."
3. Continue sequentially with the same input contract — outputs should be
   identical in content, only longer in wall-clock.
```

The wall-clock cost is real: a 5-way fan-out that degrades to sequential takes ~5× longer. Plan top-level orchestration in the main conversation when you can; reserve sub-agent orchestrators for cases where the team's outputs do not need to feed back into the main thread.

> Evidence: a Phase 2 portability-audit dispatch instructed a coordinating sub-agent to spawn 5 parallel auditors via `Agent`; the `Agent` tool was not registered in the sub-agent's sandbox. Output was equivalent but wall-clock was much longer than designed, and the failure surfaced only in the post-completion note.

## Core Concepts

### Team Architecture

```
Lead Agent (orchestrator)
    ├── TeamCreate — creates team + shared task list
    ├── Agent tool — spawns teammate agents
    ├── SendMessage — communicates with teammates
    ├── TaskUpdate — assigns tasks to teammates
    └── Teammates (run in parallel)
            ├── Read team config from ~/.claude/teams/<name>/config.json
            ├── TaskList/TaskUpdate — claim and complete tasks
            └── SendMessage — report back to lead
```

### Native Team Tools

| Tool | Purpose |
|------|---------|
| `TeamCreate` | Create team and shared task list directory |
| `TeamDelete` | Clean up team when all work is complete |
| `SendMessage` | Send DMs, broadcasts, shutdown requests, plan approvals |
| `TaskOutput` | Get output from a background agent |
| `TaskStop` | Stop a running background agent |

## Team Setup Workflow

### 1. Create the Team

```
TeamCreate({
  team_name: "my-project",
  description: "Working on feature X"
})
```

This creates:
- `~/.claude/teams/<team-name>/` — team config directory
- `~/.claude/tasks/<team-name>/` — shared task list directory

### 2. Create Initial Tasks

```
TaskCreate({
  team_name: "my-project",
  title: "Implement security review",
  description: "Audit auth module for vulnerabilities",
  status: "pending"
})
```

### 3. Spawn Teammates

Use the Agent tool to spawn each teammate with the team context:

```
Agent tool with:
  subagent_type: "agents-plugin:security-audit"
  team_name: "my-project"
  name: "security-reviewer"
  prompt: "Join team my-project and work on security review task..."
```

### 4. Assign Tasks

```
TaskUpdate({
  team_name: "my-project",
  task_id: "task-1",
  owner: "security-reviewer",
  status: "in_progress"
})
```

### 5. Receive Results

Teammates send messages automatically — they are delivered to the lead's inbox between turns. No polling needed.

## Task Management

### Task States

| State | Meaning |
|-------|---------|
| `pending` | Not yet started |
| `in_progress` | Assigned and active (one at a time per teammate) |
| `completed` | Finished successfully |
| `blocked` | Waiting on another task |

### Task Priority

Teammates should claim tasks in **ID order** (lowest first) — earlier tasks often set up context for later ones.

### TaskList Usage

Teammates should check `TaskList` after completing each task to find available work:

```
TaskList({ team_name: "my-project" })
→ Returns all tasks with status, owner, and blocked-by info
```

Claim an unassigned task:
```
TaskUpdate({ team_name: "my-project", task_id: "N", owner: "my-name" })
```

## Communication (SendMessage)

### Message Types

| Type | Use When |
|------|----------|
| `message` | Direct message to a specific teammate |
| `broadcast` | Critical team-wide announcement (use sparingly — expensive) |
| `shutdown_request` | Ask a teammate to gracefully exit |
| `shutdown_response` | Approve or reject a shutdown request |
| `plan_approval_response` | Approve or reject a teammate's plan |

### DM Example

```
SendMessage({
  type: "message",
  recipient: "security-reviewer",  // Use NAME, not agent ID
  content: "Please also check the payment module",
  summary: "Adding payment module to scope"
})
```

### Broadcast (use sparingly)

```
SendMessage({
  type: "broadcast",
  content: "Stop all work — critical blocker found in auth module",
  summary: "Critical blocker: halt work"
})
```

Broadcasting sends a separate delivery to every teammate. With N teammates, that's N API round-trips. Reserve for genuine team-wide blockers.

## Teammate Behavior

### Discovering Team Members

Read the team config to find other members:

```
Read ~/.claude/teams/<team-name>/config.json
→ members array with name, agentId, agentType
```

Always use the **name** field (not agentId) for `recipient` in SendMessage.

### Idle State

Teammates go idle after every turn — this is normal. Idle ≠ unavailable. Sending a message to an idle teammate wakes them.

### Key Teammate Rules

- Mark exactly ONE task `in_progress` at a time
- Use `TaskUpdate` (not `SendMessage`) to report task completion
- System sends idle notifications automatically — no need for status JSON messages
- All communication requires `SendMessage` — plain text output is NOT visible to the team lead

## Shutdown Procedures

### Graceful Shutdown (Lead → Teammates)

```
SendMessage({
  type: "shutdown_request",
  recipient: "security-reviewer",
  content: "All tasks complete, wrapping up"
})
```

### Teammate Approves Shutdown

```
SendMessage({
  type: "shutdown_response",
  request_id: "<id from shutdown_request JSON>",
  approve: true
})
```

### Cleanup (Lead)

After all teammates shut down:

```
TeamDelete()
→ Removes ~/.claude/teams/<name>/ and ~/.claude/tasks/<name>/
```

TeamDelete fails if teammates are still active.

## Lead Preflight Checklist

Before drafting the PRP and launching agents, run these checks:

| Check | Command | Why |
|-------|---------|-----|
| Next ADR/PRD/PRP sequence number | `ls docs/blueprint/adrs/ \| sort -V \| tail -1` | Prevents numbering collisions when agents write docs in parallel |
| Filename conflicts | `git ls-files \| grep <filename>` | Agent scope tables c