Agent Team

---
name: agent-team
description: "Create and manage agent teams — multiple Claude instances working in parallel on complex tasks. Use when: coordinating parallel work, large multi-file features, research investigations, codebase-wide refactors. Triggers on: create a team, agent team, spawn teammates, team of agents, parallel agents, multi-agent, coordinate agents, swarm, work in parallel."
---

# Agent Team

Orchestrate multiple Claude instances working together: one lead (you) + N teammates with independent context windows, shared task lists, and inter-agent messaging.

## Quick Decision: Team vs Subagent

| Situation | Use |
|-----------|-----|
| 3+ independent work streams touching different files | **Team** |
| Simple parallel research/exploration | **Subagent** (Task tool) |
| Work requires back-and-forth coordination | **Team** |
| Single task, just needs isolation | **Subagent** |
| < 3 independent pieces | **Subagent** |

## File References

| File | When to Read |
|------|-------------|
| `teams/` | Step 0 — check for a saved team template |
| `references/agent-types.md` | Step 2 — choosing teammate types |
| `references/team-patterns.md` | Step 2 — picking a team pattern |

---

## Workflow

### Step 0: Check for Saved Teams

List files in `teams/` directory. If saved templates exist:

1. Show the user available templates with a one-line description of each
2. Ask: use a saved template, or create a new team from scratch?

**If using a template:**
- Read the full template file
- Ask the user for the placeholder values (listed at the bottom of each template)
- Fill in placeholders with user's answers + project context from the chat
- Skip to Step 3 (team composition is already defined in the template)

**If creating new** → proceed to Step 1.

**Saving new teams:** After a successful team run (Step 7 complete), ask the user if they want to save this team configuration as a template in `teams/`. If yes, write a template file following the format of existing templates in `teams/`.

### Step 1: Assess the Work

Gate check before creating a team:

1. Can the work split into **3+ independent pieces** touching **different files**?
2. Would parallel execution actually save time vs sequential?
3. Is the work complex enough to justify the overhead?

**If NO to any** → Use subagents (Task tool) instead. Tell the user why a team isn't needed. Stop here.

**If YES** → Proceed. Identify the independent work streams and file boundaries.

### Step 2: Plan Team Composition

Read `references/agent-types.md` and `references/team-patterns.md`.

Determine and present to the user:

```
Team Plan: [team-name]
Pattern: [from team-patterns.md]
Teammates: [count, 2-4 max]

| # | Name | Type | Role | Owns Files | DO NOT TOUCH |
|---|------|------|------|------------|--------------|
| 1 | ... | ... | ... | ... | ... |
| 2 | ... | ... | ... | ... | ... |

Tasks:
1. [task] → assigned to [name]
2. [task] → assigned to [name] (blocked by #1)
...

Estimated complexity: [low/medium/high]
```

**Critical rules:**
- Max 4 teammates (more = diminishing returns, coordination overhead)
- Every file must have exactly ONE owner — no overlapping file boundaries
- Read-only agents (Explore, Plan, code-reviewer) cannot edit files — only assign them research/review tasks
- Use `general-purpose` for any task requiring file edits or bash commands

**Wait for user approval before proceeding.**

### Step 3: Create Team and Tasks

```
1. TeamCreate → creates team + shared task list
2. TaskCreate for each task:
   - subject: imperative form ("Implement auth middleware")
   - description: detailed requirements, file list, acceptance criteria
   - activeForm: present continuous ("Implementing auth middleware")
3. TaskUpdate to set dependencies (addBlockedBy) where needed
4. TaskList to verify everything looks correct
```

### Step 4: Spawn Teammates

For each teammate, use the **Task tool** with `team_name` and `name` parameters.

**Spawn prompt template** (adapt per teammate):

```
You are [ROLE NAME] on team "[TEAM_NAME]".

## Your Role
[1-2 sentences about what this teammate does]

## File Ownership
You OWN and may modify:
- [list of files/directories]

DO NOT TOUCH:
- [list of files owned by other teammates]

## Context
[Essential project context: tech stack, patterns, conventions, key decisions]

## Getting Started
1. Call TaskList to see available tasks
2. Call TaskGet on your assigned task to read full details
3. Call TaskUpdate to mark it in_progress
4. Do the work
5. Call TaskUpdate to mark it completed
6. Call TaskList to check for more work
7. If blocked or need help, send a message to the team lead

## Rules
- Stay within your file boundaries
- Mark tasks in_progress BEFORE starting work
- Mark tasks completed AFTER finishing
- Message the team lead if you hit blockers
- Do NOT broadcast messages — DM the lead directly
```

**Key spawn parameters:**
- `subagent_type`: Match to the agent type from Step 2 (usually `general-purpose`)
- `team_name`: The team name from Step 3
- `name`: The teammate name from Step 2
- `mode`: Use `"default"` unless the task is low-risk, then `"bypassPermissions"`

### Step 5: Assign Initial Tasks

For each teammate:
1. `TaskUpdate` with `owner` set to teammate name
2. `SendMessage` to the teammate: brief kickoff message referencing their task

Example:
```
SendMessage → type: "message", recipient: "backend-dev",
  content: "Your first task is #1 — implement the auth middleware. Check TaskGet for full details.",
  summary: "Start work on auth middleware"
```

### Step 6: Monitor and Coordinate

This is an ongoing loop. As teammates send messages:

**Normal flow:**
- Teammate completes task → acknowledge, check TaskList, assign next task or unblock dependent tasks
- Teammate goes idle → this is NORMAL, just means they're waiting. Send a message if you have work for them
- Teammate asks question → answer with specific guidance, not vague nudges
- Teammate reports blocker → help resolve, reassign if needed, create new tasks if scope changed

**Rules:**
- Do NOT use broadcast unless truly critical (blocking issue affecting everyone)
- Do NOT comment on idle teammates — idle is the normal state between tasks
- Do NOT retry failed approaches — if something fails twice, re-plan
- Do check TaskList after each teammate completion to spot newly unblocked tasks
- Do reassign tasks if a teammate is struggling or blocked

**When all tasks are done** → proceed to Step 7.

### Step 7: Cleanup

1. Verify all tasks show `completed` in TaskList
2. Send `shutdown_request` to each teammate:
   ```
   SendMessage → type: "shutdown_request", recipient: "[name]",
     content: "All tasks complete. Thanks for your work."
   ```
3. Wait for shutdown confirmations from all teammates
4. Call `TeamDelete` to clean up team and task files
5. Summarize results to the user:
   - What was accomplished
   - Files created/modified
   - Any issues encountered and how they were resolved

---

## Cautions

**File conflicts are the #1 failure mode.** If two teammates edit the same file, one will overwrite the other. Strict file ownership boundaries prevent this.

**Context is everything.** Teammates start with blank context. Their spawn prompt is their entire world. Include all essential info — tech stack, conventions, key decisions, file paths.

**Teams are expensive.** Each teammate is a full Claude instance. Don't create teams for work that a single agent + subagents can handle.

**Idle is normal.** Teammates go idle after every turn. This is expected behavior, not an error. They wake up when you send them a message.

**No broadcast spam.** Broadcasting sends to EVERY teammate. Only use for critical blocking issues. Default to direct messages.

**Read-only agents can't edit.** Explore, Plan, code-reviewer, code-architect agents cannot write files or run bash. Only use them for research/review tasks.

**Shutdown gracefully.** Always send shutdown_request and wait for confirmation. Don't just abandon teammates or delete the team while they're working.

**Plan mode teammates.** If you spawn a teammate with `mode: "plan"`, you'll need to approve their plan via `plan_approval_response` before they can execute. Use this for high-risk tasks.