Custom Workflows

Guide to creating and managing custom workflows for your project or squad

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:

1. Purpose - What problem does this workflow solve?
2. Agents - Which agents participate?
3. Sequence - What is the order of steps?
4. 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:

1. Target Context: core, squad, or hybrid
2. Workflow Name: e.g., feature-development
3. Primary Goal: What is the expected outcome?
4. Stages/Phases: Main phases of the workflow
5. Agent Orchestration: Which agents at each stage
6. 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

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

Step Definition

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

Error Handling

1. Define failure paths - What happens when a step fails?
2. Set timeouts - Prevent infinite loops
3. Save state frequently - Allow recovery from errors
4. 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