---
name: "multi-agent-orchestration"
description: >-
  Use when coordinating multiple specialized agents for complex distributed tasks. Keywords: multi-agent, orchestrator, subagent, handoff, swarm, supervisor, agent topology, coordination.
---

# Multi-Agent Orchestration

## Overview
This skill provides a framework for designing and managing multi-agent systems where specialized agents collaborate on complex, multi-stage workflows. It emphasizes clear agent boundaries, structured communication, and robust error isolation.

## When To Use
- When tasks are too large or diverse for a single agent (scope creep).
- When specific domain expertise (e.g., database design, UI/UX, security) is required in separate, modular contexts.
- To maintain clean separation of concerns and reduce context window degradation.
- When you need to delegate parallelizable work to maximize throughput.

## Topology Patterns
- **Hierarchical Supervisor**: A central supervisor agent delegates sub-tasks to specialized workers, aggregates their results, and provides final synthesis.
- **Swarm Handoffs**: Agents pass tasks directly to the next appropriate agent based on completion criteria, forming a chain or graph of expertise.
- **Router-Worker**: A router analyzes incoming requests and dispatches them to a specific pool of workers based on classification.
- **Blackboard**: Multiple agents read from and write to a shared persistent state (the "blackboard") until a task objective is satisfied.
- **Round-Robin Debate**: Agents with opposing viewpoints propose solutions, iterate, and refine based on peer criticism to improve quality.

## Communication Protocols
- **Agent-to-Agent (A2A)**: Always use structured message framing.
- **Structured Payloads**: Encapsulate tasks, constraints, and dependencies in a common JSON format or structured Markdown.
- **Return Summaries**: Every subagent MUST return a concise summary of work done, resources created, and final status (SUCCESS/FAIL/BLOCKED) before closing the conversation.

## Context Isolation & Boundary Hand-offs
- **Ephemeral Context**: Spawn subagents with only the minimal, high-signal information needed for their specific task.
- **Avoid Token Bloat**: Do not pass the entire parent conversation history unless strictly necessary. Pass pointers to file locations or artifact links instead.
- **Clean State**: Each subagent should operate within its own branched workspace to prevent side effects on the parent or other subagents.

## Failure Isolation
- **Localized Faults**: Subagent crashes must be caught by the parent via message timeout or error reporting mechanisms.
- **Graceful Retries**: Implement retry logic for discrete sub-tasks. If a worker fails, the supervisor should attempt to diagnose the root cause (using Root Cause Tracing) before retrying or pivoting strategy.
- **Never Crash Parent**: A subagent failure should trigger an alert in the parent agent, not an unhandled exception that propagates to the user.

## Task Decomposition Strategies
- **Parallel Execution**: Use when tasks are independent (e.g., unit tests for different modules, gathering info from multiple docs).
- **Sequential Execution**: Use when tasks have strict causal dependencies (e.g., design -> implement -> review -> deploy).
- **Merge Points**: Define clear synchronization points where context from different agents is consolidated, validated, and refined by the supervisor.

## State Sharing Patterns
- **Shared Artifacts**: Write common results to files in the shared artifacts/ directory.
- **Blackboard Memory**: Use shared databases or documented state files for common configurations or global project context.
- **Message Bus**: Use the parent agent as the hub for all inter-agent messages.

## Anti-patterns
- **God Orchestrator**: A single agent attempting to do everything; leads to poor specialization and context degradation.
- **Circular Dependencies**: Agents waiting on each other indefinitely; always define a clear directed acyclic graph (DAG) of task flow.
- **Context Explosion**: Passing the entire project state to every subagent; use selective scoping instead.
- **Silent Failures**: Subagents finishing without reporting status; every interaction must have an explicit "done" or "blocked" signal.

## Quality Gates
- **Pre-Handoff Check**: Does the subagent have everything it needs? (Requirements, constraints, deadline).
- **Post-Handoff Review**: Does the output meet the original task intent? Does it need further refinement before the next step?
- **Final Integration**: Verify the combined results of all subagents against original user acceptance criteria.

## References
- KILO-KIT Core Principles (skills/kilo-kit/SKILL.md)
- Systematic Debugging (skills/systematic-debugging/SKILL.md)
- Architecture Decision Making (skills/architecture/SKILL.md)