/team-composition-patterns

name: team-composition-patterns
description: Design optimal agent team compositions with sizing heuristics, preset configurations, and agent type selection. Use this skill when deciding how many agents to spawn for a task, when choosing between a review team versus a feature team versus a debug team, when selecting the correct subagent_type for each role to ensure agents have the tools they need, when configuring display modes (tmux, iTerm2, in-process) for a CI or local environment, or when building a custom team composition for a non-standard workflow such as a migration or security audit.
version: 1.0.2

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.

Preset Team Compositions

Review Team

• **Size**: 3 reviewers
• **Agents**: 3x `team-reviewer`
• **Default dimensions**: security, performance, architecture
• **Use when**: Code changes need multi-dimensional quality assessment

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 `general-purpose`
• **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**: 4x `team-reviewer`
• **Default dimensions**: OWASP/vulnerabilities, auth/access control, dependencies/supply chain, secrets/configuration
• **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

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` | Read-only tools | Architecture planning, task decomposition | | `agent-teams:team-reviewer` | Read/search/Bash plus TaskList/TaskGet/TaskUpdate/SendMessage | Code review with structured findings | | `agent-teams:team-debugger` | Read/search/Bash plus TaskList/TaskGet/TaskUpdate/SendMessage | Hypothesis-driven investigation | | `agent-teams:team-implementer` | Read/Write/Edit/search/Bash plus TaskList/TaskGet/TaskUpdate/SendMessage | Building features within file ownership boundaries | | `agent-teams:team-lead` | Read/search/Bash plus Agent Teams coordination tools | Team orchestration and coordination |

**Key distinction**: Read-only agents (Explore, Plan) cannot modify files. Never assign implementation tasks to read-only agents.

Display Mode Configuration

Configure in `~/.claude/settings.json`:

{
  "teammateMode": "tmux"
}

| Mode | Behavior | Best For | | -------------- | ------------------------------ | ------------------------------------------------- | | `"tmux"` | Each teammate in a tmux pane | Development workflows, monitoring multiple agents | | `"iterm2"` | Each teammate in an iTerm2 tab | macOS users who prefer iTerm2 | | `"in-process"` | All teammates in same process | Simple tasks, CI/CD environments |

Custom Team Guidelines

When building custom teams:

1. **Every