> ## 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

> Orchestrated sequences of agent interactions for complex development processes

## Overview

Workflows in AIOX are **prescribed sequences of steps and agent interactions** for specific project types and development scenarios. They act as strategic guides for users and orchestrating agents.

<Card title="Workflow Philosophy" icon="route">
  Workflows define the **"what" and "when"** of agent collaboration, ensuring consistent, high-quality execution of complex processes.
</Card>

## Workflow Architecture

Workflows are defined in YAML format and stored in `.aiox-core/development/workflows/`:

```yaml theme={null}
workflow:
  id: greenfield-fullstack
  name: Greenfield Full-Stack Development
  description: Complete workflow for new full-stack projects
  type: development
  
  steps:
    - id: step-1
      name: Project Ideation
      agent: analyst
      tasks:
        - market-research
        - competitive-analysis
      output: project-brief.md
      
    - id: step-2
      name: Requirements Definition
      agent: pm
      tasks:
        - create-prd
      output: prd.md
      dependencies: [step-1]
```

## Available Workflows

### Development Workflows

<Tabs>
  <Tab title="Greenfield">
    **New Projects Starting from Scratch**

    <AccordionGroup>
      <Accordion title="greenfield-fullstack.yaml" icon="layer-group">
        **Complete full-stack application development**

        **Phases:**

        1. Project ideation and market research
        2. PRD creation
        3. Architecture design
        4. UI/UX specification
        5. Database schema design
        6. Backend implementation
        7. Frontend implementation
        8. Integration and testing
        9. Deployment

        **Agents involved:** @analyst, @pm, @architect, @ux-design-expert, @data-engineer, @dev, @qa, @devops

        **Typical duration:** 2-8 weeks depending on complexity
      </Accordion>

      <Accordion title="greenfield-service.yaml" icon="server">
        **Backend service/API development**

        **Phases:**

        1. Service requirements
        2. API design
        3. Database schema
        4. Implementation
        5. Testing
        6. Deployment

        **Agents involved:** @pm, @architect, @data-engineer, @dev, @qa, @devops

        **Best for:** Microservices, API backends, serverless functions
      </Accordion>

      <Accordion title="greenfield-ui.yaml" icon="palette">
        **Frontend/UI application development**

        **Phases:**

        1. UX research
        2. Wireframing
        3. Design system definition
        4. Component implementation
        5. Integration
        6. Testing
        7. Deployment

        **Agents involved:** @ux-design-expert, @pm, @dev, @qa, @devops

        **Best for:** Web apps, mobile UIs, dashboard projects
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Brownfield">
    **Existing Codebases Requiring Assessment or Enhancement**

    <AccordionGroup>
      <Accordion title="brownfield-discovery.yaml" icon="magnifying-glass">
        **10-Phase Technical Debt Assessment**

        **Comprehensive audit workflow:**

        <Steps>
          <Step title="Phase 1: Initial Assessment">
            @architect analyzes overall system architecture

            **Output:** `system-architecture.md`
          </Step>

          <Step title="Phase 2: Database Audit">
            @data-engineer audits schema, RLS policies, migrations

            **Output:** `SCHEMA.md`, `DB-AUDIT.md`
          </Step>

          <Step title="Phase 3: Frontend Audit">
            @ux-design-expert audits UI/UX, components, design system

            **Output:** `frontend-spec.md`
          </Step>

          <Step title="Phase 4: Code Quality Review">
            @qa reviews code quality, tests, technical debt

            **Output:** Quality report with APPROVED/NEEDS WORK verdict
          </Step>

          <Step title="Phase 5: Epic Creation">
            @pm creates improvement epics with prioritized stories

            **Output:** Epic files with implementation stories
          </Step>
        </Steps>

        **Use when:** Inheriting legacy code, conducting health checks, planning refactoring
      </Accordion>

      <Accordion title="brownfield-fullstack.yaml" icon="wrench">
        **Enhancement workflow for existing full-stack apps**

        Assumes discovery phase complete, focuses on incremental improvements.
      </Accordion>

      <Accordion title="brownfield-service.yaml" icon="gears">
        **Enhancement workflow for existing backend services**
      </Accordion>

      <Accordion title="brownfield-ui.yaml" icon="paintbrush">
        **Enhancement workflow for existing frontend applications**
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Configuration">
    **Environment & Tooling Setup**

    <Accordion title="setup-environment.yaml" icon="gear">
      **IDE configuration for AIOX development**

      **Steps:**

      1. Detect installed IDEs (Cursor, Claude Code, etc.)
      2. Backup existing configurations
      3. Apply AIOX-specific rules
      4. Verify GitHub CLI installation/authentication
      5. Confirm successful setup

      **Locations:**

      * Cursor: `.cursorules`
      * Claude Code: `.claude/CLAUDE.md`

      **Command:** `aiox aiox-master setup-environment`
    </Accordion>
  </Tab>
