Orchestration

Orchestration

Overview

Coordinates skills, frameworks, and workflows across the project lifecycle. Combines pattern-based project classification with goal decomposition, hierarchical task planning, and multi-agent coordination.

Use this skill for project-level workflow decisions: which frameworks to activate, in what order, and how to validate progress between phases. For Claude Code-specific agent implementation details (agent configuration, batch sizing, prompt engineering), use the agent-patterns skill instead.

This skill does NOT replace project management tools. It provides the decision framework for sequencing capabilities and validating readiness at each transition point.

Quick Reference

Pattern Identification

Classify every project before selecting frameworks or skills.

Phase Gates

Do not advance without meeting gate criteria.

Scoring Function

Plans are evaluated using weighted utility:

Modifiers: recently used (within 3 steps) gets -30% penalty; novel capability gets +20% bonus.

Multi-Agent Orchestration Patterns

Key rules: max delegation depth of 3, use context distillation (not full codebase), log all agent interactions.

MCP Integration

MCP (Model Context Protocol) standardizes how agents connect to external tools, data sources, and prompt templates. The orchestrator discovers available MCP servers at startup and routes tool calls from subagents to the correct server.

Common Mistakes

Delegation

• Discover project pattern and classify scope: Use Explore agent to survey the codebase, dependencies, and requirements
• Execute multi-phase orchestration plan: Use Task agent to implement phase-specific deliverables with gate validation
• Design architecture and capability sequences: Use Plan agent to decompose goals and build scored HTN plans

References

• goal-decomposition.md -- HTN planning, goal analysis, capability matching, precondition validation, scoring, decision logging
• project-patterns.md -- Pattern A/B/C classification, phase sequences, skill coordination by phase, parallelization
• multi-agent-coordination.md -- Hierarchical, sequential, parallel orchestration patterns, delegation manifests, recursion limits
• mcp-orchestration.md -- MCP architecture, resources, tools, prompts, multi-server orchestration, bidirectional sampling
• context-distillation.md -- Symbol indexing, fact extraction, recursive context reduction, token management
• error-handling.md -- Objective drift, tool failure, context overflow, circuit breakers, recovery strategies, logging

Context Distillation

Passing the entire project context to every subagent is expensive and leads to "Lost in the Middle" syndrome where the agent ignores crucial information buried in a large context window.

The Problem

Distilled context produces better results because the agent focuses on exactly what matters.

Distillation Techniques

1. Symbol Indexing

Instead of passing file contents, pass a list of available functions, classes, and types. The subagent can then request specific file contents only when needed.

Available Symbols:
  - auth/validateSession(token: string): Promise<Session | null>
  - auth/createSession(userId: string): Promise<Session>
  - types/Session { id, userId, expiresAt, createdAt }
  - types/User { id, email, name, role }

The subagent sees the shape of the system without reading every file.

2. Fact Extraction

Use a context distiller to extract only the facts relevant to the sub-task:

3. Summary Chain-of-Thought

Before delegating, the parent should write a concise summary:

What we know:
  - Auth system uses JWT tokens stored in cookies
  - Session validation happens in middleware
  - The bug causes 401 errors after token refresh

What we need to find out:
  - Why the refreshed token is not being saved
  - Whether the cookie settings match between set and read

Recursive Context Reduction

As delegation depth increases, the context must become narrower:

Each level strips away information not relevant to that level's task. The executor only needs to know about the specific function call, not the entire system architecture.

Best Practices

Error Handling in Multi-Agent Systems

Common Failure Modes

Recovery Strategies

1. Reset and Re-prompt

If a subagent's output is nonsensical or fails validation, reset its context and re-issue the command with more specific constraints.

First attempt: "Implement the auth module"
Failed: Output was unrelated database code

Re-prompt: "Implement JWT authentication in src/lib/auth.ts.
  Must export: validateSession(token: string): Promise<Session | null>
  Must use: jsonwebtoken library
  Must read: existing Session type from src/types/auth.ts"

2. Circuit Breakers

If an agent fails a specific tool call repeatedly, trip the circuit breaker:

After the circuit breaker trips, the parent agent must either:

• Try an alternative capability
• Escalate to the user
• Mark the step as blocked and continue with remaining steps

3. Graceful Degradation

If a complex capability fails, fall back to simpler alternatives:

Primary:   AI-powered code analysis
Fallback:  Static analysis tool
Last resort: Manual review flag

The system should always produce some useful output, even if degraded.

4. Objective Drift Prevention

Logging and Traceability

Every agent interaction must be logged for debugging.

Trace Log Schema

Debugging Multi-Agent Failures

1. Identify the failing agent -- Check trace logs for ERROR actions 2. Examine the delegation chain -- Follow parentId links back to the root 3. Check context quality -- Was the right information passed? 4. Verify tool availability -- Are MCP servers responding? 5. Review objective alignment -- Did the agent understand the task?

Anti-Patterns

Goal Decomposition

