/agent-teams

name: agent-teams
description: Coordinates Claude agent teams via filesystem protocol. Use when orchestrating parallel agents with task dependencies. Do not use for single-agent tasks.
alwaysApply: false
category: delegation-framework
tags:
- agent-teams
- multi-agent
- coordination
- tmux
- task-management
- messaging
dependencies:
- delegation-core
- leyline:damage-control
- leyline:risk-classification
tools: []
usage_patterns:
- team-orchestration
- parallel-implementation
- multi-agent-review
- task-dependency-management
complexity: advanced
estimated_tokens: 450
progressive_loading: true
modules:
- modules/team-management.md
- modules/messaging-protocol.md
- modules/task-coordination.md
- modules/spawning-patterns.md
- modules/crew-roles.md
- modules/health-monitoring.md
references:
- ../../../leyline/skills/error-patterns/SKILL.md
- ../../../leyline/skills/service-registry/SKILL.md
- references/team-formation.md

Agent Teams Coordination

Overview

Claude Code Agent Teams enables multiple Claude CLI processes to collaborate on shared work through a filesystem-based coordination protocol. Each teammate runs as an independent `claude` process in a tmux pane, communicating via JSON files guarded by `fcntl` locks, with no database, daemon, or network layer.

This skill provides the patterns for orchestrating agent teams effectively.

When To Use

• Parallel implementation across multiple files or modules
• Multi-agent code review (one agent reviews, another implements fixes)
• Large refactoring requiring coordinated changes across subsystems
• Tasks with natural parallelism that benefit from concurrent agents

When NOT To Use

• Single-file changes or small tasks (overhead exceeds benefit)
• Tasks requiring tight sequential reasoning (agents coordinate loosely)
• When `claude` CLI is not available or tmux is not installed

Prerequisites

# Verify Claude Code CLI
claude --version

# Verify tmux (required for split-pane mode)
tmux -V

# Enable experimental feature (set by spawner automatically)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Protocol Architecture

~/.claude/
  teams/<team-name>/
    config.json            # Team metadata + member roster
    inboxes/
      <agent-name>.json    # Per-agent message queue
      .lock                # fcntl exclusive lock
  tasks/<team-name>/
    1.json ... N.json      # Auto-incrementing task files
    .lock                  # fcntl exclusive lock

**Design principles:**

• **Filesystem is the database**: JSON files, atomic writes via `tempfile` + `os.replace`
• **fcntl locking**: Prevents concurrent read/write corruption on inboxes and tasks
• **Numbered tasks**: Auto-incrementing IDs with sequential file naming
• **Loose coupling**: Agents poll their own inbox; no push notifications

Quick Start

1. Create a Team

# Programmatic team setup (via MCP or direct API)
# Team config written to ~/.claude/teams/<team-name>/config.json

The team config contains:

• `name`, `description`, `created_at` (ms timestamp)
• `lead_agent_id`, `lead_session_id`
• `members[]`: array of LeadMember and TeammateMember objects

2. Spawn Teammates

Each teammate is a separate `claude` CLI process launched with identity flags:

claude --agent-id "backend@my-team" \
       --agent-name "backend" \
       --team-name "my-team" \
       --agent-color "#FF6B6B" \
       --parent-session-id "$SESSION_ID" \
       --agent-type "general-purpose" \
       --model sonnet

See `modules/spawning-patterns.md` for tmux pane management and color assignment.

3. Create Tasks with Dependencies

{
  "id": "1",
  "subject": "Implement API endpoints",
  "description": "Create REST endpoints for user management",
  "status": "pending",
  "owner": null,
  "blocks": ["3"],
  "blocked_by": [],
  "metadata": {}
}

See `modules/task-coordination.md` for state machine and dependency management.

4. Coordinate via Messages

{
  "from": "team-lead",
  "text": "API endpoints are ready for integration testing",
  "timestamp": "2026-02-07T22:00:00Z",
  "read": false,
  "summary": "API ready"
}

See `modules/messaging-protocol.md` for message types and inbox operations.

Coordination Workflow

1. **`agent-teams:team-created`**: Initialize team config and directories 2. **`agent-teams:teammates-spawned`**: Launch agents in tmux panes 3. **`agent-teams:tasks-assigned`**: Create tasks with dependencies, assign owners 4. **`agent-teams:coordination-active`**: Agents claim tasks, exchange messages, mark completion 5. **`agent-teams:team-shutdown`**: Graceful shutdown with approval protocol

Crew Roles

Each team member has a `role` that determines their capabilities and task compatibility. Five roles are defined: `implementer` (default), `researcher`, `tester`, `reviewer`, and `architect`. Roles constrain which risk tiers an agent can handle. See `modules/crew-roles.md` for the full capability matrix and role-risk compatibility table.

Team Formation

For mission-level team sizing, use the Team Formation rules from `references/team-formation.md`. This defines:

• **Role definitions**: Coordinator (mission lead), Agents (task owners),

Reviewer (adversarial challenger)

• **Team sizing rules**: Simple (1), Moderate (2-4), Complex (5-7),

Critical (5-10)

• **Maximum team size**: 10 agents (coordination overhead limit)
• **File ownership rules**: Prevent conflicts with clear ownership

See `references/team-formation.md` for full team sizing guidance and example team formations.

Health Monitoring

Team members can be monitored for health via heartbeat messages and claim expiry. The lead polls team health every 60s with a 2-stage stall detection protocol (health_check probe and 30s wait). Stalled agents have their tasks released and are restarted or replaced following the "replace don't wait" doctrine. See `modules/health-monitoring.md` for the full protocol and state machine.

Modu