Orchestrates large-scale, cross-repository architectural epics with parallel coordination and dependency management
<codex_skill_adapter>
$workflow-create-epic.$workflow-create-epic as {{SC_ARGS}}.{{SC_ARGS}} as empty.spawn_agent(...) patterns to Codex spawn_agent(...).update_plan.config.toml when the original command mentions MCP.workflow:create:epic.$workflow-create-epic.STEP 1: Initialize epic orchestration session and analyze scope
/tmp/epic-session-$SESSION_ID.json# Initialize epic orchestration session
echo '{
"sessionId": "'$SESSION_ID'",
"epicTarget": "'{{SC_ARGS}}'",
"epicType": "auto-detect",
"affectedRepositories": [],
"estimatedComplexity": "unknown",
"coordinationStrategy": "parallel"
}' > /tmp/epic-session-$SESSION_ID.json
STEP 2: Comprehensive epic scope analysis with parallel sub-agent coordination
TRY:
IF epic_complexity == "enterprise" OR affected_repositories > 5:
LAUNCH parallel sub-agents for comprehensive scope analysis:
Agent 1: Repository Discovery: Scan and catalog all affected repositories
Agent 2: Service Architecture Analysis: Map service interactions and dependencies
Agent 3: Infrastructure Impact Assessment: Evaluate infrastructure and deployment requirements
Agent 4: Timeline & Resource Estimation: Calculate effort and resource requirements
ELSE:
EXECUTE streamlined scope analysis for focused epics:
Repository Discovery:
# Scan current repository structure
echo "📁 Analyzing repository structure..."
fd . -t d -d 2 | head -10
# Check for monorepo services
if fd "(package\.json|Cargo\.toml|go\.mod|pom\.xml)" . -d 3 | wc -l | grep -v "^[01]$" >/dev/null; then
echo "🔍 Monorepo structure detected - multiple services found"
else
echo "📦 Single repository detected"
fi
Epic Impact Assessment:
# Generate comprehensive impact analysis
echo "📊 Epic Impact Analysis:"
echo "Repositories affected: $(jq '.affectedRepositories | length' /tmp/epic-session-$SESSION_ID.json)"
echo "Epic type: $(jq -r '.epicType' /tmp/epic-session-$SESSION_ID.json)"
echo "Estimated complexity: $(jq -r '.estimatedComplexity' /tmp/epic-session-$SESSION_ID.json)"
echo "Coordination strategy: $(jq -r '.coordinationStrategy' /tmp/epic-session-$SESSION_ID.json)"
# Technology stack analysis
echo "🔧 Technology stack:"
fd "(package\.json|Cargo\.toml|go\.mod|pom\.xml|deno\.json)" . | \
rg -o "(package\.json|Cargo\.toml|go\.mod|pom\.xml|deno\.json)" | \
sort | uniq -c
STEP 3: Master epic plan generation with programmatic structure
CASE epic_type: WHEN "migration":
Technology Migration Epic Template:
# Epic: {{SC_ARGS}}
## Overview
**Session ID**: $SESSION_ID
**Epic Type**: Technology Migration
**Initiated**: $(gdate -Iseconds 2>/dev/null || date -Iseconds)
**Coordinator**: $(git config user.name 2>/dev/null || echo "Unknown")
**Goal**: {{SC_ARGS}}
**Scope Analysis**:
- Affected repositories: $(jq '.affectedRepositories | length' /tmp/epic-session-$SESSION_ID.json)
- Technology stack: Multi-language ($(fd "(package\.json|Cargo\.toml|go\.mod)" . | wc -l | tr -d ' ') services)
- Deployment target: $(kubectl config current-context 2>/dev/null || echo "Traditional deployment")
**Estimated Timeline**: $(jq -r '.estimatedComplexity' /tmp/epic-session-$SESSION_ID.json) complexity
**Risk Level**: High (involves production services)
Goal: Establish epic infrastructure and detailed planning
Coordination Strategy: Parallel preparation across all repositories
spawn_agents:
Sub-Agent Delegation for Repository Planning:
LAUNCH parallel sub-agents to create repository-specific plans:
FOR EACH repository IN affected_repositories:
Success Criteria:
Dependencies: None (foundation work)
Goal: Implement changes in dependency-critical services first
Coordination Strategy: Sequential implementation respecting dependencies
Critical Path Analysis:
# Identify critical path through dependency analysis
echo "🎯 Critical path services (implement first):"
jq -r '.criticalPath[]?' /tmp/epic-session-$SESSION_ID.json 2>/dev/null || echo " - Auto-detecting from dependencies..."
Parallel Implementation Workflow:
FOR EACH critical_service IN critical_path:
../epic-{service}-$SESSION_IDepic/$EPIC_IDspawn_agents (Per Service):
git worktree add ../epic-{service}-$SESSION_ID epic/$EPIC_IDSuccess Criteria:
Dependencies: Phase 1 completion
Goal: Migrate remaining services using true parallel execution
Coordination Strategy: Maximum parallelism with git worktree isolation
Parallel Worktree Architecture:
# Create isolated worktrees for each service team
FOR service IN remaining_services:
git worktree add ../epic-$service-$SESSION_ID epic/$EPIC_ID-$service
echo "🌿 Worktree created: ../epic-$service-$SESSION_ID"
done
Sub-Agent Service Migration Coordination:
LAUNCH parallel implementation sub-agents:
Agent {Service A}: Complete service migration in dedicated worktree
../epic-service-a-$SESSION_ID/tmp/epic-coordination-$SESSION_ID.jsonAgent {Service B}: Complete service migration in dedicated worktree
../epic-service-b-$SESSION_ID/tmp/epic-coordination-$SESSION_ID.jsonAgent {Service C}: Complete service migration in dedicated worktree
../epic-service-c-$SESSION_ID/tmp/epic-coordination-$SESSION_ID.jsonCoordination Checkpoints:
Goal: Complete remaining services and comprehensive integration testing
Batch Processing with Parallel Execution:
# Group supporting services by dependency clusters
echo "📦 Supporting service migration batches:"
jq -r '.supportingServices[]?' /tmp/epic-session-$SESSION_ID.json 2>/dev/null || echo " - Auto-detecting supporting services..."
Parallel Batch Migration Strategy:
FOR EACH service_batch IN supporting_service_batches: LAUNCH parallel sub-agents for batch processing:
Integration Testing Coordination:
Goal: Finalize epic and consolidate all changes
Epic Consolidation Strategy:
# Consolidate all worktree changes back to main repositories
echo "🔄 Consolidating epic changes..."
FOR worktree IN epic_worktrees:
cd $worktree
git push origin epic/$EPIC_ID
gh pr create --title "Epic: {{SC_ARGS}} - $service" --body "Epic implementation for $service"
cd -
done
Final Epic spawn_agents:
CATCH (epic_implementation_failed):
Coordination Complexity: Multiple teams and repositories
/tmp/epic-coordination-$SESSION_ID.json tracks all statesIntegration Conflicts: Cross-service compatibility
Performance Regression: Epic implementation overhead
# Epic-wide rollback procedure
echo "🚨 Initiating epic rollback..."
echo "Rollback target: $1" # phase number or 'full'
# Rollback all worktrees to specified checkpoint
FOR worktree IN $(git worktree list | grep epic-$SESSION_ID | cut -f1 -d' '):
cd $worktree
git reset --hard epic-checkpoint-$1
cd -
done
# Update epic coordination state
jq '.status = "rollback" | .rollbackTarget = "'$1'"' /tmp/epic-coordination-$SESSION_ID.json > /tmp/epic-coordination-$SESSION_ID.tmp
mv /tmp/epic-coordination-$SESSION_ID.tmp /tmp/epic-coordination-$SESSION_ID.json
STEP 4: Resource allocation and team coordination setup
# Automatic team assignment based on repository analysis
echo "👥 Team allocation strategy:"
echo "Epic Coordinator: $(git config user.name)"
echo "Session ID: $SESSION_ID"
echo "Affected repositories: $(jq '.affectedRepositories | length' /tmp/epic-session-$SESSION_ID.json)"
# Create team assignment in coordination state
jq '.teamAllocation = {
"epicCoordinator": "'$(git config user.name)'",
"sessionId": "'$SESSION_ID'",
"worktreeStrategy": "parallel-isolation",
"coordinationMethod": "shared-state-files"
}' /tmp/epic-session-$SESSION_ID.json > /tmp/epic-session-$SESSION_ID.tmp
mv /tmp/epic-session-$SESSION_ID.tmp /tmp/epic-session-$SESSION_ID.json
/tmp/epic-coordination-$SESSION_ID.json# Real-time epic status command
/epic status
# Displays:
# - Current phase and completion percentage
# - Worktree status for each service
# - Integration test results
# - Performance benchmarks
# - Risk assessment and blockers
/tmp/epic-coordination-$SESSION_ID.json# Each worktree updates shared coordination state
echo "📊 Updating epic coordination state..."
jq '.repositories["'$CURRENT_SERVICE'"] = {
"status": "'$STATUS'",
"worktree": "'$PWD'",
"progress": '$PROGRESS',
"lastUpdate": "'$(gdate -Iseconds)'"
}' /tmp/epic-coordination-$SESSION_ID.json > /tmp/epic-coordination-$SESSION_ID.tmp
mv /tmp/epic-coordination-$SESSION_ID.tmp /tmp/epic-coordination-$SESSION_ID.json
STEP 5: Epic execution and coordination management
# Automated dependency checking
echo "🔗 Checking epic dependencies..."
jq -r '.dependencies[]?' /tmp/epic-session-$SESSION_ID.json 2>/dev/null || echo " - Dependencies auto-detected from repository analysis"
# Cross-service dependency validation
FOR service IN affected_services:
echo "Validating $service dependencies..."
# Check if dependent services are ready
done
# Real-time blocker identification
echo "⚠️ Epic blockers analysis:"
jq -r '.blockers[]?' /tmp/epic-coordination-$SESSION_ID.json 2>/dev/null || echo " - No blockers detected"
# Performance regression detection
echo "📈 Performance regression monitoring active"
# Epic performance metrics collection
echo "📊 Epic performance metrics:"
echo "Baseline metrics: $(jq -r '.performanceBaseline' /tmp/epic-session-$SESSION_ID.json 2>/dev/null || echo 'Collecting...')"
echo "Current metrics: $(jq -r '.currentPerformance' /tmp/epic-coordination-$SESSION_ID.json 2>/dev/null || echo 'Monitoring...')"
# Automated success criteria validation
echo "✅ Epic success validation:"
echo "Target achieved: {{SC_ARGS}}"
echo "All services migrated: $(jq -r '.allServicesMigrated' /tmp/epic-coordination-$SESSION_ID.json)"
echo "Performance targets met: $(jq -r '.performanceTargetsMet' /tmp/epic-coordination-$SESSION_ID.json)"
echo "Zero incidents: $(jq -r '.zeroIncidents' /tmp/epic-coordination-$SESSION_ID.json)"
STEP 6: Repository-specific plan generation with sub-agent delegation
LAUNCH parallel sub-agents for repository-specific planning:
FOR EACH repository IN affected_repositories:
Example Generated Service Plan Template:
# {Service} Epic Implementation Plan
## Epic Integration
- **Epic Session ID**: $SESSION_ID
- **Epic Target**: {{SC_ARGS}}
- **Service Worktree**: ../epic-{service}-$SESSION_ID
- **Coordination State**: /tmp/epic-coordination-$SESSION_ID.json
## Implementation Strategy
### STEP 1: Worktree Setup and Isolation
```bash
# Create dedicated worktree for this service
git worktree add ../epic-{service}-$SESSION_ID epic/$EPIC_ID-{service}
cd ../epic-{service}-$SESSION_ID
# Update coordination state
jq '.repositories["{service}"] = {
"status": "worktree-created",
"worktree": "'$PWD'",
"startTime": "'$(gdate -Iseconds)'"
}' /tmp/epic-coordination-$SESSION_ID.json > /tmp/epic-coordination-$SESSION_ID.tmp
```
STEP 7: Cross-repository coordination with shared state management
**Epic Coordination State Management:**
```bash
# Initialize comprehensive coordination state
echo '{
"epicId": "epic-'$SESSION_ID'",
"epicTarget": "'{{SC_ARGS}}'",
"status": "in_progress",
"currentPhase": "phase_1",
"sessionId": "'$SESSION_ID'",
"initiatedBy": "'$(git config user.name)'",
"startTime": "'$(gdate -Iseconds)'",
"repositories": {},
"worktrees": {},
"milestones": {
"phase_1_target": "'$(gdate -d '+1 week' -Iseconds 2>/dev/null || date -d '+1 week' -Iseconds 2>/dev/null || echo 'Week 1')'",
"phase_2_target": "'$(gdate -d '+3 weeks' -Iseconds 2>/dev/null || date -d '+3 weeks' -Iseconds 2>/dev/null || echo 'Week 3')'",
"epic_completion_target": "'$(gdate -d '+12 weeks' -Iseconds 2>/dev/null || date -d '+12 weeks' -Iseconds 2>/dev/null || echo 'Week 12')'"
},
"performanceBaseline": {},
"risks": [],
"blockers": []
}' > /tmp/epic-coordination-$SESSION_ID.json
Real-time Coordination Monitoring:
# Epic status command for real-time monitoring
alias epic-status='jq -r "Epic: \(.epicTarget) | Status: \(.status) | Phase: \(.currentPhase) | Repositories: \(.repositories | length)" /tmp/epic-coordination-$SESSION_ID.json'
# Repository status summary
alias epic-repos='jq -r ".repositories | to_entries[] | \"\(.key): \(.value.status) (\(.value.progress // 0)%)\"" /tmp/epic-coordination-$SESSION_ID.json'
STEP 8: Epic orchestration and automation with modern tooling
Epic Management Commands:
# Epic orchestration functions
epic_status() {
echo "📊 Epic Status: $(jq -r '.status' /tmp/epic-coordination-$SESSION_ID.json)"
echo "🎯 Current Phase: $(jq -r '.currentPhase' /tmp/epic-coordination-$SESSION_ID.json)"
echo "📁 Repositories: $(jq -r '.repositories | length' /tmp/epic-coordination-$SESSION_ID.json)"
echo "🌿 Worktrees: $(jq -r '.worktrees | length' /tmp/epic-coordination-$SESSION_ID.json)"
echo "\n📋 Repository Status:"
jq -r '.repositories | to_entries[] | " \(.key): \(.value.status)"' /tmp/epic-coordination-$SESSION_ID.json
}
epic_start_phase() {
local PHASE=$1
echo "🚀 Starting Epic Phase $PHASE"
# Update coordination state
jq '.currentPhase = "phase_'$PHASE'" | .phases["phase_'$PHASE'"].startTime = "'$(gdate -Iseconds)'"' \
/tmp/epic-coordination-$SESSION_ID.json > /tmp/epic-coordination-$SESSION_ID.tmp
mv /tmp/epic-coordination-$SESSION_ID.tmp /tmp/epic-coordination-$SESSION_ID.json
# Launch sub-agents for parallel phase execution
echo "🔄 Launching parallel sub-agents for phase $PHASE..."
}
epic_create_worktrees() {
echo "🌿 Creating git worktrees for parallel development..."
jq -r '.repositories | keys[]' /tmp/epic-coordination-$SESSION_ID.json | while read repo; do
local worktree_path="../epic-$repo-$SESSION_ID"
git worktree add $worktree_path epic/$SESSION_ID-$repo
# Update coordination state with worktree info
jq '.worktrees["'$repo'"] = {
"path": "'$worktree_path'",
"branch": "epic/'$SESSION_ID'-'$repo'",
"createdAt": "'$(gdate -Iseconds)'"
}' /tmp/epic-coordination-$SESSION_ID.json > /tmp/epic-coordination-$SESSION_ID.tmp
mv /tmp/epic-coordination-$SESSION_ID.tmp /tmp/epic-coordination-$SESSION_ID.json
echo " ✅ Created worktree: $worktree_path"
done
}
epic_create_prs() {
echo "🔄 Creating pull requests for all epic services..."
jq -r '.worktrees | to_entries[]' /tmp/epic-coordination-$SESSION_ID.json | while read worktree_info; do
local repo=$(echo $worktree_info | jq -r '.key')
local path=$(echo $worktree_info | jq -r '.value.path')
cd $path
gh pr create --title "Epic: {{SC_ARGS}} - $repo" --body "$(cat <<'EOF'
## Epic Implementation
- Epic Session: $SESSION_ID
- Epic Target: {{SC_ARGS}}
- Repository: $repo
## Changes
- Implemented epic target for $repo
- Following epic coordination strategy
- Comprehensive testing and validation
## Epic Coordination
- Coordination state: `/tmp/epic-coordination-$SESSION_ID.json`
- Worktree path: $path
- Integration tested with other epic services
EOF
)"
cd -
done
}
STEP 9: Automated progress tracking and epic dashboard generation
Real-time Epic Dashboard Generation:
# Generate epic dashboard from coordination state
epic_generate_dashboard() {
local epic_target=$(jq -r '.epicTarget' /tmp/epic-coordination-$SESSION_ID.json)
local current_phase=$(jq -r '.currentPhase' /tmp/epic-coordination-$SESSION_ID.json)
local session_id=$(jq -r '.sessionId' /tmp/epic-coordination-$SESSION_ID.json)
cat > epic-dashboard-$SESSION_ID.md <<EOF
# Epic Progress Dashboard: $epic_target
## Epic Overview
- **Session ID**: $session_id
- **Epic Target**: $epic_target
- **Current Phase**: $current_phase
- **Started**: $(jq -r '.startTime' /tmp/epic-coordination-$SESSION_ID.json)
- **Coordinator**: $(jq -r '.initiatedBy' /tmp/epic-coordination-$SESSION_ID.json)
## Repository Status
$(jq -r '.repositories | to_entries[] | "- **\(.key)**: \(.value.status) (\(.value.progress // 0)%)"' /tmp/epic-coordination-$SESSION_ID.json)
## Worktree Status
$(jq -r '.worktrees | to_entries[] | "- **\(.key)**: \(.value.path) (\(.value.branch))"' /tmp/epic-coordination-$SESSION_ID.json)
## Current Blockers
$(jq -r '.blockers[]?' /tmp/epic-coordination-$SESSION_ID.json 2>/dev/null | sed 's/^/- /' || echo "- No blockers detected")
## Performance Metrics
- **Baseline**: $(jq -r '.performanceBaseline // "Collecting..."' /tmp/epic-coordination-$SESSION_ID.json)
- **Current**: $(jq -r '.currentPerformance // "Monitoring..."' /tmp/epic-coordination-$SESSION_ID.json)
## Next Actions
- Continue current phase implementation
- Monitor worktree progress
- Update coordination state regularly
---
*Auto-generated from epic coordination state at $(gdate)*
EOF
echo "📊 Epic dashboard generated: epic-dashboard-$SESSION_ID.md"
}
Automated Progress Reporting:
# Real-time progress updates
epic_update_progress() {
local repo=$1
local status=$2
local progress=$3
jq '.repositories["'$repo'"].status = "'$status'" |
.repositories["'$repo'"].progress = '$progress' |
.repositories["'$repo'"].lastUpdate = "'$(gdate -Iseconds)'"' \
/tmp/epic-coordination-$SESSION_ID.json > /tmp/epic-coordination-$SESSION_ID.tmp
mv /tmp/epic-coordination-$SESSION_ID.tmp /tmp/epic-coordination-$SESSION_ID.json
echo "📈 Updated $repo: $status ($progress%)"
}
FINALLY:
/epic "Migrate all services from REST to gRPC"
/epic status
# Real-time status from coordination state
/epic continue
# Resumes from saved session state
/epic rollback --to-phase 1
# Rolls back all worktrees to specified phase
/epic dashboard
# Creates epic-dashboard-$SESSION_ID.md
# Epic automatically creates isolated development environments
echo "🌿 Creating epic worktree infrastructure..."
FOR service IN affected_services:
git worktree add ../epic-$service-$SESSION_ID epic/$SESSION_ID-$service
echo " ✅ Worktree: ../epic-$service-$SESSION_ID"
done
# Generate dependency visualization
epic_generate_dependency_graph() {
echo "📊 Generating epic dependency graph..."
cat > epic-dependencies-$SESSION_ID.mermaid <<EOF
graph TD
$(jq -r '.repositories | to_entries[] | " \(.key)[\(.key)]"' /tmp/epic-coordination-$SESSION_ID.json)
$(jq -r '.dependencies[]?' /tmp/epic-coordination-$SESSION_ID.json 2>/dev/null | sed 's/^/ /' || echo " # Dependencies auto-detected")
EOF
echo "📈 Dependency graph: epic-dependencies-$SESSION_ID.mermaid"
}
# Coordinated testing across all epic worktrees
epic_run_integration_tests() {
echo "🧪 Running epic integration tests..."
# Test each worktree in parallel
jq -r '.worktrees | to_entries[]' /tmp/epic-coordination-$SESSION_ID.json | while read worktree_info; do
local repo=$(echo $worktree_info | jq -r '.key')
local path=$(echo $worktree_info | jq -r '.value.path')
(
cd $path
echo "Testing $repo in worktree $path..."
# Run repository-specific tests
deno task test 2>/dev/null || npm test 2>/dev/null || cargo test 2>/dev/null || mvn test 2>/dev/null || echo "No test command found for $repo"
) &
done
wait # Wait for all parallel tests to complete
echo "✅ Epic integration testing completed"
}