Multi agent orchestrator

---
description: Orchestrate multi-agent workflow for Linear epics - automated planning, execution, and stack creation
---

# Orchestrate Epic Command
**Purpose**: Orchestrate multi-agent workflow for Linear epics - automated planning, execution, and stack creation
## ⚠️ CRITICAL: PR WORKFLOW REQUIREMENTS
**ALL AGENTS MUST USE GRAPHITE - NEVER GIT FOR PRS**
- ❌ FORBIDDEN: Any agent using `git commit`, `git push`, or direct git PR creation
- ✅ REQUIRED: All agents use `gt create`, `gt modify`, `gt submit` exclusively
- ✅ REQUIRED: Maintain proper Graphite stack dependencies
- ⚠️ ORCHESTRATOR MONITORING: Track Graphite stack integrity across all agents
---
## Command Execution
Execute: immediate
Legend: 🎯 Orchestrator → 📋 Planner → 🔧 EPCT Workers → 🔍 Resolver → ✅ QA
Purpose: "Orchestrate complete epic implementation from $ARGUMENTS"
Automatically detects Linear epic from branch name (format: `feature/{TEAM}-XXX-epic-name`) and orchestrates a multi-agent workflow to decompose, implement, and validate the entire epic as a Graphite stack.
**Default Behavior**: Sequential agent execution with parallel subtask processing, automated Linear issue creation, Graphite stack management.
Examples:
- `/orchestrate-epic` - Detect epic from current branch and start orchestration
- `/orchestrate-epic --epic "LEO-11"` - Specific epic ID
- `/orchestrate-epic --dry-run` - Show execution plan without running
- `/orchestrate-epic --sequential` - Force sequential subtask execution
- `/orchestrate-epic --max-agents 5` - Limit parallel agent execution
## Command-Specific Flags
--epic: "Specific Linear epic ID to orchestrate"
--dry-run: "Show execution plan without running agents"
--sequential: "Force sequential subtask execution (default: parallel)"
--max-agents: "Maximum parallel agents (default: unlimited)"
--skip-planning: "Skip planning phase if subtasks already exist"
--skip-qa: "Skip final QA validation phase"
--resume: "Resume from last checkpoint after failure"
--verbose: "Detailed logging of agent communications"
## Phase 1: Investigation (🟢/🟡/🟠/🔴)
### Epic Detection & Analysis
1. **Auto-detect epic**: Extract Linear key from branch name or use --epic flag
2. **Fetch epic details**: Use Linear MCP to retrieve full epic information
3. **Analyze scope**: Assess complexity and estimate total effort
4. **Validate feasibility**: Check if epic can be automated
### Agent Preparation
1. **Load agent templates**: Prepare specialized agents from `agents/` directory
2. **Configure interfaces**: Set up communication channels between agents
3. **Initialize state tracking**: Create orchestration state management
## Phase 2: Execution (⬜/🔵/🟦/🟪/✅)
### Orchestration Workflow
1. Planning Phase (📋)
Spawn **planning-agent** to:
- Analyze codebase context
- Decompose epic into 3-15 optimal subtasks
- Create Linear issues with embedded prompts
- Return subtask handles for orchestration
2. Parallel Execution Phase (🔧)
For each subtask, spawn **epct-background-agent** to:
- Execute autonomous EPCT workflow
- Create feature branch via Graphite (NEVER git)
- Implement and test changes
- Submit PR to stack via `gt submit` (NEVER git push)
Monitor all agents in parallel with:
- Progress tracking dashboard
- Error detection and recovery
- Resource usage optimization
3. Resolution Phase (🔍)
When errors occur, spawn **resolution-agent** to:
- Diagnose failures automatically
- Apply fixes for common issues
- Re-trigger failed agents
- Escalate when needed
4. QA Validation Phase (✅)
Finally, spawn **qa-verification-agent** to:
- Validate entire stack quality
- Run integration tests
- Check acceptance criteria
- Approve for merge or request fixes
### State Management
Track orchestration state with:
- Agent status (running/complete/failed)
- Subtask progress percentages
- **Graphite stack PR relationships and dependencies**
- Error logs and recovery attempts
### Output Format
`Epic: LEO-11 - Orchestrator Sub-agents
Status: 🔧 Executing (12/15 subtasks complete)

Planning Phase: ✅ Complete
- Created 15 subtasks
- Estimated 30 story points
- Optimized for 5 parallel agents

Execution Phase: 🔧 80% Complete
[████████████████████████████░░░░░░░░]

Active Agents:
- epct-agent-1: LEO-12 ✅ PR submitted
- epct-agent-2: LEO-13 🔧 75% coding
- epct-agent-3: LEO-14 🔍 Resolving errors
- epct-agent-4: LEO-15 ⏸️ Waiting for LEO-13
- epct-agent-5: LEO-16 🔧 50% coding

Stack Status:
- feature/leo-12-auth-setup ✅ (Graphite branch)
- feature/leo-13-api-layer 🔧 (Graphite branch)
- feature/leo-14-ui-components 🔍 (Graphite branch)
- ...

Next: Spawning resolver for LEO-14 errors
`
## Error Recovery
- **Agent failures**: Automatic retry with resolution agent
- **Linear API errors**: Exponential backoff and retry
- **Git conflicts**: Resolution agent handles via Graphite commands only
- **Resource limits**: Queue agents when max-agents reached
- **State corruption**: Restore from checkpoint