Team Orchestration

Team Orchestration

Overview

Agent Teams enable multiple Claude Code sessions to collaborate on a shared project with direct peer-to-peer messaging and shared task lists. Unlike subagents, teammates can communicate with each other, claim tasks dynamically, and coordinate on shared problems.

Core principle: Deploy teams when tasks benefit from collaboration, not merely parallelism. If teammates will never need to message each other, use parallel subagents instead.

No exceptions. No workarounds. No shortcuts.

The Prime Directive

NO TEAM WITHOUT A COLLABORATION REQUIREMENT

If teammates will never exchange messages, you do not need a team.

When to Use

digraph when_teams {
    "Multiple tasks?" [shape=diamond];
    "Need peer-to-peer collaboration?" [shape=diamond];
    "Tasks independent?" [shape=diamond];
    "Agent Teams" [shape=box style=filled fillcolor=lightgreen];
    "parallel-execution" [shape=box];
    "delegated-execution" [shape=box];
    "Single agent" [shape=box];

    "Multiple tasks?" -> "Need peer-to-peer collaboration?" [label="yes"];
    "Multiple tasks?" -> "Single agent" [label="no"];
    "Need peer-to-peer collaboration?" -> "Agent Teams" [label="yes - teammates must share discoveries"];
    "Need peer-to-peer collaboration?" -> "Tasks independent?" [label="no"];
    "Tasks independent?" -> "parallel-execution" [label="yes - fire and forget"];
    "Tasks independent?" -> "delegated-execution" [label="no - sequential"];
}

Deploy Teams when:

• Parallel research where discoveries from one investigation redirect another
• Multi-module features where frontend/backend/tests must coordinate
• Cross-layer changes requiring interface negotiation
• Debugging with competing hypotheses that need to share evidence
• Large refactoring across multiple subsystems with shared conventions

Do not use when:

• Simple independent tasks (use godmode:parallel-execution)
• Sequential dependent tasks (use godmode:delegated-execution)
• Single-file or single-module changes
• Agent Teams feature not enabled
• Fewer than 2 genuinely collaborative tasks

Prerequisites

Agent Teams is an experimental feature. It must be enabled:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true

Without this, TeamCreate, TaskCreate, and SendMessage tools are unavailable.

Deferred tools: TeamCreate, TaskCreate, TaskUpdate, TaskGet, TaskList, SendMessage, and EnterWorktree are deferred tools. They must be loaded via ToolSearch before first use:

// Load all team tools at once
ToolSearch: { "query": "select:SendMessage,TaskCreate,TaskUpdate,TaskList,TaskGet,EnterWorktree" }

The Entry Protocol

BEFORE forming a team:

1. ENUMERATE: What are all the tasks?
2. MAP: Which tasks need information from other tasks?
3. COUNT: How many task pairs require shared discoveries?
4. DECIDE:
   - 0 pairs need collaboration -> Use parallel-execution
   - 1 pair needs collaboration -> Consider single agent or subagents
   - 2+ pairs need collaboration -> Use Agent Teams
5. ONLY THEN: Form the team

Skip any step = unnecessary team overhead

The Workflow

Step 1: Evaluate Task-Team Fit

Before reaching for TeamCreate, answer these:

Step 2: Architect the Team

Create the team, then spawn teammates using the Agent tool:

// 1. Create the team
TeamCreate: {
  "team_name": "auth-refactor-team",
  "description": "Refactor authentication across API and frontend modules"
}

// 2. Spawn each teammate (2-5 max)
Agent: {
  "name": "backend-eng",
  "team_name": "auth-refactor-team",
  "prompt": "You are the backend engineer. Own all files in src/api/auth/. Implement the new token refresh flow. Coordinate with frontend-eng on the session interface.",
  "description": "Backend auth implementation",
  "mode": "bypassPermissions"
}

Agent: {
  "name": "frontend-eng",
  "team_name": "auth-refactor-team",
  "prompt": "You are the frontend engineer. Own all files in src/ui/auth/. Update login flow to use new token refresh. Coordinate with backend-eng on the session interface.",
  "description": "Frontend auth implementation",
  "mode": "bypassPermissions"
}

Teammate count guidance:

Step 2b: Isolate Workspaces

Each teammate should work in an isolated git worktree to prevent merge conflicts at the filesystem level:

// Called by each teammate at the start of their work
EnterWorktree: { "name": "auth-backend" }

EnterWorktree creates a separate git worktree so teammates edit files in parallel without stepping on each other. The team lead runs godmode:merge-protocol to integrate worktrees at the end.

Step 3: Define Tasks with Clear Boundaries

// Create tasks with clear scope and success criteria
TaskCreate: {
  "subject": "Implement token refresh endpoint",
  "description": "Build POST /api/auth/refresh that validates expired access tokens against refresh tokens. Return new access+refresh token pair. Files: src/api/auth/refresh.ts, src/api/auth/refresh.test.ts",
  "activeForm": "Implementing token refresh endpoint"
}

