bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.20

package/src/modules/bmb/docs/workflows/templates/step-template.md

@@ -0,0 +1,290 @@
+# BMAD Workflow Step Template
+
+This template provides the standard structure for all BMAD workflow step files. Copy and modify this template for each new step you create.
+
+<!-- TEMPLATE START -->
+
+---
+
+name: 'step-[N]-[short-name]'
+description: '[Brief description of what this step accomplishes]'
+
+<!-- Path Definitions -->
+
+workflow\*path: '{project-root}/_bmad/[module]/reference/workflows/[workflow-name]' # the folder the workflow.md file is in
+
+# File References (all use {variable} format in file)
+
+thisStepFile: '{workflow_path}/steps/step-[N]-[short-name].md'
+nextStep{N+1}: '{workflow_path}/steps/step-[N+1]-[next-short-name].md' # Remove for final step or no next step
+altStep{Y}: '{workflow_path}/steps/step-[Y]-[some-other-step].md' # if there is an alternate next story depending on logic
+workflowFile: '{workflow_path}/workflow.md'
+outputFile: '{output_folder}/[output-file-name]-{project_name}.md'
+
+# Task References (IF THE workflow uses and it makes sense in this step to have these )
+
+advancedElicitationTask: '{project-root}/_bmad/core/tasks/advanced-elicitation.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+
+# Template References (if this step uses a specific templates)
+
+profileTemplate: '{workflow_path}/templates/profile-section.md'
+assessmentTemplate: '{workflow_path}/templates/assessment-section.md'
+strategyTemplate: '{workflow_path}/templates/strategy-section.md'
+
+# Data (CSV for example) References (if used in this step)
+
+someData: '{workflow_path}/data/foo.csv'
+
+# Add more as needed - but ONLY what is used in this specific step file!
+
+---
+
+# Step [N]: [Step Name]
+
+## STEP GOAL:
+
+[State the goal in context of the overall workflow goal. Be specific about what this step accomplishes and how it contributes to the workflow's purpose.]
+
+Example: "To analyze user requirements and document functional specifications that will guide the development process"
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are a [specific role, e.g., "business analyst" or "technical architect"]
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring [your expertise], user brings [their expertise], and together we produce something better than we could on our own
+- ✅ Maintain collaborative [adjective] tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on [specific task for this step]
+- 🚫 FORBIDDEN to [what not to do in this step]
+- 💬 Approach: [how to handle this specific task]
+- 📋 Additional rule relevant to this step
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 [Step-specific protocol 1]
+- 💾 [Step-specific protocol 2 - e.g., document updates]
+- 📖 [Step-specific protocol 3 - e.g., tracking requirements]
+- 🚫 [Step-specific restriction]
+
+## CONTEXT BOUNDARIES:
+
+- Available context: [what context is available from previous steps]
+- Focus: [what this step should concentrate on]
+- Limits: [what not to assume or do]
+- Dependencies: [what this step depends on]
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+[Detailed instructions for the step's work]
+
+### 1. Title
+
+[Specific instructions for first part of the work]
+
+### 2. Title
+
+[Specific instructions for second part of the work]
+
+### N. Title (as many as needed)
+
+<!-- not ever step will include advanced elicitation or party mode, in which case generally will just have the C option -->
+<!-- for example an init step 1 that loads data, or step 1b continues a workflow would not need advanced elicitation or party mode - but any step where the user and the llm work together on content, thats where it makes sense to include them -->
+
+### N. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Execute {advancedElicitationTask} # Or custom action
+- IF P: Execute {partyModeWorkflow} # Or custom action
+- IF C: Save content to {outputFile}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution completes, redisplay the menu
+- User can chat or ask questions - always respond when conversation ends, redisplay the menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+[Specific conditions for completing this step and transitioning to the next, such as output to file being created with this tasks updates]
+
+ONLY WHEN [C continue option] is selected and [completion requirements], will you then load and read fully `[installed_path]/step-[next-number]-[name].md` to execute and begin [next step description].
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- [Step-specific success criteria 1]
+- [Step-specific success criteria 2]
+- Content properly saved/document updated
+- Menu presented and user input handled correctly
+- [General success criteria]
+
+### ❌ SYSTEM FAILURE:
+
+- [Step-specific failure mode 1]
+- [Step-specific failure mode 2]
+- Proceeding without user input/selection
+- Not updating required documents/frontmatter
+- [Step-specific failure mode N]
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+<!-- TEMPLATE END-->
+
+## Common Menu Patterns to use in the final sequence item in a step file
+
+FYI Again - party mode is useful for the user to reach out and get opinions from other agents.
+
+Advanced elicitation is use to direct you to think of alternative outputs of a sequence you just performed.
+
+### Standard Menu - when a sequence in a step results in content produced by the agent or human that could be improved before proceeding
+
+```markdown
+### N. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] [Advanced Elicitation] [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Execute {advancedElicitationTask}
+- IF P: Execute {partyModeWorkflow}
+- IF C: Save content to {outputFile}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+```
+
+### Optional Menu - Auto-Proceed Menu (No User Choice or confirm, just flow right to the next step once completed)
+
+```markdown
+### N. Present MENU OPTIONS
+
+Display: "**Proceeding to [next action]...**"
+
+#### Menu Handling Logic:
+
+- After [completion condition], immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an [auto-proceed reason] step with no user choices
+- Proceed directly to next step after setup
+```
+
+### Custom Menu Options
+
+```markdown
+### N. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] [Custom Action 1] [B] [Custom Action 2] [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: [Custom handler route for option A]
+- IF B: [Custom handler route for option B]
+- IF C: Save content to {outputFile}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+```
+
+### Conditional Menu (Based on Workflow State)
+
+```markdown
+### N. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] [Continue to Step Foo] [A] [Continue to Step Bar]"
+
+#### Menu Handling Logic:
+
+- IF A: Execute {customAction}
+- IF C: Save content to {outputFile}, update frontmatter, check [condition]:
+  - IF [condition true]: load, read entire file, then execute {pathA}
+  - IF [condition false]: load, read entire file, then execute {pathB}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+```
+
+## Example Step Implementations
+
+### Initialization Step Example
+
+See [step-01-init.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-01-init.md) for an example of:
+
+- Detecting existing workflow state and short circuit to 1b
+- Creating output documents from templates
+- Auto-proceeding to the next step (this is not the normal behavior of most steps)
+- Handling continuation scenarios
+
+### Continuation Step Example
+
+See [step-01b-continue.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-01b-continue.md) for an example of:
+
+- Handling already-in-progress workflows
+- Detecting completion status
+- Presenting update vs new plan options
+- Seamless workflow resumption
+
+### Standard Step with Menu Example
+
+See [step-02-profile.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-02-profile.md) for an example of:
+
+- Presenting a menu with A/P/C options
+- Forcing halt until user selects 'C' (Continue)
+- Writing all collected content to output file only when 'C' is selected
+- Updating frontmatter with step completion before proceeding
+- Using frontmatter variables for file references
+
+### Final Step Example
+
+See [step-06-prep-schedule.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-06-prep-schedule.md) for an example of:
+
+- Completing workflow deliverables
+- Marking workflow as complete in frontmatter
+- Providing final success messages
+- Ending the workflow session gracefully
+
+## Best Practices
+
+1. **Keep step files focused** - Each step should do one thing well
+2. **Be explicit in instructions** - No ambiguity about what to do
+3. **Include all critical rules** - Don't assume anything from other steps
+4. **Use clear, concise language** - Avoid jargon unless necessary
+5. **Ensure all menu paths have handlers** - Ensure every option has clear instructions - use menu items that make sense for the situation.
+6. **Document dependencies** - Clearly state what this step needs with full paths in front matter
+7. **Define success and failure clearly** - Both for the step and the workflow
+8. **Mark completion clearly** - Ensure final steps update frontmatter to indicate workflow completion

package/src/modules/bmb/docs/workflows/templates/workflow-template.md

@@ -0,0 +1,104 @@
+# BMAD Workflow Template
+
+This template provides the standard structure for all BMAD workflow files. Copy and modify this template for each new workflow you create.
+
+<!-- TEMPLATE START -->
+
+---
+
+name: [WORKFLOW_DISPLAY_NAME]
+description: [Brief description of what this workflow accomplishes]
+web_bundle: [true/false] # Set to true for inclusion in web bundle builds
+
+---
+
+# [WORKFLOW_DISPLAY_NAME]
+
+**Goal:** [State the primary goal of this workflow in one clear sentence]
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a [role] collaborating with [user type]. This is a partnership, not a client-vendor relationship. You bring [your expertise], while the user brings [their expertise]. Work together as equals.
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time
+- **Just-In-Time Loading**: Only 1 current step file will be loaded, read, and executed to completion - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full config from {project-root}/_bmad/[MODULE FOLDER]/config.yaml and resolve:
+
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, [MODULE VARS]
+
+### 2. First Step EXECUTION
+
+Load, read the full file and then execute [FIRST STEP FILE PATH] to begin the workflow.
+
+<!-- TEMPLATE END -->
+
+## How to Use This Template
+
+### Step 1: Copy and Replace Placeholders
+
+Copy the template above and replace:
+
+- `[WORKFLOW_DISPLAY_NAME]` → Your workflow's display name
+- `[MODULE FOLDER]` → Default is `core` unless this is for another module (such as bmm, cis, or another as directed by user)
+- `[Brief description]` → One-sentence description
+- `[true/false]` → Whether to include in web bundle
+- `[role]` → AI's role in this workflow
+- `[user type]` → Who the user is
+- `[CONFIG_PATH]` → Path to config file (usually `bmm/config.yaml` or `bmb/config.yaml`)
+- `[WORKFLOW_PATH]` → Path to your workflow folder
+- `[MODULE VARS]` → Extra config variables available in a module configuration that the workflow would need to use
+
+### Step 2: Create the Folder Structure
+
+```
+[workflow-folder]/
+├── workflow.md          # This file
+├── data/                # (Optional csv or other data files)
+├── templates/           # template files for output
+└── steps/
+    ├── step-01-init.md
+    ├── step-02-[name].md
+    └── ...
+
+```
+
+### Step 3: Configure the Initialization Path
+
+Update the last line of the workflow.md being created to replace [FIRST STEP FILE PATH] with the path to the actual first step file.
+
+Example: Load, read the full file and then execute `{workflow_path}/steps/step-01-init.md` to begin the workflow.
+
+### NOTE: You can View a real example of a perfect workflow.md file that was created from this template
+
+`{project-root}/_bmad/bmb/reference/workflows/meal-prep-nutrition/workflow.md`

package/src/modules/bmb/docs/workflows/templates/workflow.md

@@ -0,0 +1,58 @@
+---
+name: { { workflowDisplayName } }
+description: { { workflowDescription } }
+web_bundle: { { webBundleFlag } }
+---
+
+# {{workflowDisplayName}}
+
+**Goal:** {{workflowGoal}}
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a {{aiRole}} collaborating with {{userType}}. This is a partnership, not a client-vendor relationship. You bring {{aiExpertise}}, while the user brings {{userExpertise}}. Work together as equals.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from {project-root}/_bmad/{{targetModule}}/config.yaml and resolve:
+
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+
+### 2. First Step EXECUTION
+
+Load, read the full file and then execute `{workflow_path}/steps/step-01-init.md` to begin the workflow.

package/src/modules/bmb/docs/workflows/terms.md

@@ -0,0 +1,97 @@
+# BMAD Workflow Terms
+
+## Core Components
+
+### BMAD Workflow
+
+A facilitated, guided process where the AI acts as a facilitator working collaboratively with a human. Workflows can serve any purpose - from document creation to brainstorming, technical implementation, or decision-making. The human may be a collaborative partner, beginner seeking guidance, or someone who wants the AI to execute specific tasks. Each workflow is self-contained and follows a disciplined execution model.
+
+### workflow.md
+
+The master control file that defines:
+
+- Workflow metadata (name, description, version)
+- Step sequence and file paths
+- Required data files and dependencies
+- Execution rules and protocols
+
+### Step File
+
+An individual markdown file containing:
+
+- One discrete step of the workflow
+- All rules and context needed for that step
+- Execution guardrails and validation criteria
+- Content generation guidance
+
+### step-01-init.md
+
+The first step file that:
+
+- Initializes the workflow
+- Sets up document frontmatter
+- Establishes initial context
+- Defines workflow parameters
+
+### step-01b-continue.md
+
+A continuation step file that:
+
+- Resumes a workflow that was paused
+- Reloads context from saved state
+- Validates current document state
+- Continues from the last completed step
+
+### CSV Data Files
+
+Structured data files that provide:
+
+- Domain-specific knowledge and complexity mappings
+- Project-type-specific requirements
+- Decision matrices and lookup tables
+- Dynamic workflow behavior based on input
+
+## Dialog Styles
+
+### Prescriptive Dialog
+
+Structured interaction with:
+
+- Exact questions and specific options
+- Consistent format across all executions
+- Finite, well-defined choices
+- High reliability and repeatability
+
+### Intent-Based Dialog
+
+Adaptive interaction with:
+
+- Goals and principles instead of scripts
+- Open-ended exploration and discovery
+- Context-aware question adaptation
+- Flexible, conversational flow
+
+### Template
+
+A markdown file that:
+
+- Starts with frontmatter (metadata)
+- Has content built through append-only operations
+- Contains no placeholder tags
+- Grows progressively as the workflow executes
+- Used when the workflow produces a document output
+
+## Execution Concepts
+
+### JIT Step Loading
+
+Just-In-Time step loading ensures:
+
+- Only the current step file is in memory
+- Complete focus on the step being executed
+- Minimal context to prevent information leakage
+- Sequential progression through workflow steps
+
+---
+
+_These terms form the foundation of the BMAD workflow system._

package/src/modules/bmb/module.yaml

@@ -0,0 +1,16 @@
+code: bmb
+name: "BMB: BMad Builder - Agent, Workflow and Module Builder"
+header: "BMad Optimized Builder (BoMB) Module Configuration"
+subheader: "Configure the settings for the BoMB Factory!\nThe agent, workflow and module builder for BMad™ "
+default_selected: false # This module will not be selected by default for new installations
+
+# Variables from Core Config inserted:
+## user_name
+## communication_language
+## document_output_language
+## output_folder
+
+bmb_creations_output_folder:
+  prompt: "Where should BoMB generated agents, workflows and modules SOURCE be saved?"
+  default: "{output_folder}/bmb-creations"
+  result: "{project-root}/{value}"

package/src/modules/bmb/reference/README.md

@@ -0,0 +1,3 @@
+# Reference Examples
+
+Reference models of best practices for agents, workflows, and whole modules.