Master multi-agent orchestration using Claude Code's TeammateTool and Task system. Use when coordinating multiple agents, running parallel code reviews, creating pipeline workflows with dependencies, building self-organizing task queues, or any task benefiting from divide-and-conquer patterns.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Master multi-agent orchestration using Claude Code's TeammateTool and Task system. Use when coordinating multiple agents, running parallel code reviews, creating pipeline workflows with dependencies, building self-organizing task queues, or any task benefiting from divide-and-conquer patterns.
Claude Code Swarm Orchestration
Master multi-agent orchestration using Claude Code's TeammateTool and Task system.
Primitives
Primitive
What It Is
File Location
Agent
A Claude instance that can use tools. You are an agent. Subagents are agents you spawn.
N/A (process)
Team
A named group of agents working together. One leader, multiple teammates.
~/.claude/teams/{name}/config.json
Teammate
An agent that joined a team. Has a name, color, inbox. Spawned via Task with team_name + name.
Listed in team config
Leader
The agent that created the team. Receives teammate messages, approves plans/shutdowns.
First member in config
Task
A work item with subject, description, status, owner, and dependencies.
~/.claude/tasks/{team}/N.json
Inbox
JSON file where an agent receives messages from teammates.
~/.claude/teams/{name}/inboxes/{agent}.json
Message
A JSON object sent between agents. Can be text or structured (shutdown_request, idle_notification, etc).
Stored in inbox files
Backend
How teammates run. Auto-detected: in-process (same Node.js, invisible), tmux (separate panes, visible), iterm2 (split panes in iTerm2). See Spawn Backends.
flowchart LR
A[1. Create Team] --> B[2. Create Tasks]
B --> C[3. Spawn Teammates]
C --> D[4. Work]
D --> E[5. Coordinate]
E --> F[6. Shutdown]
F --> G[7. Cleanup]
Message Flow
sequenceDiagram
participant L as Leader
participant T1 as Teammate 1
participant T2 as Teammate 2
participant Tasks as Task List
L->>Tasks: TaskCreate (3 tasks)
L->>T1: spawn with prompt
L->>T2: spawn with prompt
T1->>Tasks: claim task #1
T2->>Tasks: claim task #2
T1->>Tasks: complete #1
T1->>L: send findings (inbox)
Note over Tasks: #3 auto-unblocks
T2->>Tasks: complete #2
T2->>L: send findings (inbox)
L->>T1: requestShutdown
T1->>L: approveShutdown
L->>T2: requestShutdown
T2->>L: approveShutdown
L->>L: cleanup
{"name":"my-project","description":"Working on feature X","leadAgentId":"team-lead@my-project","createdAt":1706000000000,"members":[{"agentId":"team-lead@my-project","name":"team-lead","agentType":"team-lead","color":"#4A90D9","joinedAt":1706000000000,"backendType":"in-process"},{"agentId":"worker-1@my-project","name":"worker-1","agentType":"Explore","model":"haiku","prompt":"Analyze the codebase structure...","color":"#D94A4A","planModeRequired":false,"joinedAt":1706000001000,"tmuxPaneId":"in-process","cwd":"/Users/me/project","backendType":"in-process"}]}
Two Ways to Spawn Agents
Method 1: Task Tool (Subagents)
Use Task for short-lived, focused work that returns a result:
Task({
subagent_type: "Explore",
description: "Find auth files",
prompt: "Find all authentication-related files in this codebase",
model: "haiku"// Optional: haiku, sonnet, opus
})
Characteristics:
Runs synchronously (blocks until complete) or async with run_in_background: true
Returns result directly to you
No team membership required
Best for: searches, analysis, focused research
Method 2: Task Tool + team_name + name (Teammates)
Use Task with team_name and name to spawn persistent teammates:
// First create a teamTeammate({ operation: "spawnTeam", team_name: "my-project" })
// Then spawn a teammate into that teamTask({
team_name: "my-project", // Required: which team to joinname: "security-reviewer", // Required: teammate's namesubagent_type: "security-sentinel",
prompt: "Review all authentication code for vulnerabilities. Send findings to team-lead via Teammate write.",
run_in_background: true// Teammates usually run in background
})
Characteristics:
Joins team, appears in config.json
Communicates via inbox messages
Can claim tasks from shared task list
Persists until shutdown
Best for: parallel work, ongoing collaboration, pipeline stages
Key Difference
Aspect
Task (subagent)
Task + team_name + name (teammate)
Lifespan
Until task complete
Until shutdown requested
Communication
Return value
Inbox messages
Task access
None
Shared task list
Team membership
No
Yes
Coordination
One-off
Ongoing
Built-in Agent Types
These are always available without plugins:
Bash
Task({
subagent_type: "Bash",
description: "Run git commands",
prompt: "Check git status and show recent commits"
})
Tools: Bash only
Model: Inherits from parent
Best for: Git operations, command execution, system tasks
Explore
Task({
subagent_type: "Explore",
description: "Find API endpoints",
prompt: "Find all API endpoints in this codebase. Be very thorough.",
model: "haiku"// Fast and cheap
})
Tools: All read-only tools (no Edit, Write, NotebookEdit, Task)
Model: Haiku (optimized for speed)
Best for: Codebase exploration, file searches, code understanding
Task({
subagent_type: "Plan",
description: "Design auth system",
prompt: "Create an implementation plan for adding OAuth2 authentication"
})
Tools: All read-only tools
Model: Inherits from parent
Best for: Architecture planning, implementation strategies
general-purpose
Task({
subagent_type: "general-purpose",
description: "Research and implement",
prompt: "Research React Query best practices and implement caching for the user API"
})
Tools: All tools (*)
Model: Inherits from parent
Best for: Multi-step tasks, research + action combinations
claude-code-guide
Task({
subagent_type: "claude-code-guide",
description: "Help with Claude Code",
prompt: "How do I configure MCP servers?"
})
Tools: Read-only + WebFetch + WebSearch
Best for: Questions about Claude Code, Agent SDK, Anthropic API
statusline-setup
Task({
subagent_type: "statusline-setup",
description: "Configure status line",
prompt: "Set up a status line showing git branch and node version"
})
Tools: Read, Edit only
Model: Sonnet
Best for: Configuring Claude Code status line
Plugin Agent Types
From the compound-engineering plugin (examples):
Review Agents
// Security reviewTask({
subagent_type: "compound-engineering:review:security-sentinel",
description: "Security audit",
prompt: "Audit this PR for security vulnerabilities"
})
// Performance reviewTask({
subagent_type: "compound-engineering:review:performance-oracle",
description: "Performance check",
prompt: "Analyze this code for performance bottlenecks"
})
// Rails code reviewTask({
subagent_type: "compound-engineering:review:kieran-rails-reviewer",
description: "Rails review",
prompt: "Review this Rails code for best practices"
})
// Architecture reviewTask({
subagent_type: "compound-engineering:review:architecture-strategist",
description: "Architecture review",
prompt: "Review the system architecture of the authentication module"
})
// Code simplicityTask({
subagent_type: "compound-engineering:review:code-simplicity-reviewer",
description: "Simplicity check",
prompt: "Check if this implementation can be simplified"
})
All review agents from compound-engineering:
agent-native-reviewer - Ensures features work for agents too
kieran-typescript-reviewer - TypeScript best practices
pattern-recognition-specialist - Design patterns and anti-patterns
performance-oracle - Performance analysis
security-sentinel - Security vulnerabilities
Research Agents
// Best practices researchTask({
subagent_type: "compound-engineering:research:best-practices-researcher",
description: "Research auth best practices",
prompt: "Research current best practices for JWT authentication in Rails 2024-2026"
})
// Framework documentationTask({
subagent_type: "compound-engineering:research:framework-docs-researcher",
description: "Research Active Storage",
prompt: "Gather comprehensive documentation about Active Storage file uploads"
})
// Git history analysisTask({
subagent_type: "compound-engineering:research:git-history-analyzer",
description: "Analyze auth history",
prompt: "Analyze the git history of the authentication module to understand its evolution"
})
All research agents:
best-practices-researcher - External best practices
12. rejectPlan - Reject Plan with Feedback (Leader Only)
Teammate({
operation: "rejectPlan",
target_agent_id: "architect",
request_id: "plan-456",
feedback: "Please add error handling for the API calls and consider rate limiting"
})
13. cleanup - Remove Team Resources
Teammate({ operation: "cleanup" })
Removes:
~/.claude/teams/{team-name}/ directory
~/.claude/tasks/{team-name}/ directory
IMPORTANT: Will fail if teammates are still active. Use requestShutdown first.
Task System Integration
TaskCreate - Create Work Items
TaskCreate({
subject: "Review authentication module",
description: "Review all files in app/services/auth/ for security vulnerabilities",
activeForm: "Reviewing auth module..."// Shown in spinner when in_progress
})
Returns full task with description, status, blockedBy, etc.
TaskUpdate - Update Task Status
// Claim a taskTaskUpdate({ taskId: "2", owner: "security-reviewer" })
// Start workingTaskUpdate({ taskId: "2", status: "in_progress" })
// Mark completeTaskUpdate({ taskId: "2", status: "completed" })
// Set up dependenciesTaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })
Task Dependencies
When a blocking task is completed, blocked tasks are automatically unblocked:
// Create pipelineTaskCreate({ subject: "Step 1: Research" }) // #1TaskCreate({ subject: "Step 2: Implement" }) // #2TaskCreate({ subject: "Step 3: Test" }) // #3TaskCreate({ subject: "Step 4: Deploy" }) // #4// Set up dependenciesTaskUpdate({ taskId: "2", addBlockedBy: ["1"] }) // #2 waits for #1TaskUpdate({ taskId: "3", addBlockedBy: ["2"] }) // #3 waits for #2TaskUpdate({ taskId: "4", addBlockedBy: ["3"] }) // #4 waits for #3// When #1 completes, #2 auto-unblocks// When #2 completes, #3 auto-unblocks// etc.
Task File Structure
~/.claude/tasks/{team-name}/1.json:
{"id":"1","subject":"Review authentication module","description":"Review all files in app/services/auth/...","status":"in_progress","owner":"security-reviewer","activeForm":"Reviewing auth module...","blockedBy":[],"blocks":["3"],"createdAt":1706000000000,"updatedAt":1706000001000}
Message Formats
Regular Message
{"from":"team-lead","text":"Please prioritize the auth module","timestamp":"2026-01-25T23:38:32.588Z","read":false}
{"type":"join_request","proposedName":"helper","requestId":"join-abc123","capabilities":"Code review and testing","timestamp":"2026-01-25T23:42:00.000Z"}
// 1. Create teamTeammate({ operation: "spawnTeam", team_name: "code-review" })
// 2. Spawn specialists in parallel (single message, multiple Task calls)Task({
team_name: "code-review",
name: "security",
subagent_type: "compound-engineering:review:security-sentinel",
prompt: "Review the PR for security vulnerabilities. Focus on: SQL injection, XSS, auth bypass. Send findings to team-lead.",
run_in_background: true
})
Task({
team_name: "code-review",
name: "performance",
subagent_type: "compound-engineering:review:performance-oracle",
prompt: "Review the PR for performance issues. Focus on: N+1 queries, memory leaks, slow algorithms. Send findings to team-lead.",
run_in_background: true
})
Task({
team_name: "code-review",
name: "simplicity",
subagent_type: "compound-engineering:review:code-simplicity-reviewer",
prompt: "Review the PR for unnecessary complexity. Focus on: over-engineering, premature abstraction, YAGNI violations. Send findings to team-lead.",
run_in_background: true
})
// 3. Wait for results (check inbox)// cat ~/.claude/teams/code-review/inboxes/team-lead.json// 4. Synthesize findings and cleanupTeammate({ operation: "requestShutdown", target_agent_id: "security" })
Teammate({ operation: "requestShutdown", target_agent_id: "performance" })
Teammate({ operation: "requestShutdown", target_agent_id: "simplicity" })
// Wait for approvals...Teammate({ operation: "cleanup" })
Pattern 2: Pipeline (Sequential Dependencies)
Each stage depends on the previous:
// 1. Create team and task pipelineTeammate({ operation: "spawnTeam", team_name: "feature-pipeline" })
TaskCreate({ subject: "Research", description: "Research best practices for the feature", activeForm: "Researching..." })
TaskCreate({ subject: "Plan", description: "Create implementation plan based on research", activeForm: "Planning..." })
TaskCreate({ subject: "Implement", description: "Implement the feature according to plan", activeForm: "Implementing..." })
TaskCreate({ subject: "Test", description: "Write and run tests for the implementation", activeForm: "Testing..." })
TaskCreate({ subject: "Review", description: "Final code review before merge", activeForm: "Reviewing..." })
// Set up sequential dependenciesTaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })
TaskUpdate({ taskId: "5", addBlockedBy: ["4"] })
// 2. Spawn workers that claim and complete tasksTask({
team_name: "feature-pipeline",
name: "researcher",
subagent_type: "compound-engineering:research:best-practices-researcher",
prompt: "Claim task #1, research best practices, complete it, send findings to team-lead. Then check for more work.",
run_in_background: true
})
Task({
team_name: "feature-pipeline",
name: "implementer",
subagent_type: "general-purpose",
prompt: "Poll TaskList every 30 seconds. When task #3 unblocks, claim it and implement. Then complete and notify team-lead.",
run_in_background: true
})
// Tasks auto-unblock as dependencies complete
Pattern 3: Swarm (Self-Organizing)
Workers grab available tasks from a pool:
// 1. Create team and task poolTeammate({ operation: "spawnTeam", team_name: "file-review-swarm" })
// Create many independent tasks (no dependencies)for (const file of ["auth.rb", "user.rb", "api_controller.rb", "payment.rb"]) {
TaskCreate({
subject: `Review ${file}`,
description: `Review ${file} for security and code quality issues`,
activeForm: `Reviewing ${file}...`
})
}
// 2. Spawn worker swarmTask({
team_name: "file-review-swarm",
name: "worker-1",
subagent_type: "general-purpose",
prompt: `
You are a swarm worker. Your job:
1. Call TaskList to see available tasks
2. Find a task with status 'pending' and no owner
3. Claim it with TaskUpdate (set owner to your name)
4. Do the work
5. Mark it completed with TaskUpdate
6. Send findings to team-lead via Teammate write
7. Repeat until no tasks remain
`,
run_in_background: true
})
Task({
team_name: "file-review-swarm",
name: "worker-2",
subagent_type: "general-purpose",
prompt: `[Same prompt as worker-1]`,
run_in_background: true
})
Task({
team_name: "file-review-swarm",
name: "worker-3",
subagent_type: "general-purpose",
prompt: `[Same prompt as worker-1]`,
run_in_background: true
})
// Workers race to claim tasks, naturally load-balance
Pattern 4: Research + Implementation
Research first, then implement:
// 1. Research phase (synchronous, returns results)const research = awaitTask({
subagent_type: "compound-engineering:research:best-practices-researcher",
description: "Research caching patterns",
prompt: "Research best practices for implementing caching in Rails APIs. Include: cache invalidation strategies, Redis vs Memcached, cache key design."
})
// 2. Use research to guide implementationTask({
subagent_type: "general-purpose",
description: "Implement caching",
prompt: `
Implement API caching based on this research:
${research.content}
Focus on the user_controller.rb endpoints.
`
})
Pattern 5: Plan Approval Workflow
Require plan approval before implementation:
// 1. Create teamTeammate({ operation: "spawnTeam", team_name: "careful-work" })
// 2. Spawn architect with plan_mode_requiredTask({
team_name: "careful-work",
name: "architect",
subagent_type: "Plan",
prompt: "Design an implementation plan for adding OAuth2 authentication",
mode: "plan", // Requires plan approvalrun_in_background: true
})
// 3. Wait for plan approval request// You'll receive: {"type": "plan_approval_request", "from": "architect", "requestId": "plan-xxx", ...}// 4. Review and approve/rejectTeammate({
operation: "approvePlan",
target_agent_id: "architect",
request_id: "plan-xxx"
})
// ORTeammate({
operation: "rejectPlan",
target_agent_id: "architect",
request_id: "plan-xxx",
feedback: "Please add rate limiting considerations"
})
Pattern 6: Coordinated Multi-File Refactoring
// 1. Create team for coordinated refactoringTeammate({ operation: "spawnTeam", team_name: "refactor-auth" })
// 2. Create tasks with clear file boundariesTaskCreate({
subject: "Refactor User model",
description: "Extract authentication methods to AuthenticatableUser concern",
activeForm: "Refactoring User model..."
})
TaskCreate({
subject: "Refactor Session controller",
description: "Update to use new AuthenticatableUser concern",
activeForm: "Refactoring Sessions..."
})
TaskCreate({
subject: "Update specs",
description: "Update all authentication specs for new structure",
activeForm: "Updating specs..."
})
// Dependencies: specs depend on both refactors completingTaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })
// 3. Spawn workers for each taskTask({
team_name: "refactor-auth",
name: "model-worker",
subagent_type: "general-purpose",
prompt: "Claim task #1, refactor the User model, complete when done",
run_in_background: true
})
Task({
team_name: "refactor-auth",
name: "controller-worker",
subagent_type: "general-purpose",
prompt: "Claim task #2, refactor the Session controller, complete when done",
run_in_background: true
})
Task({
team_name: "refactor-auth",
name: "spec-worker",
subagent_type: "general-purpose",
prompt: "Wait for task #3 to unblock (when #1 and #2 complete), then update specs",
run_in_background: true
})
Task({
team_name: "my-project",
name: "worker",
subagent_type: "general-purpose",
prompt: "Your name is $CLAUDE_CODE_AGENT_NAME. Use it when sending messages to team-lead."
})
Spawn Backends
A backend determines how teammate Claude instances actually run. Claude Code supports three backends, and auto-detects the best one based on your environment.
Backend Comparison
Backend
How It Works
Visibility
Persistence
Speed
in-process
Same Node.js process as leader
Hidden (background)
Dies with leader
Fastest
tmux
Separate terminal in tmux session
Visible in tmux
Survives leader exit
Medium
iterm2
Split panes in iTerm2 window
Visible side-by-side
Dies with window
Medium
Auto-Detection Logic
Claude Code automatically selects a backend using this decision tree:
flowchart TD
A[Start] --> B{Running inside tmux?}
B -->|Yes| C[Use tmux backend]
B -->|No| D{Running in iTerm2?}
D -->|No| E{tmux available?}
E -->|Yes| F[Use tmux - external session]
E -->|No| G[Use in-process]
D -->|Yes| H{it2 CLI installed?}
H -->|Yes| I[Use iterm2 backend]
H -->|No| J{tmux available?}
J -->|Yes| K[Use tmux - prompt to install it2]
J -->|No| L[Error: Install tmux or it2]
Detection checks:
$TMUX environment variable → inside tmux
$TERM_PROGRAM === "iTerm.app" or $ITERM_SESSION_ID → in iTerm2
which tmux → tmux available
which it2 → it2 CLI installed
in-process (Default for non-tmux)
Teammates run as async tasks within the same Node.js process.
How it works:
No new process spawned
Teammates share the same Node.js event loop
Communication via in-memory queues (fast)
You don't see teammate output directly
When it's used:
Not running inside tmux session
Non-interactive mode (CI, scripts)
Explicitly set via CLAUDE_CODE_SPAWN_BACKEND=in-process
// in-process is automatic when not in tmuxTask({
team_name: "my-project",
name: "worker",
subagent_type: "general-purpose",
prompt: "...",
run_in_background: true
})
// Force in-process explicitly// export CLAUDE_CODE_SPAWN_BACKEND=in-process
tmux
Teammates run as separate Claude instances in tmux panes/windows.
Outside tmux (external session): Creates a new tmux session called claude-swarm
# Your terminal stays as-is# Workers run in separate tmux session# View workers:
tmux attach -t claude-swarm
Pros:
See teammate output in real-time
Teammates survive leader exit
Can attach/detach sessions
Works in CI/headless environments
Cons:
Slower startup (process spawn)
Requires tmux installed
More resource usage
# Start tmux session first
tmux new-session -s claude
# Or force tmux backendexport CLAUDE_CODE_SPAWN_BACKEND=tmux
Useful tmux commands:
# List all panes in current window
tmux list-panes
# Switch to pane by number
tmux select-pane -t 1
# Kill a specific pane
tmux kill-pane -t %5
# View swarm session (if external)
tmux attach -t claude-swarm
# Rebalance pane layout
tmux select-layout tiled
iterm2 (macOS only)
Teammates run as split panes within your iTerm2 window.
# See what backend was detectedcat ~/.claude/teams/{team}/config.json | jq '.members[].backendType'# Check if inside tmuxecho$TMUX# Check if in iTerm2echo$TERM_PROGRAM# Check tmux availabilitywhich tmux
# Check it2 availabilitywhich it2
Error Handling
Common Errors
Error
Cause
Solution
"Cannot cleanup with active members"
Teammates still running
requestShutdown all teammates first, wait for approval
"Already leading a team"
Team already exists
cleanup first, or use different team name
"Agent not found"
Wrong teammate name
Check config.json for actual names
"Team does not exist"
No team created
Call spawnTeam first
"team_name is required"
Missing team context
Provide team_name parameter
"Agent type not found"
Invalid subagent_type
Check available agents with proper prefix
Graceful Shutdown Sequence
Always follow this sequence:
// 1. Request shutdown for all teammatesTeammate({ operation: "requestShutdown", target_agent_id: "worker-1" })
Teammate({ operation: "requestShutdown", target_agent_id: "worker-2" })
// 2. Wait for shutdown approvals// Check for {"type": "shutdown_approved", ...} messages// 3. Verify no active members// Read ~/.claude/teams/{team}/config.json// 4. Only then cleanupTeammate({ operation: "cleanup" })
Handling Crashed Teammates
Teammates have a 5-minute heartbeat timeout. If a teammate crashes:
They'll be automatically marked as inactive after timeout
Their tasks remain in the task list
Another teammate can claim their tasks
Cleanup will work after timeout expires
Debugging
# Check team configcat ~/.claude/teams/{team}/config.json | jq '.members[] | {name, agentType, backendType}'# Check teammate inboxescat ~/.claude/teams/{team}/inboxes/{agent}.json | jq '.'# List all teamsls ~/.claude/teams/
# Check task statescat ~/.claude/tasks/{team}/*.json | jq '{id, subject, status, owner, blockedBy}'# Watch for new messagestail -f ~/.claude/teams/{team}/inboxes/team-lead.json
Complete Workflows
Workflow 1: Full Code Review with Parallel Specialists
// === STEP 1: Setup ===Teammate({ operation: "spawnTeam", team_name: "pr-review-123", description: "Reviewing PR #123" })
// === STEP 2: Spawn reviewers in parallel ===// (Send all these in a single message for parallel execution)Task({
team_name: "pr-review-123",
name: "security",
subagent_type: "compound-engineering:review:security-sentinel",
prompt: `Review PR #123 for security vulnerabilities.
Focus on:
- SQL injection
- XSS vulnerabilities
- Authentication/authorization bypass
- Sensitive data exposure
When done, send your findings to team-lead using:
Teammate({ operation: "write", target_agent_id: "team-lead", value: "Your findings here" })`,
run_in_background: true
})
Task({
team_name: "pr-review-123",
name: "perf",
subagent_type: "compound-engineering:review:performance-oracle",
prompt: `Review PR #123 for performance issues.
Focus on:
- N+1 queries
- Missing indexes
- Memory leaks
- Inefficient algorithms
Send findings to team-lead when done.`,
run_in_background: true
})
Task({
team_name: "pr-review-123",
name: "arch",
subagent_type: "compound-engineering:review:architecture-strategist",
prompt: `Review PR #123 for architectural concerns.
Focus on:
- Design pattern adherence
- SOLID principles
- Separation of concerns
- Testability
Send findings to team-lead when done.`,
run_in_background: true
})
// === STEP 3: Monitor and collect results ===// Poll inbox or wait for idle notifications// cat ~/.claude/teams/pr-review-123/inboxes/team-lead.json// === STEP 4: Synthesize findings ===// Combine all reviewer findings into a cohesive report// === STEP 5: Cleanup ===Teammate({ operation: "requestShutdown", target_agent_id: "security" })
Teammate({ operation: "requestShutdown", target_agent_id: "perf" })
Teammate({ operation: "requestShutdown", target_agent_id: "arch" })
// Wait for approvals...Teammate({ operation: "cleanup" })
Workflow 2: Research → Plan → Implement → Test Pipeline
// === SETUP ===Teammate({ operation: "spawnTeam", team_name: "feature-oauth" })
// === CREATE PIPELINE ===TaskCreate({ subject: "Research OAuth providers", description: "Research OAuth2 best practices and compare providers (Google, GitHub, Auth0)", activeForm: "Researching OAuth..." })
TaskCreate({ subject: "Create implementation plan", description: "Design OAuth implementation based on research findings", activeForm: "Planning..." })
TaskCreate({ subject: "Implement OAuth", description: "Implement OAuth2 authentication according to plan", activeForm: "Implementing OAuth..." })
TaskCreate({ subject: "Write tests", description: "Write comprehensive tests for OAuth implementation", activeForm: "Writing tests..." })
TaskCreate({ subject: "Final review", description: "Review complete implementation for security and quality", activeForm: "Final review..." })
// Set dependenciesTaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })
TaskUpdate({ taskId: "5", addBlockedBy: ["4"] })
// === SPAWN SPECIALIZED WORKERS ===Task({
team_name: "feature-oauth",
name: "researcher",
subagent_type: "compound-engineering:research:best-practices-researcher",
prompt: "Claim task #1. Research OAuth2 best practices, compare providers, document findings. Mark task complete and send summary to team-lead.",
run_in_background: true
})
Task({
team_name: "feature-oauth",
name: "planner",
subagent_type: "Plan",
prompt: "Wait for task #2 to unblock. Read research from task #1. Create detailed implementation plan. Mark complete and send plan to team-lead.",
run_in_background: true
})
Task({
team_name: "feature-oauth",
name: "implementer",
subagent_type: "general-purpose",
prompt: "Wait for task #3 to unblock. Read plan from task #2. Implement OAuth2 authentication. Mark complete when done.",
run_in_background: true
})
Task({
team_name: "feature-oauth",
name: "tester",
subagent_type: "general-purpose",
prompt: "Wait for task #4 to unblock. Write comprehensive tests for the OAuth implementation. Run tests. Mark complete with results.",
run_in_background: true
})
Task({
team_name: "feature-oauth",
name: "reviewer",
subagent_type: "compound-engineering:review:security-sentinel",
prompt: "Wait for task #5 to unblock. Review the complete OAuth implementation for security. Send final assessment to team-lead.",
run_in_background: true
})
// Pipeline auto-progresses as each stage completes
Workflow 3: Self-Organizing Code Review Swarm
// === SETUP ===Teammate({ operation: "spawnTeam", team_name: "codebase-review" })
// === CREATE TASK POOL (all independent, no dependencies) ===const filesToReview = [
"app/models/user.rb",
"app/models/payment.rb",
"app/controllers/api/v1/users_controller.rb",
"app/controllers/api/v1/payments_controller.rb",
"app/services/payment_processor.rb",
"app/services/notification_service.rb",
"lib/encryption_helper.rb"
]
for (const file of filesToReview) {
TaskCreate({
subject: `Review ${file}`,
description: `Review ${file} for security vulnerabilities, code quality, and performance issues`,
activeForm: `Reviewing ${file}...`
})
}
// === SPAWN WORKER SWARM ===const swarmPrompt = `
You are a swarm worker. Your job is to continuously process available tasks.
LOOP:
1. Call TaskList() to see available tasks
2. Find a task that is:
- status: 'pending'
- no owner
- not blocked
3. If found:
- Claim it: TaskUpdate({ taskId: "X", owner: "YOUR_NAME" })
- Start it: TaskUpdate({ taskId: "X", status: "in_progress" })
- Do the review work
- Complete it: TaskUpdate({ taskId: "X", status: "completed" })
- Send findings to team-lead via Teammate write
- Go back to step 1
4. If no tasks available:
- Send idle notification to team-lead
- Wait 30 seconds
- Try again (up to 3 times)
- If still no tasks, exit
Replace YOUR_NAME with your actual agent name from $CLAUDE_CODE_AGENT_NAME.
`// Spawn 3 workersTask({ team_name: "codebase-review", name: "worker-1", subagent_type: "general-purpose", prompt: swarmPrompt, run_in_background: true })
Task({ team_name: "codebase-review", name: "worker-2", subagent_type: "general-purpose", prompt: swarmPrompt, run_in_background: true })
Task({ team_name: "codebase-review", name: "worker-3", subagent_type: "general-purpose", prompt: swarmPrompt, run_in_background: true })
// Workers self-organize: race to claim tasks, naturally load-balance// Monitor progress with TaskList() or by reading inbox
Best Practices
1. Always Cleanup
Don't leave orphaned teams. Always call cleanup when done.
// Goodprompt: `
1. Review app/models/user.rb for N+1 queries
2. Check all ActiveRecord associations have proper includes
3. Document any issues found
4. Send findings to team-lead via Teammate write
`// Badprompt: "Review the code"
4. Use Task Dependencies
Let the system manage unblocking:
// Good: Auto-unblockingTaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
// Bad: Manual polling"Wait until task #1 is done, check every 30 seconds..."