For complex goals, decompose into executable capability sequences using Hierarchical Task Network (HTN) planning.

Process Overview

1. Analyze goal -- Extract required and optional effects 2. Find candidates -- Query capability graph for capabilities producing desired effects 3. Validate preconditions -- Check project state against each capability's requirements 4. Build HTN plan -- Order capabilities by dependencies, identify parallel steps, list alternatives 5. Score and rank -- Evaluate using weighted utility function 6. Log decisions -- Capture rationale, alternatives considered, rejection reasons

Step 1: Goal Analysis

Break the goal into discrete effects:

Goal: "Build RAG system for documentation search"

Required Effects:
- enables_embedding_generation
- creates_vector_index
- configures_retrieval_pipeline

Optional Effects:
- adds_caching_layer
- implements_reranking

Domains: [rag, api, database]

Effects are specific, measurable outcomes. Examples:

• creates_vector_index
• adds_auth_middleware
• configures_database
• implements_api_endpoint
• adds_tests

Step 2: Find Candidate Capabilities

For each required effect, find capabilities that produce it:

Effect: creates_vector_index
Candidates:
  - pinecone-integration (managed, low latency)
  - weaviate-setup (self-hosted, more control)
  - qdrant-setup (open source, local dev)

Step 3: Validate Preconditions

Check if current project state satisfies each capability's requirements:

Capabilities with unsatisfied required preconditions are marked as blocked. Either resolve the precondition or use an alternative capability.

Step 4: Build HTN Plan

Order capabilities by dependencies and identify parallelism:

Plan for "Build RAG system":
  Step 1: openai-integration     (enables embeddings)     [no deps]
  Step 2: pinecone-setup         (creates vector index)   [no deps]
  Step 3: rag-implementer        (retrieval pipeline)     [depends on 1, 2]

Parallel steps: [[1, 2]]  -- Steps 1 and 2 can run simultaneously

Each step includes:

• Capability name and effect
• Whether it is required or optional
• Blocked status
• Alternative capabilities
• Dependencies on other steps
• Reasoning for selection

Step 5: Score and Rank

Evaluate plans using the weighted utility function:

utility = cost_score * 0.3 + risk_score * 0.3 + latency_score * 0.2 + diversity_score * 0.2

Score mappings:

Modifiers:

• Cooldown penalty: Capability used within 3 steps gets -30%
• Novelty bonus: Capability not yet in plan gets +20%

Step 6: Decision Logging

Every plan must include a decision log:

Decision Log:
  Goal: "Build RAG system"
  Selected: pinecone-integration (score: 0.78)
  Alternatives considered:
    - weaviate-setup (score: 0.72, rejected: higher operational cost)
    - qdrant-setup (score: 0.65, rejected: requires self-hosting)
  Precondition checks: all passed
  Reasoning: Managed service reduces operational overhead

Log fields: goal, timestamp, selected capabilities, alternatives with scores and rejection reasons, precondition results, overall reasoning.

MCP Orchestration

MCP (Model Context Protocol) provides a standardized way for agents to connect to servers that host tools, resources, and prompts.

MCP Architecture

Resources

Readable data sources like files, database schemas, or API documentation. Subagents should use list_resources to discover what is available before reading specific resources.

Examples:

• File system contents
• Database schemas
• API documentation
• Configuration files
• Environment information

Tools

Executable functions with JSON-Schema validated arguments. MCP standardizes argument typing and validation.

Examples:

• Database queries
• File operations
• API calls
• Code analysis
• Build commands

Prompts

Servers can provide prompt templates that guide agents on how to use specific tools effectively. These encode domain expertise into reusable instructions.

Multi-Server Orchestration

An orchestrator often connects to multiple MCP servers simultaneously.

Unified Toolset Pattern

The parent agent acts as a gateway, exposing a unified set of tools to subagents. The parent routes tool calls to the correct MCP server.

Parent Agent (Gateway)
  ├── MCP Server: PostgreSQL (database tools)
  ├── MCP Server: GitHub (repository tools)
  ├── MCP Server: Filesystem (file tools)
  └── Subagent (sees unified toolset)

Server Selection

Configuration

MCP servers are configured per project. The orchestrator discovers available servers and their capabilities at startup.

Key configuration:

• Server endpoints and authentication
• Available tools per server
• Resource access patterns
• Rate limits and quotas

Bidirectional Communication (Sampling)

MCP servers can request the agent to generate text as part of tool execution. This enables complex workflows where tool execution requires AI reasoning mid-stream.

Protocol Flow

1. Agent calls Tool A on Server X 2. Tool A starts executing 3. Tool A sends a sampling/createMessage request back to the Agent 4. Agent generates a response 5. Tool A receives the response and finishes execution

Use Cases

• Code analysis tool asks agent to explain a pattern
• Database tool asks agent to generate a migration
• Review tool asks agent to summarize findings

Best Practices

Multi-Agent Coordination

Orchestration Patterns

Hierarchical Orchestration