</Tabs>

## Workflow Patterns

Common workflow sequences are defined in `.aiox-core/data/workflow-patterns.yaml`:

### Story Development Cycle (Primary)

<Card title="Most Common Workflow" icon="repeat">
  Complete story lifecycle from validation to deployment
</Card>

```mermaid theme={null}
graph TD
    A[@sm draft story] --> B[@po validate-story-draft]
    B -->|Approved| C[@dev develop]
    B -->|Needs Changes| A
    C --> D[@qa review]
    D -->|PASS| E[@devops pre-push-quality-gate]
    D -->|Needs Work| F[@dev apply-qa-fixes]
    F --> D
    E --> G[@devops push]
    
    style A fill:#1a73e8,color:#fff
    style B fill:#f9ab00,color:#fff
    style C fill:#34a853,color:#fff
    style D fill:#ea4335,color:#fff
    style E fill:#f9ab00,color:#fff
    style G fill:#34a853,color:#fff
```

**Key Commands:**

* `validate-story-draft`
* `develop` / `develop-yolo` / `develop-interactive`
* `review-qa`
* `pre-push-quality-gate`
* `github-pr-automation`

**Typical Duration:** 1-5 days

**Success Indicators:**

* Story status: "Ready for Review"
* All tests passing
* PR created and merged

### Epic Creation Workflow

<Card title="Planning & Organization" icon="folder-tree">
  Create and organize epics with initial stories
</Card>

```mermaid theme={null}
graph LR
    A[@po create-epic] --> B[@sm create-story]
    B --> C[@architect analyze-impact]
    C --> D[@po validate-story-draft]
    D --> E[Ready for Development]
    
    style A fill:#1a73e8,color:#fff
    style B fill:#f9ab00,color:#fff
    style C fill:#34a853,color:#fff
    style D fill:#f9ab00,color:#fff
    style E fill:#34a853,color:#fff
```

**Agent Sequence:** @po → @sm → @architect

**Typical Duration:** 0.5-2 days

### QA Loop (Iterative Review)

<Card title="Automated Review-Fix Cycle" icon="arrows-rotate">
  Continues until code meets quality standards (max 5 iterations)
</Card>

```mermaid theme={null}
graph TD
    A[@qa review] --> B{Verdict?}
    B -->|APPROVE| C[Complete]
    B -->|REJECT| D[@dev fix-qa-issues]
    D --> E[Apply Fixes]
    E --> A
    B -->|BLOCKED| F[Escalate]
    
    style A fill:#f9ab00,color:#fff
    style C fill:#34a853,color:#fff
    style D fill:#1a73e8,color:#fff
    style F fill:#dc3545,color:#fff
```

**Max Iterations:** 5 before escalation

### Database Development Workflow

<Card title="Schema Design & Migration" icon="database">
  Safe, validated database changes
</Card>

```mermaid theme={null}
graph LR
    A[@data-engineer db-domain-modeling] --> B[@data-engineer db-schema-audit]
    B --> C[@data-engineer db-dry-run]
    C --> D{Safe?}
    D -->|Yes| E[@data-engineer db-apply-migration]
    D -->|No| A
    E --> F[@data-engineer db-smoke-test]
    F --> G[@data-engineer db-rls-audit]
    
    style A fill:#1a73e8,color:#fff
    style E fill:#34a853,color:#fff
    style G fill:#f9ab00,color:#fff
```

**Agent:** @data-engineer (primary)

**Key Commands:**

* `db-domain-modeling` - Design schema
* `db-schema-audit` - Audit for best practices
* `db-dry-run` - Test migration safely
* `db-apply-migration` - Execute migration
* `db-rls-audit` - Validate security policies

**Typical Duration:** 1-3 days

## Workflow Intelligence

AIOX includes sophisticated workflow detection and suggestion systems:

### Pattern-Based Detection

<Card title="Context-Aware Suggestions" icon="lightbulb">
  Agents detect workflow context from command history and suggest next steps.
</Card>

**How it works:**

<Steps>
  <Step title="Command Tracking">
    System tracks executed commands in current session
  </Step>

  <Step title="Pattern Matching">
    Compares command history to workflow patterns in `workflow-patterns.yaml`
  </Step>

  <Step title="Workflow Detection">
    When threshold met (default: 2 matching commands), workflow is detected
  </Step>

  <Step title="Next Step Suggestion">
    Agent greeting includes suggested next command based on workflow chain
  </Step>
</Steps>

**Example:**

User executed:

