mirror of
https://github.com/wshobson/agents.git
synced 2026-03-18 09:37:15 +00:00
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.
This commit is contained in:
Seth Hobson
153
plugins/agent-teams/README.md
Normal file
153
plugins/agent-teams/README.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# Agent Teams Plugin
|
||||
|
||||
Orchestrate multi-agent teams for parallel code review, hypothesis-driven debugging, and coordinated feature development using Claude Code's experimental Agent Teams feature.
|
||||
|
||||
## Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. Enable the experimental Agent Teams feature:
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
|
||||
```
|
||||
|
||||
2. Configure teammate display mode in your `~/.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"teammateMode": "tmux"
|
||||
}
|
||||
```
|
||||
|
||||
Available display modes:
|
||||
|
||||
- `"tmux"` — Each teammate runs in a tmux pane (recommended)
|
||||
- `"iterm2"` — Each teammate gets an iTerm2 tab (macOS only)
|
||||
- `"in-process"` — Teammates run in the same process (default)
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
claude --plugin-dir ./plugins/agent-teams
|
||||
```
|
||||
|
||||
Or add to your project's `.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": ["./plugins/agent-teams"]
|
||||
}
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
- **Preset Teams** — Spawn pre-configured teams for common workflows (review, debug, feature, fullstack, research, security, migration)
|
||||
- **Multi-Reviewer Code Review** — Parallel review across security, performance, architecture, testing, and accessibility dimensions
|
||||
- **Hypothesis-Driven Debugging** — Competing hypothesis investigation with evidence-based root cause analysis
|
||||
- **Parallel Feature Development** — Coordinated multi-agent implementation with file ownership boundaries
|
||||
- **Parallel Research** — Multiple Explore agents investigating different questions or codebase areas simultaneously
|
||||
- **Security Audit** — Comprehensive parallel security review across OWASP, auth, dependencies, and configuration
|
||||
- **Migration Support** — Coordinated codebase migration with parallel implementation streams and correctness verification
|
||||
- **Task Coordination** — Dependency-aware task management with workload balancing
|
||||
- **Team Communication** — Structured messaging protocols for efficient agent collaboration
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
| ---------------- | ---------------------------------------------------------- |
|
||||
| `/team-spawn` | Spawn a team using presets or custom composition |
|
||||
| `/team-status` | Display team members, tasks, and progress |
|
||||
| `/team-shutdown` | Gracefully shut down a team and clean up resources |
|
||||
| `/team-review` | Multi-reviewer parallel code review |
|
||||
| `/team-debug` | Competing hypotheses debugging with parallel investigation |
|
||||
| `/team-feature` | Parallel feature development with file ownership |
|
||||
| `/team-delegate` | Task delegation dashboard and workload management |
|
||||
|
||||
## Agents
|
||||
|
||||
| Agent | Role | Color |
|
||||
| ------------------ | --------------------------------------------------------------------------------- | ------ |
|
||||
| `team-lead` | Team orchestrator — decomposes work, manages lifecycle, synthesizes results | Blue |
|
||||
| `team-reviewer` | Multi-dimensional code reviewer — operates on assigned review dimension | Green |
|
||||
| `team-debugger` | Hypothesis investigator — gathers evidence to confirm/falsify assigned hypothesis | Red |
|
||||
| `team-implementer` | Parallel builder — implements within strict file ownership boundaries | Yellow |
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Description |
|
||||
| ------------------------------ | ------------------------------------------------------------------------ |
|
||||
| `team-composition-patterns` | Team sizing heuristics, preset compositions, agent type selection |
|
||||
| `task-coordination-strategies` | Task decomposition, dependency graphs, workload monitoring |
|
||||
| `parallel-debugging` | Hypothesis generation, evidence collection, result arbitration |
|
||||
| `multi-reviewer-patterns` | Review dimension allocation, finding deduplication, severity calibration |
|
||||
| `parallel-feature-development` | File ownership strategies, conflict avoidance, integration patterns |
|
||||
| `team-communication-protocols` | Message type selection, plan approval workflow, shutdown protocol |
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Multi-Reviewer Code Review
|
||||
|
||||
```
|
||||
/team-review src/ --reviewers security,performance,architecture
|
||||
```
|
||||
|
||||
Spawns 3 reviewers, each analyzing the codebase from their assigned dimension, then consolidates findings into a prioritized report.
|
||||
|
||||
### Hypothesis-Driven Debugging
|
||||
|
||||
```
|
||||
/team-debug "API returns 500 on POST /users with valid payload" --hypotheses 3
|
||||
```
|
||||
|
||||
Generates 3 competing hypotheses, spawns investigators for each, collects evidence, and presents the most likely root cause with a fix.
|
||||
|
||||
### Parallel Feature Development
|
||||
|
||||
```
|
||||
/team-feature "Add user authentication with OAuth2" --team-size 3 --plan-first
|
||||
```
|
||||
|
||||
Decomposes the feature into work streams with file ownership boundaries, gets your approval, then spawns implementers to build in parallel.
|
||||
|
||||
### Parallel Research
|
||||
|
||||
```
|
||||
/team-spawn research --name codebase-research
|
||||
```
|
||||
|
||||
Spawns 3 researchers to investigate different aspects in parallel — across your codebase (Grep/Read), the web (WebSearch/WebFetch), and library documentation (Context7 MCP). Each reports findings with citations.
|
||||
|
||||
### Security Audit
|
||||
|
||||
```
|
||||
/team-spawn security
|
||||
```
|
||||
|
||||
Spawns 4 security reviewers covering OWASP vulnerabilities, auth/access control, dependency supply chain, and secrets/configuration. Produces a consolidated security report.
|
||||
|
||||
### Codebase Migration
|
||||
|
||||
```
|
||||
/team-spawn migration --name react-hooks-migration
|
||||
```
|
||||
|
||||
Spawns a lead to plan the migration, 2 implementers to migrate code in parallel streams, and a reviewer to verify correctness of the migrated code.
|
||||
|
||||
### Custom Team
|
||||
|
||||
```
|
||||
/team-spawn custom --name my-team --members 4
|
||||
```
|
||||
|
||||
Interactively configure team composition with custom roles and agent types.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with presets** — Use `/team-spawn review`, `/team-spawn debug`, or `/team-spawn feature` before building custom teams
|
||||
2. **Use `--plan-first`** — For feature development, always review the decomposition before spawning implementers
|
||||
3. **File ownership is critical** — Never assign the same file to multiple implementers; use interface contracts at boundaries
|
||||
4. **Monitor with `/team-status`** — Check progress regularly and use `/team-delegate --rebalance` if work is uneven
|
||||
5. **Graceful shutdown** — Always use `/team-shutdown` rather than killing processes manually
|
||||
6. **Keep teams small** — 2-4 teammates is optimal; larger teams increase coordination overhead
|
||||
7. **Use Shift+Tab** — Claude Code's built-in delegate mode (Shift+Tab) complements these commands for ad-hoc delegation
|
||||
Reference in New Issue
Block a user