Team Composition Patterns

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

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:

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"
}

Custom Team Guidelines

When building custom teams:

1. Every team needs a coordinator — Either designate a team-lead or have the user coordinate directly 2. Match roles to agent types — Use specialized agents (reviewer, debugger, implementer) when available 3. Avoid duplicate roles — Two agents doing the same thing wastes resources 4. Define boundaries upfront — Each teammate needs clear ownership of files or responsibilities 5. Keep it small — 2-4 teammates is the sweet spot; 5+ requires significant coordination overhead

Troubleshooting

A teammate was spawned as `Explore` but needs to write files. 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.

The team is growing too large and coordination is slowing everything down. Each 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.

tmux mode is not showing panes. Ensure 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.

Two reviewers are flagging the same issues. The 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.

A `team-lead` is spawning teammates but they are not receiving tasks. Verify 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.

Related Skills

• parallel-feature-development — Decompose work streams and assign file ownership once the team is composed
• team-communication-protocols — Establish messaging norms and shutdown procedures for the assembled team

Agent Type Selection Guide

Decision matrix for choosing the right subagent_type when spawning teammates.

Decision Matrix

Does the teammate need a specialized Agent Teams role?
├── YES → Which role?
│         ├── Team coordination → agent-teams:team-lead
│         ├── Feature building → agent-teams:team-implementer
│         ├── Code review → agent-teams:team-reviewer
│         └── Bug investigation → agent-teams:team-debugger
└── NO → Does it need to modify files?
          ├── YES → general-purpose
          └── NO → Does it need deep codebase exploration?
                    ├── YES → Explore
                    └── NO → Plan (for architecture/design tasks)

Agent Type Comparison

Common Mistakes

When to Use Each

general-purpose

• One-off tasks that don't fit specialized roles
• Tasks requiring unique tool combinations
• Ad-hoc scripting or automation

Explore

• Codebase research and analysis
• Finding files, patterns, or dependencies
• Understanding architecture before planning

Plan

• Designing implementation approaches
• Creating task decompositions
• Architecture review (read-only)

team-lead

• Coordinating multiple teammates
• Decomposing work and managing tasks
• Synthesizing results from parallel work

team-reviewer

• Focused code review on a specific dimension
• Producing structured findings with severity ratings
• Following dimension-specific checklists

team-debugger

• Investigating a specific hypothesis about a bug
• Gathering evidence with file:line citations
• Reporting confidence levels and causal chains

team-implementer

• Building code within file ownership boundaries
• Following interface contracts
• Coordinating at integration points

Preset Team Definitions

Detailed preset team configurations with task templates for common workflows.

Review Team Preset

Command: /team-spawn review

Configuration

• Team Size: 3
• Agent Type: agent-teams:team-reviewer
• Display Mode: tmux recommended

Members

Task Template

Subject: Review {target} for {dimension} issues
Description:
  Dimension: {dimension}
  Target: {file list or diff}
  Checklist: {dimension-specific checklist}
  Output format: Structured findings with file:line, severity, evidence, fix

Variations

• Security-focused: --reviewers security,testing (2 members)
• Full review: --reviewers security,performance,architecture,testing,accessibility (5 members)
• Frontend review: --reviewers architecture,testing,accessibility (3 members)

Debug Team Preset

Command: /team-spawn debug

Configuration

• Team Size: 3 (default) or N with --hypotheses N
• Agent Type: agent-teams:team-debugger
• Display Mode: tmux recommended

Members

Task Template

Subject: Investigate hypothesis: {hypothesis summary}
Description:
  Hypothesis: {full hypothesis statement}
  Scope: {files/module/project}
  Evidence criteria:
    Confirming: {what would confirm}
    Falsifying: {what would falsify}
  Report format: confidence level, evidence with file:line, causal chain

Feature Team Preset

Command: /team-spawn feature

Configuration

• Team Size: 3 (1 lead + 2 implementers)
• Agent Types: agent-teams:team-lead + agent-teams:team-implementer
• Display Mode: tmux recommended

Members

Task Template

