/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
model_hint: deep
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

Table of Contents

• [Overview](#overview)
• [When to Use](#when-to-use)
• [Prerequisites](#prerequisites)
• [Protocol Architecture](#protocol-architecture)
• [Quick Start](#quick-start)
• [Coordination Workflow](#coordination-workflow)
• [Module Reference](#module-reference)
• [Integration with Conjure](#integration-with-conjure)
• [Troubleshooting](#troubleshooting)
• [Exit Criteria](#exit-criteria)

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 for