TaskCreate: {
  "subject": "Update login UI for token refresh",
  "description": "Update login flow to store refresh token and auto-refresh on 401. Files: src/ui/auth/login.tsx, src/ui/auth/session.ts",
  "activeForm": "Updating login UI for token refresh"
}

// Set up dependencies and assign owners
TaskUpdate: { "taskId": "2", "addBlockedBy": ["1"] }
TaskUpdate: { "taskId": "1", "owner": "backend-eng" }
TaskUpdate: { "taskId": "2", "owner": "frontend-eng" }

Task design rules:

• Clear scope: exactly which files/modules this teammate owns
• Dependencies: use addBlockedBy for tasks that must complete first
• Success criteria: what "done" looks like in the description
• File ownership: NO overlap between teammates (prevents merge conflicts)

File ownership is non-negotiable. Two teammates editing the same file guarantees merge conflicts. If a shared file needs changes from multiple perspectives, assign it to ONE teammate who coordinates with others via messaging.

Step 4: Coordinate as Team Lead

digraph team_lead_loop {
    "Check TaskList" [shape=box];
    "All tasks completed?" [shape=diamond];
    "Any teammate blocked?" [shape=diamond];
    "Send clarifying message" [shape=box];
    "Resolve dependency" [shape=box];
    "Integrate results" [shape=box style=filled fillcolor=lightgreen];

    "Check TaskList" -> "All tasks completed?";
    "All tasks completed?" -> "Integrate results" [label="yes"];
    "All tasks completed?" -> "Any teammate blocked?" [label="no"];
    "Any teammate blocked?" -> "Send clarifying message" [label="needs info"];
    "Any teammate blocked?" -> "Resolve dependency" [label="blocked by task"];
    "Any teammate blocked?" -> "Check TaskList" [label="no - working"];
    "Send clarifying message" -> "Check TaskList";
    "Resolve dependency" -> "Check TaskList";
}

As team lead:

• Track task completion via TaskList (no parameters needed — just call it)
• Relay discoveries between teammates using direct messages:

// Direct message to relay a discovery
SendMessage: {
  "type": "message",
  "recipient": "frontend-eng",
  "content": "backend-eng finished the refresh endpoint. The response shape is { accessToken, refreshToken, expiresIn }. You can unblock now.",
  "summary": "Refresh endpoint contract ready"
}

• Unblock dependencies by marking prerequisite tasks complete:

TaskUpdate: { "taskId": "1", "status": "completed" }

• Arbitrate conflicts if teammates disagree on approach
• Use broadcast ONLY for team-wide critical issues (expensive — sends N messages):

// Broadcast — use sparingly, sends N separate messages
SendMessage: {
  "type": "broadcast",
  "content": "Convention change: all auth endpoints now return camelCase keys",
  "summary": "Auth API convention change"
}

Step 5: Integrate Results

When all tasks complete:

1. Review all changes together for consistency
2. Confirm no file conflicts between teammates
3. Run full test suite
4. Verify that cross-module interfaces agree
5. REQUIRED SUB-PROTOCOL: Use godmode:merge-protocol

Team Patterns

See team-patterns.md in this directory for five documented team patterns:

1. Exploration Team — Parallel investigation of different dimensions
2. Feature Team — Multi-module development (frontend + backend + tests)
3. Diagnosis Team — Competing hypotheses tested concurrently
4. Inspection Team — Multi-perspective code review
5. Migration Team — Cross-cutting convention changes across codebase

Each pattern includes: when to use, team structure, task design, coordination flow, and example.

Tools at a Glance

Teammate Behavior: What to Expect

Teammates are independent Claude sessions. Key behaviors:

• Idle between turns — This is normal. Teammates go idle when waiting for messages or tasks. They reactivate when messaged or when tasks become available.
• Claim tasks — Teammates use TaskUpdate to assign themselves before starting work.
• Message each other — Teammates can and should message each other directly, not just the team lead.
• Self-directed — Once given a task, teammates work autonomously. Avoid micromanagement.

Cognitive Traps

Guardrails

Prohibited:

• Forming teams for simple tasks (overhead not justified)
• Allowing teammates to edit the same files (merge conflicts)
• Skipping integration review after team completion
• Ignoring teammate messages (they contain discoveries)
• Forming teams with more than 5 teammates (coordination explodes)
• Using broadcast for routine updates (use direct messages)
• Starting a team without clearly designed tasks
• Leaving dependencies undefined between tasks

Mandatory:

• Define clear file ownership boundaries
• Set up task dependencies with blockedBy
• Review all changes together after completion
• Run full test suite after integration
• Use SendMessage for teammate-to-teammate coordination
• Mark tasks complete when done (teammates check TaskList for available work)

Tool Invocation Reference

Complete parameter specifications for every Agent Teams tool. Copy these directly — parameter names are exact.

TeamCreate

Creates a named team. Call once before spawning teammates.

{
  "team_name": "feature-billing-team",
  "description": "Build subscription billing feature"
}

