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

# 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

```bash theme={null}
# 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

````yaml theme={null}
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

```bash theme={null}
*run-workflow feature-development status

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

### Continue to Next Step

```bash theme={null}
*run-workflow feature-development continue

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

### Skip Optional Step

```bash theme={null}
*run-workflow feature-development skip

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

### Abort Workflow

```bash theme={null}
*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`:

```yaml theme={null}
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

```yaml theme={null}
- 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

```yaml theme={null}
- 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

```yaml theme={null}
- 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Start the workflow first
*run-workflow feature-development start

# Then continue
*run-workflow feature-development continue
```

### Step not optional

```bash theme={null}
# Cannot skip non-optional steps
# Either complete the step or abort the workflow
*run-workflow feature-development abort
```

### State corruption

```bash theme={null}
# Remove corrupted state file
rm .aiox/wf-*-state.yaml

# Restart workflow
*run-workflow feature-development start
```

## Examples

### Bug Fix Workflow

```yaml theme={null}
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

```yaml theme={null}
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