1. `aiox sm draft`
2. `aiox po validate-story-draft story-1.2.3`

Agent detects: **Story Development Cycle**

Next greeting suggests:

```
💡 Suggested: *develop story-1.2.3
Also: *develop-yolo story-1.2.3, *develop-preflight story-1.2.3
```

### State-Based Workflows

<Card title="File-Based State Persistence" icon="file">
  Workflows can maintain state across sessions using YAML files in `.aiox/`
</Card>

**State File Location:** `.aiox/{instance-id}-state.yaml`

**State File Schema:**

```yaml theme={null}
workflow_id: story-development-cycle
current_step: 3
story_id: story-1.2.3
status: in_progress
steps_completed:
  - validate-story-draft
  - develop
steps_remaining:
  - review-qa
  - pre-push-quality-gate
  - push
last_updated: 2026-03-05T14:30:00Z
```

**Commands:**

* `*run-workflow {name} start` - Create state file, begin workflow
* `*run-workflow {name} continue` - Resume from last checkpoint
* `*run-workflow {name} status` - Show progress
* `*run-workflow {name} skip` - Skip optional step
* `*run-workflow {name} abort` - Abort workflow (preserves state)

**Benefits:**

* Session continuity across restarts
* Progress tracking
* Resume capability
* Handoff support

### Workflow Chains

Defined in `.aiox-core/data/workflow-chains.yaml`, chains specify exact command sequences:

```yaml theme={null}
chain:
  - step: 1
    agent: "@sm"
    command: "*draft"
    task: create-next-story.md
    output: Story file (Draft)
    condition: Epic context available
    
  - step: 2
    agent: "@po"
    command: "*validate-story-draft {story-id}"
    task: validate-next-story.md
    output: GO/NO-GO decision
    condition: Story status is Draft
    
  - step: 3
    agent: "@dev"
    command: "*develop {story-id}"
    task: dev-develop-story.md
    output: Implementation complete
    condition: Story status is Approved
    alternatives:
      - agent: "@dev"
        command: "*develop-yolo {story-id}"
        condition: Simple story, autonomous mode preferred
```

**Agent Greeting Integration:**

When agent activates, it:

1. Checks `.aiox/handoffs/` for unconsumed handoff
2. Reads `from_agent` and `last_command`
3. Looks up position in workflow chain
4. Suggests next command with alternatives

## Bob Orchestration (Epic-Level)

<Card title="@pm (Bob) Multi-Agent Coordination" icon="diagram-project">
  Bob orchestrates complete epic execution across multiple agents and stories.
</Card>

### Epic Execution Workflow

```mermaid theme={null}
graph TD
    A[@pm execute-epic] --> B[@pm assign-executor]
    B --> C{Executor Type?}
    C -->|Dev| D[@dev build-autonomous]
    C -->|Data| E[@data-engineer db-workflow]
    C -->|UX| F[@ux-design-expert ux-workflow]
    D --> G{Story Complete?}
    E --> G
    F --> G
    G -->|Yes| H[@pm wave-execute next]
    G -->|No| I[Resume/Retry]
    I --> D
    H --> B
    
    style A fill:#1a73e8,color:#fff
    style B fill:#f9ab00,color:#fff
    style D fill:#34a853,color:#fff
    style H fill:#1a73e8,color:#fff
```

**Key Commands:**

* `*execute-epic {epic-id}` - Start epic orchestration
* `*assign-executor` - Assign appropriate agent to story
* `*wave-execute` - Execute parallel story wave
* `*build-status --all` - Check all story build statuses

**Wave Execution:**

Bob can identify **parallel execution opportunities** using `*waves` command:

```bash theme={null}
aiox pm waves epic-5.1 --visual
```

**Output:**

```
Wave 1 (Parallel):
  - story-5.1.1 (Database Schema)
  - story-5.1.2 (API Endpoints)
  - story-5.1.3 (UI Components)
  
Wave 2 (Sequential - depends on Wave 1):
  - story-5.1.4 (Integration)
  
Wave 3 (Parallel):
  - story-5.1.5 (Testing)
  - story-5.1.6 (Documentation)
```

**Benefits:**

* Maximize parallelism
* Respect dependencies
* Optimize team velocity
* Clear progress tracking

## Cross-Agent Handoff Workflow

<Card title="Seamless Agent Transitions" icon="hand-holding-hand">
  Agents create handoff artifacts to maintain context across transitions.
</Card>

### Handoff Artifact Structure

**Location:** `.aiox/handoffs/{workflow-id}-{timestamp}.yaml`