Agent (spawn teammate)

Spawns a teammate into an existing team. Each teammate is an independent Claude session.

{
  "name": "backend-eng",
  "team_name": "feature-billing-team",
  "prompt": "You are the backend engineer on this team. Own src/api/billing/. Build the Stripe webhook handler and subscription CRUD endpoints. Use godmode:test-first for implementation. Coordinate with frontend-eng on API contracts via SendMessage.",
  "description": "Backend billing implementation",
  "mode": "bypassPermissions"
}

EnterWorktree

Creates an isolated git worktree for a teammate. Prevents filesystem conflicts when multiple teammates edit files in parallel.

{
  "name": "billing-feature"
}

TaskCreate

Adds a task to the shared task list visible to all teammates.

{
  "subject": "Implement Stripe webhook handler",
  "description": "Build POST /webhooks/stripe endpoint that handles subscription.created, subscription.updated, and subscription.deleted events. Files: src/api/billing/webhooks.ts, src/api/billing/webhooks.test.ts",
  "activeForm": "Implementing Stripe webhook handler"
}

TaskUpdate

Updates a task's status, owner, or dependencies. Use for claiming, completing, and wiring up blocked-by relationships.

// Assign owner
{ "taskId": "1", "owner": "backend-eng" }

// Set dependency — task 3 cannot start until tasks 1 and 2 complete
{ "taskId": "3", "addBlockedBy": ["1", "2"] }

// Mark in progress
{ "taskId": "1", "status": "in_progress" }

// Mark complete
{ "taskId": "1", "status": "completed" }

TaskList

Returns all tasks with their status, owner, and blocked-by info. No parameters.

// No parameters — just call it
TaskList: {}

TaskGet

Retrieves full details of a specific task.

{ "taskId": "1" }

SendMessage

Three message types for team communication.

Direct message (default — use this for most communication):

{
  "type": "message",
  "recipient": "backend-eng",
  "content": "The profile API needs a PUT /profile/preferences endpoint. Frontend needs to update preferences without replacing the full profile.",
  "summary": "API contract update request"
}

Broadcast (sends to ALL teammates — use sparingly):

{
  "type": "broadcast",
  "content": "Convention change: all API responses now use camelCase keys",
  "summary": "API convention change"
}

Shutdown request (graceful teammate shutdown):

{
  "type": "shutdown_request",
  "recipient": "backend-eng",
  "content": "All tasks complete, wrapping up"
}

Complete Team Setup Example

End-to-end example wiring up a 2-person feature team:

// 1. Create team
TeamCreate: { "team_name": "billing-team", "description": "Build subscription billing" }

// 2. Create tasks
TaskCreate: {
  "subject": "Build Stripe webhook handler",
  "description": "POST /webhooks/stripe handling subscription events. Files: src/api/billing/webhooks.ts",
  "activeForm": "Building Stripe webhook handler"
}
TaskCreate: {
  "subject": "Build billing dashboard UI",
  "description": "Subscription management page showing plan, usage, invoices. Files: src/ui/billing/",
  "activeForm": "Building billing dashboard"
}

// 3. Wire dependencies and assign owners
TaskUpdate: { "taskId": "2", "addBlockedBy": ["1"] }
TaskUpdate: { "taskId": "1", "owner": "backend-eng" }
TaskUpdate: { "taskId": "2", "owner": "frontend-eng" }

// 4. Spawn teammates (they auto-claim their assigned tasks)
Agent: {
  "name": "backend-eng",
  "team_name": "billing-team",
  "prompt": "You are the backend engineer. Own src/api/billing/. Start with task #1. Use EnterWorktree to isolate your workspace. Use godmode:test-first. Message frontend-eng with the API contract when done.",
  "description": "Backend billing implementation",
  "mode": "bypassPermissions"
}
Agent: {
  "name": "frontend-eng",
  "team_name": "billing-team",
  "prompt": "You are the frontend engineer. Own src/ui/billing/. Task #2 is blocked by #1. Wait for backend-eng to share the API contract, then implement. Use EnterWorktree to isolate your workspace.",
  "description": "Frontend billing implementation",
  "mode": "bypassPermissions"
}

// 5. Monitor as team lead
TaskList: {}

// 6. When all tasks complete, shutdown teammates
SendMessage: { "type": "shutdown_request", "recipient": "backend-eng", "content": "All done, wrapping up" }
SendMessage: { "type": "shutdown_request", "recipient": "frontend-eng", "content": "All done, wrapping up" }

Integration

Related orchestration protocols:

• godmode:parallel-execution — For independent tasks without collaboration requirement
• godmode:delegated-execution — For sequential tasks with review checkpoints
• godmode:task-runner — For plan execution in a separate session

Teammates should use:

• godmode:test-first — For implementation tasks
• godmode:fault-diagnosis — For diagnosis team investigations
• godmode:completion-gate — Before marking tasks complete

Required for completion:

• godmode:merge-protocol — After all team tasks complete