Structured Data
Capability Metadata
| Field | Value |
|---|---|
| ID | CAP-009 |
| Version | v1.4 |
| Domain | Agent Orchestration |
| Status | Documented |
| Related | CAP-006, CAP-011, CAP-027, CAP-052, CAP-053 |
| Source | src/teams/team-manager.ts |
| Storage | .claude/teams/ |
Configuration Reference
Team definitions: YAML files in .claude/teams/
# .claude/teams/my-team.yaml
name: my-team
topology: leader-worker
members:
- role: leader
agent: orchestrator.md
- role: worker
agent: researcher.md
- role: worker
agent: writer.md
storage: .claude/teams/my-team/Topology options: leader-worker, pipeline, swarm
Start team: skill-creator team start my-team
Technical Specifications
Class: TeamManager
type Topology = "leader-worker" | "pipeline" | "swarm";
interface TeamMember {
role: "leader" | "worker" | "stage" | "peer";
agent: string; // Agent filename in .claude/agents/
capabilities?: string[]; // Optional capability filter
}
interface TeamSchema {
name: string;
topology: Topology;
members: TeamMember[];
storage: string; // Working directory for team state
}
// Coordination message passed between agents
interface CoordinationMessage {
from: string; // Sending agent role
to: string | "all"; // Target role or broadcast
type: "task" | "result" | "status" | "error";
payload: unknown;
}
class TeamManager {
startTeam(schema: TeamSchema): void;
sendMessage(msg: CoordinationMessage): void;
getStatus(): TeamStatus;
stopTeam(): void;
}Overview
Agent Teams formalizes the coordination patterns that Composing Agents (CAP-006) hinted at. Where composition groups skills that travel together, teams are explicitly designed multi-agent systems where each agent has a defined role and the team has a defined coordination topology. Leader-worker teams have a coordinator directing specialists; pipeline teams pass work sequentially; swarm teams parallelize across identical agents.
Teams are defined as YAML schemas stored in .claude/teams/. Each schema specifies the team's name, topology, member agents, and storage directory. The TeamManager class reads the schema, instantiates the agents, and manages the coordination message protocol between them. The topology determines how messages flow: in leader-worker, the leader dispatches tasks and collects results; in pipeline, each stage passes its output to the next; in swarm, the TeamManager fans work out to all peers and aggregates results.
Teams compose with the rest of the skill system — each team member agent can carry its own skill set, and skills activate normally within each agent's context. This allows teams to be both structurally coordinated (at the team level) and individually specialized (at the agent level).
History
Agent Teams was introduced in v1.4, filling the gap between composed agents (bottom-up emergence, CAP-006) and deliberate system design (top-down architecture). Composed agents formed through co-activation patterns — the system noticed that certain agents were always spawned together and built a combined agent. Teams, by contrast, are intentionally designed: you specify the coordination pattern before the agents start working.
The three initial topologies covered the most common orchestration patterns in software engineering: boss-worker (leader-worker), assembly line (pipeline), and embarrassingly parallel (swarm). In v1.9, router and map-reduce patterns were added by CAP-027, extending the topology set for more sophisticated distribution patterns. In v1.13, the Team-as-Chip framework (CAP-052) extended teams with an Amiga-inspired hardware-metaphor architecture, where teams are treated as silicon chips with defined input/output pins and power characteristics.
Key Concepts
A leader-worker team is like a film crew — the director (leader) coordinates, the camera operator, sound engineer, and gaffer (workers) execute their specialty. The director doesn't do the technical work; they manage the big picture and direct the specialists.
A pipeline team is like an assembly line — each station does one thing and passes the result to the next. Station 1 gathers data, Station 2 analyzes it, Station 3 writes the report. No station starts until the previous one finishes.
A swarm is like a search party — many agents doing the same thing in parallel to cover more ground faster. If you need to search 100 files, a swarm of 10 agents each searches 10 files, then all results are combined.
Usage Examples
Example 1: Define a leader-worker team
# .claude/teams/research-team.yaml
name: research-team
topology: leader-worker
members:
- role: leader
agent: orchestrator.md
capabilities: ["planning", "task-dispatch"]
- role: worker
agent: web-researcher.md
capabilities: ["web-search", "summarization"]
- role: worker
agent: code-analyst.md
capabilities: ["code-review", "pattern-detection"]
storage: .claude/teams/research-team/Example 2: Start a team and monitor progress
# Start the team
skill-creator team start research-team
# Monitor team status
skill-creator team status research-team
# Output:
# Team: research-team (topology: leader-worker)
# Leader: orchestrator.md — ACTIVE, dispatched 3 tasks
# Worker 1: web-researcher.md — WORKING on task-002
# Worker 2: code-analyst.md — IDLE, waiting for task-003
# Messages in queue: 1Example 3: Define a pipeline team
# .claude/teams/doc-pipeline.yaml
name: doc-pipeline
topology: pipeline
members:
- role: stage
agent: content-extractor.md # Stage 1: extract raw content
- role: stage
agent: narrative-writer.md # Stage 2: write narrative from content
- role: stage
agent: publisher.md # Stage 3: publish to WordPress
storage: .claude/teams/doc-pipeline/