Custom Workflows

Overview

Custom workflows allow you to orchestrate multiple agents through a sequence of steps, creating repeatable processes for complex operations.

Workflow Concepts

Key Components

Concept	Description
Workflow	A YAML definition orchestrating multiple agents
Phase	A logical grouping of related steps
Step	A single action performed by an agent
Transition	Movement from one step to the next with optional conditions
State	Persistent tracking of workflow progress across sessions

Workflow Types

Type	Description	Use Case
Greenfield	New projects from scratch	Starting new applications
Brownfield	Existing projects	Enhancing existing code
Generic	Any project type	Cross-cutting processes

Creating a Workflow

Step 1: Plan Your Workflow

Define:

Purpose - What problem does this workflow solve?
Agents - Which agents participate?
Sequence - What is the order of steps?
Conditions - Are there decision points or parallel activities?

Step 2: Use Create Workflow Task

# Activate an agent that can create workflows
@architect

# Run the create workflow task
*create-workflow

Step 3: Answer Elicitation Questions

The task will ask:

Target Context: core, squad, or hybrid
Workflow Name: e.g., feature-development
Primary Goal: What is the expected outcome?
Stages/Phases: Main phases of the workflow
Agent Orchestration: Which agents at each stage
Resource Requirements: Templates, data files needed

Workflow Structure

Basic Template

workflow:
  id: my-workflow
  name: My Custom Workflow
  version: "1.0"
  description: "Description of what this workflow does"
  type: greenfield | brownfield | generic
  project_types:
    - web-app
    - saas

  metadata:
    elicit: true
    confirmation_required: true

  phases:
    - phase_1: Phase Name
    - phase_2: Another Phase

  sequence:
    - step: step_name
      id: unique-id
      phase: 1
      agent: agent-name
      action: Action description
      creates: output-file.md
      requires: previous-step-id
      optional: false
      notes: |
        Detailed instructions for this step...
      next: next-step-id

  flow_diagram: |
    ```mermaid
    graph TD
      A[Start] --> B[Step 1]
      B --> C[Step 2]

decision_guidance: when_to_use:

Scenario 1
Scenario 2 when_not_to_use:
Anti-pattern 1

handoff_prompts: step1_complete: “Step 1 done. Next: @agent for step 2”

## Example: Feature Development Workflow

### Workflow Definition

```yaml
workflow:
  id: feature-development
  name: Feature Development Workflow
  version: "1.0"
  description: "Standard workflow for developing a new feature"
  type: generic
  project_types:
    - web-app
    - mobile-app
    - api

  metadata:
    elicit: true
    confirmation_required: true

  phases:
    - phase_1: Planning
    - phase_2: Story Creation
    - phase_3: Implementation
    - phase_4: Quality Assurance
    - phase_5: Deployment

  sequence:
    # Phase 1: Planning
    - step: create_prd
      id: prd
      phase: 1
      agent: pm
      action: Create product requirements document
      creates: docs/prd/feature.md
      optional: false
      notes: |
        Define the feature requirements, user stories, and success criteria.
        Include technical constraints and dependencies.
      next: validate_prd

    - step: validate_prd
      id: validate
      phase: 1
      agent: po
      action: Validate PRD completeness and feasibility
      requires: prd
      optional: false
      notes: |
        Review PRD for:
        - Clear acceptance criteria
        - Technical feasibility
        - Business value alignment
      next: create_story

    # Phase 2: Story Creation
    - step: create_story
      id: story
      phase: 2
      agent: sm
      action: Create development story from PRD
      requires: validate
      creates: docs/stories/X.X-feature.yaml
      optional: false
      notes: |
        Break down PRD into implementable story with:
        - Clear acceptance criteria
        - Task breakdown
        - Testable requirements
      next: validate_story

    - step: validate_story
      id: validate_story
      phase: 2
      agent: po
      action: Validate story with 10-point checklist
      requires: story
      optional: false
      next: implement

    # Phase 3: Implementation
    - step: implement
      id: dev
      phase: 3
      agent: dev
      action: Implement feature according to story
      requires: validate_story
      creates:
        - src/**/*.js
        - tests/**/*.test.js
      optional: false
      notes: |
        Implement according to:
        - Acceptance criteria
        - Coding standards
        - Test coverage requirements (80%+)
      next: qa_review

    # Phase 4: Quality Assurance
    - step: qa_review
      id: qa
      phase: 4
      agent: qa
      action: Run quality gates and review implementation
      requires: dev
      optional: false
      notes: |
        Execute:
        - Layer 1: Lint, typecheck, tests
        - Layer 2: CodeRabbit, Quinn review
        - Verify acceptance criteria met
      next: push

    # Phase 5: Deployment
    - step: push
      id: push
      phase: 5
      agent: devops
      action: Push changes and create PR
      requires: qa
      optional: false
      notes: |
        - Commit with story reference
        - Push to feature branch
        - Create pull request
        - Ensure CI passes
      next: complete

    - step: complete
      id: complete
      phase: 5
      agent: po
      action: Close story and update backlog
      requires: push
      optional: true

  flow_diagram: |
    ```mermaid
    graph TD
      A[Start] --> B[@pm: Create PRD]
      B --> C[@po: Validate PRD]
      C --> D[@sm: Create Story]
      D --> E[@po: Validate Story]
      E --> F[@dev: Implement]
      F --> G[@qa: Review]
      G --> H[@devops: Push]
      H --> I[@po: Close Story]
      I --> J[Complete]

decision_guidance: when_to_use:

New features requiring full process
Complex features spanning multiple agents
Features needing formal validation when_not_to_use:
Simple bug fixes
Documentation-only changes
Urgent hotfixes

handoff_prompts: prd_complete: “PRD complete. Next: @po validate PRD” validate_complete: “PRD validated. Next: @sm create story” story_complete: “Story created. Next: @po validate story” validate_story_complete: “Story validated. Next: @dev implement” dev_complete: “Implementation complete. Next: @qa review” qa_complete: “QA passed. Next: @devops push” push_complete: “Changes pushed. Next: @po close story”

## Running Workflows

### Start a Workflow

```bash
# Start the workflow
*run-workflow feature-development start

# Output:
# Workflow: feature-development v1.0
# Phase 1: Planning
# Current step: create_prd (@pm)
# Action: Create product requirements document

Check Status

*run-workflow feature-development status

# Output:
# Workflow: feature-development
# Status: active
# Progress: 3/8 steps (37%)
# Current: implement (@dev)

Continue to Next Step

*run-workflow feature-development continue

# Output:
# Step complete: implement
# Next step: qa_review (@qa)
# Action: Run quality gates and review implementation

Skip Optional Step

*run-workflow feature-development skip

# Output:
# Skipped: complete (optional step)
# Workflow finished

Abort Workflow

*run-workflow feature-development abort

# Output:
# Workflow aborted
# Progress saved to .aiox/wf-abc123-state.yaml

Workflow State

State is persisted in .aiox/{instance-id}-state.yaml:

instance_id: "wf-abc123"
workflow_name: "feature-development"
status: "active"
current_step: 3
total_steps: 8
started_at: "2025-01-15T10:00:00Z"
steps:
  - id: prd
    status: completed
    completed_at: "2025-01-15T10:15:00Z"
    output:
      file: docs/prd/feature.md
  - id: validate
    status: completed
    completed_at: "2025-01-15T10:30:00Z"
  - id: story
    status: completed
    completed_at: "2025-01-15T11:00:00Z"
    output:
      file: docs/stories/1.5-feature.yaml
  - id: validate_story
    status: in_progress
  - id: dev
    status: pending
  - id: qa
    status: pending
  - id: push
    status: pending
  - id: complete
    status: pending

Advanced Features

Conditional Steps

- step: check_coverage
  id: coverage
  phase: 4
  agent: qa
  action: Check test coverage
  condition:
    type: coverage_threshold
    minimum: 80
  on_success: qa_review
  on_failure: request_more_tests

Parallel Steps

- step: parallel_reviews
  id: parallel
  phase: 4
  type: parallel
  steps:
    - agent: qa
      action: Quality review
    - agent: architect
      action: Architecture review
    - agent: ux-expert
      action: UX review
  next: consolidate_feedback

Loop Steps

- step: iterative_refinement
  id: refine
  phase: 3
  agent: dev
  action: Refine implementation
  loop:
    condition: qa_feedback_present
    max_iterations: 3
  next: final_qa

Output Location

Workflows are saved based on context:

Core: .aiox-core/development/workflows/{name}.yaml
Squad: squads/{squad}/workflows/{name}.yaml
Hybrid: squads/{squad}/workflows/{name}.yaml

Best Practices

Workflow Design

Keep phases focused - Each phase should have a clear purpose
Define clear handoffs - Document what each agent passes to the next
Include optional steps - Allow flexibility for simple cases
Add decision guidance - Help users know when to use/not use

Step Definition

Single responsibility - Each step does one thing well
Clear actions - Describe what the agent should do
Document outputs - Specify what files/data are created
Include notes - Provide detailed instructions

Error Handling

Define failure paths - What happens when a step fails?
Set timeouts - Prevent infinite loops
Save state frequently - Allow recovery from errors
Provide rollback - Undo steps if needed

Workflow Validation

# Validate workflow syntax
*validate-workflow feature-development

# Output:
# ✓ Workflow ID is valid
# ✓ All agents exist
# ✓ All steps have required fields
# ✓ Phase sequence is valid
# ✓ No circular dependencies
# ✓ Flow diagram is valid mermaid syntax

Troubleshooting

Workflow not found

# List available workflows
ls .aiox-core/development/workflows/

# Verify workflow name matches file ID
cat .aiox-core/development/workflows/feature-development.yaml

No active instance

# Start the workflow first
*run-workflow feature-development start

# Then continue
*run-workflow feature-development continue

Step not optional

# Cannot skip non-optional steps
# Either complete the step or abort the workflow
*run-workflow feature-development abort

State corruption

# Remove corrupted state file
rm .aiox/wf-*-state.yaml

# Restart workflow
*run-workflow feature-development start

Examples

Bug Fix Workflow

workflow:
  id: bug-fix
  name: Bug Fix Workflow
  version: "1.0"
  description: "Quick workflow for bug fixes"
  type: generic

  phases:
    - phase_1: Report
    - phase_2: Fix
    - phase_3: Verify

  sequence:
    - step: create_bug_story
      phase: 1
      agent: sm
      action: Create bug story
      next: fix_bug

    - step: fix_bug
      phase: 2
      agent: dev
      action: Fix the bug with tests
      next: verify_fix

    - step: verify_fix
      phase: 3
      agent: qa
      action: Verify bug is fixed
      next: push

    - step: push
      phase: 3
      agent: devops
      action: Push fix

Code Review Workflow

workflow:
  id: code-review
  name: Code Review Workflow
  version: "1.0"
  description: "Multi-layer code review process"
  type: generic

  phases:
    - phase_1: Automated Review
    - phase_2: Human Review

  sequence:
    - step: lint_typecheck
      phase: 1
      agent: qa
      action: Run lint and typecheck
      next: coderabbit

    - step: coderabbit
      phase: 1
      agent: qa
      action: Run CodeRabbit review
      next: architect_review

    - step: architect_review
      phase: 2
      agent: architect
      action: Review architecture decisions
      next: approve

    - step: approve
      phase: 2
      agent: po
      action: Final approval and merge

Next Steps

Workflow Patterns - Learn common workflow patterns
Agent Flows - Understand how agents collaborate
Task Creation - Build tasks for your workflows
Squad Workflows - Create workflows for your squads

Getting Started

Development

Extensions

Overview

Workflow Concepts

Key Components

Workflow Types

Creating a Workflow

Step 1: Plan Your Workflow

Step 2: Use Create Workflow Task

Step 3: Answer Elicitation Questions

Workflow Structure

Basic Template

Check Status

Continue to Next Step

Skip Optional Step

Abort Workflow

Workflow State

Advanced Features

Conditional Steps

Parallel Steps

Loop Steps

Output Location

Best Practices

Workflow Design

Step Definition

Error Handling

Workflow Validation

Troubleshooting

Workflow not found

No active instance

Step not optional

State corruption

Examples

Bug Fix Workflow

Code Review Workflow

Next Steps

Build docs developers (and LLMs) love

Getting Started

Development

Extensions

​Overview

​Workflow Concepts

​Key Components

​Workflow Types

​Creating a Workflow

​Step 1: Plan Your Workflow

​Step 2: Use Create Workflow Task

​Step 3: Answer Elicitation Questions

​Workflow Structure

​Basic Template

​Check Status

​Continue to Next Step

​Skip Optional Step

​Abort Workflow

​Workflow State

​Advanced Features

​Conditional Steps

​Parallel Steps

​Loop Steps

​Output Location

​Best Practices

​Workflow Design

​Step Definition

​Error Handling

​Workflow Validation

​Troubleshooting

​Workflow not found

​No active instance

​Step not optional

​State corruption

​Examples

​Bug Fix Workflow

​Code Review Workflow

​Next Steps

Build docs developers (and LLMs) love

Overview

Workflow Concepts

Key Components

Workflow Types

Creating a Workflow

Step 1: Plan Your Workflow

Step 2: Use Create Workflow Task

Step 3: Answer Elicitation Questions

Workflow Structure

Basic Template

Check Status

Continue to Next Step

Skip Optional Step

Abort Workflow

Workflow State

Advanced Features

Conditional Steps

Parallel Steps

Loop Steps

Output Location

Best Practices

Workflow Design

Step Definition

Error Handling

Workflow Validation

Troubleshooting

Workflow not found

No active instance

Step not optional

State corruption

Examples

Bug Fix Workflow

Code Review Workflow

Next Steps