Agent Teams

Key principle: Each agent is a fresh Claude session with zero shared memory. All coordination happens through files (WORKTREE_TASK.md, shared contracts) and git (branches, PRs). There is no runtime communication between agents.

Spawn a 2-agent team:

"Set up a team: Agent 1 builds the API endpoints, Agent 2 builds the React components.
They share this contract: POST /api/tasks returns { id, title, status }."

What happens:

1. Team lead creates 2 worktrees via worktree-manager
2. Writes WORKTREE_TASK.md with focused prompt + contract to each
3. Launches each agent in its own Ghostty terminal
4. Agents work independently, team lead monitors and merges

Prerequisites

Required skill: worktree-manager — agent-teams delegates ALL worktree creation, port allocation, and terminal launching to worktree-manager. Install it first.

Recommended: Project has a .claude/ directory with CLAUDE.md (dev commands, conventions). If the project also has .claude/agents/ with custom subagents or .claude/settings.json with hooks/permissions, these are automatically propagated to each agent's worktree.

Environment check:

# Agent teams config
echo "Max agents: ${AGENT_TEAMS_MAX:-3}"

# Worktree manager available?
ls ~/.claude/skills/worktree-manager/ 2>/dev/null && echo "worktree-manager: OK" || echo "worktree-manager: MISSING"

# Running agents (approximate)
pgrep -f "claude.*--model" | wc -l | xargs echo "Active Claude processes:"

# Memory pressure
vm_stat | grep "Pages free" | awk '{print "Free pages:", $3}'

Worktree registry: !cat ~/.claude/worktree-registry.json 2>/dev/null | jq -r '.worktrees[] | select(.status == "active") | "\(.project)/\(.branch)"' | head -5

Memory: !memory_pressure 2>/dev/null | head -1 || echo "Unknown"

Git status: !git status --short --branch 2>/dev/null | head -3

Hardware Constraints (M1/8GB)

Rule of thumb: If memory_pressure reports "WARN" or higher, reduce to 2 agents.

When to Use Agent Teams

Use when:

• Task naturally decomposes into 2-3 independent work streams
• Each stream touches different files (low conflict risk)
• Wall-clock speed matters more than token efficiency
• You have clear contracts between components (API shape, shared types)

Don't use when:

• Task is tightly coupled (every change touches the same files)
• You're on battery with <30% charge (agents drain power fast)
• Memory pressure is already high (check memory_pressure)
• The codebase has no tests (merging blind is risky)

Decision heuristic:

Can I describe each agent's task in <50 words?
  YES → Good candidate for agent teams
  NO  → Break it down more, or do it sequentially

Lightweight alternative: For tasks where agents DON'T need file isolation (different files, read-only, reviews), use subagent-teams instead. It uses Claude's native Task tool for in-session parallel agents — faster startup, no worktrees needed. See also the Native Teams API section below.

Architecture

┌──────────────────────────────────────────────────┐
│                   TEAM LEAD                       │
│            (this Claude session)                  │
│                                                   │
│  Responsibilities:                                │
│  • Decompose task into agent assignments          │
│  • Create worktrees (via worktree-manager)        │
│  • Write WORKTREE_TASK.md for each agent          │
│  • Monitor progress (git log, file checks)        │
│  • Coordinate merges back to main                 │
└─────────┬───────────────┬───────────────┬────────┘
          │               │               │
    ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
    │  AGENT 1  │   │  AGENT 2  │   │  AGENT 3  │
    │           │   │           │   │           │
    │ Worktree: │   │ Worktree: │   │ Worktree: │
    │ ~/tmp/wt/ │   │ ~/tmp/wt/ │   │ ~/tmp/wt/ │
    │ proj/br-1 │   │ proj/br-2 │   │ proj/br-3 │
    │           │   │           │   │           │
    │ Terminal: │   │ Terminal: │   │ Terminal: │
    │ Ghostty 1 │   │ Ghostty 2 │   │ Ghostty 3 │
    └───────────┘   └───────────┘   └───────────┘
         │               │               │
         └───── git branches ─────────────┘
                     │
               [main branch]

Context Isolation

Each agent is a completely separate Claude session. Agents:

• Cannot read each other's context windows
• Cannot send messages to each other
• Share state ONLY through the filesystem and git
• Read their task from WORKTREE_TASK.md on startup

Coordination Through Files

Display Modes

Config: "teammateMode": "auto" in ~/.claude/settings.json. CLI: claude --teammate-mode in-process. Ghostty requires tmux wrapper for split-pane.

Split Pane Setup

tmux: Auto-detected when $TMUX is set. Each teammate gets a split pane. Navigate with Ctrl+B + arrow keys.

iTerm2: Uses AppleScript automation. Teammates open in split panes within the current tab.

Limitations: Ghostty lacks programmatic pane splitting — use tmux wrapper: ghostty -e "tmux new-session". Max 4 panes recommended (leader + 3 teammates). Each pane needs ~120 columns.

Team Hooks

TeammateIdle Hook

Fires when a teammate finishes its current turn and goes idle. Configure in settings.json:

{
  "hooks": {
    "TeammateIdle": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'echo \"Teammate idle — check TaskList for unassigned work\" >&2'"
      }]
    }]
  }
}

Use cases: Auto-assign next task, log idle time, trigger cleanup. Exit code 2 blocks the idle transition (keeps teammate working). Does NOT support matchers — fires for all teammates.

