BMAD Workflow Creation Guide

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

Quick Start
Core Concepts
Workflow Structure
Writing Instructions
Templates and Variables
Flow Control
Validation
Examples
Best Practices
Troubleshooting

Quick Start

Minimal Workflow (3 minutes)

Create a folder with these files:

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

# template.md

# {{project_name}} Output

{{main_content}}

# 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

Document Workflows - Generate PRDs, specs, architectures
Action Workflows - Refactor code, run tools, orchestrate tasks
Interactive Workflows - Brainstorming, meditations, guided sessions
Autonomous Workflows - Run without human input (story generation)
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

# 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

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

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

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

Templates and Variables

Variable Syntax

# template.md

# {{project_name}} Document

## Section

{{section_content}}

_Generated on {{date}}_

Variable Sources

workflow.yaml - Config values
User input - Runtime values
Step outputs - <template-output> tags
System - Date, paths, etc.

Naming Convention

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

Flow Control

Sub-Steps

<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

Generate example {{iteration}}

Generate content Satisfactory? (y/n)

Define epic {{epic_name}} ```

Conditional Execution

Single Action (use action if=""):

<step n="6" goal="Load context">
  <action if="file exists">Load existing document</action>
  <action if="new project">Initialize from template</action>
</step>

Multiple Actions (use <check if="">...</check>):

<step n="7" goal="Validate">
  <action>Check requirements</action>
  <check if="incomplete">
    <action>Log validation errors</action>
    <goto step="2">Return to gathering</goto>
  </check>
  <check if="complete">
    <action>Mark as validated</action>
    <continue>Proceed</continue>
  </check>
</step>

When to use which:

<action if=""> - Single conditional action (cleaner, more concise)
<check if="">...</check> - Multiple items under same condition (explicit scope)

Loops

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

Common XML Tags

Execution:

<action> - Required action
<action if="condition"> - Single conditional action (inline)
<check if="condition">...</check> - Conditional block for multiple items (requires closing tag)
<ask> - User prompt
<goto> - Jump to step
<invoke-workflow> - Call another workflow

Output:

<template-output> - Save checkpoint
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task> - Trigger AI enhancement
<critical> - Important info
<example> - Show example

Validation

checklist.md Structure

# 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

<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>
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
</step>

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

Action Workflow

<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">
    <goto step="2">Fix issues</goto>
  </check>
</step>
</workflow>

Meta-Workflow

<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

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

Instruction Guidelines

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

Conditional Execution Best Practices

✅ DO:

Use <action if=""> for single conditional actions
Use <check if="">...</check> for blocks with multiple items
Always close <check> tags explicitly
Keep conditions simple and readable

❌ DON’T:

Wrap single actions in <check> blocks (unnecessarily verbose)
Forget to close <check> tags
Nest too many levels (makes logic hard to follow)

Examples: