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
2. Core Concepts
3. Workflow Structure
4. Writing Instructions
5. Templates and Variables
6. Flow Control
7. Validation
8. Examples
9. Best Practices
10. 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

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

# 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:</check>
  <goto step="1">Return to previous step</goto>
  <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

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

<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

<!-- 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

<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

<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

# 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>
<elicit-required/>
</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:</check>
  <goto step="2">Fix issues</goto>
</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

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