```yaml theme={null}
workflow_id: story-development-cycle
from_agent: dev
to_agent: qa
last_command: develop
story_id: story-1.2.3
timestamp: 2026-03-05T14:30:00Z
consumed: false

context:
  - Implementation complete
  - All tests passing (12/12)
  - File list updated (7 files modified)
  - CodeRabbit pre-commit passed
  
suggested_next: review story-1.2.3

artifacts:
  - src/auth/login.ts
  - tests/auth/login.test.ts
  - docs/stories/story-1.2.3.md
```

### Handoff Lifecycle

<Steps>
  <Step title="Create">
    Agent completes work, creates handoff artifact with context
  </Step>

  <Step title="Detect">
    Next agent activates, detects unconsumed handoff in greeting
  </Step>

  <Step title="Suggest">
    Greeting displays suggested next command based on handoff
  </Step>

  <Step title="Consume">
    After successful display, handoff marked `consumed: true`
  </Step>
</Steps>

**Example:**

@dev completes story → Creates handoff to @qa

@qa activates → Greeting shows:

```
💡 Suggested: *review story-1.2.3
  Context from @dev:
  - Implementation complete
  - All tests passing
  - Ready for review
```

## Hybrid Workflows (Cross-Context)

<Card title="Squad + Core Agent Workflows" icon="users-gear">
  Workflows can use agents from both core AIOX context AND squad-specific contexts.
</Card>

### Resolution Rules

**Order:** Squad-first, core-fallback

<Steps>
  <Step title="Check Squad Agents">
    Look in `squads/{squad}/agents/` first
  </Step>

  <Step title="Fallback to Core">
    If not found, check `.aiox-core/development/agents/`
  </Step>

  <Step title="Emit Warning on Ambiguity">
    If found in both, emit `WF_AGENT_AMBIGUOUS` warning
  </Step>
</Steps>

### Explicit Prefix

Avoid ambiguity with explicit context prefix:

```yaml theme={null}
steps:
  - agent: core:architect  # Force core architect
  - agent: squad:validator # Force squad-specific validator
```

**Storage:** Hybrid workflows live in `squads/{squad_name}/workflows/`

## Workflow Orchestration with @aiox-master

<Card title="High-Level Workflow Guidance" icon="crown">
  @aiox-master uses workflow definitions to guide users through complete processes.
</Card>

**Capabilities:**

* Workflow selection based on project type
* Step-by-step guidance
* Agent coordination
* Environment transition management (web UI → IDE)
* Progress tracking

**Example:**

```bash theme={null}
User: I want to build a new full-stack app

@aiox-master: I'll guide you through the Greenfield Full-Stack workflow.

  Phase 1: Ideation & Planning (Web UI)
    → Activate @analyst for market research
    
  Phase 2: Requirements (Web UI)  
    → Activate @pm to create PRD
    
  Phase 3: Architecture (Web UI)
    → Activate @architect for system design
    
  📁 CRITICAL: Switch to IDE for development phase
    
  Phase 4: Development (IDE)
    → Activate @sm to create stories
    → Activate @dev to implement
```

## Best Practices

<Check>
  **Workflow Selection**

  * Match workflow to project type (greenfield vs. brownfield)
  * Use discovery workflows for legacy codebases
  * Follow recommended agent sequences
</Check>

<Check>
  **Workflow Execution**

  * Complete each phase before moving to next
  * Respect phase dependencies
  * Use appropriate environment (web UI vs. IDE)
  * Track progress via state files
</Check>

<Check>
  **Agent Coordination**

  * Follow workflow-specified agent sequences
  * Respect agent authority boundaries
  * Use handoff artifacts for context continuity
  * Leverage Bob for multi-agent orchestration
</Check>

<Check>
  **Workflow Customization**

  * Create squad-specific workflows when needed
  * Use hybrid workflows for specialized agents
  * Document custom workflow patterns
  * Version control workflow definitions
</Check>

## Summary

<Card title="Workflow System Principles" icon="list-check">
  **Prescribed Sequences**: Clear step-by-step processes for complex tasks

  **Agent Coordination**: Multi-agent collaboration patterns

  **State Management**: Persist progress across sessions

  **Context Detection**: Intelligent next-step suggestions

  **Flexibility**: Hybrid workflows support custom agents

  **Orchestration**: High-level coordination via @pm and @aiox-master
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Agent System" icon="robot" href="/concepts/agents">
    Learn about agents that execute workflows
  </Card>

  <Card title="Story-Driven Development" icon="book" href="/concepts/story-driven-development">
    Understand the story workflow pattern
  </Card>

  <Card title="Using Workflows" icon="play" href="/guides/using-workflows">
    Practical guide to executing workflows
  </Card>

  <Card title="Creating Custom Workflows" icon="wrench" href="/guides/custom-workflows">
    Build your own workflow definitions
  </Card>
</CardGroup>