Agent Teams

Orchestrate collaborative agent teams using Claude Code's experimental agent teams feature.

When to Use

Is the work parallelizable with inter-agent communication needs?
├─ Single focused output? → Use a subagent (Task tool), not a team
├─ 2-3 independent outputs? → Use parallel subagents, not a team
├─ Parallel work + agents need to share findings? → USE A TEAM
├─ Competing hypotheses to test? → USE A TEAM
├─ Multi-file implementation with integration? → USE A TEAM
└─ Multi-lens review (security + perf + correctness)? → USE A TEAM

Don't use teams for: simple delegation, single-file work, sequential tasks, or anything a subagent handles fine.

The Process

Step 1: Assess the Task

Before spawning a team, answer:

1. Can the work be split into 2-5 genuinely independent streams?
2. Will agents need to communicate mid-task (not just return results)?
3. Is there a clear integration point where results come together?

If any answer is "no", use subagents instead.

Step 2: Design the Team

Choose a pattern (see below) and define:

• Roles: What each teammate focuses on (be specific)
• File ownership: Which files each teammate can edit (CRITICAL — no overlaps)
• Deliverables: What each teammate produces
• Communication plan: When teammates should message vs. work independently

Step 3: Spawn with Context

Each teammate starts with zero context. Their spawn prompt must include:

• The overall goal and their specific role
• File paths they own (and must NOT touch)
• Expected deliverable format
• When to message the lead vs. work independently

Teammate tool → operation: "spawnTeam", team_name: "<descriptive-name>"
Task tool → team_name: "<name>", name: "<role>", subagent_type: "general-purpose"

Step 4: Coordinate

• Create tasks with TaskCreate before or after spawning
• Assign tasks with TaskUpdate (set owner to teammate name)
• Use SendMessage type: "message" for targeted communication
• Avoid broadcast unless truly team-wide critical information
• Monitor progress via TaskList — don't poll teammates

Step 5: Integrate & Clean Up

1. Review all teammate outputs
2. Integrate results (you, the lead, handle merging)
3. Send shutdown_request to each teammate
4. Call Teammate cleanup to remove team resources
5. Commit the integrated work

Team Patterns

Research Team

When: Exploring a problem space, literature review, multi-angle analysis.

Composition (3-5 teammates):

Role	Focus	Deliverable
Literature Scout	Find relevant prior work	Annotated reference list
Methodology Analyst	Evaluate approaches	Pros/cons comparison table
Devil's Advocate	Challenge assumptions	Counter-arguments and risks
Synthesizer	Integrate findings	Unified recommendation

See research-team-prompt.md for spawn template.

Implementation Team

When: Building a feature that spans multiple files/modules with clear boundaries.

Composition (2-4 teammates):

Role	Focus	Deliverable
Backend Dev	API routes, data layer	Working endpoints
Frontend Dev	UI components, state	Working interface
Test Writer	Test coverage	Passing test suite
Lead (you)	Integration, review	Merged feature

Critical: Assign file ownership explicitly. No two teammates edit the same file.

See implementation-team-prompt.md for spawn template.

Debugging Team

When: Complex bug with multiple plausible root causes.

Composition (3-5 teammates):

Role	Focus	Deliverable
Hypothesis A	Investigate theory A	Evidence for/against
Hypothesis B	Investigate theory B	Evidence for/against
Hypothesis C	Investigate theory C	Evidence for/against
Reproducer	Create minimal repro	Reproducible test case

Teammates investigate concurrently. First to find strong evidence messages the team.

See debugging-team-prompt.md for spawn template.

Review Team

When: Thorough code review from multiple expert perspectives.

Composition (2-3 teammates):

Role	Focus	Deliverable
Security Reviewer	Vulnerabilities, auth, injection	Security findings
Performance Reviewer	Bottlenecks, complexity, caching	Performance findings
Correctness Reviewer	Logic errors, edge cases, types	Correctness findings

All teammates read the same code but from different lenses. Read-only — no edits.

See review-team-prompt.md for spawn template.

Key Constraints

• One team per session — can't create a second team or nest teams
• File ownership is sacred — concurrent edits cause cascading Edit failures
• Clean up when done — orphaned teams waste resources
• Rich spawn prompts — teammates have zero prior context
• 2-5 teammates — more causes diminishing returns and coordination overhead
• teammateMode: "auto" — uses tmux panes when available, in-process otherwise

Integration with Other Skills

• /brainstorming → Use before team spawning to clarify the approach
• /writing-plans → Create the plan, then use a team to execute it
• /finishing-a-development-branch → After team work, use to prepare for merge
• /subagent-driven-development → For independent tasks without communication needs (lighter weight)