feat(agent-teams): add plugin for multi-agent team orchestration

New plugin with 7 presets (review, debug, feature, fullstack, research, security, migration), 4 specialized agents, 7 slash commands, 6 skills with reference docs, and Context7 MCP integration for research teams.
2026-03-18 09:37:15 +00:00 · 2026-02-05 17:10:02 -05:00
parent 918a770990
commit 0752775afc
30 changed files with 3080 additions and 0 deletions
--- a/plugins/agent-teams/skills/team-composition-patterns/SKILL.md
+++ b/plugins/agent-teams/skills/team-composition-patterns/SKILL.md
@@ -0,0 +1,118 @@
+---
+name: team-composition-patterns
+description: Design optimal agent team compositions with sizing heuristics, preset configurations, and agent type selection. Use this skill when deciding team size, selecting agent types, or configuring team presets for multi-agent workflows.
+---
+
+# 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), library documentation (Context7 MCP)
+- **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 Task 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`    | All tools                                 | Code review with structured findings                       |
+| `agent-teams:team-debugger`    | All tools                                 | Hypothesis-driven investigation                            |
+| `agent-teams:team-implementer` | All tools                                 | Building features within file ownership boundaries         |
+| `agent-teams:team-lead`        | All 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`:
+
+```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 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
--- a/plugins/agent-teams/skills/team-composition-patterns/references/agent-type-selection.md
+++ b/plugins/agent-teams/skills/team-composition-patterns/references/agent-type-selection.md
@@ -0,0 +1,84 @@
+# Agent Type Selection Guide
+
+Decision matrix for choosing the right `subagent_type` when spawning teammates.
+
+## Decision Matrix
+
+```
+Does the teammate need to modify files?
+├── YES → Does it need a specialized role?
+│         ├── YES → Which role?
+│         │         ├── Code review → agent-teams:team-reviewer
+│         │         ├── Bug investigation → agent-teams:team-debugger
+│         │         ├── Feature building → agent-teams:team-implementer
+│         │         └── Team coordination → agent-teams:team-lead
+│         └── NO → general-purpose
+└── NO → Does it need deep codebase exploration?
+          ├── YES → Explore
+          └── NO → Plan (for architecture/design tasks)
+```
+
+## Agent Type Comparison
+
+| Agent Type                   | Can Read | Can Write | Can Edit | Can Bash | Specialized        |
+| ---------------------------- | -------- | --------- | -------- | -------- | ------------------ |
+| general-purpose              | Yes      | Yes       | Yes      | Yes      | No                 |
+| Explore                      | Yes      | No        | No       | No       | Search/explore     |
+| Plan                         | Yes      | No        | No       | No       | Architecture       |
+| agent-teams:team-lead        | Yes      | Yes       | Yes      | Yes      | Team orchestration |
+| agent-teams:team-reviewer    | Yes      | Yes       | Yes      | Yes      | Code review        |
+| agent-teams:team-debugger    | Yes      | Yes       | Yes      | Yes      | Bug investigation  |
+| agent-teams:team-implementer | Yes      | Yes       | Yes      | Yes      | Feature building   |
+
+## Common Mistakes
+
+| Mistake                               | Why It Fails                   | Correct Choice                          |
+| ------------------------------------- | ------------------------------ | --------------------------------------- |
+| Using `Explore` for implementation    | Cannot write/edit files        | `general-purpose` or `team-implementer` |
+| Using `Plan` for coding tasks         | Cannot write/edit files        | `general-purpose` or `team-implementer` |
+| Using `general-purpose` for reviews   | No review structure/checklists | `team-reviewer`                         |
+| Using `team-implementer` for research | Has tools but wrong focus      | `Explore` or `Plan`                     |
+
+## 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
--- a/plugins/agent-teams/skills/team-composition-patterns/references/preset-teams.md
+++ b/plugins/agent-teams/skills/team-composition-patterns/references/preset-teams.md
@@ -0,0 +1,268 @@
+# 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
+
+| Name                  | Dimension    | Focus Areas                                       |
+| --------------------- | ------------ | ------------------------------------------------- |
+| security-reviewer     | Security     | Input validation, auth, injection, secrets, CVEs  |
+| performance-reviewer  | Performance  | Query efficiency, memory, caching, async patterns |
+| architecture-reviewer | Architecture | SOLID, coupling, patterns, error handling         |
+
+### 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
+
+| Name           | Role                      |
+| -------------- | ------------------------- |
+| investigator-1 | Investigates hypothesis 1 |
+| investigator-2 | Investigates hypothesis 2 |
+| investigator-3 | Investigates hypothesis 3 |
+
+### 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
+
+| Name          | Role             | Responsibility                           |
+| ------------- | ---------------- | ---------------------------------------- |
+| feature-lead  | team-lead        | Decomposition, coordination, integration |
+| implementer-1 | team-implementer | Work stream 1 (assigned files)           |
+| implementer-2 | team-implementer | Work stream 2 (assigned files)           |
+
+### 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
+
+| Name           | Role             | Layer                            |
+| -------------- | ---------------- | -------------------------------- |
+| fullstack-lead | team-lead        | Coordination, integration        |
+| frontend-dev   | team-implementer | UI components, client-side logic |
+| backend-dev    | team-implementer | API endpoints, business logic    |
+| test-dev       | team-implementer | Unit, integration, e2e tests     |
+
+### 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
+
+| Name         | Role            | Focus                                            |
+| ------------ | --------------- | ------------------------------------------------ |
+| researcher-1 | general-purpose | Research area 1 (e.g., codebase architecture)    |
+| researcher-2 | general-purpose | Research area 2 (e.g., library documentation)    |
+| researcher-3 | general-purpose | Research area 3 (e.g., web resources & examples) |
+
+### 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
+- **Library Docs**: Context7 MCP (`resolve-library-id`, `query-docs`) — look up current documentation for any library
+- **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
+    - Docs: Context7 MCP for up-to-date library documentation
+  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
+- **Documentation**: 3 researchers using Context7 to compare library APIs and patterns
+- **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 (docs): "Use Context7 to look up the latest NextAuth.js v5 API. How does it handle JWT and session management?"
+Researcher 3 (web): "Search for comparisons between NextAuth, Clerk, and Auth0 for Next.js apps. Focus on pricing, DX, and migration effort."
+```
+
+## Security Team Preset
+
+**Command**: `/team-spawn security`
+
+### Configuration
+
+- **Team Size**: 4
+- **Agent Type**: `agent-teams:team-reviewer`
+- **Display Mode**: tmux recommended
+
+### Members
+
+| Name            | Dimension      | Focus Areas                                          |
+| --------------- | -------------- | ---------------------------------------------------- |
+| vuln-reviewer   | OWASP/Vulns    | Injection, XSS, CSRF, deserialization, SSRF          |
+| auth-reviewer   | Auth/Access    | Authentication, authorization, session management    |
+| deps-reviewer   | Dependencies   | CVEs, supply chain, outdated packages, license risks |
+| config-reviewer | Secrets/Config | Hardcoded secrets, env vars, debug endpoints, CORS   |
+
+### 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
+
+| Name             | Role             | Responsibility                                  |
+| ---------------- | ---------------- | ----------------------------------------------- |
+| migration-lead   | team-lead        | Migration plan, coordination, conflict handling |
+| migrator-1       | team-implementer | Migration stream 1 (assigned files/modules)     |
+| migrator-2       | team-implementer | Migration stream 2 (assigned files/modules)     |
+| migration-verify | team-reviewer    | Verify migrated code correctness and patterns   |
+
+### 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)