aios-core
Version:
Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework
327 lines (285 loc) • 16.9 kB
YAML
# ============================================
# Epic Orchestration Workflow Template
#
# Generic, reusable template for executing epics
# with wave-based parallel execution and quality gates.
#
# Each story within a wave runs the full development-cycle
# (PO validates → Executor develops → Self-healing → Quality Gate → DevOps push)
#
# Project-specific execution plans reference this template
# and live in docs/stories/epics/{epic-name}/
#
# @version 1.0.0
# @author @pm (Bob) + @architect (Aria)
# ============================================
workflow:
id: epic-orchestration
name: "Epic Wave Orchestration"
version: "1.0.0"
description: >-
Reusable template for executing epics with wave-based parallel development.
Stories within each wave run the full development-cycle workflow
(PO → Executor → Self-Healing → Quality Gate → DevOps → Checkpoint).
Wave gates validate integration before proceeding to next wave.
Supports worktree isolation for conflict-free parallel development.
type: epic-orchestration
project_types:
- greenfield
- brownfield
- aios-development
- epic-execution
metadata:
elicit: true
confirmation_required: true
# ═══════════════════════════════════════════════════════════════════════════════════
# EXECUTION MODES
# ═══════════════════════════════════════════════════════════════════════════════════
execution_modes:
- mode: yolo
description: Autonomous - waves run with minimal interaction, checkpoints auto-GO
prompts: 0-2
- mode: interactive
description: Human checkpoints between waves and at quality gates
prompts: 5-10
default: true
- mode: preflight
description: Full dependency analysis before execution begins
prompts: 10-15
# ═══════════════════════════════════════════════════════════════════════════════════
# CONFIGURATION (overridden by project execution plan)
# ═══════════════════════════════════════════════════════════════════════════════════
config:
# These values are OVERRIDDEN by the project-specific execution plan
epicId: "${epicId}"
epicIndex: "${epicIndex}"
storyBasePath: "${storyBasePath}"
# Parallel execution defaults
maxConcurrency: 4
worktreeIsolation: true
# Timeouts
storyTimeout: 7200000 # 2 hours per story (development-cycle total)
gateTimeout: 1800000 # 30 min per wave gate
totalTimeout: 43200000 # 12 hours total
# Quality gates
gatePolicy: strict # strict | lenient | skip
requireIntegrationReview: true
# ═══════════════════════════════════════════════════════════════════════════════════
# INNER WORKFLOW
# ═══════════════════════════════════════════════════════════════════════════════════
#
# Each story within a wave executes the full development-cycle:
#
# Phase 1: @po validates story (validate-story-draft)
# Phase 2: ${story.executor} develops (dynamic executor)
# Phase 3: @dev self-healing (CodeRabbit, conditional)
# Phase 4: ${story.quality_gate} reviews (agent != executor)
# Phase 5: @devops push & PR
# Phase 6: @po checkpoint (AUTO-GO in wave mode, human in interactive)
#
# Reference: .aios-core/development/workflows/development-cycle.yaml
inner_workflow:
ref: development-cycle
per_story: true
checkpoint_mode:
in_wave: auto_go # Don't pause between parallel stories
between_waves: interactive # Pause for human decision between waves
# ═══════════════════════════════════════════════════════════════════════════════════
# WAVE EXECUTION PATTERN
# ═══════════════════════════════════════════════════════════════════════════════════
#
# Waves are defined in the project-specific execution plan.
# This template defines the PATTERN each wave follows:
#
# ┌─────────────────────────────────────────────────────┐
# │ WAVE N │
# │ │
# │ Story A ──→ development-cycle ──→ branch pushed │
# │ Story B ──→ development-cycle ──→ branch pushed │ PARALLEL
# │ Story C ──→ development-cycle ──→ branch pushed │
# │ │
# │ ──→ WAVE GATE (integration review) ──→ merge │
# └─────────────────────────────────────────────────────┘
wave_pattern:
# Step 1: Per-story development (parallel within wave)
story_execution:
parallel: true
max_concurrency: "${config.maxConcurrency}"
worktree_isolation: "${config.worktreeIsolation}"
workflow: development-cycle
inputs:
story_file: "${story.file}"
epic_context:
epicId: "${config.epicId}"
waveNumber: "${wave.number}"
totalWaves: "${wave.total}"
# Step 2: Wave gate (sequential, after all stories in wave complete)
wave_gate:
description: "Integration review after wave completes"
steps:
- id: integration-review
agent: "${wave.gate_agent}"
action: review_wave_integration
notes: |
Review focus (per-story QA already done in development-cycle):
- Cross-story integration compatibility
- Shared file conflict detection
- Combined test suite passes
- No regressions from parallel changes
- Architecture consistency across stories
- id: merge-wave
agent: devops
action: merge_wave_branches
condition: gate_approved
notes: |
Merge all wave branches to main:
- Follow merge order from execution plan
- Resolve conflicts if any
- Run full test suite on merged result
- Tag: wave-{N}-complete
- Clean up worktrees
# Step 3: Human checkpoint (between waves)
checkpoint:
agent: po
elicit: true
options:
GO: "Continue to next wave"
PAUSE: "Save state, stop execution"
REVIEW: "Show wave summary before deciding"
ABORT: "Stop the epic"
on_go: next_wave
on_pause: save_state
on_abort: abort_epic
# ═══════════════════════════════════════════════════════════════════════════════════
# STATE MANAGEMENT
# ═══════════════════════════════════════════════════════════════════════════════════
state:
persistence:
enabled: true
location: ".aios/workflow-state/"
format: json
file: "${config.epicId}-pipeline.json"
tracked_fields:
- current_wave
- wave_status
- story_statuses
- gate_verdicts
- started_at
- last_updated
recovery:
enabled: true
auto_resume: true
resume_from: last_completed_wave
# ═══════════════════════════════════════════════════════════════════════════════════
# ERROR HANDLING
# ═══════════════════════════════════════════════════════════════════════════════════
error_handling:
story_failed:
description: "A story's development-cycle failed"
action: |
- development-cycle handles retries internally (max 3 attempts)
- If still failing, mark story as blocked
- Continue other parallel stories in wave
- Report blocked story at wave gate
escalation: wave_gate
gate_failed:
description: "Wave integration gate failed"
action: |
- Identify failing stories/integrations
- Create fix tasks for specific issues
- Re-run development-cycle for affected stories
- Re-submit for gate review
max_retries: 2
escalation: human
merge_conflict:
description: "Conflict during wave branch merge"
action: |
- Follow merge order from execution plan
- Resolve conflicts in recommended order
- Re-run tests after resolution
escalation: human
# ═══════════════════════════════════════════════════════════════════════════════════
# FLOW DIAGRAM
# ═══════════════════════════════════════════════════════════════════════════════════
flow_diagram: |
```
┌─────────────────────────────────────────────────────────────┐
│ EPIC WAVE ORCHESTRATION │
└─────────────────────────────────────────────────────────────┘
For each WAVE defined in project execution plan:
┌─────────────────────────────────────────────────────────────┐
│ WAVE N (stories run in PARALLEL) │
│ │
│ Story A ──→ development-cycle ──→ branch pushed │
│ (PO validate → Executor dev → Self-heal → QA → Push) │
│ │
│ Story B ──→ development-cycle ──→ branch pushed │
│ (PO validate → Executor dev → Self-heal → QA → Push) │
│ │
│ Story C ──→ development-cycle ──→ branch pushed │
│ (PO validate → Executor dev → Self-heal → QA → Push) │
└───────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ WAVE GATE (integration review only - per-story QA done) │
│ │
│ gate_agent: Review cross-story integration │
│ @devops: Merge branches → main │
└───────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ CHECKPOINT (between waves) │
│ │
│ @po asks: [ GO ] [ PAUSE ] [ REVIEW ] [ ABORT ] │
└───────────────────────┬─────────────────────────────────────┘
│
▼
Next Wave...
```
# ═══════════════════════════════════════════════════════════════════════════════════
# DECISION GUIDANCE
# ═══════════════════════════════════════════════════════════════════════════════════
decision_guidance:
when_to_use:
- Epic with 4+ stories that can be grouped into parallel waves
- Stories have clear dependency graph (some parallel, some sequential)
- Need quality gates between groups of related stories
- Team has capacity for parallel development streams
when_not_to_use:
- Epic with 1-3 stories (use story-development-cycle directly)
- All stories are strictly sequential (use story-development-cycle in loop)
- Simple bug fixes without integration concerns
how_to_use:
- Create project execution plan in docs/stories/epics/{epic}/
- Define waves, story assignments, branches, gates
- Reference this template as the orchestration pattern
- Execute via WorkflowOrchestrator with execution plan config
# ═══════════════════════════════════════════════════════════════════════════════════
# RELATED WORKFLOWS
# ═══════════════════════════════════════════════════════════════════════════════════
related:
- id: development-cycle
role: "Inner loop - runs per story within each wave"
file: development-cycle.yaml
- id: qa-loop
role: "QA review cycle - used within development-cycle Phase 4"
file: qa-loop.yaml
- id: auto-worktree
role: "Worktree creation - used for parallel story isolation"
file: auto-worktree.yaml
- id: story-development-cycle
role: "Simplified story cycle (legacy) - use development-cycle instead"
file: story-development-cycle.yaml
metadata:
author: "@pm (Bob) + @architect (Aria)"
created: "2026-02-06"
version: 1.0.0
tags:
- epic-orchestration
- parallel-execution
- wave-executor
- quality-gates
- worktree-isolation
- reusable-template