Subject: Implement {work stream name}
Description:
  Owned files: {explicit file list}
  Requirements: {specific deliverables}
  Interface contract: {shared types/APIs}
  Acceptance criteria: {verification steps}
  Blocked by: {dependency task IDs if any}

Fullstack Team Preset

Command: /team-spawn fullstack

Configuration

• Team Size: 4 (1 lead + 3 implementers)
• Agent Types: agent-teams:team-lead + 3x agent-teams:team-implementer
• Display Mode: tmux recommended

Members

Dependency Pattern

frontend-dev ──┐
               ├──→ test-dev (blocked by both)
backend-dev  ──┘

Research Team Preset

Command: /team-spawn research

Configuration

• Team Size: 3
• Agent Type: general-purpose
• Display Mode: tmux recommended

Members

Available Research Tools

Each researcher has access to:

• Codebase: Grep, Glob, Read — search and read local files
• Web: WebSearch, WebFetch — search the web and fetch page content
• Deep Exploration: Task with subagent_type: Explore — spawn sub-explorers for deep dives

Task Template

Subject: Research {topic or question}
Description:
  Question: {specific research question}
  Scope: {codebase files, web resources, library docs, or all}
  Tools to prioritize:
    - Codebase: Grep/Glob/Read for local code analysis
    - Web: WebSearch/WebFetch for articles, examples, best practices
  Deliverable: Summary with citations (file:line for code, URLs for web)
  Output format: Structured report with sections, evidence, and recommendations

Variations

• Codebase-only: 3 researchers exploring different modules or patterns locally
• Web research: 3 researchers using WebSearch to survey approaches, benchmarks, or best practices
• Mixed: 1 codebase researcher + 1 docs researcher + 1 web researcher (recommended for evaluating new libraries)

Example Research Assignments

Researcher 1 (codebase): "How does our current auth system work? Trace the flow from login to token validation."
Researcher 2 (web): "Search for comparisons between NextAuth, Clerk, and Auth0 for Next.js apps. Focus on pricing, DX, and migration effort."
Researcher 3 (docs): "Look up the latest NextAuth.js v5 API docs. How does it handle JWT and session management?"

Security Team Preset

Command: /team-spawn security

Configuration

• Team Size: 4
• Agent Type: agent-teams:team-reviewer
• Display Mode: tmux recommended

Members

Task Template

Subject: Security audit {target} for {dimension}
Description:
  Dimension: {security sub-dimension}
  Target: {file list, directory, or entire project}
  Checklist: {dimension-specific security checklist}
  Output format: Structured findings with file:line, CVSS-like severity, evidence, remediation
  Standards: OWASP Top 10, CWE references where applicable

Variations

• Quick scan: --reviewers owasp,secrets (2 members for fast audit)
• Full audit: All 4 dimensions (default)
• CI/CD focused: Add a 5th reviewer for pipeline security and deployment configuration

Migration Team Preset

Command: /team-spawn migration

Configuration

• Team Size: 4 (1 lead + 2 implementers + 1 reviewer)
• Agent Types: agent-teams:team-lead + 2x agent-teams:team-implementer + agent-teams:team-reviewer
• Display Mode: tmux recommended

Members

Task Template

Subject: Migrate {module/files} from {old} to {new}
Description:
  Owned files: {explicit file list}
  Migration rules: {specific transformation patterns}
  Old pattern: {what to change from}
  New pattern: {what to change to}
  Acceptance criteria: {tests pass, no regressions, new patterns used}
  Blocked by: {dependency task IDs if any}

Dependency Pattern

migration-lead (plan) → migrator-1 ──┐
                      → migrator-2 ──┼→ migration-verify
                                     ┘

Use Cases

• Framework upgrades (React class → hooks, Vue 2 → Vue 3, Angular version bumps)
• Language migrations (JavaScript → TypeScript, Python 2 → 3)
• API version bumps (REST v1 → v2, GraphQL schema changes)
• Database migrations (ORM changes, schema restructuring)
• Build system changes (Webpack → Vite, CRA → Next.js)