multi-agent-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 Agent: dev:architect Output: ai-docs/architecture-plan.md Wait for completion ✓ Phase 2: Implementation (depends on Phase 1) Agent: dev: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) Agent: dev:qa-engineer 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 — several reviewers, ONE target** ``` Single Message with Multiple Task Calls: Agent( subagent_type: "dev:reviewer", run_in_background: false, description: "Code review", prompt: "TARGET: BRANCH FOCUS: code OUTPUT: ai-docs/reviews/code.md MODELS: none" ) --- Agent( subagent_type: "dev:reviewer", run_in_background: false, description: "Security review", prompt: "TARGET: BRANCH FOCUS: security OUTPUT: ai-docs/reviews/security.md MODELS: none" ) --- Agent( subagent_type: "dev:reviewer", run_in_background: false, description: "Plugin-quality review", prompt: "TARGET: BRANCH FOCUS: plugin OUTPUT: ai-docs/reviews/plugin.md MODELS: none" ) All three execute simultaneously (3x speedup!) Wait for all to complete, then hand the three output paths to `dev:aggregator` on REVIEWS: with `dev:reviewer`'s scale on THRESHOLDS: — the three lines under 'Apply verdict thresholds' in that agent's file, read at dispatch time, never recalled — and the consolidated file on OUTPUT:. It consolidates; none of the three reviewers sees another's output. Without THRESHOLDS: it ends the report `VERDICT: none`. ``` Review consolidation takes reviews of ONE target that share a location, a severity scale and a verdict vocabulary — here three `dev:reviewer` dispatches over the same `TARGET:`, differing only in `FOCUS:`. Heterogeneous specialist reports — a Figma design review, a browser usability test and a code review — share none of those; present them side by side through a coordination summary, never feed them to review consolidation. **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 Agent calls, NO Tasks Message 2: Parallel Execution (Task Only) - Launch ALL agents in SINGLE message - ONLY Agent tool calls - Each Task is independent - All execute simultaneously Message 3: Consolidation (Task Only) - Launch `dev:aggregator` with every output path on REVIEWS:, the scale of the reviewer that wrote them on THRESHOLDS: (for `dev:reviewer`, the three lines under 'Apply verdict thresholds' in its agent file, read at dispatch time, never recalled) and the consolidated file on OUTPUT: - It is given the reviews, never the code; no reviewer consolidates - Automatically triggered when the agents complete — at N = 1 too, where it passes the single review through with a `VERDICT:` line 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 TaskCreate({...}); // Tool 1 await Agent({...}); // Tool 2 - waits for Tasks await Bash({...}); // Tool 3 - waits for Task await Agent({...}); // Tool 4 - waits for Bash ✅ CORRECT - Executes in Parallel: await Agent({...}); // Task 1 await Agent({...}); // Task 2 await Agent({...}); // 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 Agent 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, qa-engineer → 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: qa-engineer, ui-manual-tester → Optional: analyze (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 | qa-engineer | ui-manual-tester | - | | Code Review | senior-code-reviewer | - | codex-code-reviewer | | Architecture Planning | api-architect OR frontend-architect | - | plan-reviewer | | Bug Investigation | analyze | qa-engineer | - | | 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: Agent: dev:frontend-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 Agent: dev: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: Agent: dev: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]" ``` **External Model Invocation:** For external AI models, the orchestrating command (/team, /delegate) handles invocation via claudish MCP tools. Sub-agents do NOT invoke claudish directly. ``` /team command: 1. Uses `team` MCP tool with model list and vote prompt 2. team tool runs all external models in parallel internally 3. Results returned as structured per-model responses 4. Sub-agents only handle internal Claude work via Agent tool /delegate command: 1. Uses `create_session` MCP tool with model and prompt 2. Channel events notify on progress (tool_executing, input_required, completed) 3. `get_output(session_id)` retrieves the result ``` **Key:** External model execution is handled by the MCP server, not by sub-agents. Sub-agents receive their work context through Task prompts and write results to files. --- ### 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 Agent: dev:developer Instruction file: ai-docs/product-catalog-requirements.md Output file: ai-docs/product-catalog-implementation.md Agent: dev: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 Agent: dev: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 + task-orchestration:** ``` Use Case: Multi-phase implementation workflow Step 1: Initialize Tasks (task-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: qa-engineer (depends on Phase 2) - TaskUpdate 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:**