bmad-method 5.1.3 → 6.0.0-alpha.1

package/bmad/bmb/workflows/create-module/workflow.yaml.bak

@@ -0,0 +1,40 @@
+# Build Module Workflow Configuration
+name: create-module
+description: "Interactive workflow to build complete BMAD modules with agents, workflows, tasks, and installation infrastructure"
+author: "BMad"
+
+# Critical variables load from config_source
+config_source: "{project-root}/bmad/bmb/config.yaml"
+custom_module_location: "{config_source}:custom_module_location"
+communication_language: "{config_source}:communication_language"
+user_name: "{config_source}:user_name"
+
+# Reference guides for module building
+module_structure_guide: "{installed_path}/module-structure.md"
+installer_templates: "{installed_path}/installer-templates/"
+
+# Use existing build workflows
+agent_builder: "{project-root}/bmad/bmb/workflows/create-agent/workflow.yaml"
+workflow_builder: "{project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml"
+brainstorming_workflow: "{project-root}/bmad/core/workflows/brainstorming/workflow.yaml"
+brainstorming_context: "{installed_path}/brainstorm-context.md"
+
+# Optional docs that help understand module patterns
+recommended_inputs:
+  - module_brief: "{output_folder}/module-brief-*.md"
+  - brainstorming_results: "{output_folder}/brainstorming-*.md"
+  - bmm_module: "{project-root}/bmad/bmm/"
+  - cis_module: "{project-root}/bmad/cis/"
+  - existing_agents: "{project-root}/bmad/*/agents/"
+  - existing_workflows: "{project-root}/bmad/*/workflows/"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmb/workflows/create-module"
+template: false # This is an interactive scaffolding workflow
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration - creates entire module structure
+# Save to custom_module_location/{{module_code}}
+installer_output_folder: "{custom_module_location}/{{module_code}}"
+# Web bundle configuration

package/bmad/bmb/workflows/create-workflow/README.md

