bmad-method 6.0.0-alpha.22 → 6.0.0-alpha.23

package/src/modules/bmb/docs/workflows/step-file-rules.md

@@ -1,469 +0,0 @@
-# BMAD Step File Guidelines
-
-**Version:** 1.0
-**Module:** bmb (BMAD Builder)
-**Purpose:** Definitive guide for creating BMAD workflow step files
-
----
-
-## Overview
-
-BMAD workflow step files follow a strict structure to ensure consistency, progressive disclosure, and mode-aware routing. Every step file MUST adhere to these guidelines.
-
----
-
-## File Size Optimization
-
-**CRITICAL:** Keep step files **LT 200 lines** (250 lines absolute maximum).
-
-If a step exceeds this limit:
-- Consider splitting into multiple steps
-- Extract content to `/data/` reference files
-- Optimize verbose explanations
-
----
-
-## Required Frontmatter Structure
-
-CRITICAL: Frontmatter should only have items that are used in the step file!
-
-```yaml
----
-name: 'step-2-foo.md'
-description: 'Brief description of what this step accomplishes'
-
-# File References ## CRITICAL: Frontmatter references or variables should only have items that are used in the step file!
-outputFile: {bmb_creations_output_folder}/output-file-name.md
-nextStepFile: './step-3-bar.md'
-
-# Task References (as needed)
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
-# ... other task-specific references
----
-```
-
-### Frontmatter Field Descriptions
-
-| Field           | Required  | Description                       |
-| --------------- | --------- | --------------------------------- |
-| `name`          | Yes       | Step identifier (kebab-case)      |
-| `description`   | Yes       | One-line summary of step purpose  |
-| `outputFile`    | Yes       | Where results are documented      |
-| Task references | As needed | Paths to external workflows/tasks |
-
----
-
-## Document Structure
-
-### 1. Title
-
-```markdown
-# Step X: [Step Name]
-```
-
-### 2. STEP GOAL
-
-```markdown
-## STEP GOAL:
-
-[Single sentence stating what this step accomplishes]
-```
-
-### 3. Role Reinforcement
-
-```markdown
-### Role Reinforcement:
-
-- ✅ You are a [specific role] who [does what]
-- ✅ 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], together we [achieve goal]
-- ✅ Maintain [tone/approach] throughout
-```
-
-### 4. Language Preference
-
-```markdown
-### Language Preference:
-The user has chosen to communicate in the **{language}** language.
-You MUST respond in **{language}** throughout this step.
-```
-
-**IMPORTANT:** Read `userPreferences.language` from tracking file (agentPlan, validationReport, etc.) and enforce it.
-
-### 5. Step-Specific Rules
-
-```markdown
-### Step-Specific Rules:
-
-- 🎯 Focus only on [specific scope]
-- 🚫 FORBIDDEN to [prohibited action]
-- 💬 Approach: [how to engage]
-- 📋 Ensure [specific outcome]
-```
-
-### 6. EXECUTION PROTOCOLS
-
-```markdown
-## EXECUTION PROTOCOLS:
-
-- [What to do - use verbs]
-- [Another action]
-- 🚫 FORBIDDEN to [prohibited action]
-```
-
-### 7. CONTEXT BOUNDARIES
-
-```markdown
-## CONTEXT BOUNDARIES:
-
-- Available context: [what's available]
-- Focus: [what to focus on]
-- Limits: [boundaries]
-- Dependencies: [what this step depends on]
-```
-
-### 8. Sequence of Instructions
-
-```markdown
-## Sequence of Instructions:
-
-### 1. [First Action]
-
-**[Action Description]**
-
-### 2. [Second Action]
-
-...
-```
-
-### 9. MENU OPTIONS
-
-```markdown
-### X. Present MENU OPTIONS
-
-Display: "**Select:** [A] [menu item A] [P] [menu item P] [C] [menu item C]"
-
-#### Menu Handling Logic:
-- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
-- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
-- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
-- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#x-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
-
-## CRITICAL STEP COMPLETION NOTE
-ONLY WHEN [C continue option] is selected and [completion conditions], will you then load and read fully `{nextStepFile}`...
-```
-
-### 10. SYSTEM SUCCESS/FAILURE METRICS
-
-```markdown
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-- [Success criterion 1]
-- [Success criterion 2]
-- ...
-
-### ❌ SYSTEM FAILURE:
-- [Failure criterion 1]
-- [Failure criterion 2]
-- ...
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
-```
-
----
-
-## A/P/C Menu Convention
-
-BMAD workflows use a fixed menu structure:
-
-| Option | Meaning              | Behavior                                             |
-| ------ | -------------------- | ---------------------------------------------------- |
-| **A**  | Advanced Elicitation | Execute advancedElicitationTask, then redisplay menu |
-| **P**  | Party Mode           | Execute partyModeWorkflow, then redisplay menu       |
-| **C**  | Continue/Accept      | Save output, update frontmatter, load nextStepFile   |
-| Other  | Custom               | Defined per step (e.g., F = Fix, X = Exit)           |
-
-**Rules:**
-- A and P MUST always be present
-- C MUST be present except in final step (use X or similar for exit)
-- After A/P → redisplay menu
-- After C → proceed to next step
-- Custom letters can be used for step-specific options
-
----
-
-## Progressive Disclosure
-
-**Core Principle:** Each step only knows about its immediate next step.
-
-### Implementation
-
-1. **Never pre-load future steps** - Only load `nextStepFile` when user selects [C]
-
-2. **Mode-aware routing** (for shared steps):
-   ```markdown
-   ## MODE-AWARE ROUTING:
-   ### If entered from CREATE mode:
-   Load ./s-next-step.md
-
-   ### If entered from EDIT mode:
-   Load ./e-next-step.md
-
-   ### If entered from VALIDATE mode:
-   Load ./v-next-step.md
-   ```
-
-3. **Read tracking file first** - Always read the tracking file (agentPlan, validationReport, etc.) to determine current mode and routing
-
----
-
-## Mode-Aware Routing (Shared Steps)
-
-Shared steps (`s-*.md`) must route based on the mode stored in the tracking file.
-
-### Tracking File Frontmatter
-
-```yaml
----
-mode: create              # or edit | validate
-stepsCompleted:
-  - c-01-brainstorm.md
-  - s-01-discovery.md
-# ... other tracking fields
----
-```
-
-### Routing Implementation
-
-```markdown
-## COMPLETION ROUTING:
-
-1. Append `./this-step-name.md` to {trackingFile}.stepsCompleted
-2. Save content to {trackingFile}
-3. Read {trackingFile}.mode
-4. Route based on mode:
-
-### IF mode == create:
-Load ./s-next-create-step.md
-
-### IF mode == edit:
-Load ./e-next-edit-step.md
-
-### IF mode == validate:
-Load ./s-next-validate-step.md
-```
-
----
-
-## File Naming Conventions
-
-### Tri-Modal Workflows
-
-| Prefix | Meaning            | Example                |
-| ------ | ------------------ | ---------------------- |
-| `c-`   | Create-specific    | `c-01-brainstorm.md`   |
-| `e-`   | Edit-specific      | `e-01-load-analyze.md` |
-| `v-`   | Validate-specific  | `v-01-load-review.md`  |
-| `s-`   | Shared by 2+ modes | `s-05-activation.md`   |
-
-### Numbering
-
-- Within each prefix type, number sequentially
-- Restart numbering for each prefix type (c-01, e-01, v-01, s-01)
-- Use letters for sub-steps (s-06a, s-06b, s-06c)
-
----
-
-## Language Preference Enforcement
-
-**CRITICAL:** Every step MUST respect the user's chosen language.
-
-### Implementation
-
-```markdown
-### Language Preference:
-The user has chosen to communicate in the **{language}** language.
-You MUST respond in **{language}** throughout this step.
-```
-
-### Reading Language Preference
-
-From tracking file frontmatter:
-```yaml
----
-userPreferences:
-  language: spanish    # or any language
----
-```
-
-### Rules
-
-- **MUST** read language preference from tracking file at step start
-- **MUST** respond in user's chosen language for ALL content
-- **MUST** include menu options in user's chosen language
-- **EXCEPTION:** Technical terms, file names, and code remain in English
-
----
-
-## Data File References
-
-When step content becomes too large (>200 lines), extract to `/data/` files:
-
-### When to Extract
-
-- Step file exceeds 200 lines
-- Content is reference material (rules, examples, patterns)
-- Content is reused across multiple steps
-
-### How to Reference
-
-```markdown
-## Reference Material:
-
-Load and reference: `../data/{data-file-name}.md`
-
-Key points from that file:
-- [Point 1]
-- [Point 2]
-```
-
-### Data File Best Practices
-
-- Keep data files focused on single topic
-- Use clear, descriptive names
-- Include examples and non-examples
-- Optimize for LLM usage (concise, structured)
-
----
-
-## Common Pitfalls to Avoid
-
-### ❌ DON'T:
-
-- Pre-load future steps (violates progressive disclosure)
-- Exceed 250 lines without splitting
-- Forget to update `stepsCompleted` array
-- Ignore user's language preference
-- Skip mode checking in shared steps
-- Use vague menu option letters (stick to A/P/C plus 1-2 custom)
-
-### ✅ DO:
-
-- Keep files under 200 lines
-- Read tracking file first thing
-- Route based on `mode` field
-- Include A/P in every menu
-- Use descriptive step names
-- Extract complex content to data files
-
----
-
-## Template: New Step File
-
-```markdown
----
-name: 'step-name'
-description: 'What this step does'
-
-# File References
-thisStepFile: ./step-name.md
-workflowFile: ../workflow.md
-outputFile: {bmb_creations_output_folder}/output.md
-
-# Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
----
-
-# Step X: [Step Name]
-
-## STEP GOAL:
-
-[Single sentence goal]
-
-### Role Reinforcement:
-
-- ✅ You are a [role] who [does what]
-- ✅ 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 [expertise], user brings [expertise], together we [achieve]
-- ✅ Maintain [tone] throughout
-
-### Language Preference:
-The user has chosen to communicate in the **{language}** language.
-You MUST respond in **{language}** throughout this step.
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on [scope]
-- 🚫 FORBIDDEN to [prohibited action]
-- 💬 Approach: [how to engage]
-- 📋 Ensure [outcome]
-
-## EXECUTION PROTOCOLS:
-
-- [Action 1]
-- [Action 2]
-- 🚫 FORBIDDEN to [prohibited action]
-
-## CONTEXT BOUNDARIES:
-
-- Available context: [what's available]
-- Focus: [what to focus on]
-- Limits: [boundaries]
-- Dependencies: [what depends on what]
-
-## Sequence of Instructions:
-
-### 1. [First Action]
-
-**Description of first action**
-
-### 2. [Second Action]
-
-**Description of second action**
-
-...
-
-### X. Present MENU OPTIONS
-
-Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
-
-#### Menu Handling Logic:
-- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
-- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
-- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
-- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#x-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
-
-## CRITICAL STEP COMPLETION NOTE
-ONLY WHEN [C continue option] is selected and [conditions], will you then load and read fully `{nextStepFile}`...
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-- [Success criteria]
-
-### ❌ SYSTEM FAILURE:
-- [Failure criteria]
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
-```
-
----
-
-**End of Guidelines**

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