Parent agent delegates to specialized subagents. The parent validates output and handles errors.

Supervisor
  ├── architect-agent (produces design doc)
  ├── developer-agent (implements features)
  └── reviewer-agent (validates code quality)

Use when: complex tasks requiring multiple specialized capabilities.

Sequential Pipeline (Chain of Experts)

One agent passes output to the next in a defined sequence.

architect -> developer -> reviewer -> deployer

Use when: tasks have clear phases where each depends on the previous output.

Parallel Execution

Independent tasks run simultaneously, results aggregated by parent.

Supervisor
  ├── frontend-agent (parallel)
  ├── backend-agent (parallel)
  └── [aggregate results]

Use when: tasks are independent and can run concurrently.

Handoff Pattern

One agent passes full context to another when its expertise is exhausted.

generalist-agent -> specialist-agent (with full context transfer)

Use when: task requires expertise transition (e.g., architecture to implementation).

Delegation Manifests

Every subagent must receive a clear objective manifest:

interface DelegationManifest {
  objective: string;
  constraints: string[];
  maxTokens: number;
  availableTools: string[];
  planId: string;
  currentStepIndex: number;
}

Key rules:

• Never delegate with vague objectives ("fix this")
• Include specific constraints and success criteria
• List available tools explicitly
• Reference the current plan step

Recursion Limits

To prevent "Inception Loops" and excessive token spend:

• Maximum delegation depth: 3 levels
• Each subagent must report its recursionDepth in metadata
• If depth limit is reached, task must be completed at current level or escalated to user

Level 0: User request
Level 1: Supervisor agent
Level 2: Specialist agent
Level 3: Executor agent (max depth, no further delegation)

A2A Communication (Peer-to-Peer)

Unlike hierarchical delegation, Agent-to-Agent (A2A) focuses on peer collaboration.

Request-Response Pattern

{
  "type": "A2A_REQUEST",
  "from": "frontend-dev",
  "to": "backend-architect",
  "payload": {
    "action": "QUERY_SCHEMA",
    "params": { "table": "users" }
  }
}

Negotiation Protocol

When agents have conflicting plans:

1. Proposal: Agent A proposes a change 2. Critique: Agent B provides feedback with constraints 3. Synthesis: Parent or third agent resolves based on project priorities

Shared Working Memory (Blackboard)

Agents post findings to a shared state to avoid redundant work:

• Discovered symbols and types
• Architectural decisions
• Blockers and dependencies
• Completed sub-tasks

Anti-Patterns

Project Patterns

Classify every project before selecting frameworks or skills.

Pattern A: Simple Feature/Enhancement

• Adding to existing system, well-understood requirements
• Low risk, single-team, 1-5 days
• Examples: search filter, dashboard widget, form field, styling update

Sequence: feature framework -> code quality -> testing -> deployment

Pattern B: New Product/System

• Building from scratch or major module, user validation needed
• Security/compliance important, multiple considerations, 4-12 weeks
• Examples: SaaS product, customer portal, internal tool, API platform

Phases:

1. Discovery -- Validation frameworks, product-market fit analysis, user research 2. Architecture and Design -- System design, prototyping, UX design, security architecture, API design 3. Development -- Full-stack development, frontend/backend build, API implementation, quality assurance 4. Testing -- Test validation, QA, usability testing, security review 5. Deployment -- DevOps setup, deployment, go-to-market planning

Pattern C: AI-Native/Complex System

All Pattern B phases, plus:

• Phase 2b (AI Architecture) -- Multi-agent architecture, RAG implementation, knowledge graph design, agentic workflow orchestration
• Phase 3b (AI Development) -- Context engineering, multi-agent orchestration implementation
• Phase 4b (AI Testing) -- Agent behavior tests, RAG retrieval quality, LLM benchmarks

Characteristics: AI agents, RAG, knowledge graphs, complex orchestration, 8-20 weeks.

Phase Gates

Do not advance without meeting gate criteria.

Skill Coordination by Phase

Limit to 1-3 skills per phase. Each skill has a specific deliverable and clear handoff.

Parallelization Opportunities

• UX design + Architecture design (Phase 2)
• Frontend + Backend development (Phase 3)
• Test writing + Feature development (Phase 3)
• Independent capability steps with no shared dependencies (HTN parallel steps)

Troubleshooting

Wrong pattern identified mid-project: Adapt orchestration. Pattern A to B: add discovery and design phases. Pattern B to C: add AI architecture and testing. Scope reduction: simplify orchestration.

Phase gate not met: Do not skip. Identify specific unmet criteria, address them, then re-validate. Partial advancement leads to compounding rework.

Deliverables

When orchestrating, produce:

1. Pattern classification with rationale and timeline estimate 2. Orchestration plan with phase breakdown, framework sequence, skill activation points, and gate criteria 3. Phase status showing current position, completion percentage, gate readiness, and next steps 4. Decision log capturing selected capabilities, alternatives considered, scores, and reasoning