> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows Overview

> Introduction to AIOX multi-agent workflows and orchestration patterns

## What are Workflows?

Workflows in Synkra AIOX orchestrate multiple tasks and agents to accomplish complex operations. They provide structured sequences of actions that guide development from planning through deployment.

<Note>
  Workflows are the coordination layer that transforms individual agent capabilities into cohesive development processes.
</Note>

## Workflow Types

AIOX supports several workflow patterns for different development scenarios:

### 1. Story Development Cycle (Primary)

The core workflow for all feature development:

```mermaid theme={null}
graph LR
    A[@sm: Draft Story] --> B[@po: Validate]
    B --> C[@dev: Implement]
    C --> D[@qa: Review]
    D --> E[@devops: Deploy]
```

**Agents involved:** SM → PO → Dev → QA → DevOps

**Duration:** 1-5 days

**Use when:** Implementing any new feature or change

### 2. Epic Creation Workflow

Breaks down large initiatives into actionable stories:

```mermaid theme={null}
graph LR
    A[@po: Plan Epic] --> B[@sm: Create Stories]
    B --> C[@architect: Review]
    C --> D[Stories Ready]
```

**Agents involved:** PO → SM → Architect

**Duration:** 0.5-2 days

**Use when:** Starting a new epic or major feature set

### 3. Planning Workflow

Pre-implementation specification and research:

```mermaid theme={null}
graph TD
    A[@analyst: Research] --> B[@pm: Requirements]
    B --> C[@architect: Impact Analysis]
    C --> D[@sm: Story Creation]
```

**Agents involved:** Analyst → PM → Architect → SM

**Duration:** 0.5-2 days

**Use when:** Complex features requiring upfront research

### 4. Quality Gates Workflow

Three-layer validation system:

```mermaid theme={null}
graph TD
    A[Layer 1: Pre-commit] --> B{Pass?}
    B -->|Yes| C[Layer 2: PR Automation]
    B -->|No| D[Fix Issues]
    D --> A
    C --> E{Pass?}
    E -->|Yes| F[Layer 3: Human Review]
    E -->|No| D
    F --> G[Merge]
```

**Agents involved:** Dev → QA → DevOps → Human reviewers

**Duration:** Continuous

**Use when:** Every code change before merge

## Workflow Characteristics

<CardGroup cols={2}>
  <Card title="Task-First Architecture" icon="list-check">
    Every workflow step maps to a specific task file in `.aiox-core/development/tasks/`
  </Card>

  <Card title="Agent Transitions" icon="arrow-right-arrow-left">
    Workflows define clear handoff points between specialized agents
  </Card>

  <Card title="State Persistence" icon="floppy-disk">
    Workflow state is saved to `.aiox/{instance-id}-state.yaml` for cross-session continuity
  </Card>

  <Card title="Confidence Gates" icon="shield-check">
    Each transition includes confidence thresholds to ensure quality progression
  </Card>
</CardGroup>

## Workflow Execution Modes

### Interactive Mode (Default)

Pauses at key decision points for human input:

```bash theme={null}
*run-workflow story-development --mode=interactive
```

### YOLO Mode (Autonomous)

Runs end-to-end without interruption:

```bash theme={null}
*run-workflow story-development --mode=yolo
```

### Pre-flight Mode

Plans all steps upfront, then executes:

```bash theme={null}
*run-workflow story-development --mode=preflight
```

## Workflow State Management

AIOX tracks workflow progress in YAML state files:

```yaml theme={null}
workflow_id: story_development
current_phase: 3
status: in_progress
started_at: 2026-03-05T10:30:00Z
phases_completed:
  - validate-story-draft
  - develop
current_context:
  story_id: "3.1"
  story_path: "docs/stories/3.1-feature-name.md"
```

### State Commands

```bash theme={null}
# Check current workflow status
*run-workflow {name} status

# Continue from last checkpoint
*run-workflow {name} continue

# Skip optional step
*run-workflow {name} skip

# Abort workflow (preserves state)
*run-workflow {name} abort
```

## Common Workflow Patterns

### Fork-Join Pattern

Execute multiple tasks in parallel, then synchronize:

```yaml theme={null}
phases:
  - name: parallel-implementation
    type: fork-join
    parallel_tasks:
      - agent: dev
        task: implement-frontend
      - agent: dev  
        task: implement-backend
    join_condition: all_complete
```

### Organizer-Worker Pattern

One agent delegates to multiple workers:

```yaml theme={null}
phases:
  - name: epic-execution
    agent: pm
    task: execute-epic
    delegates:
      - agent: dev
      - agent: qa
      - agent: devops
```

### Iterative Loop Pattern

Repeat until quality criteria met:

```yaml theme={null}
phases:
  - name: qa-loop
    type: iterative
    max_iterations: 5
    steps:
      - agent: qa
        task: review
      - agent: dev
        task: apply-fixes
    exit_condition: qa_verdict == APPROVE
```

## Workflow Intelligence

AIOX uses pattern detection to suggest next steps:

<Steps>
  <Step title="Detect Context">
    Analyzes recent command history and current project state
  </Step>

  <Step title="Match Patterns">
    Compares against known workflow patterns in `workflow-patterns.yaml`
  </Step>

  <Step title="Calculate Confidence">
    Determines likelihood of workflow match (threshold: 0.80)
  </Step>

  <Step title="Suggest Next">
    Presents recommended next commands with context
  </Step>
</Steps>

## Integration with Quality Gates

Workflows automatically enforce quality gates at key transitions:

| Transition              | Quality Gate     | Required Checks                           |
| ----------------------- | ---------------- | ----------------------------------------- |
| Draft → Approved        | Story Validation | Acceptance criteria, file list, structure |
| Implementation → Review | Pre-commit       | Lint, typecheck, tests, build             |
| Review → Merge          | PR Automation    | CodeRabbit, Quinn review, CI              |
| Merge → Deploy          | Human Review     | Architecture approval, final sign-off     |

## Next Steps

<CardGroup cols={2}>
  <Card title="Planning Workflow" icon="diagram-project" href="/workflows/planning">
    Learn about the analyst → PM → architect → SM planning sequence
  </Card>

  <Card title="Development Cycle" icon="code" href="/workflows/development-cycle">
    Explore the core SM → Dev → QA → DevOps development workflow
  </Card>

  <Card title="Quality Gates" icon="shield-check" href="/workflows/quality-gates">
    Understand the three-layer quality validation system
  </Card>

  <Card title="Workflow Commands" icon="terminal" href="/essentials/commands">
    Reference for all workflow management commands
  </Card>
</CardGroup>

## Related Documentation

* [Agent Reference](/essentials/agents) - Individual agent capabilities
* [Tasks Overview](/essentials/tasks) - Task definitions and execution
* [Story-Driven Development](/guides/story-driven-development) - Core development methodology
* [Quality Gates Guide](/workflows/quality-gates) - Validation layers explained