BMAD-METHOD/src/modules/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 & 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.md</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.md</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 & 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 & 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.md - Execution engine
• /bmad/bmm/workflows/ - Production examples