TaskCompleted Hook

Fires when a task is marked complete via TaskUpdate. Use for auto-assignment pipelines:

{
  "hooks": {
    "TaskCompleted": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'echo \"Task completed — assigning next unblocked task\" >&2'"
      }]
    }]
  }
}

Exit code 2 blocks task completion (keeps task in_progress). Does NOT support matchers.

Plan Approval Flow

Teammates spawned with mode: "plan" must get plans approved before implementing:

1. Teammate calls ExitPlanMode → sends plan_approval_request to team lead
2. Team lead reviews → sends plan_approval_response (approve or reject with feedback)
3. On approval: teammate exits plan mode, begins implementation
4. On rejection: teammate receives feedback and revises

// Approving a teammate's plan
SendMessage({
  type: "plan_approval_response",
  request_id: "abc-123",  // from plan_approval_request
  recipient: "architect",
  approve: true
})

Workflows

Native vs Worktree decision: Different files → Native Teams API. Same files → Worktrees. Real-time messaging → Native. Long-running processes → Worktrees.

See reference/workflows-detailed.md for step-by-step instructions, WORKTREE_TASK.md template, merge protocol, and Native Teams API examples.

Team Patterns

Feature Parallel

2-3 agents build independent features simultaneously. Lowest conflict risk. Best for: Sprint-style parallel feature work. See: reference/prompt-templates.md#feature-parallel for spawn prompts.

Frontend / Backend

One agent builds the API, another builds the UI. Connected by a shared contract. Best for: Full-stack features where API and UI are clearly separable. See: reference/prompt-templates.md#frontend-backend for spawn prompts.

Test / Implement (TDD Pair)

Agent 1 writes tests first, commits and pushes. Agent 2 pulls tests and implements until they pass. Best for: High-quality code where test coverage matters. See: reference/prompt-templates.md#test-implement for spawn prompts.

Review / Refactor

Agent 1 refactors code. Agent 2 reviews the refactored code and writes improvement suggestions. Best for: Large refactoring tasks that benefit from a second perspective. See: reference/prompt-templates.md#review-refactor for spawn prompts.

Best Practices

• Isolate context per agent — only relevant info in WORKTREE_TASK.md, keep tasks to <50 words
• Use external state — .agent-status, git commits, WORKTREE_TASK.md (agents have no shared memory)
• Front-load instructions — most important info at TOP of task files
• Contract-first — define shared API shapes in CONTRACT.md BEFORE spawning agents
• Merge order matters — foundation (API) before consumer (UI), test after each, use --no-ff
• Project config inheritance — .claude/ dir auto-copied gives agents CLAUDE.md, hooks, permissions, custom subagents
• Team hooks — TeammateIdle and TaskCompleted hooks use exit code 2 to keep working / block completion

See reference/best-practices-full.md for context engineering, session harness patterns, permissions model, and hook configuration.

Limitations

M1/8GB Constraints

• Max 3 agents — Beyond this, memory pressure causes thrashing
• No GPU agents — All agents are CPU-bound Claude sessions
• Startup time — Each agent takes 5-10s to initialize

Coordination Limits

• No real-time communication — Worktree agents can't message each other (but native Teams API agents can — see Workflow 7)
• File conflicts — If two agents edit the same file, manual resolution needed
• No shared context — Each agent starts fresh with only WORKTREE_TASK.md
• Sequential dependency — If Agent 2 needs Agent 1's output, Agent 2 must wait

Native Agent Teams Constraints

Known constraints of Claude Code's native agent teams:

What This Skill Is NOT

• Not a CI/CD pipeline — Use GitHub Actions for automated testing
• Not a subagent framework — Subagents (Claude's built-in Task tool) run within one session. This skill coordinates SEPARATE sessions.
• Not auto-scaling — You manually decide team size and assignments

Troubleshooting

Agent not reading WORKTREE_TASK.md

Cause: Agent started without --dangerously-skip-permissions or task file not in worktree root. Fix: Ensure worktree-manager writes the task file to the worktree root directory.

Merge conflicts between agents

Cause: Agents edited overlapping files despite file boundary instructions. Fix:

1. Check if boundaries were clear in WORKTREE_TASK.md
2. Resolve conflicts manually on main
3. Next time, use stricter file boundaries

Agent runs out of context

Cause: Agent's task was too broad, causing it to read too many files. Fix: Break the task into smaller pieces. Each agent should touch <10 files.

Memory pressure / system slowdown

Cause: Too many agents for available RAM. Fix:

1. Reduce to 2 agents
2. Close non-essential applications
3. Check memory_pressure before spawning

Agent completes but work is wrong

Cause: Insufficient verification steps in WORKTREE_TASK.md. Fix: Add explicit verification commands:

## Verification
1. Run: npm test -- --filter auth
2. Run: npx tsc --noEmit
3. Manually test: curl localhost:8100/api/auth/login

Reference Files

Load these on demand when you need deeper guidance:

Emit Outcome Sidecar

As the final step, write to ~/.claude/skill-analytics/last-outcome-agent-teams.json:

{"ts":"[UTC ISO8601]","skill":"agent-teams","version":"1.2.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"agents_spawned":[n],"tasks_delegated":[n],"merges_completed":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

Use status "partial" if some stages failed but results were produced. Use "error" only if no output was generated.