team-composition-patterns

What this skill does

# Team Composition Patterns

Best practices for composing multi-agent teams, selecting team sizes, choosing agent types, and configuring display modes for Claude Code's Agent Teams feature.

## When to Use This Skill

- Deciding how many teammates to spawn for a task
- Choosing between preset team configurations
- Selecting the right agent type (subagent_type) for each role
- Configuring teammate display modes (tmux, iTerm2, in-process)
- Building custom team compositions for non-standard workflows

## Team Sizing Heuristics

| Complexity   | Team Size | When to Use                                                 |
| ------------ | --------- | ----------------------------------------------------------- |
| Simple       | 1-2       | Single-dimension review, isolated bug, small feature        |
| Moderate     | 2-3       | Multi-file changes, 2-3 concerns, medium features           |
| Complex      | 3-4       | Cross-cutting concerns, large features, deep debugging      |
| Very Complex | 4-5       | Full-stack features, comprehensive reviews, systemic issues |

**Rule of thumb**: Start with the smallest team that covers all required dimensions. Adding teammates increases coordination overhead.

### Token cost multiplier

A team costs **3-10x the tokens of a single Claude** (typical ~7x for plan-mode workflows). Each teammate runs in its own context window and consumes tokens independently. Drivers of cost:

- Number of teammates (linear).
- Token budget per teammate (linear in exploration depth).
- Duration of unsupervised exploration (the largest variance source; unbounded scope explodes here).

Cheap-team recipe: Opus lead + Sonnet teammates, 2-3 teammates, scope-bounded spawn prompts, Haiku for any role where summarization is the main job. Cost killers: unbounded scope, no file ownership (forces rework), no task dependencies (forces rework on unstable foundations), no `TaskCompleted` quality gates (forces rework on broken code).

### Hard limits (as of 2026-05)

These are enforced by the harness and cannot be worked around with prompt engineering:

- **One team per lead.** A lead can only manage one team at a time. Clean up before creating the next.
- **No nested teams.** Teammates cannot spawn their own teams or further teammates.
- **No nested subagents.** A teammate spawned with `Agent` cannot itself call `Agent` to spawn a sub-subagent.
- **Lead is fixed for the team's lifetime.** No promotion, no leadership transfer.
- **Permissions set at spawn.** Per-teammate at spawn time is not supported.
- **No session resumption for in-process teammates.** `/resume` and `/rewind` do not restore them.
- **Broadcast removed.** Send one `message` per recipient by name.

Reference: `docs/references/agent-teams-best-practices.md` § Hard limits.

## Preset Team Compositions

### Review Team

- **Size**: 3 reviewers
- **Agents**: prefer specialized `senior-review:security-auditor` + `senior-review:code-auditor` + a third dimension matching the diff (e.g. `senior-review:ui-race-auditor` for frontend changes, `senior-review:distributed-flow-auditor` for cross-service changes). Fall back to `agent-teams:team-reviewer` only when no specialized agent fits the dimension.
- **Default dimensions**: security, code quality (architecture + patterns + scoring), and one context-driven dimension
- **Use when**: Code changes need multi-dimensional quality assessment. For pipeline reviews driven by `/team-review`, the command auto-selects specialized agents based on the diff and adds Phase 1 context (deep-dive + interconnect map) automatically.

### Debug Team

- **Size**: 3 investigators
- **Agents**: 3x `team-debugger`
- **Default hypotheses**: 3 competing hypotheses
- **Use when**: Bug has multiple plausible root causes

### Feature Team

- **Size**: 3 (1 lead + 2 implementers)
- **Agents**: 1x `team-lead` + 2x `team-implementer`
- **Use when**: Feature can be decomposed into parallel work streams

### Fullstack Team

- **Size**: 4 (1 lead + 3 implementers)
- **Agents**: 1x `team-lead` + 1x frontend `team-implementer` + 1x backend `team-implementer` + 1x test `team-implementer`
- **Use when**: Feature spans frontend, backend, and test layers

### Research Team

- **Size**: 3 researchers
- **Agents**: 3x `research:deep-researcher` (for systematic multi-source investigation) or `general-purpose` fallback; use `research:quick-searcher` for single-fact lookups
- **Default areas**: Each assigned a different research question, module, or topic
- **Capabilities**: Codebase search (Grep, Glob, Read), web search (WebSearch, WebFetch)
- **Use when**: Need to understand a codebase, research libraries, compare approaches, or gather information from code and web sources in parallel

### Security Team

- **Size**: 4 reviewers
- **Agents**: prefer `senior-review:security-auditor` for OWASP / auth / secrets, `platform-engineering:platform-reviewer` for client-side hardening (CSP, token storage, secrets in bundles), `senior-review:distributed-flow-auditor` for cross-service auth flows, and `codebase-cleanup:deps-audit` (or `senior-review:cleanup-auditor`) for dependencies / supply chain. Fall back to `agent-teams:team-reviewer` only if a dimension has no specialized agent.
- **Default dimensions**: OWASP / vulnerabilities, platform / client-side security, cross-service auth, dependencies / supply chain
- **Use when**: Comprehensive security audit covering multiple attack surfaces.

### Migration Team

- **Size**: 4 (1 lead + 2 implementers + 1 reviewer)
- **Agents**: 1x `team-lead` + 2x `team-implementer` + 1x `team-reviewer`
- **Use when**: Large codebase migration (framework upgrade, language port, API version bump) requiring parallel work with correctness verification

### Deep Search Team

- **Size**: 2-4 (depends on depth level)
- **Agents**: 2-3x `research:deep-researcher` + optional domain expert (auto-selected)
- **Use when**: Complex questions requiring systematic coverage across codebase, web, and domain expertise

### Docs Team

- **Size**: 3 (explorer + writer + verifier)
- **Agents**: 1x `codebase-mapper:codebase-explorer` + 1x `codebase-mapper:documentation-engineer` + 1x `senior-review:code-auditor`
- **Use when**: Creating or overhauling project documentation from code analysis

### App Analysis Team

- **Size**: 3 (mapper + researcher + designer)
- **Agents**: 1x `app-analyzer:app-analyzer` + 1x `research:deep-researcher` + 1x `frontend:frontend-design`
- **Use when**: Competitive app analysis, navigation mapping, design system extraction

### Tauri Team

- **Size**: 4 (1 lead + 3 specialists)
- **Agents**: 1x `team-lead` + 1x `tauri-development:rust-engineer` + 1x `frontend:frontend-engineer` + 1x `tauri-development:tauri-desktop`
- **Use when**: Building or optimizing Tauri v2 desktop/mobile applications

### UI Studio Team

- **Size**: 3+3 (design wave + polish wave, spawned sequentially)
- **Design wave**: 1x `frontend:frontend-design` (direction) + 1x `frontend:frontend-layout` (layout) + 1x `frontend:frontend-design` (UX)
- **Polish wave**: 1x `frontend:frontend-design` (polish) + 1x `react-development:react-performance-optimizer` (perf) + 1x `senior-review:code-auditor` (review)
- **Use when**: Building new UI from scratch or major redesigns

## Agent Type Selection

When spawning teammates with the `Agent` tool, choose `subagent_type` based on what tools the teammate needs:

| Agent Type                     | Tools Available                           | Use For                                                    |
| ------------------------------ | ----------------------------------------- | ---------------------------------------------------------- |
| `general-purpose`              | All tools (Read, Write, Edit, Bash, etc.) | Implementation, debugging, any task requiring file changes |
| `Explore`                      | Read-only tools (Read, Grep, Glob)        | Research, code exploration, analysis                       |
| `Plan`                         | Re