Team Composition Patterns

1---2name: team-composition-patterns3description: 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.4version: 1.0.25---6 7# Team Composition Patterns8 9Best practices for composing multi-agent teams, selecting team sizes, choosing agent types, and configuring display modes for Claude Code's Agent Teams feature.10 11## When to Use This Skill12 13- Deciding how many teammates to spawn for a task14- Choosing between preset team configurations15- Selecting the right agent type (subagent_type) for each role16- Configuring teammate display modes (tmux, iTerm2, in-process)17- Building custom team compositions for non-standard workflows18 19## Team Sizing Heuristics20 21| Complexity   | Team Size | When to Use                                                 |22| ------------ | --------- | ----------------------------------------------------------- |23| Simple       | 1-2       | Single-dimension review, isolated bug, small feature        |24| Moderate     | 2-3       | Multi-file changes, 2-3 concerns, medium features           |25| Complex      | 3-4       | Cross-cutting concerns, large features, deep debugging      |26| Very Complex | 4-5       | Full-stack features, comprehensive reviews, systemic issues |27 28**Rule of thumb**: Start with the smallest team that covers all required dimensions. Adding teammates increases coordination overhead.29 30## Preset Team Compositions31 32### Review Team33 34- **Size**: 3 reviewers35- **Agents**: 3x `team-reviewer`36- **Default dimensions**: security, performance, architecture37- **Use when**: Code changes need multi-dimensional quality assessment38 39### Debug Team40 41- **Size**: 3 investigators42- **Agents**: 3x `team-debugger`43- **Default hypotheses**: 3 competing hypotheses44- **Use when**: Bug has multiple plausible root causes45 46### Feature Team47 48- **Size**: 3 (1 lead + 2 implementers)49- **Agents**: 1x `team-lead` + 2x `team-implementer`50- **Use when**: Feature can be decomposed into parallel work streams51 52### Fullstack Team53 54- **Size**: 4 (1 lead + 3 implementers)55- **Agents**: 1x `team-lead` + 1x frontend `team-implementer` + 1x backend `team-implementer` + 1x test `team-implementer`56- **Use when**: Feature spans frontend, backend, and test layers57 58### Research Team59 60- **Size**: 3 researchers61- **Agents**: 3x `general-purpose`62- **Default areas**: Each assigned a different research question, module, or topic63- **Capabilities**: Codebase search (Grep, Glob, Read), web search (WebSearch, WebFetch)64- **Use when**: Need to understand a codebase, research libraries, compare approaches, or gather information from code and web sources in parallel65 66### Security Team67 68- **Size**: 4 reviewers69- **Agents**: 4x `team-reviewer`70- **Default dimensions**: OWASP/vulnerabilities, auth/access control, dependencies/supply chain, secrets/configuration71- **Use when**: Comprehensive security audit covering multiple attack surfaces72 73### Migration Team74 75- **Size**: 4 (1 lead + 2 implementers + 1 reviewer)76- **Agents**: 1x `team-lead` + 2x `team-implementer` + 1x `team-reviewer`77- **Use when**: Large codebase migration (framework upgrade, language port, API version bump) requiring parallel work with correctness verification78 79## Agent Type Selection80 81When spawning teammates with the `Agent` tool, choose `subagent_type` based on what tools the teammate needs:82 83| Agent Type                     | Tools Available                           | Use For                                                    |84| ------------------------------ | ----------------------------------------- | ---------------------------------------------------------- |85| `general-purpose`              | All tools (Read, Write, Edit, Bash, etc.) | Implementation, debugging, any task requiring file changes |86| `Explore`                      | Read-only tools (Read, Grep, Glob)        | Research, code exploration, analysis                       |87| `Plan`                         | Read-only tools                           | Architecture planning, task decomposition                  |88| `agent-teams:team-reviewer`    | All tools                                 | Code review with structured findings                       |89| `agent-teams:team-debugger`    | All tools                                 | Hypothesis-driven investigation                            |90| `agent-teams:team-implementer` | All tools                                 | Building features within file ownership boundaries         |91| `agent-teams:team-lead`        | All tools                                 | Team orchestration and coordination                        |92 93**Key distinction**: Read-only agents (Explore, Plan) cannot modify files. Never assign implementation tasks to read-only agents.94 95## Display Mode Configuration96 97Configure in `~/.claude/settings.json`:98 99```json100{101  "teammateMode": "tmux"102}103```104 105| Mode           | Behavior                       | Best For                                          |106| -------------- | ------------------------------ | ------------------------------------------------- |107| `"tmux"`       | Each teammate in a tmux pane   | Development workflows, monitoring multiple agents |108| `"iterm2"`     | Each teammate in an iTerm2 tab | macOS users who prefer iTerm2                     |109| `"in-process"` | All teammates in same process  | Simple tasks, CI/CD environments                  |110 111## Custom Team Guidelines112 113When building custom teams:114 1151. **Every team needs a coordinator** — Either designate a `team-lead` or have the user coordinate directly1162. **Match roles to agent types** — Use specialized agents (reviewer, debugger, implementer) when available1173. **Avoid duplicate roles** — Two agents doing the same thing wastes resources1184. **Define boundaries upfront** — Each teammate needs clear ownership of files or responsibilities1195. **Keep it small** — 2-4 teammates is the sweet spot; 5+ requires significant coordination overhead120 121## Troubleshooting122 123**A teammate was spawned as `Explore` but needs to write files.**124`Explore` and `Plan` are read-only agents. Change the `subagent_type` to `general-purpose` or an appropriate specialized agent type. Never assign implementation tasks to read-only agents.125 126**The team is growing too large and coordination is slowing everything down.**127Each additional teammate adds communication overhead. Consolidate roles: can one agent cover two dimensions? A 4-person team doing 6 independent tasks is usually better served by 3 agents covering 2 tasks each.128 129**tmux mode is not showing panes.**130Ensure tmux is installed and a session is already running before spawning teammates. The `in-process` mode works without tmux and is suitable for CI or scripted environments.131 132**Two reviewers are flagging the same issues.**133The review dimensions overlap. Redefine each reviewer's focus area: one on correctness/logic, one on security, one on performance/scalability. Overlapping coverage wastes tokens and produces duplicate findings.134 135**A `team-lead` is spawning teammates but they are not receiving tasks.**136Verify that the lead is using the `Agent` tool to spawn teammates and passing complete context in the prompt. Teammates start fresh with no prior conversation history — they need all relevant information in their initial prompt.137 138## Related Skills139 140- [parallel-feature-development](../parallel-feature-development/SKILL.md) — Decompose work streams and assign file ownership once the team is composed141- [team-communication-protocols](../team-communication-protocols/SKILL.md) — Establish messaging norms and shutdown procedures for the assembled team