From base
Orchestrate agent teams for parallel implementation tasks. Use when the user requests agent teams, multi-teammate coordination, or parallel feature development across independent modules. Also use when the user mentions 'spawn teammates', 'create a team', 'work in parallel', 'multi-agent', or describes tasks spanning multiple independent modules (frontend/backend/tests) that could benefit from simultaneous development, concurrent code review, or competing-hypothesis debugging.
npx claudepluginhub kkhys/claude-code-marketplaceThis skill uses the workspace's default tool permissions.
Agent teams run multiple Claude Code sessions in parallel on the same codebase. Each teammate operates as an independent process with its own context window, communicating through a shared mailbox and task list. The lead (you) creates the team, assigns work, reviews plans, and integrates results — but does not implement anything directly.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Agent teams run multiple Claude Code sessions in parallel on the same codebase. Each teammate operates as an independent process with its own context window, communicating through a shared mailbox and task list. The lead (you) creates the team, assigns work, reviews plans, and integrates results — but does not implement anything directly.
The deciding factor is whether workers need to talk to each other.
| Agent Teams | Subagents (Agent tool) | |
|---|---|---|
| Communication | Teammates message each other directly | Report only to the caller |
| Context | Each has its own context window | Runs inside caller's context |
| Coordination | Shared task list, peer-to-peer | Caller manages everything |
| Cost | Higher (independent instances) | Lower (result summaries) |
| Best for | Collaborative, multi-module work | Independent, result-oriented tasks |
Use teams when teammates need to agree on interfaces, challenge each other's approaches, or coordinate across modules. Use subagents when you just need results collected back to you.
Agent teams require an experimental flag. Verify in settings.json before creating a team:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
If not enabled, offer to add it to the user's settings before proceeding.
Peer-to-peer messaging is what makes teams fundamentally different from subagents. Teammates can share discoveries, warn about edge cases, or agree on interface contracts without the lead mediating every exchange.
Two teammates editing the same file causes silent overwrites — the second save destroys the first teammate's work with no warning or merge. This is the most common and most costly failure mode.
Every teammate must own distinct files. Declare ownership explicitly in the spawn prompt:
Backend dev: owns src/api/auth/, src/services/auth/, tests/api/auth/
Frontend dev: owns src/components/auth/, src/hooks/auth/
Test engineer: owns tests/integration/auth/, tests/e2e/auth/
If a shared file needs changes (config, type definitions, interfaces), assign exactly one teammate as sole editor. Others communicate their required changes via messages.
3-5 teammates for most tasks. Three focused teammates consistently outperform five scattered ones because:
Aim for 5-6 tasks per teammate. If each teammate has fewer than 3 substantive tasks, reduce the team size.
Follow the codebase's natural boundaries — modules, layers, packages. Each work unit should be:
When dependencies exist (e.g., frontend needs backend API contracts), have the upstream teammate message downstream when interfaces stabilize rather than making downstream wait entirely.
Identify independent work units, then create the team with explicit roles and file ownership:
Create an agent team to implement [feature].
Spawn N teammates:
- [Role]: owns [files]. Responsible for [scope].
- [Role]: owns [files]. Responsible for [scope].
Require plan approval before making changes.
Require plan approval for work that modifies production code. Skip it for read-heavy tasks (reviews, investigations, research) where uncoordinated changes are not a risk.
When a teammate submits a plan, verify:
Reject plans that violate these and provide specific feedback on what to fix.
The lead's role during execution is coordination, not implementation.
This is the hardest discipline. The natural instinct is to help by coding, but doing so breaks the parallel model and risks file conflicts. A lead who implements is a lead who creates merge conflicts.
Always clean up explicitly — teams consume resources until shut down.
The most frequent anti-pattern. The lead starts writing code instead of coordinating. Always include these instructions when spawning:
Do not implement any tasks yourself.
Wait for all teammates to complete their tasks before proceeding.
If a teammate gets stuck, send them guidance rather than taking over.
Two teammates editing the same file produces no error and no merge — just data loss. The second save silently destroys the first. Prevention:
More teammates does not mean faster results. Signs you have too many:
Teams persist until explicitly cleaned up. Always run cleanup when done, even if something went wrong. Only the lead should run cleanup, and all teammates should be shut down first.
Teammates sometimes forget to mark tasks complete. If progress appears stuck, check whether the work is actually done and nudge the teammate or update status manually.
Hooks automate quality checks when teammates finish work:
Configure in .claude/settings.json (project) or ~/.claude/settings.json (user). Hook scripts receive teammate/task context as JSON on stdin.
/resume does not restore in-process teammatesSee patterns.md for team composition patterns covering feature development, code review, debugging, migration, and research spikes.