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
| Need |
Action |
| Identify project type |
Classify as Pattern A / B / C |
| Sequence frameworks |
Follow pattern-specific phase order |
| Decompose a goal |
Extract required effects, match capabilities |
| Validate readiness |
Check phase-gate criteria before advancing |
| Find alternatives |
Generate fallback capabilities per step |
| Score a plan |
Evaluate cost, latency, risk, diversity |
| Coordinate agents |
Select orchestration pattern for task type |
| Pass context |
Use context distillation for subagents |
Pattern Identification
Classify every project before selecting frameworks or skills.
| Pattern |
Characteristics |
Timeline |
| A: Simple Feature |
Existing system, well-understood, single-team |
1-5 days |
| B: New Product/System |
From scratch, security/compliance matters |
4-12 weeks |
| C: AI-Native/Complex |
AI agents, RAG, knowledge graphs, orchestration |
8-20 weeks |
Phase Gates
Do not advance without meeting gate criteria.
| Gate |
Entry Criteria |
| Design (Phase 2) |
PRP complete, problem validated, success metrics, user stories |
| Development (3) |
Architecture documented, data model designed, security threats mapped |
| Testing (Phase 4) |
Features complete, unit tests over 80%, code review, SAST clean |
| Deployment (5) |
All tests passing, UAT completed, security tested, coverage over 90% |
Scoring Function
Plans are evaluated using weighted utility:
| Factor |
Weight |
Scores |
| Cost |
0.3 |
free=1.0, low=0.8, medium=0.5, high=0.2 |
| Risk |
0.3 |
safe=1.0, low=0.8, medium=0.5, high=0.2 |
| Latency |
0.2 |
instant=1.0, fast=0.7, slow=0.3 |
| Diversity |
0.2 |
min(unique_domains / 5, 1.0) |
Modifiers: recently used (within 3 steps) gets -30% penalty; novel capability gets +20% bonus.
Multi-Agent Orchestration Patterns
| Pattern |
Use Case |
| Hierarchical |
Parent delegates to specialized subagents |
| Sequential |
Chain of experts (architect -> dev -> review) |
| Parallel |
Independent tasks running simultaneously |
| Handoff |
One agent passes context to the next |
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.
| MCP Primitive |
Role in Orchestration |
| Resources |
Discover available data (schemas, configs, docs) before work |
| Tools |
Execute validated actions with typed arguments |
| Prompts |
Reuse domain-specific instruction templates across agents |
| Sampling |
Allow servers to request AI reasoning mid-execution |
Common Mistakes
| Mistake |
Correct Pattern |
| Treating all projects as Pattern A (simple feature) |
Classify first: Pattern A (simple), B (new product), C (AI-native) before selecting frameworks |
| Skipping phase gates to move faster |
Enforce gate criteria before advancing; skipping causes compounding rework |
| Activating all available skills simultaneously |
Limit to 1-3 skills per phase with clear deliverables and handoffs |
| No decision logging for capability choices |
Log rationale, alternatives considered, scores, and rejection reasons at each step |
| Building HTN plans without validating preconditions |
Check project state (files, dependencies, env vars) against each capability's requirements first |
| Delegating without a clear objective manifest |
Every subagent needs an objective, constraints, max tokens, and available tools |
| Passing entire codebase to subagents |
Use context distillation to pass only relevant symbols and facts |
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
1---
2name: orchestration
3description: 'Coordinates skills, frameworks, and workflows throughout the project lifecycle using pattern-based sequencing, goal decomposition, phase-gate validation, and multi-agent orchestration. Use when starting multi-phase projects, sequencing frameworks, decomposing goals into capability plans, validating phase-gate readiness, coordinating subagents, or designing MCP-based tool orchestration.'
4license: MIT
5metadata:
6 author: oakoss
7 version: '1.0'
8---
9
10# Orchestration
11
12## Overview
13
14Coordinates skills, frameworks, and workflows across the project lifecycle. Combines pattern-based project classification with goal decomposition, hierarchical task planning, and multi-agent coordination.
15
16Use 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.
17
18This skill does NOT replace project management tools. It provides the decision framework for sequencing capabilities and validating readiness at each transition point.
19
20## Quick Reference
21
22| Need | Action |
23| --------------------- | -------------------------------------------- |
24| Identify project type | Classify as Pattern A / B / C |
25| Sequence frameworks | Follow pattern-specific phase order |
26| Decompose a goal | Extract required effects, match capabilities |
27| Validate readiness | Check phase-gate criteria before advancing |
28| Find alternatives | Generate fallback capabilities per step |
29| Score a plan | Evaluate cost, latency, risk, diversity |
30| Coordinate agents | Select orchestration pattern for task type |
31| Pass context | Use context distillation for subagents |
32
33## Pattern Identification
34
35Classify every project before selecting frameworks or skills.
36
37| Pattern | Characteristics | Timeline |
38| --------------------- | ----------------------------------------------- | ---------- |
39| A: Simple Feature | Existing system, well-understood, single-team | 1-5 days |
40| B: New Product/System | From scratch, security/compliance matters | 4-12 weeks |
41| C: AI-Native/Complex | AI agents, RAG, knowledge graphs, orchestration | 8-20 weeks |
42
43## Phase Gates
44
45Do not advance without meeting gate criteria.
46
47| Gate | Entry Criteria |
48| ----------------- | --------------------------------------------------------------------- |
49| Design (Phase 2) | PRP complete, problem validated, success metrics, user stories |
50| Development (3) | Architecture documented, data model designed, security threats mapped |
51| Testing (Phase 4) | Features complete, unit tests over 80%, code review, SAST clean |
52| Deployment (5) | All tests passing, UAT completed, security tested, coverage over 90% |
53
54## Scoring Function
55
56Plans are evaluated using weighted utility:
57
58| Factor | Weight | Scores |
59| --------- | ------ | --------------------------------------- |
60| Cost | 0.3 | free=1.0, low=0.8, medium=0.5, high=0.2 |
61| Risk | 0.3 | safe=1.0, low=0.8, medium=0.5, high=0.2 |
62| Latency | 0.2 | instant=1.0, fast=0.7, slow=0.3 |
63| Diversity | 0.2 | min(unique_domains / 5, 1.0) |
64
65Modifiers: recently used (within 3 steps) gets -30% penalty; novel capability gets +20% bonus.
66
67## Multi-Agent Orchestration Patterns
68
69| Pattern | Use Case |
70| ------------ | --------------------------------------------- |
71| Hierarchical | Parent delegates to specialized subagents |
72| Sequential | Chain of experts (architect -> dev -> review) |
73| Parallel | Independent tasks running simultaneously |
74| Handoff | One agent passes context to the next |
75
76Key rules: max delegation depth of 3, use context distillation (not full codebase), log all agent interactions.
77
78## MCP Integration
79
80MCP (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.
81
82| MCP Primitive | Role in Orchestration |
83| ------------- | ------------------------------------------------------------ |
84| Resources | Discover available data (schemas, configs, docs) before work |
85| Tools | Execute validated actions with typed arguments |
86| Prompts | Reuse domain-specific instruction templates across agents |
87| Sampling | Allow servers to request AI reasoning mid-execution |
88
89## Common Mistakes
90
91| Mistake | Correct Pattern |
92| --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
93| Treating all projects as Pattern A (simple feature) | Classify first: Pattern A (simple), B (new product), C (AI-native) before selecting frameworks |
94| Skipping phase gates to move faster | Enforce gate criteria before advancing; skipping causes compounding rework |
95| Activating all available skills simultaneously | Limit to 1-3 skills per phase with clear deliverables and handoffs |
96| No decision logging for capability choices | Log rationale, alternatives considered, scores, and rejection reasons at each step |
97| Building HTN plans without validating preconditions | Check project state (files, dependencies, env vars) against each capability's requirements first |
98| Delegating without a clear objective manifest | Every subagent needs an objective, constraints, max tokens, and available tools |
99| Passing entire codebase to subagents | Use context distillation to pass only relevant symbols and facts |
100
101## Delegation
102
103- **Discover project pattern and classify scope**: Use `Explore` agent to survey the codebase, dependencies, and requirements
104- **Execute multi-phase orchestration plan**: Use `Task` agent to implement phase-specific deliverables with gate validation
105- **Design architecture and capability sequences**: Use `Plan` agent to decompose goals and build scored HTN plans
106
107## References
108
109- [goal-decomposition.md](references/goal-decomposition.md) -- HTN planning, goal analysis, capability matching, precondition validation, scoring, decision logging
110- [project-patterns.md](references/project-patterns.md) -- Pattern A/B/C classification, phase sequences, skill coordination by phase, parallelization
111- [multi-agent-coordination.md](references/multi-agent-coordination.md) -- Hierarchical, sequential, parallel orchestration patterns, delegation manifests, recursion limits
112- [mcp-orchestration.md](references/mcp-orchestration.md) -- MCP architecture, resources, tools, prompts, multi-server orchestration, bidirectional sampling
113- [context-distillation.md](references/context-distillation.md) -- Symbol indexing, fact extraction, recursive context reduction, token management
114- [error-handling.md](references/error-handling.md) -- Objective drift, tool failure, context overflow, circuit breakers, recovery strategies, logging
oakoss