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

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

@@ -0,0 +1,241 @@
+# BMAD Continuable Step 01 Init Template
+
+This template provides the standard structure for step-01-init files that support workflow continuation. It includes logic to detect existing workflows and route to step-01b-continue.md for resumption.
+
+Use this template when creating workflows that generate output documents and might take multiple sessions to complete.
+
+<!-- TEMPLATE START -->
+
+---
+
+name: 'step-01-init'
+description: 'Initialize the [workflow-type] workflow by detecting continuation state and creating output document'
+
+<!-- Path Definitions -->
+
+workflow\*path: `{project-root}/_bmad/[module-path]/workflows/[workflow-name]`
+
+# File References (all use {variable} format in file)
+
+thisStepFile: `{workflow_path}/steps/step-01-init.md`
+nextStepFile: `{workflow_path}/steps/step-02-[step-name].md`
+workflowFile: `{workflow_path}/workflow.md`
+outputFile: `{output_folder}/[output-file-name]-{project_name}.md`
+continueFile: `{workflow_path}/steps/step-01b-continue.md`
+templateFile: `{workflow_path}/templates/[main-template].md`
+
+# Template References
+
+# This step doesn't use content templates, only the main template
+
+---
+
+# Step 1: Workflow Initialization
+
+## 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"]
+- ✅ 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 initialization and setup
+- 🚫 FORBIDDEN to look ahead to future steps
+- 💬 Handle initialization professionally
+- 🚪 DETECT existing workflow state and handle continuation properly
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show analysis before taking any action
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+- Input document discovery happens in this step
+
+## STEP GOAL:
+
+To initialize the [workflow-type] workflow by detecting continuation state, creating the output document, and preparing for the first collaborative session.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Workflow
+
+First, check if the output document already exists:
+
+- Look for file at `{output_folder}/[output-file-name]-{project_name}.md`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted`:
+
+- **STOP here** and load `./step-01b-continue.md` immediately
+- Do not proceed with any initialization tasks
+- Let step-01b handle the continuation logic
+
+### 3. Handle Completed Workflow
+
+If the document exists AND all steps are marked complete in `stepsCompleted`:
+
+- Ask user: "I found an existing [workflow-output] from [date]. Would you like to:
+  1. Create a new [workflow-output]
+  2. Update/modify the existing [workflow-output]"
+- If option 1: Create new document with timestamp suffix
+- If option 2: Load step-01b-continue.md
+
+### 4. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+This workflow requires [describe input documents if any]:
+
+**[Document Type] Documents (Optional):**
+
+- Look for: `{output_folder}/*[pattern1]*.md`
+- Look for: `{output_folder}/*[pattern2]*.md`
+- If found, load completely and add to `inputDocuments` frontmatter
+
+#### B. Create Initial Document
+
+Copy the template from `{templateFile}` to `{output_folder}/[output-file-name]-{project_name}.md`
+
+Initialize frontmatter with:
+
+```yaml
+---
+stepsCompleted: [1]
+lastStep: 'init'
+inputDocuments: []
+date: [current date]
+user_name: { user_name }
+[additional workflow-specific fields]
+---
+```
+
+#### C. Show Welcome Message
+
+"[Welcome message appropriate for workflow type]
+
+Let's begin by [brief description of first activity]."
+
+## ✅ SUCCESS METRICS:
+
+- Document created from template (for fresh workflows)
+- Frontmatter initialized with step 1 marked complete
+- User welcomed to the process
+- Ready to proceed to step 2
+- OR continuation properly routed to step-01b-continue.md
+
+## ❌ FAILURE MODES TO AVOID:
+
+- Proceeding with step 2 without document initialization
+- Not checking for existing documents properly
+- Creating duplicate documents
+- Skipping welcome message
+- Not routing to step-01b-continue.md when needed
+
+### 5. Present MENU OPTIONS
+
+Display: **Proceeding to [next step description]...**
+
+#### EXECUTION RULES:
+
+- This is an initialization step with no user choices
+- Proceed directly to next step after setup
+- Use menu handling logic section below
+
+#### Menu Handling Logic:
+
+- After setup completion, immediately load, read entire file, then execute `{nextStepFile}` to begin [next step description]
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Document created from template (for fresh workflows)
+- update frontmatter `stepsCompleted` to add 1 at the end of the array before loading next step
+- Frontmatter initialized with `stepsCompleted: [1]`
+- User welcomed to the process
+- Ready to proceed to step 2
+- OR existing workflow properly routed to step-01b-continue.md
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with step 2 without document initialization
+- Not checking for existing documents properly
+- Creating duplicate documents
+- Skipping welcome message
+- Not routing to step-01b-continue.md when appropriate
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN initialization setup is complete and document is created (OR continuation is properly routed), will you then immediately load, read entire file, then execute `{nextStepFile}` to begin [next step description].
+
+<!-- TEMPLATE END -->
+
+## Customization Guidelines
+
+When adapting this template for your specific workflow:
+
+### 1. Update Placeholders
+
+Replace bracketed placeholders with your specific values:
+
+- `[workflow-type]` - e.g., "nutrition planning", "project requirements"
+- `[module-path]` - e.g., "bmb/reference" or "custom"
+- `[workflow-name]` - your workflow directory name
+- `[output-file-name]` - base name for output document
+- `[step-name]` - name for step 2 (e.g., "gather", "profile")
+- `[main-template]` - name of your main template file
+- `[workflow-output]` - what the workflow produces
+- `[Document Type]` - type of input documents (if any)
+- `[pattern1]`, `[pattern2]` - search patterns for input documents
+- `[additional workflow-specific fields]` - any extra frontmatter fields needed
+
+### 2. Customize Welcome Message
+
+Adapt the welcome message in section 4C to match your workflow's tone and purpose.
+
+### 3. Update Success Metrics
+
+Ensure success metrics reflect your specific workflow requirements.
+
+### 4. Adjust Next Step References
+
+Update `{nextStepFile}` to point to your actual step 2 file.
+
+## Implementation Notes
+
+1. **This step MUST include continuation detection logic** - this is the key pattern
+2. **Always include `continueFile` reference** in frontmatter
+3. **Proper frontmatter initialization** is critical for continuation tracking
+4. **Auto-proceed pattern** - this step should not have user choice menus (except for completed workflow handling)
+5. **Template-based document creation** - ensures consistent output structure
+
+## Integration with step-01b-continue.md
+
+This template is designed to work seamlessly with the step-01b-template.md continuation step. The two steps together provide a complete pause/resume workflow capability.

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

@@ -0,0 +1,223 @@
+# BMAD Workflow Step 1B Continuation Template
+
+This template provides the standard structure for workflow continuation steps. It handles resuming workflows that were started but not completed, ensuring seamless continuation across multiple sessions.
+
+Use this template alongside **step-01-init-continuable-template.md** to create workflows that can be paused and resumed. The init template handles the detection and routing logic, while this template handles the resumption logic.
+
+<!-- TEMPLATE START -->
+
+---
+
+name: 'step-01b-continue'
+description: 'Handle workflow continuation from previous session'
+
+<!-- Path Definitions -->
+
+workflow\*path: '{project-root}/_bmad/[module-path]/workflows/[workflow-name]'
+
+# File References (all use {variable} format in file)
+
+thisStepFile: '{workflow_path}/steps/step-01b-continue.md'
+outputFile: '{output_folder}/[output-file-name]-{project_name}.md'
+workflowFile: '{workflow_path}/workflow.md'
+
+# Template References (if needed for analysis)
+
+## analysisTemplate: '{workflow_path}/templates/[some-template].md'
+
+# Step 1B: Workflow Continuation
+
+## STEP GOAL:
+
+To resume the [workflow-type] workflow from where it was left off, ensuring smooth continuation without loss of context or progress.
+
+## 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 analyzing and resuming workflow state
+- 🚫 FORBIDDEN to modify content completed in previous steps
+- 💬 Maintain continuity with previous sessions
+- 🚪 DETECT exact continuation point from frontmatter of incomplete file {outputFile}
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis of current state before taking action
+- 💾 Keep existing frontmatter `stepsCompleted` values intact
+- 📖 Review the template content already generated in {outputFile}
+- 🚫 FORBIDDEN to modify content that was completed in previous steps
+- 📝 Update frontmatter with continuation timestamp when resuming
+
+## CONTEXT BOUNDARIES:
+
+- Current [output-file-name] document is already loaded
+- Previous context = complete template + existing frontmatter
+- [Key data collected] already gathered in previous sessions
+- Last completed step = last value in `stepsCompleted` array from frontmatter
+
+## CONTINUATION SEQUENCE:
+
+### 1. Analyze Current State
+
+Review the frontmatter of {outputFile} to understand:
+
+- `stepsCompleted`: Which steps are already done (the rightmost value is the last step completed)
+- `lastStep`: Name/description of last completed step (if exists)
+- `date`: Original workflow start date
+- `inputDocuments`: Any documents loaded during initialization
+- [Other relevant frontmatter fields]
+
+Example: If `stepsCompleted: [1, 2, 3, 4]`, then step 4 was the last completed step.
+
+### 2. Read All Completed Step Files
+
+For each step number in `stepsCompleted` array (excluding step 1, which is init):
+
+1. **Construct step filename**: `step-[N]-[name].md`
+2. **Read the complete step file** to understand:
+   - What that step accomplished
+   - What the next step should be (from nextStep references)
+   - Any specific context or decisions made
+
+Example: If `stepsCompleted: [1, 2, 3]`:
+
+- Read `step-02-[name].md`
+- Read `step-03-[name].md`
+- The last file will tell you what step-04 should be
+
+### 3. Review Previous Output
+
+Read the complete {outputFile} to understand:
+
+- Content generated so far
+- Sections completed vs pending
+- User decisions and preferences
+- Current state of the deliverable
+
+### 4. Determine Next Step
+
+Based on the last completed step file:
+
+1. **Find the nextStep reference** in the last completed step file
+2. **Validate the file exists** at the referenced path
+3. **Confirm the workflow is incomplete** (not all steps finished)
+
+### 5. Welcome Back Dialog
+
+Present a warm, context-aware welcome:
+
+"Welcome back! I see we've completed [X] steps of your [workflow-type].
+
+We last worked on [brief description of last step].
+
+Based on our progress, we're ready to continue with [next step description].
+
+Are you ready to continue where we left off?"
+
+### 6. Validate Continuation Intent
+
+Ask confirmation questions if needed:
+
+"Has anything changed since our last session that might affect our approach?"
+"Are you still aligned with the goals and decisions we made earlier?"
+"Would you like to review what we've accomplished so far?"
+
+### 7. Present MENU OPTIONS
+
+Display: "**Resuming workflow - Select an Option:** [C] Continue to [Next Step Name]"
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can chat or ask questions - always respond and then end with display again of the menu options
+- Update frontmatter with continuation timestamp when 'C' is selected
+
+#### Menu Handling Logic:
+
+- IF C:
+  1. Update frontmatter: add `lastContinued: [current date]`
+  2. Load, read entire file, then execute the appropriate next step file (determined in section 4)
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and continuation analysis is complete, will you then:
+
+1. Update frontmatter in {outputFile} with continuation timestamp
+2. Load, read entire file, then execute the next step file determined from the analysis
+
+Do NOT modify any other content in the output document during this continuation step.
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Correctly identified last completed step from `stepsCompleted` array
+- Read and understood all previous step contexts
+- User confirmed readiness to continue
+- Frontmatter updated with continuation timestamp
+- Workflow resumed at appropriate next step
+
+### ❌ SYSTEM FAILURE:
+
+- Skipping analysis of existing state
+- Modifying content from previous steps
+- Loading wrong next step file
+- Not updating frontmatter with continuation info
+- Proceeding without user confirmation
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+<!-- TEMPLATE END -->
+
+## Customization Guidelines
+
+When adapting this template for your specific workflow:
+
+### 1. Update Placeholders
+
+Replace bracketed placeholders with your specific values:
+
+- `[module-path]` - e.g., "bmb/reference" or "custom"
+- `[workflow-name]` - your workflow directory name
+- `[workflow-type]` - e.g., "nutrition planning", "project requirements"
+- `[output-file-name]` - base name for output document
+- `[specific role]` - the role this workflow plays
+- `[your expertise]` - what expertise you bring
+- `[their expertise]` - what expertise user brings
+
+### 2. Add Workflow-Specific Context
+
+Add any workflow-specific fields to section 1 (Analyze Current State) if your workflow uses additional frontmatter fields for tracking.
+
+### 3. Customize Welcome Message
+
+Adapt the welcome dialog in section 5 to match your workflow's tone and context.
+
+### 4. Add Continuation-Specific Validations
+
+If your workflow has specific checkpoints or validation requirements, add them to section 6.
+
+## Implementation Notes
+
+1. **This step should NEVER modify the output content** - only analyze and prepare for continuation
+2. **Always preserve the `stepsCompleted` array** - don't modify it in this step
+3. **Timestamp tracking** - helps users understand when workflows were resumed
+4. **Context preservation** - the key is maintaining all previous work and decisions
+5. **Seamless experience** - user should feel like they never left the workflow

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

@@ -0,0 +1,139 @@
+---
+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/tasks/advanced-elicitation.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.