@@ -1,139 +0,0 @@
----
-name: "step-{{stepNumber}}-{{stepName}}"
-description: "{{stepDescription}}"
-
-# Path Definitions
-workflow_path: "{project-root}/_bmad/{{targetModule}}/workflows/{{workflowName}}"
-
-# File References
-thisStepFile: "{workflow_path}/steps/step-{{stepNumber}}-{{stepName}}.md"
-{{#hasNextStep}}
-nextStepFile: "{workflow_path}/steps/step-{{nextStepNumber}}-{{nextStepName}}.md"
-{{/hasNextStep}}
-workflowFile: "{workflow_path}/workflow.md"
-{{#hasOutput}}
-outputFile: "{output_folder}/{{outputFileName}}-{project_name}.md"
-{{/hasOutput}}
-
-# Task References (list only if used in THIS step file instance and only the ones used, there might be others)
-advancedElicitationTask: "{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml"
-partyModeWorkflow: "{project-root}/_bmad/core/workflows/party-mode/workflow.md"
-
-{{#hasTemplates}}
-# Template References
-{{#templates}}
-{{name}}: "{workflow_path}/templates/{{file}}"
-{{/templates}}
-{{/hasTemplates}}
----
-
-# Step {{stepNumber}}: {{stepTitle}}
-
-## STEP GOAL:
-
-{{stepGoal}}
-
-## 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 {{aiRole}}
-- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
-- ✅ We engage in collaborative dialogue, not command-response
-- ✅ You bring {{aiExpertise}}, user brings {{userExpertise}}
-- ✅ Maintain collaborative {{collaborationStyle}} tone throughout
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on {{stepFocus}}
-- 🚫 FORBIDDEN to {{forbiddenAction}}
-- 💬 Approach: {{stepApproach}}
-- 📋 {{additionalRule}}
-
-## EXECUTION PROTOCOLS:
-
-{{#executionProtocols}}
-
-- 🎯 {{.}}
-  {{/executionProtocols}}
-
-## CONTEXT BOUNDARIES:
-
-- Available context: {{availableContext}}
-- Focus: {{contextFocus}}
-- Limits: {{contextLimits}}
-- Dependencies: {{contextDependencies}}
-
-## SEQUENCE OF INSTRUCTIONS (Do not deviate, skip, or optimize)
-
-{{#instructions}}
-
-### {{number}}. {{title}}
-
-{{content}}
-
-{{#hasContentToAppend}}
-
-#### Content to Append (if applicable):
-
-```markdown
-{{contentToAppend}}
-```
-
-{{/hasContentToAppend}}
-
-{{/instructions}}
-
-{{#hasMenu}}
-
-### {{menuNumber}}. Present MENU OPTIONS
-
-Display: **{{menuDisplay}}**
-
-#### 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
-- Use menu handling logic section below
-
-#### Menu Handling Logic:
-
-{{#menuOptions}}
-
-- IF {{key}}: {{action}}
-  {{/menuOptions}}
-- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#{{menuNumber}}-present-menu-options)
-  {{/hasMenu}}
-
-## CRITICAL STEP COMPLETION NOTE
-
-{{completionNote}}
-
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-{{#successCriteria}}
-
-- {{.}}
-  {{/successCriteria}}
-
-### ❌ SYSTEM FAILURE:
-
-{{#failureModes}}
-
-- {{.}}
-  {{/failureModes}}
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

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

@@ -1,58 +0,0 @@
----
-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.