Skills
skills/scientiacapital/skills/agent-teams

agent-teams

SKILL.md

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.

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

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:

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

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

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

<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

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

</display_modes>

<team_hooks>

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
})

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

<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

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:

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
Weekly Installs
18
Repository
scientiacapital/skills
GitHub Stars
5
First Seen
Feb 9, 2026
Security Audits
Gen Agent Trust HubFail
SocketWarn
SnykWarn
Installed on
opencode18
gemini-cli18
github-copilot18
amp18
codex18
kimi-cli18