---
name: agent-team-orchestration
description: >-
  Orchestrate multi-agent teams for parallel development, reviews, and debugging. Covers team composition, task coordination, communication protocols, and parallel feature development. Use when spawning agent teams, breaking down work for parallel execution, establishing file ownership boundaries, or coordinating multi-agent workflows.
version: 1.0.0
enabled: false
source: github:JuanJoseGonGi/skills
imported-from: github:JuanJoseGonGi/skills
---

# Agent Team Orchestration

End-to-end guidance for composing, coordinating, and communicating within
multi-agent teams in Claude Code's Agent Teams feature.

## When to Use

- Deciding team size and composition for a task
- Decomposing work into parallel, conflict-free streams
- Establishing file ownership boundaries between agents
- Choosing message types and communication patterns
- Managing plan approval, shutdown, and integration workflows

## Team Sizing

| Complexity   | Size | Example                                          |
|-------------|------|--------------------------------------------------|
| Simple       | 1–2  | Single-dimension review, isolated bug fix         |
| Moderate     | 2–3  | Multi-file changes, 2–3 concerns                 |
| Complex      | 3–4  | Cross-cutting concerns, large features            |
| Very Complex | 4–5  | Full-stack features, comprehensive reviews        |

Start with the smallest team that covers all dimensions. Each extra agent adds coordination overhead.

## Preset Teams

| Preset      | Agents                                    | Use When                              |
|------------|-------------------------------------------|---------------------------------------|
| Review      | 3× `team-reviewer`                        | Multi-dimension code review           |
| Debug       | 3× `team-debugger`                        | Bug with competing hypotheses         |
| Feature     | 1× `team-lead` + 2× `team-implementer`   | Parallelizable feature work           |
| Fullstack   | 1× lead + 3× implementer (FE/BE/test)    | Feature spanning all layers           |
| Research    | 3× `general-purpose`                      | Codebase exploration, library research|
| Security    | 4× `team-reviewer`                        | OWASP, auth, deps, secrets audit      |
| Migration   | 1× lead + 2× implementer + 1× reviewer   | Framework upgrade, language port      |

> **Full details:** See `references/team-composition.md` for agent type selection table, display mode config, and custom team guidelines.

## Task Decomposition

Split work by **directory**, **module**, **layer**, or **concern** — pick whichever gives the cleanest file ownership boundaries.

### Dependency Graphs

Prefer wide, shallow graphs. Only use `blockedBy` for true dependencies.

```
Independent:    A ─┐              Diamond:    ┌→ B ─┐
                B ─┼→ Integrate               A ─┤     ├→ D
                C ─┘                          └→ C ─┘
```

### Task Description Template

Every task needs: **Objective**, **Owned Files**, **Requirements**, **Interface Contract**, **Acceptance Criteria**, **Out of Scope**.

> **Full template and workload monitoring guide:** See `references/task-coordination.md`

## File Ownership Rules

**Cardinal rule: one owner per file.** No file assigned to multiple agents.

When sharing is unavoidable:
1. Designate a single owner
2. Others request changes via message
3. Owner applies changes sequentially
4. Alternative: extract an interface file (read-only for non-owners)

> **Full ownership strategies and integration patterns:** See `references/parallel-development.md`

## Communication

### Message Types

| Type               | When                                          |
|-------------------|-----------------------------------------------|
| `message`          | Default — direct to one teammate              |
| `broadcast`        | Critical blockers affecting everyone (sparingly)|
| `shutdown_request` | Graceful termination                          |

### Anti-Patterns

- Broadcasting routine updates (use direct message)
- Sending JSON status data (use `TaskUpdate`)
- Not communicating at integration points
- Micromanaging via messages (check in at milestones)

### Plan Approval Flow

1. Teammate explores with read-only tools → calls `ExitPlanMode`
2. Lead reviews plan → `plan_approval_response` (approve/reject with feedback)

### Shutdown Sequence

1. Lead sends `shutdown_request` to each teammate
2. Teammate responds `approve: true` (exits) or `approve: false` + reason
3. Lead retries after teammate finishes current work

> **Full protocol details, message JSON examples, and teammate discovery:** See `references/communication-protocols.md`

## References

| File | Content |
|------|---------|
| `references/team-composition.md` | Agent types, display modes, custom team guidelines |
| `references/task-coordination.md` | Task description template, dependency patterns, workload monitoring |
| `references/parallel-development.md` | File ownership strategies, integration patterns, branch management |
| `references/communication-protocols.md` | Message JSON examples, plan approval, shutdown, teammate discovery |
