doc status updates
This commit is contained in:
Brian Madison
@@ -1,456 +0,0 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user