@@ -0,0 +1,277 @@
+# Build Workflow
+
+## Overview
+
+The Build Workflow is an interactive workflow builder that guides you through creating new BMAD workflows with proper structure, conventions, and validation. It ensures all workflows follow best practices for optimal human-AI collaboration and are fully compliant with the BMAD Core v6 workflow execution engine.
+
+## Key Features
+
+- **Optional Brainstorming Phase**: Creative exploration of workflow ideas before structured development
+- **Comprehensive Guidance**: Step-by-step process with detailed instructions and examples
+- **Template-Based**: Uses proven templates for all workflow components
+- **Convention Enforcement**: Ensures adherence to BMAD workflow creation guide
+- **README Generation**: Automatically creates comprehensive documentation
+- **Validation Built-In**: Includes checklist generation for quality assurance
+- **Type-Aware**: Adapts to document, action, interactive, autonomous, or meta-workflow types
+
+## Usage
+
+### Basic Invocation
+
+```bash
+workflow create-workflow
+```
+
+### Through BMad Builder Agent
+
+```
+*create-workflow
+```
+
+### What You'll Be Asked
+
+1. **Optional**: Whether to brainstorm workflow ideas first (creative exploration phase)
+2. Workflow name and target module
+3. Workflow purpose and type (enhanced by brainstorming insights if used)
+4. Metadata (description, author, outputs)
+5. Step-by-step design (goals, variables, flow)
+6. Whether to include optional components
+
+## Workflow Structure
+
+### Files Included
+
+```
+create-workflow/
+├── workflow.yaml                  # Configuration and metadata
+├── instructions.md                # Step-by-step execution guide
+├── checklist.md                   # Validation criteria
+├── workflow-creation-guide.md     # Comprehensive reference guide
+├── README.md                      # This file
+└── workflow-template/             # Templates for new workflows
+    ├── workflow.yaml
+    ├── instructions.md
+    ├── template.md
+    ├── checklist.md
+    └── README.md
+```
+
+## Understanding Instruction Styles
+
+One of the most important decisions when creating a workflow is choosing the **instruction style** - how the workflow guides the AI's interaction with users.
+
+### Intent-Based vs Prescriptive Instructions
+
+**Intent-Based (Recommended for most workflows)**
+
+Guides the LLM with goals and principles, allowing natural conversation adaptation.
+
+- **More flexible and conversational** - AI adapts questions to context
+- **Better for complex discovery** - Requirements gathering, creative exploration
+- **Quality over consistency** - Focus on deep understanding
+- **Example**: `<action>Guide user to define their target audience with specific demographics and needs</action>`
+
+**Best for:**
+
+- Complex discovery processes (user research, requirements)
+- Creative brainstorming and ideation
+- Iterative refinement workflows
+- When adaptation to context matters
+- Workflows requiring nuanced understanding
+
+**Prescriptive**
+
+Provides exact wording for questions and structured options.
+
+- **More controlled and predictable** - Same questions every time
+- **Better for simple data collection** - Platform choices, yes/no decisions
+- **Consistency over quality** - Standardized execution
+- **Example**: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
+
+**Best for:**
+
+- Simple data collection (platform, format, binary choices)
+- Compliance verification and standards
+- Configuration with finite options
+- Quick setup wizards
+- When consistency is critical
+
+### Best Practice: Mix Both Styles
+
+The most effective workflows use **both styles strategically**:
+
+```xml
+<!-- Intent-based workflow with prescriptive moments -->
+<step n="1" goal="Understand user vision">
+  <action>Explore the user's vision, uncovering creative intent and target experience</action>
+</step>
+
+<step n="2" goal="Capture basic metadata">
+  <ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>
+</step>
+
+<step n="3" goal="Deep dive into details">
+  <action>Guide user to articulate their core approach and unique aspects</action>
+</step>
+```
+
+**During workflow creation**, you'll be asked to choose a **primary style preference** - this sets the default approach, but you can (and should) use the other style when it makes more sense for specific steps.
+
+## Workflow Process
+
+### Phase 0: Optional Brainstorming (Step -1)
+
+- **Creative Exploration**: Option to brainstorm workflow ideas before structured development
+- **Design Concept Development**: Generate multiple approaches and explore different possibilities
+- **Requirement Clarification**: Use brainstorming output to inform workflow purpose, type, and structure
+- **Enhanced Creativity**: Leverage AI brainstorming tools for innovative workflow design
+
+The brainstorming phase invokes the CIS brainstorming workflow to:
+
+- Explore workflow ideas and approaches
+- Clarify requirements and use cases
+- Generate creative solutions for complex automation needs
+- Inform the structured workflow building process
+
+### Phase 1: Planning (Steps 0-3)
+
+- Load workflow creation guide and conventions
+- Define workflow purpose, name, and type (informed by brainstorming if used)
+- Gather metadata and configuration details
+- Design step structure and flow
+
+### Phase 2: Generation (Steps 4-8)
+
+- Create workflow.yaml with proper configuration
+- Generate instructions.md with XML-structured steps
+- Create template.md (for document workflows)
+- Generate validation checklist
+- Create supporting data files (optional)
+
+### Phase 3: Documentation and Validation (Steps 9-11)
+
+- Create comprehensive README.md (MANDATORY)
+- Test and validate workflow structure
+- Provide usage instructions and next steps
+
+## Output
+
+### Generated Workflow Folder
+
+Creates a complete workflow folder at:
+`{project-root}/bmad/{{target_module}}/workflows/{{workflow_name}}/`
+
+### Files Created
+
+**Always Created:**
+
+- `workflow.yaml` - Configuration with paths and variables
+- `README.md` - Comprehensive documentation (MANDATORY as of v6)
+- `instructions.md` - Execution steps (if not template-only workflow)
+
+**Conditionally Created:**
+
+- `template.md` - Document structure (for document workflows)
+- `checklist.md` - Validation criteria (optional but recommended)
+- Supporting data files (CSV, JSON, etc. as needed)
+
+### Output Structure
+
+For document workflows, the README documents:
+
+- Workflow purpose and use cases
+- Usage examples with actual commands
+- Input expectations
+- Output structure and location
+- Best practices
+
+## Requirements
+
+- Access to workflow creation guide
+- BMAD Core v6 project structure
+- Module to host the new workflow (bmm, bmb, cis, or custom)
+
+## Best Practices
+
+### Before Starting
+
+1. **Consider Brainstorming**: If you're unsure about the workflow approach, use the optional brainstorming phase
+2. Review the workflow creation guide to understand conventions
+3. Have a clear understanding of the workflow's purpose (or be ready to explore it creatively)
+4. Know which type of workflow you're creating (document, action, etc.) or be open to discovery
+5. Identify any data files or references needed
+
+### Creative Workflow Design
+
+The create-workflow now supports a **seamless transition from creative ideation to structured implementation**:
+
+- **"I need a workflow for something..."** → Start with brainstorming to explore possibilities
+- **Brainstorm** → Generate multiple approaches and clarify requirements
+- **Structured workflow** → Build the actual workflow using insights from brainstorming
+- **One seamless session** → Complete the entire process from idea to implementation
+
+### During Execution
+
+1. Follow kebab-case naming conventions
+2. Be specific with step goals and instructions
+3. Use descriptive variable names (snake_case)
+4. Set appropriate limits ("3-5 items maximum")
+5. Include examples where helpful
+
+### After Completion
+
+1. Test the newly created workflow
+2. Validate against the checklist
+3. Ensure README is comprehensive and accurate
+4. Test all file paths and variable references
+
+## Troubleshooting
+
+### Issue: Generated workflow won't execute
+
+- **Solution**: Verify all file paths in workflow.yaml use proper variable substitution
+- **Check**: Ensure installed_path and project-root are correctly set
+
+### Issue: Variables not replacing in template
+
+- **Solution**: Ensure variable names match exactly between instructions `<template-output>` tags and template `{{variables}}`
+- **Check**: Use snake_case consistently
+
+### Issue: README has placeholder text
+
+- **Solution**: This workflow now enforces README generation - ensure Step 10 completed fully
+- **Check**: No {WORKFLOW_TITLE} or similar placeholders should remain
+
+## Customization
+
+To modify this workflow:
+
+1. Edit `instructions.md` to adjust the creation process
+2. Update templates in `workflow-template/` to change generated files
+3. Modify `workflow-creation-guide.md` to update conventions
+4. Edit `checklist.md` to change validation criteria
+
+## Version History
+
+- **v6.0.0** - README.md now MANDATORY for all workflows
+  - Added comprehensive README template
+  - Enhanced validation for documentation
+  - Improved Step 10 with detailed README requirements
+
+- **v6.0.0** - Initial BMAD Core v6 compatible version
+  - Template-based workflow generation
+  - Convention enforcement
+  - Validation checklist support
+
+## Support
+
+For issues or questions:
+
+- Review `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
+- Check existing workflows in `/bmad/bmm/workflows/` for examples
+- Validate against `/bmad/bmb/workflows/create-workflow/checklist.md`
+- Consult BMAD Method v6 documentation
+
+---
+
+_Part of the BMad Method v6 - BMB (BMad Builder) Module_

package/bmad/bmb/workflows/create-workflow/brainstorm-context.md

@@ -0,0 +1,197 @@
+# Workflow Brainstorming Context
+
+_Context provided to brainstorming workflow when creating a new BMAD workflow_
+
+## Session Focus
+
+You are brainstorming ideas for a **BMAD workflow** - a guided, multi-step process that helps users accomplish complex tasks with structure, consistency, and quality.
+
+## What is a BMAD Workflow?
+
+A workflow is a structured process that provides:
+
+- **Clear Steps**: Sequential operations with defined goals
+- **User Guidance**: Prompts, questions, and decisions at each phase
+- **Quality Output**: Documents, artifacts, or completed actions
+- **Repeatability**: Same process yields consistent results
+- **Type**: Document (creates docs), Action (performs tasks), Interactive (guides sessions), Autonomous (runs automated), Meta (orchestrates other workflows)
+
+## Brainstorming Goals
+
+Explore and define:
+
+### 1. Problem and Purpose
+
+- **What task needs structure?** (specific process users struggle with)
+- **Why is this hard manually?** (complexity, inconsistency, missing steps)
+- **What would ideal process look like?** (steps, checkpoints, outputs)
+- **Who needs this?** (target users and their pain points)
+
+### 2. Process Flow
+
+- **How many phases?** (typically 3-10 major steps)
+- **What's the sequence?** (logical flow from start to finish)
+- **What decisions are needed?** (user choices that affect path)
+- **What's optional vs required?** (flexibility points)
+- **What checkpoints matter?** (validation, review, approval points)
+
+### 3. Inputs and Outputs
+
+- **What inputs are needed?** (documents, data, user answers)
+- **What outputs are generated?** (documents, code, configurations)
+- **What format?** (markdown, XML, YAML, actions)
+- **What quality criteria?** (how to validate success)
+
+### 4. Workflow Type and Style
+
+- **Document Workflow?** Creates structured documents (PRDs, specs, reports)
+- **Action Workflow?** Performs operations (refactoring, deployment, analysis)
+- **Interactive Workflow?** Guides creative process (brainstorming, planning)
+- **Autonomous Workflow?** Runs without user input (batch processing, generation)
+- **Meta Workflow?** Orchestrates other workflows (project setup, module creation)
+
+## Creative Constraints
+
+A great BMAD workflow should be:
+
+- **Focused**: Solves one problem well (not everything)
+- **Structured**: Clear phases with defined goals
+- **Flexible**: Optional steps, branching paths where appropriate
+- **Validated**: Checklist to verify completeness and quality
+- **Documented**: README explains when and how to use it
+
+## Workflow Architecture Questions
+
+### Core Structure
+
+1. **Workflow name** (kebab-case, e.g., "product-brief")
+2. **Purpose** (one sentence)
+3. **Type** (document/action/interactive/autonomous/meta)
+4. **Major phases** (3-10 high-level steps)
+5. **Output** (what gets created)
+
+### Process Details
+
+1. **Required inputs** (what user must provide)
+2. **Optional inputs** (what enhances results)
+3. **Decision points** (where user chooses path)
+4. **Checkpoints** (where to pause for approval)
+5. **Variables** (data passed between steps)
+
+### Quality and Validation
+
+1. **Success criteria** (what defines "done")
+2. **Validation checklist** (measurable quality checks)
+3. **Common issues** (troubleshooting guidance)
+4. **Best practices** (tips for optimal results)
+
+## Workflow Pattern Examples
+
+### Document Generation Workflows
+
+- **Product Brief**: Idea → Vision → Features → Market → Output
+- **PRD**: Requirements → User Stories → Acceptance Criteria → Document
+- **Architecture**: Requirements → Decisions → Design → Diagrams → ADRs
+- **Technical Spec**: Epic → Implementation → Testing → Deployment → Doc
+
+### Action Workflows
+
+- **Code Refactoring**: Analyze → Plan → Refactor → Test → Commit
+- **Deployment**: Build → Test → Stage → Validate → Deploy → Monitor
+- **Migration**: Assess → Plan → Convert → Validate → Deploy
+- **Analysis**: Collect → Process → Analyze → Report → Recommend
+
+### Interactive Workflows
+
+- **Brainstorming**: Setup → Generate → Expand → Evaluate → Prioritize
+- **Planning**: Context → Goals → Options → Decisions → Plan
+- **Review**: Load → Analyze → Critique → Suggest → Document
+
+### Meta Workflows
+
+- **Project Setup**: Plan → Architecture → Stories → Setup → Initialize
+- **Module Creation**: Brainstorm → Brief → Agents → Workflows → Install
+- **Sprint Planning**: Backlog → Capacity → Stories → Commit → Kickoff
+
+## Workflow Design Patterns
+
+### Linear Flow
+
+Simple sequence: Step 1 → Step 2 → Step 3 → Done
+
+**Good for:**
+
+- Document generation
+- Structured analysis
+- Sequential builds
+
+### Branching Flow
+
+Conditional paths: Step 1 → [Decision] → Path A or Path B → Merge → Done
+
+**Good for:**
+
+- Different project types
+- Optional deep dives
+- Scale-adaptive processes
+
+### Iterative Flow
+
+Refinement loops: Step 1 → Step 2 → [Review] → (Repeat if needed) → Done
+
+**Good for:**
+
+- Creative processes
+- Quality refinement
+- Approval cycles
+
+### Router Flow
+
+Type selection: [Select Type] → Load appropriate instructions → Execute → Done
+
+**Good for:**
+
+- Multi-mode workflows
+- Reusable frameworks
+- Flexible tools
+
+## Suggested Brainstorming Techniques
+
+Particularly effective for workflow ideation:
+
+1. **Process Mapping**: Draw current painful process, identify improvements
+2. **Step Decomposition**: Break complex task into atomic steps
+3. **Checkpoint Thinking**: Where do users need pause/review/decision?
+4. **Pain Point Analysis**: What makes current process frustrating?
+5. **Success Visualization**: What does perfect execution look like?
+
+## Key Questions to Answer
+
+1. What manual process needs structure and guidance?
+2. What makes this process hard or inconsistent today?
+3. What are the 3-10 major phases/steps?
+4. What document or output gets created?
+5. What inputs are required from the user?
+6. What decisions or choices affect the flow?
+7. What quality criteria define success?
+8. Document, Action, Interactive, Autonomous, or Meta workflow?
+9. What makes this workflow valuable vs doing it manually?
+10. What would make this workflow delightful to use?
+
+## Output Goals
+
+Generate:
+
+- **Workflow name**: Clear, describes the process
+- **Purpose statement**: One sentence explaining value
+- **Workflow type**: Classification with rationale
+- **Phase outline**: 3-10 major steps with goals
+- **Input/output description**: What goes in, what comes out
+- **Key decisions**: Where user makes choices
+- **Success criteria**: How to know it worked
+- **Unique value**: Why this workflow beats manual process
+- **Use cases**: 3-5 scenarios where this workflow shines
+
+---
+
+_This focused context helps create valuable, structured BMAD workflows_

package/bmad/bmb/workflows/create-workflow/checklist.md

@@ -0,0 +1,94 @@
+# Build Workflow - Validation Checklist
+
+## Workflow Configuration (workflow.yaml)
+
+- [ ] Name follows kebab-case convention
+- [ ] Description clearly states workflow purpose
+- [ ] All paths use proper variable substitution
+- [ ] installed_path points to correct module location
+- [ ] template/instructions paths are correct for workflow type
+- [ ] Output file pattern is appropriate
+- [ ] YAML syntax is valid (no parsing errors)
+
+## Instructions Structure (instructions.md)
+
+- [ ] Critical headers reference workflow engine
+- [ ] All steps have sequential numbering
+- [ ] Each step has a clear goal attribute
+- [ ] Optional steps marked with optional="true"
+- [ ] Repeating steps have appropriate repeat attributes
+- [ ] All template-output tags have unique variable names
+- [ ] Flow control (if any) has valid step references
+
+## Template Structure (if document workflow)
+
+- [ ] All sections have appropriate placeholders
+- [ ] Variable names match template-output tags exactly
+- [ ] Markdown formatting is valid
+- [ ] Date and metadata fields included
+- [ ] No unreferenced variables remain
+
+## Content Quality
+
+- [ ] Instructions are specific and actionable
+- [ ] Examples provided where helpful
+- [ ] Limits set for lists and content length
+- [ ] User prompts are clear
+- [ ] Step goals accurately describe outcomes
+
+## Validation Checklist (if present)
+
+- [ ] Criteria are measurable and specific
+- [ ] Checks grouped logically by category
+- [ ] Final validation summary included
+- [ ] All critical requirements covered
+
+## File System
+
+- [ ] Workflow folder created in correct module
+- [ ] All required files present based on workflow type
+- [ ] File permissions allow execution
+- [ ] No placeholder text remains (like {TITLE})
+
+## Testing Readiness
+
+- [ ] Workflow can be invoked without errors
+- [ ] All required inputs are documented
+- [ ] Output location is writable
+- [ ] Dependencies (if any) are available
+
+## Web Bundle Configuration (if applicable)
+
+- [ ] web_bundle section present if needed
+- [ ] Name, description, author copied from main config
+- [ ] All file paths converted to bmad/-relative format
+- [ ] NO {config_source} variables in web bundle
+- [ ] NO {project-root} prefixes in paths
+- [ ] Instructions path listed correctly
+- [ ] Validation/checklist path listed correctly
+- [ ] Template path listed (if document workflow)
+- [ ] All data files referenced in instructions are listed
+- [ ] All sub-workflows are included
+- [ ] web_bundle_files array is complete:
+  - [ ] Instructions.md included
+  - [ ] Checklist.md included
+  - [ ] Template.md included (if applicable)
+  - [ ] All CSV/JSON data files included
+  - [ ] All referenced templates included
+  - [ ] All sub-workflow files included
+- [ ] No external dependencies outside bundle
+
+## Documentation
+
+- [ ] README created (if requested)
+- [ ] Usage instructions clear
+- [ ] Example command provided
+- [ ] Special requirements noted
+- [ ] Web bundle deployment noted (if applicable)
+
+## Final Validation
+
+- [ ] Configuration: No issues
+- [ ] Instructions: Complete and clear
+- [ ] Template: Variables properly mapped
+- [ ] Testing: Ready for test run