teams

name	teams
description	Orchestrate a team of Claude agents to parallelize complex tasks. Analyzes the request, determines optimal team size and strategy, spawns specialized teammates with unique voices, coordinates via shared task lists, and cleans up when done. Use when the user says "use a team", "parallelize this", "swarm this", "use N agents", or invokes /teams.
allowed-tools	Bash, Read, Grep, Glob, Edit, Write, TeamCreate, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, TeamDelete, Agent, TaskOutput

Teams

You are now a team orchestrator. Your job is to decompose the user's request into subtasks, spawn Claude teammates to work in parallel, coordinate their work, and deliver a unified result. You do coordination — teammates do the work.

Strategy Selection

Before doing anything, classify the task:

Strategy	When	Agents	Pattern
Breadth	>= 4 independent subtasks (fix these files, write tests for N modules, review N PRs)	3-5	All agents work in parallel on independent tasks
Depth	Sequential phases — research → design → implement → test	2-3	Agents work in phases; later tasks blocked on earlier ones
Mixed	Research + implement, explore + refactor	2-4	Phase 1: parallel exploration. Phase 2: sequential implementation

Agent count:

• If the user specified a number, use it (max 5).
• Otherwise: Breadth = min(subtask_count, 5), Depth = 2-3, Mixed = 3-4.

Voice Assignment (optional)

If the speak skill is installed, every teammate gets a unique voice so the user can distinguish them by ear. Assign by slot order:

Slot	Voice	Channel	Personality
Lead (you)	Claude	—	Default, orchestrator
Agent 1	Adam	agent-1	Deep, authoritative — backend, infra
Agent 2	Rachel	agent-2	Calm, clear — frontend, docs
Agent 3	Josh	agent-3	Confident, resonant — testing, DevOps
Agent 4	Bella	agent-4	Warm, approachable — research, exploration
Agent 5	Antoni	agent-5	Friendly, conversational — utilities, glue

If the speak skill is not installed, skip the voice step entirely — teammates simply don't speak, and the orchestration still works.

Workflow

Step 1 — Analyze and Plan

Think through: What is the task? What are the subtasks? Which strategy? How many agents? What are the dependencies? State this plan briefly to the user.

Step 2 — Create the Team

TeamCreate(team_name="<slugified-task-name>", description="<one-line summary>")

Use a short, descriptive slug (e.g., auth-refactor, test-suite-expansion, bug-fixes-march).

Step 3 — Create Tasks

Use TaskCreate for each subtask. Each task MUST have:

• subject: Short title
• description: Detailed, self-contained instructions including:
  • What to do
  • Which files/paths are relevant
  • Acceptance criteria
  • Any context the teammate needs (they have NO conversation history)
• activeForm: Short status string (shown in UI)

For Depth/Mixed strategies, use addBlockedBy to set dependencies between tasks.

Step 4 — Spawn Teammates

For each agent, use the Agent tool:

Agent(
  team_name="<team-name>",
  name="<agent-name>",
  prompt="<spawn prompt from template below>"
)

Spawn all independent agents in parallel (single message, multiple Agent tool calls).

Mode: Do NOT pass an explicit mode parameter — let teammates inherit the orchestrator's permission mode. Whatever permission mode the top-level session is running in (bypass, auto, plan, default), teammates inherit it cleanly. Passing mode="auto" explicitly here would paradoxically force teammates into the auto-classifier path even when the orchestrator is in a more permissive mode like bypass. Inheriting avoids unnecessary classifier prompts and permission interruptions.

Step 5 — Assign Tasks

After spawning, use TaskUpdate to set owner on each task to the appropriate teammate name.

Step 6 — Monitor and Coordinate

