Skip to main content

​
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.

Workflow Philosophy

Workflows define the “what” and “when” of agent collaboration, ensuring consistent, high-quality execution of complex processes.

​
Workflow Architecture

Workflows are defined in YAML format and stored in .aiox-core/development/workflows/: 
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

New Projects Starting from Scratch
Complete full-stack application developmentPhases:
  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, @devopsTypical duration: 2-8 weeks depending on complexity
Backend service/API developmentPhases:
  1. Service requirements
  2. API design
  3. Database schema
  4. Implementation
  5. Testing
  6. Deployment
Agents involved: @pm, @architect, @data-engineer, @dev, @qa, @devopsBest for: Microservices, API backends, serverless functions
Frontend/UI application developmentPhases:
  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, @devopsBest for: Web apps, mobile UIs, dashboard projects

​
Workflow Patterns

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

​
Story Development Cycle (Primary)

Most Common Workflow

Complete story lifecycle from validation to deployment
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

Planning & Organization

Create and organize epics with initial stories
Agent Sequence: @po → @sm → @architect Typical Duration: 0.5-2 days

​
QA Loop (Iterative Review)

Automated Review-Fix Cycle

Continues until code meets quality standards (max 5 iterations)
Max Iterations: 5 before escalation

​
Database Development Workflow

Schema Design & Migration

Safe, validated database changes
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

Context-Aware Suggestions

Agents detect workflow context from command history and suggest next steps.
How it works:
1

Command Tracking

System tracks executed commands in current session
2

Pattern Matching

Compares command history to workflow patterns in workflow-patterns.yaml
3

Workflow Detection

When threshold met (default: 2 matching commands), workflow is detected
4

Next Step Suggestion

Agent greeting includes suggested next command based on workflow chain
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

File-Based State Persistence

Workflows can maintain state across sessions using YAML files in .aiox/
State File Location: .aiox/{instance-id}-state.yaml State File Schema: 
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: 
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)

@pm (Bob) Multi-Agent Coordination

Bob orchestrates complete epic execution across multiple agents and stories.

​
Epic Execution Workflow

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

Seamless Agent Transitions

Agents create handoff artifacts to maintain context across transitions.

​
Handoff Artifact Structure

Location: .aiox/handoffs/{workflow-id}-{timestamp}.yaml 
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

1

Create

Agent completes work, creates handoff artifact with context
2

Detect

Next agent activates, detects unconsumed handoff in greeting
3

Suggest

Greeting displays suggested next command based on handoff
4

Consume

After successful display, handoff marked consumed: true
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)

Squad + Core Agent Workflows

Workflows can use agents from both core AIOX context AND squad-specific contexts.

​
Resolution Rules

Order: Squad-first, core-fallback
1

Check Squad Agents

Look in squads/{squad}/agents/ first
2

Fallback to Core

If not found, check .aiox-core/development/agents/
3

Emit Warning on Ambiguity

If found in both, emit WF_AGENT_AMBIGUOUS warning

​
Explicit Prefix

Avoid ambiguity with explicit context prefix: 
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

High-Level Workflow Guidance

@aiox-master uses workflow definitions to guide users through complete processes.
Capabilities:
  • Workflow selection based on project type
  • Step-by-step guidance
  • Agent coordination
  • Environment transition management (web UI → IDE)
  • Progress tracking
Example: 
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

Workflow Selection
  • Match workflow to project type (greenfield vs. brownfield)
  • Use discovery workflows for legacy codebases
  • Follow recommended agent sequences
Workflow Execution
  • Complete each phase before moving to next
  • Respect phase dependencies
  • Use appropriate environment (web UI vs. IDE)
  • Track progress via state files
Agent Coordination
  • Follow workflow-specified agent sequences
  • Respect agent authority boundaries
  • Use handoff artifacts for context continuity
  • Leverage Bob for multi-agent orchestration
Workflow Customization
  • Create squad-specific workflows when needed
  • Use hybrid workflows for specialized agents
  • Document custom workflow patterns
  • Version control workflow definitions

​
Summary

Workflow System Principles

Prescribed Sequences: Clear step-by-step processes for complex tasksAgent Coordination: Multi-agent collaboration patternsState Management: Persist progress across sessionsContext Detection: Intelligent next-step suggestionsFlexibility: Hybrid workflows support custom agentsOrchestration: High-level coordination via @pm and @aiox-master

​
Next Steps

Agent System

Learn about agents that execute workflows

Story-Driven Development

Understand the story workflow pattern

Using Workflows

Practical guide to executing workflows

Creating Custom Workflows

Build your own workflow definitions

Build docs developers (and LLMs) love

Get started for freeTalk to us