SamuelChien/mega-skills-collection

Table of Contents

• Overview
• When to Use
• Prerequisites
• Protocol Architecture
• Quick Start
• Coordination Workflow
• Module Reference
• Integration with Conjure
• Troubleshooting
• 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. No database, no daemon, no 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.

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 + 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.

Module Reference

• team-management.md: Team lifecycle, config format, member management
• messaging-protocol.md: Message types, inbox operations, locking patterns
• task-coordination.md: Task CRUD, state machine, dependency cycle detection
• spawning-patterns.md: tmux spawning, CLI flags, pane management
• crew-roles.md: Role taxonomy, capability matrix, role-risk compatibility
• health-monitoring.md: Heartbeat protocol, stall detection, automated recovery

Integration with Conjure

Agent Teams extends the conjure delegation model:

Conjure Pattern	Agent Teams Equivalent
delegation-core:task-assessed	agent-teams:team-created
delegation-core:handoff-planned	agent-teams:tasks-assigned
delegation-core:results-integrated	agent-teams:team-shutdown
External LLM execution	Teammate agent execution

Use Skill(conjure:delegation-core) first to determine if the task benefits from multi-agent coordination vs. single-service delegation.

Worktree Isolation Alternative (Claude Code 2.1.49+)

For parallel agents that modify files, isolation: worktree provides a lightweight alternative to filesystem-based coordination. Each agent runs in its own temporary git worktree, eliminating the need for fcntl locking or inbox-based conflict avoidance on shared files.

• When to prefer worktrees over agent teams messaging: Agents work on overlapping files but don't need mid-execution communication
• When to prefer agent teams messaging: Agents need to coordinate discoveries or adjust plans based on each other's progress
• Combine both: Use agent teams for coordination with isolation: worktree per teammate for filesystem safety

Troubleshooting

Common Issues

tmux not found Install via package manager: brew install tmux / apt install tmux

Stale lock files If an agent crashes mid-operation, lock files may persist. Remove .lock files manually from ~/.claude/teams/<team>/inboxes/ or ~/.claude/tasks/<team>/

Orphaned tasks Tasks claimed by a crashed agent stay in_progress indefinitely. Use modules/health-monitoring.md for heartbeat-based stall detection and automatic task release. The health monitoring protocol detects unresponsive agents within 60s + 30s probe window and releases their tasks for reassignment.

Message ordering Filesystem timestamp resolution varies (HFS+ = 1s granularity). Use numbered filenames or UUID-sorted names to avoid collision on rapid message bursts.

Model errors on Bedrock/Vertex/Foundry (pre-2.1.39) Teammate agents could use incorrect model identifiers on enterprise providers, causing 400 errors. Upgrade to Claude Code 2.1.39+ for correct model ID qualification across all providers.

Nested session guard (2.1.39+) If claude refuses to launch within an existing session, ensure you're using tmux pane splitting (not subshell invocation). The guard is intentional — see modules/spawning-patterns.md for details.

Exit Criteria

• Team created with config and directories
• Teammates spawned and registered in config
• Tasks created with dependency graph (no cycles)
• Agents coordinating via inbox messages
• Graceful shutdown completed