lennetech/coordinating-agent-teams

Coordinating Agent Teams

Claude Code Agent Teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) coordinate multiple independent Claude Code sessions with inter-agent messaging and a shared task list. Unlike subagents (Agent tool), teammates communicate directly and challenge each other.

Gotchas

• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 must be set BEFORE session start — Setting it mid-session has no effect. The flag is read once at startup. Team-capable commands silently fall back to single-agent mode if the env var is missing. Verify with echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS before running /debug, /review, or any team command.
• Token cost is 3-5× single-agent — not 2× — Each teammate runs a full Claude Code session with its own context, memory, and transcript. A 4-teammate debug session easily consumes 5× the tokens of a single-agent run. Budget accordingly and prefer --no-team for simple tasks.
• No session resumption for teams — claude --resume cannot restore a multi-teammate session. If a team run is interrupted (crash, network, user exit), the teammates' transcripts are lost. Treat every team run as one-shot and save important findings to disk before stopping.
• Agent tool does NOT work inside a subagent or teammate — Nested spawning is blocked. Teammates can message each other, but they cannot spawn their own subagents. Structure workflows as flat teams, not hierarchies.
• Worktree isolation is per-teammate, not shared — Each teammate with isolation: worktree gets its own worktree. Shared state must go through the messaging channel or through files written to the parent repo after merge. Teammates cannot see each other's unmerged worktree files.
• pkill in one teammate can kill processes of another — If pkill -f "nuxt dev" runs in one teammate, it kills ALL nuxt dev processes on the machine, including ones owned by other teammates. Use PID-tracked kills (save PID at start, kill by PID at end) in team contexts.

Auto-Detection Protocol

Every team-capable command follows this decision tree:

1. Is CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 set?
   No → Single Agent Mode (existing behavior)
2. Did user pass --no-team?
   Yes → Single Agent Mode (forced)
3. Did user pass --team?
   Yes → Team Mode (forced)
4. Does complexity heuristic match?
   Yes → Team Mode (auto-detected)
   No  → Single Agent Mode (overhead not justified)

Complexity Heuristics by Command

| Command | Team Trigger | |---------|-------------| | /review | >100 changed lines AND >3 files, OR changes in both projects/api/ and projects/app/ | | /create-story (TDD) | Fullstack monorepo detected AND story involves backend + frontend | | /rebase-mrs | >2 branches selected | | /debug | Always team (the workflow requires it) |

When Teams Beat Single Agents

| Task Type | Team Advantage | Token Overhead | |-----------|---------------|----------------| | Multi-dimension review | Independent analysis prevents anchoring bias | ~3x | | Fullstack test writing | Parallel backend + frontend, contract sharing | ~2x | | Adversarial debugging | Competing hypotheses with falsification | ~3-5x | | Batch rebase | True parallelism via worktrees | ~1.5x per branch |

When Single Agents Are Better

• Small changes (<100 lines, <=3 files)
• Sequential dependencies (step B needs output of step A)
• Trivial tasks (obvious fix, single-file change)
• Non-fullstack changes (only backend OR only frontend)

Core Patterns

Each pattern is described in detail in patterns.md. Summary:

1. Independent Then Challenge (Review) - Teammates review independently, then cross-challenge findings
2. Parallel With Handoff (TDD) - Backend defines contracts, frontend consumes them, implementation stays sequential
3. Adversarial Convergence (Debug) - One hypothesis per teammate, active falsification of competing theories
4. Parallel Worktree Execution (Batch Rebase) - One git worktree per teammate, true parallel branch operations

Communication

• message (1:1): Direct communication between specific teammates. Use for contract sharing, targeted challenges
• broadcast (1:all): Message to all teammates. Use sparingly - only for coordination signals (e.g., "Phase 1 complete, starting Phase 2")

Token Cost Guidance

Agent Teams cost approximately 3-5x a single agent run. This is justified when:

• The task benefits from independent perspectives (review, debugging)
• True parallelism saves wall-clock time (batch rebase, parallel tests)
• The quality improvement outweighs the cost (adversarial debugging finds bugs single agents miss)

Not justified when:

• A single agent can complete the task in <5 minutes
• The task is straightforward with one obvious approach
• Token budget is constrained

Parallel Subagent Isolation

When spawning multiple file-modifying subagents concurrently via the Agent tool (not Agent Teams), use isolation: "worktree" to prevent file conflicts:

Agent tool call:
  subagent_type: "lt-dev:backend-dev"
  isolation: "worktree"         ← each gets its own working copy
  prompt: "Implement feature X in projects/api/..."

Agent tool call:
  subagent_type: "lt-dev:frontend-dev"
  isolation: "worktree"
  prompt: "Implement feature X in projects/app/..."

When to use isolation: "worktree"

| Scenario | Isolation needed? | |----------|-------------------| | Multiple file-modifying agents in parallel | Yes | | Single agent (sequential) | No | | Read-only agents (reviewers) in parallel | No | | Agent modifying lockfiles/dependencies | No — needs in-place access |

Agent compatibility

| Supports worktree | No worktree (in-place only) | |-------------------|-----------------------------| | backend-dev, frontend-dev, devops, branch-rebaser | fullstack-updater, nest-server-updater, npm-package-maintainer, all reviewers |

Worktree Operations Reference

See worktree-guide.md for setup, cleanup, naming conventions, performance settings (worktree.sparsePaths, worktree.symlinkDirectories), dependency isolation, and known limitations.

Limitations

• Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable
• No session resumption: If the lead crashes, the team cannot be resumed
• No nested teams: A teammate cannot spawn its own team
• Shared filesystem: Teammates share the same filesystem (use worktrees for parallel git operations)

Related Skills & Commands

| Element | Relationship | |---------|-------------| | /lt-dev:debug | Always uses team (Adversarial Convergence pattern) | | /lt-dev:review | Auto-detects team for large/fullstack changes | | /lt-dev:create-story | Auto-detects team for fullstack TDD | | /lt-dev:git:rebase-mrs | Auto-detects team for batch operations |

Note: /lt-dev:debug REQUIRES Agent Teams (no single-agent fallback). All other commands auto-detect based on complexity heuristics and fall back to single-agent mode gracefully.