• Review messages from teammates as they arrive
• For Depth/Mixed: forward context from completed phases to the next agent via SendMessage
• If an agent reports a blocker, help unblock or reassign
• Silence watchdog — never trust completion notifications. The harness can drop teammate completion/idle notifications and teammate→lead sends (claude-code #78338 / #43706). If a teammate has been silent >20 minutes, read its transcript tail (~/.claude/projects/<project-slug>/<session-id>/subagents/agent-*.jsonl) BEFORE nudging: a finished report sitting there means the delivery was lost — harvest it from the transcript and move on; nudge only if the teammate truly idled without working. Never end your own turn into an open-ended "waiting for reports" state — schedule the check, don't sleep on notifications.

Step 7 — Collect and Present

When all tasks are completed:

• Review the results across all agents
• Summarize the combined output to the user
• Highlight anything that needs user attention

Step 8 — Cleanup (verify process death — do not trust tool success)

TeamDelete no longer exists in current harnesses, teammates routinely ignore shutdown_request, and TaskStop can return "Successfully stopped" while the agent's OS process survives (known upstream bugs: claude-code #28552, #33043). Reap deterministically:

1. Per teammate: TaskStop(task_id="<name>") — registry hygiene; an error "No task found" is fine (finished agents age out of the registry while their process lives on).
2. Kill + verify, session-scoped: pgrep -fl -- "--agent-id" → kill any PID whose --parent-session-id matches the current session (your session id = the UUID in your transcript path), then re-check with kill -0 and escalate to SIGKILL for survivors. Never touch agents belonging to other sessions.

Run this on failure/abort paths too. Prose like "you're released" terminates nothing. If you orchestrate teams often, wrap step 2 in a small script.

Spawn Prompt Template

Every teammate spawn prompt MUST include all of this (they have zero conversation history):

You are "{agent_name}" on team "{team_name}".

## Your Role
{role_description}

## Project Context
- Working directory: {project_dir}
- Key files: {list of relevant files and paths}
{any additional context — framework, language, conventions, recent changes}

## Your Tasks
Check TaskList for tasks assigned to you. Work through them in order:
1. Mark a task as in_progress when you start it
2. Do the work
3. Mark it as completed when done
4. Check TaskList for your next assignment

## Voice (optional)
If the speak skill is installed at `~/.claude/skills/speak/`, your voice is {voice_name}. When speaking, use:
~/.claude/skills/speak/scripts/say.sh "message" --voice {voice_name} --channel {channel_name}
Speak at the end of every turn — voice is how you communicate completion and status.
If the speak skill is not installed, skip this step.

## Coordination
- Message the lead if you're blocked or need clarification: SendMessage(to="lead", message="...")
- If you finish all your tasks, message the lead: SendMessage(to="lead", message="All tasks complete.")
- Do NOT edit files that another teammate is working on — check task ownership first.
- MANDATORY LAST ACTION: deliver your report to the lead via SendMessage BEFORE ending your turn.
  Your final plain-text output is INVISIBLE to the lead in teams mode — a report written as
  ordinary text reaches nobody. No turn of yours ends with an undelivered result.

Rules

1. Max 5 teammates. More creates coordination overhead that outweighs parallelism gains.
2. Unique voices and channels. Every teammate must be distinguishable by ear.
3. Self-contained prompts. Teammates have ZERO conversation history. Every spawn prompt must be a complete briefing with all necessary context.
4. You coordinate, they execute. The lead plans, decomposes, assigns, monitors, and synthesizes. Teammates do the actual work.
5. Always clean up — and VERIFY. TaskStop each teammate, then kill + verify the session's --agent-id processes (see Step 8). Trust process death, not tool success messages.
6. Speak every turn (if the speak skill is installed). Use your Claude voice to keep the user informed of orchestration status. Skip this rule if speak is not installed.
7. No file conflicts. Never assign two teammates to edit the same file. If a task touches shared files, make it sequential (use task dependencies).
8. Degrade, don't abort. If teammate spawning fails — tmux respawn pane failed: fork failed / no space for new pane, or a model-unavailable / 429 wave — do NOT abort the task. Fall back to in-process Agent-tool subagents (fewer, run them sequentially if needed), cap default fan-out at ≤5, and tell the user which mode you degraded to.
9. Reports travel by SendMessage only — and the lead verifies by transcript. A teammate's final plain text is invisible to the lead, and the harness can drop completion notifications (#78338). Teammates SendMessage their report before ending any turn; the lead treats >20 min of silence as "check the transcript tail", never as "still working".