agent-teams

<objective> Coordinate teams of 2-3 Claude Code agents working in parallel on the same codebase. Each agent runs in its own terminal, its own git worktree, and its own context window. The team lead (you, the orchestrating Claude) decomposes work, spawns agents with focused prompts, monitors progress, and coordinates merges.

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. </objective>

<quick_start> Set the environment variable (one-time):

bash

export AGENT_TEAMS_MAX=3  # M1/8GB safe default

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:

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

<success_criteria> A team session is successful when:

Each agent completes its assigned task in its worktree
No merge conflicts between agent branches (or conflicts are trivially resolvable)
Each agent's context stays focused (no bloat, no re-reading unrelated code)
All agent work passes the project's test suite after merge
Total wall-clock time is less than sequential execution would take </success_criteria>

<setup>

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:

bash

# 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}'

<current_state> Active agents: !

pgrep -f "claude.*--model" 2>/dev/null | wc -l | tr -d ' '

Claude processes running

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

</current_state>

Hardware Constraints (M1/8GB)

Resource	Budget	Per Agent	System Reserved
RAM	8 GB	~1.5 GB	2 GB
CPU cores	8	Shared	—
Max agents	3	—	—

Rule of thumb: If

memory_pressure

reports "WARN" or higher, reduce to 2 agents.

</setup>

<when_to_use>

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.

</when_to_use>

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

File	Purpose	Written By	Read By
`WORKTREE_TASK.md`	Agent's assignment + context	Team lead	Agent
`CONTRACT.md`	Shared API/interface definitions	Team lead	All agents
`.agent-status`	Agent self-reports progress	Agent	Team lead
`.claude/CLAUDE.md`	Project conventions, dev commands	Project	Agent (auto-loaded)
`.claude/settings.json`	Hooks (auto-format), permissions	Project	Agent (auto-loaded)
`.claude/agents/*.md`	Custom subagent definitions	Project	Agent (on dispatch)
Git commits	Work product	Agent	Team lead at merge

</architecture>

<display_modes>

Display Modes

Mode	Terminal	How
`in-process`	Any terminal	All teammates in main terminal. `Shift+Down` to cycle, `Ctrl+T` for task list.
`split-pane`	tmux or iTerm2 only	Each teammate gets own pane. Click pane to interact.

Config:

"teammateMode": "auto"

~/.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.

</display_modes>

<team_hooks>

Team Hooks

TeammateIdle Hook

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

settings.json

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:

json

{
  "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:

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

javascript

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

</team_hooks>

Workflows

Workflow	Purpose
1. Spawn a Team	Decompose → JSON roadmap → worktrees → task files → launch → monitor
2. Write WORKTREE_TASK.md	Context, assignment, file boundaries, contract, verification, completion protocol
3. Monitor Progress	`git log` per branch + `.agent-status` checks
4. Merge Agent Work	Merge in planned order, test after each, `--no-ff`
5. Async Handoff	`@claude` bot on GitHub PRs for long-running tasks
6. Plan Mode	Explore codebase read-only before committing to decomposition
7. Native Teams API	`TeamCreate` + `TaskCreate` + `SendMessage` for in-session teams without worktrees
8. Plan Approval	Teammates with `mode: "plan"` submit plans for lead approval before implementing

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.

</workflows>

<use_cases>

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.

</use_cases>

<best_practices>

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:

Limitation	Details
No session resumption	`/resume` does not restore in-process teammates. Only the lead agent resumes.
No nested teams	Teammates cannot spawn sub-teams. Only one level of team hierarchy.
One team per session	Clean up current team (TeamDelete) before starting a new one.
Lead is fixed	Cannot promote teammates or transfer leadership mid-session.
Permissions at spawn	Teammate permissions set at spawn time. Can adjust per-teammate after creation, not during spawn.
Shutdown can be slow	Teammates finish their current request before shutting down. Plan for graceful wind-down.

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

</limitations> <troubleshooting>

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:

Check if boundaries were clear in WORKTREE_TASK.md
Resolve conflicts manually on main
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:

Reduce to 2 agents
Close non-essential applications
Check
```
memory_pressure
```
before spawning

Agent completes but work is wrong

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

markdown

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

</troubleshooting> <routing>

Reference Files

Load these on demand when you need deeper guidance:

Reference	Load When
`reference/workflows-detailed.md`	Step-by-step spawn, monitor, merge, async handoff, Native Teams API
`reference/best-practices-full.md`	Context engineering, session harness, contract-first, hooks config
`reference/context-engineering.md`	Designing agent prompts, optimizing context usage, delegation patterns
`reference/worktree-integration.md`	Coordinating with worktree-manager, port allocation, terminal strategies
`reference/prompt-templates.md`	Need ready-to-use spawn prompts for the 4 team patterns

</routing>

agent-teams

NPX Install

Tags

SKILL.md Content

Prerequisites

Hardware Constraints (M1/8GB)

When to Use Agent Teams

Architecture

Context Isolation

Coordination Through Files

Display Modes

Split Pane Setup

Team Hooks

TeammateIdle Hook

TaskCompleted Hook

Plan Approval Flow

Workflows

Team Patterns

Feature Parallel

Frontend / Backend

Test / Implement (TDD Pair)

Review / Refactor

Best Practices

Limitations

M1/8GB Constraints

Coordination Limits

Native Agent Teams Constraints

What This Skill Is NOT

Troubleshooting

Agent not reading WORKTREE_TASK.md

Merge conflicts between agents

Agent runs out of context

Memory pressure / system slowdown

Agent completes but work is wrong

Reference Files