Team Orchestration

NO TEAM WITHOUT A COLLABORATION REQUIREMENT

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"];
}

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true

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

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

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

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

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

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";
}

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

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

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