multi-agent-coordination

name	multi-agent-coordination
description	Coordinate multiple agents in parallel or sequential workflows. Use when running agents simultaneously, delegating to sub-agents, switching between specialized agents, or managing agent selection. Trigger keywords - "parallel agents", "sequential workflow", "delegate", "multi-agent", "sub-agent", "agent switching", "task decomposition".
version	0.1.0
tags	["orchestration","multi-agent","parallel","sequential","delegation","coordination"]
keywords	["parallel","sequential","delegate","sub-agent","agent-switching","multi-agent","task-decomposition","coordination"]

Multi-Agent Coordination

Version: 1.0.0 Purpose: Patterns for coordinating multiple agents in complex workflows Status: Production Ready

Overview

Multi-agent coordination is the foundation of sophisticated Claude Code workflows. This skill provides battle-tested patterns for orchestrating multiple specialized agents to accomplish complex tasks that are beyond the capabilities of a single agent.

The key challenge in multi-agent systems is dependencies. Some tasks must execute sequentially (one agent's output feeds into another), while others can run in parallel (independent validations from different perspectives). Getting this right is the difference between a 5-minute workflow and a 15-minute one.

This skill teaches you:

• When to run agents in parallel vs sequential
• How to select the right agent for each task
• How to delegate to sub-agents without polluting context
• How to manage context windows across multiple agent calls

Core Patterns

Pattern 1: Sequential vs Parallel Execution

When to Use Sequential:

Use sequential execution when there are dependencies between agents:

• Agent B needs Agent A's output as input
• Workflow phases must complete in order (plan → implement → test → review)
• Each agent modifies shared state (same files)

Example: Multi-Phase Implementation

Phase 1: Architecture Planning
  Task: api-architect
    Output: ai-docs/architecture-plan.md
    Wait for completion ✓

Phase 2: Implementation (depends on Phase 1)
  Task: backend-developer
    Input: Read ai-docs/architecture-plan.md
    Output: src/auth.ts, src/routes.ts
    Wait for completion ✓

Phase 3: Testing (depends on Phase 2)
  Task: test-architect
    Input: Read src/auth.ts, src/routes.ts
    Output: tests/auth.test.ts

When to Use Parallel:

Use parallel execution when agents are independent:

• Multiple validation perspectives (designer + tester + reviewer)
• Multiple AI models reviewing same code (Grok + Gemini + Claude)
• Multiple feature implementations in separate files

Example: Multi-Perspective Validation

Single Message with Multiple Task Calls:

Task: designer
  Prompt: Validate UI against Figma design
  Output: ai-docs/design-review.md
---
Task: ui-manual-tester
  Prompt: Test UI in browser for usability
  Output: ai-docs/testing-report.md
---
Task: senior-code-reviewer
  Prompt: Review code quality and patterns
  Output: ai-docs/code-review.md

All three execute simultaneously (3x speedup!)
Wait for all to complete, then consolidate results.

The 4-Message Pattern for True Parallel Execution:

This is CRITICAL for achieving true parallelism:

Message 1: Preparation (Bash Only)
  - Create workspace directories
  - Validate inputs
  - Write context files
  - NO Task calls, NO TodoWrite

Message 2: Parallel Execution (Task Only)
  - Launch ALL agents in SINGLE message
  - ONLY Task tool calls
  - Each Task is independent
  - All execute simultaneously

Message 3: Consolidation (Task Only)
  - Launch consolidation agent
  - Automatically triggered when N agents complete

Message 4: Present Results
  - Show user final consolidated results
  - Include links to detailed reports

Anti-Pattern: Mixing Tool Types Breaks Parallelism

❌ WRONG - Executes Sequentially:
  await TodoWrite({...});  // Tool 1
  await Task({...});       // Tool 2 - waits for TodoWrite
  await Bash({...});       // Tool 3 - waits for Task
  await Task({...});       // Tool 4 - waits for Bash

✅ CORRECT - Executes in Parallel:
  await Task({...});  // Task 1
  await Task({...});  // Task 2
  await Task({...});  // Task 3
  // All execute simultaneously

Why Mixing Fails:

Claude Code sees different tool types and assumes there are dependencies between them, forcing sequential execution. Using a single tool type (all Task calls) signals that operations are independent and can run in parallel.

---

Pattern 2: Agent Selection by Task Type

Task Detection Logic:

Intelligent workflows automatically detect task type and select appropriate agents:

Task Type Detection:

IF request mentions "API", "endpoint", "backend", "database":
  → API-focused workflow
  → Use: api-architect, backend-developer, test-architect
  → Skip: designer, ui-developer (not relevant)

ELSE IF request mentions "UI", "component", "design", "Figma":
  → UI-focused workflow
  → Use: designer, ui-developer, ui-manual-tester
  → Optional: ui-developer-codex (external validation)

ELSE IF request mentions both API and UI:
  → Mixed workflow
  → Use all relevant agents from both categories
  → Coordinate between backend and frontend agents

ELSE IF request mentions "test", "coverage", "bug":
  → Testing-focused workflow
  → Use: test-architect, ui-manual-tester
  → Optional: codebase-detective (for bug investigation)

ELSE IF request mentions "review", "validate", "feedback":
  → Review-focused workflow
  → Use: senior-code-reviewer, designer, ui-developer
  → Optional: external model reviewers

Agent Capability Matrix:

Task Type	Primary Agent	Secondary Agent	Optional External
API Implementation	backend-developer	api-architect	-
UI Implementation	ui-developer	designer	ui-developer-codex
Testing	test-architect	ui-manual-tester	-
Code Review	senior-code-reviewer	-	codex-code-reviewer
Architecture Planning	api-architect OR frontend-architect	-	plan-reviewer
Bug Investigation	codebase-detective	test-architect	-
Design Validation	designer	ui-developer	designer-codex

Agent Switching Pattern:

Some workflows benefit from adaptive agent selection based on context:

Example: UI Development with External Validation

Base Implementation:
  Task: ui-developer
    Prompt: Implement navbar component from design

User requests external validation:
  → Switch to ui-developer-codex OR add parallel ui-developer-codex
  → Run both: embedded ui-developer + external ui-developer-codex
  → Consolidate feedback from both

Scenario 1: User wants speed
  → Use ONLY ui-developer (embedded, fast)

Scenario 2: User wants highest quality
  → Use BOTH ui-developer AND ui-developer-codex (parallel)
  → Consensus analysis on feedback

Scenario 3: User is out of credits
  → Fallback to ui-developer only
  → Notify user external validation unavailable

---

Pattern 3: Sub-Agent Delegation

File-Based Instructions (Context Isolation):

When delegating to sub-agents, use file-based instructions to avoid context pollution:

✅ CORRECT - File-Based Delegation:

Step 1: Write instructions to file
  Write: ai-docs/architecture-instructions.md
    Content: "Design authentication system with JWT tokens..."

Step 2: Delegate to agent with file reference
  Task: api-architect
    Prompt: "Read instructions from ai-docs/architecture-instructions.md
             and create architecture plan."

Step 3: Agent reads file, does work, writes output
  Agent reads: ai-docs/architecture-instructions.md
  Agent writes: ai-docs/architecture-plan.md

Step 4: Agent returns brief summary ONLY
  Return: "Architecture plan complete. See ai-docs/architecture-plan.md"

Step 5: Orchestrator reads output file if needed
  Read: ai-docs/architecture-plan.md
  (Only if orchestrator needs to process the output)

Why File-Based?

• Avoids context pollution: Long user requirements don't bloat orchestrator context
• Reusable: Multiple agents can read same instruction file
• Debuggable: Files persist after workflow completes
• Clean separation: Input file, output file, orchestrator stays lightweight

Anti-Pattern: Inline Delegation

❌ WRONG - Context Pollution:

Task: api-architect
  Prompt: "Design authentication system with:
    - JWT tokens with refresh token rotation
    - Email/password login with bcrypt hashing
    - OAuth2 integration with Google, GitHub
    - Rate limiting on login endpoint (5 attempts per 15 min)
    - Password reset flow with time-limited tokens
    - Email verification on signup
    - Role-based access control (admin, user, guest)
    - Session management with Redis
    - Security headers (CORS, CSP, HSTS)
    - ... (500 more lines of requirements)"

Problem: Orchestrator's context now contains 500+ lines of requirements
         that are only relevant to the architect agent.

Brief Summary Returns:

Sub-agents should return 2-5 sentence summaries, not full output:

✅ CORRECT - Brief Summary:
  "Architecture plan complete. Designed 3-layer authentication:
   JWT with refresh tokens, OAuth2 integration (Google/GitHub),
   and Redis session management. See ai-docs/architecture-plan.md
   for detailed component breakdown."

❌ WRONG - Full Output:
  "Architecture plan:
   [500 lines of detailed architecture documentation]
   Components: AuthController, TokenService, OAuthService...
   [another 500 lines]"

Proxy Mode Invocation:

For external AI models (Claudish), use the PROXY_MODE directive:

Task: codex-code-reviewer PROXY_MODE: x-ai/grok-code-fast-1
  Prompt: "Review authentication implementation for security issues.
           Code context in ai-docs/code-review-context.md"

Agent Behavior:
  1. Detects PROXY_MODE directive
  2. Extracts model: x-ai/grok-code-fast-1
  3. Extracts task: "Review authentication implementation..."
  4. Executes: claudish --model x-ai/grok-code-fast-1 --stdin <<< "..."
  5. Waits for full response (blocking execution)
  6. Writes: ai-docs/grok-review.md (full detailed review)
  7. Returns: "Grok review complete. Found 3 CRITICAL issues. See ai-docs/grok-review.md"

Key: Blocking Execution

External models MUST execute synchronously (blocking) so the agent waits for the full response:

✅ CORRECT - Blocking:
  RESULT=$(claudish --model x-ai/grok-code-fast-1 --stdin <<< "$PROMPT")
  echo "$RESULT" > ai-docs/grok-review.md
  echo "Review complete - see ai-docs/grok-review.md"

❌ WRONG - Background (returns before completion):
  claudish --model x-ai/grok-code-fast-1 --stdin <<< "$PROMPT" &
  echo "Review started..."  # Agent returns immediately, review not done!

---

Pattern 4: Context Window Management

When to Delegate:

Delegate to sub-agents when:

• Task is self-contained (clear input → output)
• Output is large (architecture plan, test suite, review report)
• Task requires specialized expertise (designer, tester, reviewer)
• Multiple independent tasks can run in parallel

When to Execute in Main Context:

Execute in main orchestrator when:

• Task is small (simple file edit, command execution)
• Output is brief (yes/no decision, status check)
• Task depends on orchestrator state (current phase, iteration count)
• Context pollution risk is low

Context Size Estimation:

Note: Token estimates below are approximations based on typical usage. Actual context consumption varies by skill complexity, Claude model version, and conversation history. Use these as guidelines, not exact measurements.

Estimate context usage to decide delegation strategy:

Context Budget: ~200k tokens (Claude Sonnet 4.5 - actual varies by model)

Current context usage breakdown:
  - System prompt: 10k tokens
  - Skill content (5 skills): 10k tokens
  - Command instructions: 5k tokens
  - User request: 1k tokens
  - Conversation history: 20k tokens
  ───────────────────────────────────
  Total used: 46k tokens
  Remaining: 154k tokens

Safe threshold for delegation: If task will consume >30k tokens, delegate

Example: Architecture planning for large system
  - Requirements: 5k tokens
  - Expected output: 20k tokens
  - Total: 25k tokens
  ───────────────────────────────────
  Decision: Delegate (keeps orchestrator lightweight)

Delegation Strategy by Context Size:

Task Output Size	Strategy
< 1k tokens	Execute in orchestrator
1k - 10k tokens	Delegate with summary return
10k - 30k tokens	Delegate with file-based output
> 30k tokens	Multi-agent decomposition

Example: Multi-Agent Decomposition

User Request: "Implement complete e-commerce system"

This is >100k tokens if done by single agent. Decompose:

Phase 1: Break into sub-systems
  - Product catalog
  - Shopping cart
  - Checkout flow
  - User authentication
  - Order management
  - Payment integration

Phase 2: Delegate each sub-system to separate agent
  Task: backend-developer
    Instruction file: ai-docs/product-catalog-requirements.md
    Output file: ai-docs/product-catalog-implementation.md

  Task: backend-developer
    Instruction file: ai-docs/shopping-cart-requirements.md
    Output file: ai-docs/shopping-cart-implementation.md

  ... (6 parallel agent invocations)

Phase 3: Integration agent
  Task: backend-developer
    Instruction: "Integrate 6 sub-systems. Read output files:
                  ai-docs/*-implementation.md"
    Output: ai-docs/integration-plan.md

Total context per agent: ~20k tokens (manageable)
vs. Single agent: 120k+ tokens (context overflow risk)

---

Integration with Other Skills

multi-agent-coordination + multi-model-validation:

Use Case: Code review with multiple AI models

Step 1: Agent Selection (multi-agent-coordination)
  - Detect task type: Code review
  - Select agents: senior-code-reviewer (embedded) + external models

Step 2: Parallel Execution (multi-model-validation)
  - Follow 4-Message Pattern
  - Launch all reviewers simultaneously
  - Wait for all to complete

Step 3: Consolidation (multi-model-validation)
  - Auto-consolidate reviews
  - Apply consensus analysis

multi-agent-coordination + quality-gates:

Use Case: Iterative UI validation

Step 1: Agent Selection (multi-agent-coordination)
  - Detect task type: UI validation
  - Select agents: designer, ui-developer

Step 2: Iteration Loop (quality-gates)
  - Run designer validation
  - If not PASS: delegate to ui-developer for fixes
  - Loop until PASS or max iterations

Step 3: User Validation Gate (quality-gates)
  - MANDATORY user approval
  - Collect feedback if issues found

multi-agent-coordination + todowrite-orchestration:

Use Case: Multi-phase implementation workflow

Step 1: Initialize TodoWrite (todowrite-orchestration)
  - Create task list for all phases

Step 2: Sequential Agent Delegation (multi-agent-coordination)
  - Phase 1: api-architect
  - Phase 2: backend-developer (depends on Phase 1)
  - Phase 3: test-architect (depends on Phase 2)
  - Update TodoWrite after each phase

---

Best Practices

Do:

• ✅ Use parallel execution for independent tasks (3-5x speedup)
• ✅ Use sequential execution when there are dependencies
• ✅ Use file-based instructions to avoid context pollution
• ✅ Return brief summaries (2-5 sentences) from sub-agents
• ✅ Select agents based on task type (API/UI/Testing/Review)
• ✅ Decompose large tasks into multiple sub-agent calls
• ✅ Estimate context usage before delegating

Don't:

• ❌ Mix tool types in parallel execution (breaks parallelism)
• ❌ Inline long instructions in Task prompts (context pollution)
• ❌ Return full output from sub-agents (use files instead)
• ❌ Use parallel execution for dependent tasks (wrong results)
• ❌ Use single agent for >100k token tasks (context overflow)
• ❌ Forget to wait for all parallel tasks before consolidating

Performance Tips:

• Parallel execution: 3-5x faster than sequential (5min vs 15min)
• File-based delegation: Saves 50-80% context usage
• Agent switching: Adapt to user preferences (speed vs quality)
• Context decomposition: Enables tasks that would otherwise overflow

---

Examples

Example 1: Parallel Multi-Model Code Review

Scenario: User requests "Review my authentication code with Grok and Gemini"

Agent Selection:

• Task type: Code review
• Agents: senior-code-reviewer (embedded), external Grok, external Gemini

Execution:

Message 1: Preparation
  - Write code context to ai-docs/code-review-context.md

Message 2: Parallel Execution (3 Task calls in single message)
  Task: senior-code-reviewer
    Prompt: "Review ai-docs/code-review-context.md for security issues"
  ---
  Task: codex-code-reviewer PROXY_MODE: x-ai/grok-code-fast-1
    Prompt: "Review ai-docs/code-review-context.md for security issues"
  ---
  Task: codex-code-reviewer PROXY_MODE: google/gemini-2.5-flash
    Prompt: "Review ai-docs/code-review-context.md for security issues"

  All 3 execute simultaneously (3x faster than sequential)

Message 3: Auto-Consolidation
  Task: senior-code-reviewer
    Prompt: "Consolidate 3 reviews from:
             - ai-docs/claude-review.md
             - ai-docs/grok-review.md
             - ai-docs/gemini-review.md
             Prioritize by consensus."

Message 4: Present Results
  "Review complete. 3 models analyzed your code.
   Top 5 issues by consensus:
   1. [UNANIMOUS] Missing input validation on login endpoint
   2. [STRONG] SQL injection risk in user query
   3. [MAJORITY] Weak password requirements
   See ai-docs/consolidated-review.md for details."

Result: 5 minutes total (vs 15+ if sequential), consensus-based prioritization

---

Example 2: Sequential Multi-Phase Implementation

Scenario: User requests "Implement payment integration feature"

Agent Selection:

• Task type: API implementation
• Agents: api-architect → backend-developer → test-architect → senior-code-reviewer

Execution:

Phase 1: Architecture Planning
  Write: ai-docs/payment-requirements.md
    "Integrate Stripe payment processing with webhook support..."

  Task: api-architect
    Prompt: "Read ai-docs/payment-requirements.md
             Create architecture plan"
    Output: ai-docs/payment-architecture.md
    Return: "Architecture plan complete. Designed 3-layer payment system."

  Wait for completion ✓

Phase 2: Implementation (depends on Phase 1)
  Task: backend-developer
    Prompt: "Read ai-docs/payment-architecture.md
             Implement payment integration"
    Output: src/payment.ts, src/webhooks.ts
    Return: "Payment integration implemented. 2 new files, 500 lines."

  Wait for completion ✓

Phase 3: Testing (depends on Phase 2)
  Task: test-architect
    Prompt: "Write tests for src/payment.ts and src/webhooks.ts"
    Output: tests/payment.test.ts, tests/webhooks.test.ts
    Return: "Test suite complete. 20 tests covering payment flows."

  Wait for completion ✓

Phase 4: Code Review (depends on Phase 3)
  Task: senior-code-reviewer
    Prompt: "Review payment integration implementation"
    Output: ai-docs/payment-review.md
    Return: "Review complete. 2 MEDIUM issues found."

  Wait for completion ✓

Result: Sequential execution ensures each phase has correct inputs

---

Example 3: Adaptive Agent Switching

Scenario: User requests "Validate navbar implementation" with optional external AI

Agent Selection:

• Task type: UI validation
• Base agent: designer
• Optional: designer-codex (if user wants external validation)

Execution:

Step 1: Ask user preference
  "Do you want external AI validation? (Yes/No)"

Step 2a: If user says NO (speed mode)
  Task: designer
    Prompt: "Validate navbar against Figma design"
    Output: ai-docs/design-review.md
    Return: "Design validation complete. PASS with 2 minor suggestions."

Step 2b: If user says YES (quality mode)
  Message 1: Parallel Validation
    Task: designer
      Prompt: "Validate navbar against Figma design"
    ---
    Task: designer PROXY_MODE: design-review-codex
      Prompt: "Validate navbar against Figma design"

  Message 2: Consolidate
    Task: designer
      Prompt: "Consolidate 2 design reviews. Prioritize by consensus."
      Output: ai-docs/design-review-consolidated.md
      Return: "Consolidated review complete. Both agree on 1 CRITICAL issue."

Step 3: User validation
  Present consolidated review to user for approval

Result: Adaptive workflow based on user preference (speed vs quality)

---

Troubleshooting

Problem: Parallel tasks executing sequentially

Cause: Mixed tool types in same message

Solution: Use 4-Message Pattern with ONLY Task calls in Message 2

❌ Wrong:
  await TodoWrite({...});
  await Task({...});
  await Task({...});

✅ Correct:
  Message 1: await Bash({...});  (prep only)
  Message 2: await Task({...}); await Task({...}); (parallel)

---

Problem: Orchestrator context overflowing

Cause: Inline instructions or full output returns

Solution: Use file-based delegation + brief summaries

❌ Wrong:
  Task: agent
    Prompt: "[1000 lines of inline requirements]"
  Return: "[500 lines of full output]"

✅ Correct:
  Write: ai-docs/requirements.md
  Task: agent
    Prompt: "Read ai-docs/requirements.md"
  Return: "Complete. See ai-docs/output.md"

---

Problem: Wrong agent selected for task

Cause: Task type detection failed

Solution: Explicitly detect task type using keywords

Check user request for keywords:
  - API/endpoint/backend → api-architect, backend-developer
  - UI/component/design → designer, ui-developer
  - test/coverage → test-architect
  - review/validate → senior-code-reviewer

Default: Ask user to clarify task type

---

Problem: Agent returns immediately before external model completes

Cause: Background execution (non-blocking claudish call)

Solution: Use synchronous (blocking) execution

❌ Wrong:
  claudish --model grok ... &  (background, returns immediately)

✅ Correct:
  RESULT=$(claudish --model grok ...)  (blocks until complete)

---

Summary

Multi-agent coordination is about choosing the right execution strategy:

• Parallel when tasks are independent (3-5x speedup)
• Sequential when tasks have dependencies (correct results)
• File-based delegation to avoid context pollution (50-80% savings)
• Brief summaries from sub-agents (clean orchestrator context)
• Task type detection for intelligent agent selection
• Context decomposition for large tasks (avoid overflow)

Master these patterns and you can orchestrate workflows of any complexity.

---

Extracted From:

• /implement command (task detection, sequential workflows)
• /validate-ui command (adaptive agent switching)
• /review command (parallel execution, 4-Message Pattern)
• CLAUDE.md Parallel Multi-Model Execution Protocol