Menu
Multi-agent workflow coordination with routing, state management, and failure recovery
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Plan-and-Execute methodology for adaptive execution with replanning
Plan-and-Solve methodology for goal decomposition and plan creation
Intelligent context window management with tiered content, token budgets, and LLM-powered summarization
Plan validation with confidence scoring and adversarial challenge
Brand discovery methodology for establishing identity, voice, and messaging
Content creation methodology leveraging brand context for consistent, strategic content
| name | orchestration |
| description | Multi-agent workflow coordination with routing, state management, and failure recovery |
| triggers | ["orchestrate","coordinate","workflow","multi-agent"] |
This skill teaches the methodology for coordinating multiple STUDIO agents to accomplish complex goals. The orchestrator is a meta-agent that routes, manages state, handles failures, and coordinates context across the system.
Complex software tasks often require multiple specialized agents:
Without orchestration:
┌─────────────────────────────────────────────────────────────────────┐
│ THE ORCHESTRATOR │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ RESPONSIBILITIES: │
│ │
│ 1. ROUTING │
│ └── Analyze request → Select agent(s) → Determine order │
│ │
│ 2. STATE MANAGEMENT │
│ └── Track progress → Maintain checkpoints → Handle recovery │
│ │
│ 3. FAILURE HANDLING │
│ └── Detect failures → Decide: retry | replan | escalate │
│ │
│ 4. CONTEXT COORDINATION │
│ └── Pass context between agents → Trigger optimization │
│ │
└─────────────────────────────────────────────────────────────────────┘
When users run /build "goal", orchestration happens transparently:
User: /build "Add user authentication with OAuth"
[Behind the scenes]
Orchestrator:
→ Analyzes goal complexity
→ Routes to Planner (goal is complex)
→ Handles Planner → Builder handoff
→ Manages any failures
→ Returns unified result
User sees: Seamless planning and building
Key principle: Users shouldn't need to know orchestration is happening.
When users want visibility and control:
User: /orchestrate build
Orchestrator:
[ROUTING]
→ Goal: "Add user authentication with OAuth"
→ Complexity: HIGH
→ Workflow: plan_then_build
→ Agents: Planner → Builder
→ Confidence: 85%
Proceed? [y/n]
PLANNER ──────────────→ BUILDER
│ │
├─ Question loop ├─ Execute loop
├─ Plan construction ├─ Quality gates
└─ plan.json └─ learnings
Triggers: New features, complex changes, ambiguous requests
BUILDER
│
├─ Load existing plan
├─ Execute loop
└─ Quality gates
Triggers: Simple fixes, bugs, tasks with existing plans
BUILDER ──→ BUILDER ──→ BUILDER
│ │ │
T1 T2 T3
Triggers: /project:run, batch execution from backlog
ARCHITECT ──→ PLANNER ──→ BUILDER
│ │ │
├─ Epics ├─ Plans ├─ Execution
├─ Features └─ per task └─ per task
└─ Tasks
Triggers: Enterprise projects, large scope requests
┌──────────────────┐
│ Analyze Goal │
└────────┬─────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌────▼────┐ ┌─────▼─────┐ ┌────▼────┐
│ Simple │ │ Complex │ │ Huge │
│fix/bug │ │ feature │ │ project │
└────┬────┘ └─────┬─────┘ └────┬────┘
│ │ │
▼ ▼ ▼
BUILD_ONLY PLAN_THEN_BUILD DECOMPOSE_FIRST
| Signal | Workflow |
|---|---|
| "fix", "bug", "error", "typo" | build_only |
| "add", "create", "implement" | plan_then_build |
| "refactor", "restructure" | plan_then_build |
| "project", "system", "platform" | decompose_first |
| Existing plan in .studio/tasks/ | build_only |
| Multiple tasks specified | multi_task |
orchestration_state:
id: "orch_20260202_143052_a1b2"
mode: "implicit"
status: "executing"
goal: "Add user authentication"
routing:
workflow: "plan_then_build"
agent_sequence:
- agent: "planner"
status: "completed"
- agent: "builder"
status: "active"
confidence: 0.85
agent_states:
- agent: "planner"
status: "completed"
output: { plan_id: "bp_xxx" }
- agent: "builder"
status: "active"
current_step: 3
checkpoints:
- id: "cp_1706789123"
name: "planning_complete"
after_agent: "planner"
failures: []
Save checkpoints after:
./scripts/orchestrator.sh checkpoint "planning_complete"
If session interrupted:
./scripts/orchestrator.sh resume cp_1706789123
When transitioning between agents, context must be passed:
handoff:
from: "planner"
to: "builder"
context:
task_id: "task_xxx"
plan_id: "bp_xxx"
plan_summary: |
8 steps to implement OAuth:
1. Install dependencies
2. Create auth schema
...
learnings_loaded:
- "security"
- "backend"
requirements_summary:
scope_in: [...]
scope_out: [...]
handoff:
from: "builder"
to: "planner"
context:
failure_reason: "Step 3 failed: API incompatibility"
completed_steps: [1, 2]
failed_step: 3
error_details: "..."
suggestion: "Consider alternative OAuth library"
┌──────────────────┐
│ Agent Failed │
└────────┬─────────┘
│
┌────────▼────────┐
│ Is Recoverable? │
└────────┬────────┘
│ │
YES │ │ NO
│ │
┌──────────▼───┐ │
│ Retries Left? │ │
└──────┬───────┘ │
│ │ │
YES │ │ NO │
│ │ │
▼ ▼ ▼
RETRY REPLAN ESCALATE
Same agent, same input, increment retry count.
./scripts/orchestrator.sh agent-start builder # Re-invoke
Go back to Planner with failure context.
./scripts/orchestrator.sh handoff builder planner '{
"failure_reason": "Step 3 incompatible with existing code",
"suggestion": "Use different approach"
}'
User intervention required.
Build failed after 5 retries and 1 replan attempt.
Last error: Cannot resolve OAuth callback URL
Options:
1. [r] Retry with different approach
2. [s] Skip this step (if non-critical)
3. [a] Abort and review plan
| Category | Action | Example |
|---|---|---|
| Transient | Retry | Network timeout |
| Code Error | Retry with fix | Syntax error |
| Design Flaw | Replan | Wrong approach |
| Blocker | Escalate | Missing dependency |
| Critical | Halt | Security violation |
The orchestrator allocates context budgets to agents:
Before starting workflow:
./scripts/context-manager.sh budget
Pool Used Soft Status
─────────────────────────────────────
reserved 28000 30000 OK
learnings 15000 20000 OK
backlog 8000 15000 OK
plans 0 30000 OK
context7 12000 25000 OK
working 0 30000 OK
─────────────────────────────────────
TOTAL 63000 150000 OK (42%)
Monitor for pressure:
When context pressure is critical:
┌─────────────────────────────────────────────────────────────────────┐
│ /build "Add OAuth authentication" │
└─────────────────────────────────────────────────────────────────────┘
│
┌──────────────▼──────────────┐
│ ORCHESTRATOR │
│ ┌─────────────────────┐ │
│ │ 1. Initialize │ │
│ │ session │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ 2. Analyze goal │ │
│ │ → Complex │ │
│ │ → Needs planning │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ 3. Allocate context │ │
│ │ budgets │ │
│ └──────────┬──────────┘ │
└─────────────┼───────────────┘
│
┌─────────────▼───────────────┐
│ PLANNER │
│ ┌─────────────────────┐ │
│ │ Question loop │ │
│ │ (max 5 rounds) │ │
│ └──────────┬──────────┘ │
│ ┌──────────▼──────────┐ │
│ │ Plan construction │ │
│ └──────────┬──────────┘ │
│ │ plan.json │
└─────────────┼───────────────┘
│
┌─────────────▼───────────────┐
│ ORCHESTRATOR │
│ ┌─────────────────────┐ │
│ │ Evaluate confidence │ │
│ │ 85% → Proceed │ │
│ └──────────┬──────────┘ │
│ ┌──────────▼──────────┐ │
│ │ Handoff context │ │
│ │ to Builder │ │
│ └──────────┬──────────┘ │
└─────────────┼───────────────┘
│
┌─────────────▼───────────────┐
│ BUILDER │
│ ┌─────────────────────┐ │
│ │ Execute loop │ │
│ │ (max 5 per step) │ │
│ └──────────┬──────────┘ │
│ ┌──────────▼──────────┐ │
│ │ Quality gates │ │
│ └──────────┬──────────┘ │
│ │ result │
└─────────────┼───────────────┘
│
┌─────────────▼───────────────┐
│ ORCHESTRATOR │
│ ┌─────────────────────┐ │
│ │ Finalize │ │
│ │ - Capture learnings │ │
│ │ - Update backlog │ │
│ │ - Clean up session │ │
│ └─────────────────────┘ │
└─────────────────────────────┘
Users should see a seamless experience. Hide orchestration complexity unless explicitly requested.
Always save state before any failure. Enable resume.
Handoffs must include all context needed for the receiving agent.
Try retry and replan before asking user for help.
Full audit trail enables debugging and improvement.
orchestrator.sh status"The orchestra plays as one. Each instrument, perfectly timed."