BMAD-METHOD/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md

# BMAD Workflow Creation Guide

Create structured, repeatable workflows for human-AI collaboration in BMAD v6.

## Table of Contents

1. [Quick Start](#quick-start)
2. [Core Concepts](#core-concepts)
3. [Workflow Structure](#workflow-structure)
4. [Writing Instructions](#writing-instructions)
5. [Templates and Variables](#templates--variables)
6. [Flow Control](#flow-control)
7. [Validation](#validation)
8. [Examples](#examples)
9. [Best Practices](#best-practices)
10. [Troubleshooting](#troubleshooting)

## Quick Start

### Minimal Workflow (3 minutes)

Create a folder with these files:

```yaml
# workflow.yaml (REQUIRED)
name: 'my-workflow'
description: 'What this workflow does'
installed_path: '{project-root}/bmad/module/workflows/my-workflow'
template: '{installed_path}/template.md'
instructions: '{installed_path}/instructions.md'
default_output_file: '{output_folder}/output.md'
```

```markdown
# template.md

# {{project_name}} Output

{{main_content}}
```

```markdown
# instructions.md

<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
<critical>You MUST have already loaded and processed: workflow.yaml</critical>

<workflow>
<step n="1" goal="Generate content">
Create the main content for this document.
<template-output>main_content</template-output>
</step>
</workflow>
```

That's it! To execute, tell the BMAD agent: `workflow my-workflow`

## Core Concepts

### Tasks vs Workflows

| Aspect         | Task               | Workflow                |
| -------------- | ------------------ | ----------------------- |
| **Purpose**    | Single operation   | Multi-step process      |
| **Format**     | XML in `.md` file  | Folder with YAML config |
| **Location**   | `/src/core/tasks/` | `/bmad/*/workflows/`    |
| **User Input** | Minimal            | Extensive               |
| **Output**     | Variable           | Usually documents       |

### Workflow Types

1. **Document Workflows** - Generate PRDs, specs, architectures
2. **Action Workflows** - Refactor code, run tools, orchestrate tasks
3. **Interactive Workflows** - Brainstorming, meditations, guided sessions
4. **Autonomous Workflows** - Run without human input (story generation)
5. **Meta-Workflows** - Coordinate other workflows

## Workflow Structure

### Required Files

```
my-workflow/
  └── workflow.yaml      # REQUIRED - Configuration
```

### Optional Files

```
my-workflow/
  ├── template.md        # Document structure
  ├── instructions.md    # Step-by-step guide
  ├── checklist.md       # Validation criteria
  └── [data files]       # Supporting resources
```

### workflow.yaml Configuration

```yaml
# Basic metadata
name: 'workflow-name'
description: 'Clear purpose statement'

# Paths
installed_path: '{project-root}/bmad/module/workflows/name'
template: '{installed_path}/template.md' # or false
instructions: '{installed_path}/instructions.md' # or false
validation: '{installed_path}/checklist.md' # optional

# Output
default_output_file: '{output_folder}/document.md'

# Advanced options
autonomous: true # Skip user checkpoints
recommended_inputs: # Expected input docs
  - input_doc: 'path/to/doc.md'
```

### Common Patterns

**Full Document Workflow** (most common)

- Has: All 4 files
- Use for: PRDs, architectures, specs

**Action Workflow** (no template)

- Has: workflow.yaml + instructions.md
- Use for: Refactoring, tool orchestration

**Autonomous Workflow** (no interaction)

- Has: workflow.yaml + template + instructions
- Use for: Automated generation

## Writing Instructions

### Basic Structure

```markdown
# instructions.md

<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
<critical>You MUST have already loaded and processed: workflow.yaml</critical>

<workflow>

<step n="1" goal="Clear goal statement">
Instructions for this step.
<template-output>variable_name</template-output>
</step>

<step n="2" goal="Next goal" optional="true">
Optional step instructions.
<template-output>another_variable</template-output>
</step>

</workflow>
```

### Step Attributes

- `n="X"` - Step number (required)
- `goal="..."` - What the step accomplishes (required)
- `optional="true"` - User can skip
- `repeat="3"` - Repeat N times
- `if="condition"` - Conditional execution

### Content Formats

**Markdown Format** (human-friendly):

```xml
<step n="1" goal="Define goals">
Write 1-3 bullet points about project success:
- User outcomes
- Business value
- Measurable results

<template-output>goals</template-output>
</step>
```

**XML Format** (precise control):

```xml
<step n="2" goal="Validate input">
  <action>Load validation criteria</action>
  <check>If validation fails:</check>
  <goto step="1">Return to previous step</goto>
  <template-output>validated_data</template-output>
</step>
```

## Templates and Variables

### Variable Syntax

```markdown
# template.md

# {{project_name}} Document

## Section

{{section_content}}

_Generated on {{date}}_
```

### Variable Sources

1. **workflow.yaml** - Config values
2. **User input** - Runtime values
3. **Step outputs** - `<template-output>` tags
4. **System** - Date, paths, etc.

### Naming Convention

- Use snake_case: `{{user_requirements}}`
- Be descriptive: `{{primary_user_journey}}` not `{{puj}}`

## Flow Control

### Sub-Steps

```xml
<step n="3" goal="Process items">
  <step n="3a" title="Gather data">
    <action>Collect information</action>
  </step>

  <step n="3b" title="Analyze">
    <action>Process collected data</action>
    <template-output>analysis</template-output>
  </step>
</step>
```

### Repetition

```xml
<!-- Fixed repetitions -->
<step n="4" repeat="3">
  <action>Generate example {{iteration}}</action>
</step>

<!-- Conditional repetition -->
<step n="5" repeat="until-approved">
  <action>Generate content</action>
  <ask>Satisfactory? (y/n)</ask>
</step>

<!-- For-each repetition -->
<step n="6" repeat="for-each-epic">
  <action>Define epic {{epic_name}}</action>
</step>
```

### Branching and Goto

```xml
<step n="7" goal="Validate">
  <action>Check requirements</action>
  <check>If incomplete:</check>
  <goto step="2">Return to gathering</goto>
  <check>If complete:</check>
  <continue>Proceed</continue>
</step>
```

### Loops

```xml
<step n="8" goal="Refine">
  <loop max="5">
    <action>Generate solution</action>
    <check>If criteria met:</check>
    <break>Exit loop</break>
  </loop>
</step>
```

### Common XML Tags

**Execution:**

- `<action>` - Required action
- `<check>` - Conditional check
- `<ask>` - User prompt
- `<goto>` - Jump to step
- `<invoke-workflow>` - Call another workflow

**Output:**

- `<template-output>` - Save checkpoint
- `<elicit-required/>` - Trigger AI enhancement
- `<critical>` - Important info
- `<example>` - Show example

## Validation

### checklist.md Structure

```markdown
# Validation Checklist

## Structure

- [ ] All sections present
- [ ] No placeholders remain
- [ ] Proper formatting

## Content Quality

- [ ] Clear and specific
- [ ] Technically accurate
- [ ] Consistent terminology

## Completeness

- [ ] Ready for next phase
- [ ] Dependencies documented
- [ ] Action items defined
```

### Making Criteria Measurable

❌ `- [ ] Good documentation`
✅ `- [ ] Each function has JSDoc comments with parameters and return types`

## Examples

### Document Generation

```xml
<workflow>
<step n="1" goal="Gather context">
Load existing documents and understand project scope.
<template-output>context</template-output>
</step>

<step n="2" goal="Define requirements">
Create functional and non-functional requirements.
<template-output>requirements</template-output>
<elicit-required/>
</step>

<step n="3" goal="Validate">
Check requirements against goals.
<template-output>validated_requirements</template-output>
</step>
</workflow>
```

### Action Workflow

```xml
<workflow>
<step n="1" goal="Analyze codebase">
  <action>Find all API endpoints</action>
  <action>Identify patterns</action>
</step>

<step n="2" goal="Refactor">
  <repeat for-each="endpoint">
    <action>Update to new pattern</action>
  </repeat>
</step>

<step n="3" goal="Verify">
  <action>Run tests</action>
  <check>If tests fail:</check>
  <goto step="2">Fix issues</goto>
</step>
</workflow>
```

### Meta-Workflow

```xml
<workflow name="greenfield-app">
<step n="1" goal="Discovery">
  <invoke-workflow>product-brief</invoke-workflow>
  <template-output>brief</template-output>
</step>

<step n="2" goal="Requirements">
  <invoke-workflow input="{{brief}}">prd</invoke-workflow>
  <template-output>prd</template-output>
</step>

<step n="3" goal="Architecture">
  <invoke-workflow input="{{prd}}">architecture</invoke-workflow>
  <template-output>architecture</template-output>
</step>
</workflow>
```

## Best Practices

### Design Principles

1. **Keep steps focused** - Single goal per step
2. **Limit scope** - 5-10 steps maximum
3. **Build progressively** - Start simple, add detail
4. **Checkpoint often** - Save after major sections
5. **Make sections optional** - Let users skip when appropriate

### Instruction Guidelines

1. **Be specific** - "Write 1-2 paragraphs" not "Write about"
2. **Provide examples** - Show expected output format
3. **Set limits** - "3-5 items maximum"
4. **Explain why** - Context helps AI make better decisions

### Common Pitfalls

- **Missing critical headers** - Always include workflow engine references
- **Variables not replaced** - Ensure names match exactly
- **Too many steps** - Combine related actions
- **No checkpoints** - Add `<template-output>` tags
- **Vague instructions** - Be explicit about expectations

## Troubleshooting

### Variables Not Replaced

- Check exact name match
- Verify `<template-output>` tag present
- Ensure step generates the variable

### Validation Fails

- Review checklist specificity
- Check for impossible requirements
- Verify checklist matches template

### Workflow Too Long

- Combine related steps
- Make sections optional
- Reduce elicitation points

### User Confusion

- Add clearer step goals
- Provide more examples
- Explain section purpose

---

_For implementation details, see:_

- `/src/core/tasks/workflow.xml` - Execution engine
- `/bmad/bmm/workflows/` - Production examples