bmad-method 5.1.2 → 6.0.0-alpha.0

package/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md

@@ -0,0 +1,456 @@
+# 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 & 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.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
+
+```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.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):
+
+```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 & 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 & 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.md` - Execution engine
+- `/bmad/bmm/workflows/` - Production examples

package/src/modules/bmb/workflows/create-workflow/workflow-template/checklist.md

@@ -0,0 +1,24 @@
+# {Title} Checklist Validation
+
+## {Section Foo}
+
+- [ ] Check 1
+- [ ] Check 2
+- [ ] ...
+- [ ] Check n
+
+...
+
+## {Section Bar}
+
+- [ ] Check 1
+- [ ] Check 2
+- [ ] ...
+- [ ] Check n
+
+## Final Validation
+
+- [ ] Section Foo
+  - Issue List
+- [ ] Section Bar
+  - Issue List

package/src/modules/bmb/workflows/create-workflow/workflow-template/instructions.md

@@ -0,0 +1,12 @@
+# PRD Workflow Instructions
+
+<workflow>
+
+<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
+<critical>You MUST have already loaded and processed: {project_root}/bmad/{module-code}/workflows/{workflow}/workflow.yaml</critical>
+
+<step n="1" goal="">
+...
+</step>
+...
+</workflow>

package/src/modules/bmb/workflows/create-workflow/workflow-template/template.md

@@ -0,0 +1,9 @@
+# Title
+
+**Date:** {{date}}
+
+## {Section 1}
+
+{{section_1_results}}
+
+etc...

package/src/modules/bmb/workflows/create-workflow/workflow-template/workflow.yaml

@@ -0,0 +1,35 @@
+# {TITLE} Workflow Template Configuration
+name: "{WORKFLOW_CODE}"
+description: "{WORKFLOW_DESCRIPTION}"
+author: "BMad"
+
+# Critical variables load from config_source
+# Add Additional Config Pulled Variables Here
+config_source: "{project-root}/{module-code}/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+date: system-generated
+
+# Required Data Files - HALT if missing!
+# optional, can be omitted
+brain_techniques: "{installed_path}/{critical-data-file.csv}" # example, can be other formats or URLs
+
+# Optional docs that if loaded on start to kickstart this workflow or used at some point, these are meant to be suggested inputs for the user
+recommended_inputs: # optional, can be omitted
+  - example_input: "{project-root}/{path/to/file.md}"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/{module-code}/workflows/{workflow-code}"
+template: "{installed_path}/template.md" # optional, can be omitted
+instructions: "{installed_path}/instructions.md" # optional, can be omitted
+validation: "{installed_path}/checklist.md" # optional, can be omitted
+
+# Output configuration
+default_output_file: "{output_folder}/{file.md}" # optional, can be omitted
+validation_output_file: "{output_folder}/{file-validation-report.md}" # optional, can be omitted
+
+# Tool Requirements (MCP Required Tools or other tools needed to run this workflow)
+required_tools: #optional, can be omitted
+  - "Tool Name": #example, can be omitted if none
+      description: "Description of why this tool is needed"
+      link: "https://link-to-tool.com"

package/src/modules/bmb/workflows/create-workflow/workflow.yaml

@@ -0,0 +1,42 @@
+# Build Workflow - Workflow Builder Configuration
+name: build-workflow
+description: "Interactive workflow builder that guides creation of new BMAD workflows with proper structure and validation for optimal human-AI collaboration. Includes optional brainstorming phase for workflow ideas and design."
+author: "BMad Builder"
+
+# Critical variables
+config_source: "{project-root}/bmad/bmb/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+src_impact: "{config_source}:src_impact"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Template files for new workflows
+template_workflow_yaml: "{workflow_template_path}/workflow.yaml"
+template_instructions: "{workflow_template_path}/instructions.md"
+template_template: "{workflow_template_path}/template.md"
+template_checklist: "{workflow_template_path}/checklist.md"
+
+# Optional input docs
+recommended_inputs:
+  - existing_workflows: "{project-root}/bmad/*/workflows/"
+  - bmm_workflows: "{project-root}/bmad/bmm/workflows/"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmb/workflows/build-workflow"
+template: false # This is an action workflow - no template needed
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Required data files - CRITICAL for workflow conventions
+workflow_creation_guide: "{installed_path}/workflow-creation-guide.md"
+workflow_template_path: "{installed_path}/workflow-template"
+
+# Output configuration - Creates the new workflow folder with all files
+# If src_impact=true: Save to src/modules/{{target_module}}/workflows/{{workflow_name}}
+# If src_impact=false: Save to output_folder/workflows/{{workflow_name}}
+default_output_folder: "{output_folder}/workflows/{{workflow_name}}"
+src_output_folder: "{project-root}/src/modules/{{target_module}}/workflows/{{workflow_name}}"
+
+# No special tools required
+required_tools: []

package/src/modules/bmb/workflows/edit-workflow/README.md

@@ -0,0 +1,63 @@
+# Edit Workflow
+
+## Purpose
+
+An intelligent workflow editor that helps you modify existing BMAD workflows while adhering to all best practices and conventions documented in the workflow creation guide.
+
+## Use Case
+
+When you need to:
+
+- Fix issues in existing workflows
+- Update workflow configuration or metadata
+- Improve instruction clarity and specificity
+- Add new features or capabilities
+- Ensure compliance with BMAD workflow conventions
+
+## How to Invoke
+
+```
+workflow edit-workflow
+```
+
+Or through a BMAD agent:
+
+```
+*edit-workflow
+```
+
+## Expected Inputs
+
+- **Target workflow path**: Path to the workflow.yaml file or workflow folder you want to edit
+- **Edit type selection**: Choice of what aspect to modify
+- **User approval**: For each proposed change
+
+## Generated Outputs
+
+- Modified workflow files (in place)
+- Optional change log at: `{output_folder}/workflow-edit-log-{date}.md`
+
+## Features
+
+1. **Comprehensive Analysis**: Checks workflows against the official creation guide
+2. **Prioritized Issues**: Identifies and ranks issues by importance
+3. **Guided Editing**: Step-by-step process with explanations
+4. **Best Practices**: Ensures all edits follow BMAD conventions
+5. **Validation**: Checks all changes for correctness
+6. **Change Tracking**: Documents what was modified and why
+
+## Workflow Steps
+
+1. Load and analyze target workflow
+2. Check against best practices
+3. Select editing focus
+4. Load relevant documentation
+5. Perform edits with user approval
+6. Validate all changes (optional)
+7. Generate change summary
+
+## Requirements
+
+- Access to workflow creation guide
+- Read/write permissions for target workflow
+- Understanding of BMAD workflow types