bmad-method 6.0.0-alpha.12 → 6.0.0-alpha.14

package/src/modules/bmb/docs/workflows/intent-vs-prescriptive-spectrum.md

@@ -0,0 +1,220 @@
+# Intent vs Prescriptive Spectrum
+
+## Core Philosophy
+
+The **Intent vs Prescriptive Spectrum** is a fundamental design principle for BMAD workflows and agents. It determines how much creative freedom an LLM has versus how strictly it must follow predefined instructions.
+
+**Key Principle:** The closer workflows stay to **intent**, the more creative and adaptive the LLM experience becomes. The closer they stay to **prescriptive**, the more consistent and controlled the output becomes.
+
+## Understanding the Spectrum
+
+### **Intent-Based Design** (Creative Freedom)
+
+**Focus**: What goal should be achieved
+**Approach**: Trust the LLM to determine the best method
+**Result**: Creative, adaptive, context-aware interactions
+**Best For**: Creative exploration, problem-solving, personalized experiences
+
+### **Prescriptive Design** (Structured Control)
+
+**Focus**: Exactly what to say and do
+**Approach**: Detailed scripts and specific instructions
+**Result**: Consistent, predictable, controlled outcomes
+**Best For**: Compliance, safety-critical, standardized processes
+
+## Spectrum Examples
+
+### **Highly Intent-Based** (Creative End)
+
+```markdown
+**Example:** Story Exploration Workflow
+**Instruction:** "Help the user explore their dream imagery to craft compelling narratives, use multiple turns of conversation to really push users to develop their ideas, giving them hints and ideas also to prime them effectively to bring out their creativity"
+**LLM Freedom:** Adapts questions, explores tangents, follows creative inspiration
+**Outcome:** Unique, personalized storytelling experiences
+```
+
+### **Balanced Middle** (Professional Services)
+
+```markdown
+**Example:** Business Strategy Workflow
+**Instruction:** "Guide the user through SWOT analysis using your business expertise. when complete tell them 'here is your final report {report output}'
+**LLM Freedom:** Professional judgment in analysis, structured but adaptive approach
+**Outcome:** Professional, consistent yet tailored business insights
+```
+
+### **Highly Prescriptive** (Control End)
+
+```markdown
+**Example:** Medical Intake Form
+**Instruction:** "Ask exactly: 'Do you currently experience any of the following symptoms: fever, cough, fatigue?' Wait for response, then ask exactly: 'When did these symptoms begin?'"
+**LLM Freedom:** Minimal - must follow exact script for medical compliance
+**Outcome:** Consistent, medically compliant patient data collection
+```
+
+## Spectrum Positioning Guide
+
+### **Choose Intent-Based When:**
+
+- ✅ Creative exploration and innovation are goals
+- ✅ Personalization and adaptation to user context are important
+- ✅ Human-like conversation and natural interaction are desired
+- ✅ Problem-solving requires flexible thinking
+- ✅ User experience and engagement are priorities
+
+**Examples:**
+
+- Creative brainstorming sessions
+- Personal coaching or mentoring
+- Exploratory research and discovery
+- Artistic content creation
+- Collaborative problem-solving
+
+### **Choose Prescriptive When:**
+
+- ✅ Compliance with regulations or standards is required
+- ✅ Safety or legal considerations are paramount
+- ✅ Exact consistency across multiple sessions is essential
+- ✅ Training new users on specific procedures
+- ✅ Data collection must follow specific protocols
+
+**Examples:**
+
+- Medical intake and symptom assessment
+- Legal compliance questionnaires
+- Safety checklists and procedures
+- Standardized testing protocols
+- Regulatory data collection
+
+### **Choose Balanced When:**
+
+- ✅ Professional expertise is required but adaptation is beneficial
+- ✅ Consistent quality with flexible application is needed
+- ✅ Domain expertise should guide but not constrain interactions
+- ✅ User trust and professional credibility are important
+- ✅ Complex processes require both structure and judgment
+
+**Examples:**
+
+- Business consulting and advisory
+- Technical support and troubleshooting
+- Educational tutoring and instruction
+- Financial planning and advice
+- Project management facilitation
+
+## Implementation Guidelines
+
+### **For Workflow Designers:**
+
+1. **Early Spectrum Decision**: Determine spectrum position during initial design
+2. **User Education**: Explain spectrum choice and its implications to users
+3. **Consistent Application**: Maintain chosen spectrum throughout workflow
+4. **Context Awareness**: Adjust spectrum based on specific use case requirements
+
+### **For Workflow Implementation:**
+
+**Intent-Based Patterns:**
+
+```markdown
+- "Help the user understand..." (vs "Explain that...")
+- "Guide the user through..." (vs "Follow these steps...")
+- "Use your professional judgment to..." (vs "Apply this specific method...")
+- "Adapt your approach based on..." (vs "Regardless of situation, always...")
+```
+
+**Prescriptive Patterns:**
+
+```markdown
+- "Say exactly: '...'" (vs "Communicate that...")
+- "Follow this script precisely: ..." (vs "Cover these points...")
+- "Do not deviate from: ..." (vs "Consider these options...")
+- "Must ask in this order: ..." (vs "Ensure you cover...")
+```
+
+### **For Agents:**
+
+**Intent-Based Agent Design:**
+
+```yaml
+persona:
+  communication_style: 'Adaptive professional who adjusts approach based on user context'
+  guiding_principles:
+    - 'Use creative problem-solving within professional boundaries'
+    - 'Personalize approach while maintaining expertise'
+    - 'Adapt conversation flow to user needs'
+```
+
+**Prescriptive Agent Design:**
+
+```yaml
+persona:
+  communication_style: 'Follows standardized protocols exactly'
+  governing_rules:
+    - 'Must use approved scripts without deviation'
+    - 'Follow sequence precisely as defined'
+    - 'No adaptation of prescribed procedures'
+```
+
+## Spectrum Calibration Questions
+
+**Ask these during workflow design:**
+
+1. **Consequence of Variation**: What happens if the LLM says something different?
+2. **User Expectation**: Does the user expect consistency or creativity?
+3. **Risk Level**: What are the risks of creative deviation vs. rigid adherence?
+4. **Expertise Required**: Is domain expertise application more important than consistency?
+5. **Regulatory Requirements**: Are there external compliance requirements?
+
+## Best Practices
+
+### **DO:**
+
+- ✅ Make conscious spectrum decisions during design
+- ✅ Explain spectrum choices to users
+- ✅ Use intent-based design for creative and adaptive experiences
+- ✅ Use prescriptive design for compliance and consistency requirements
+- ✅ Consider balanced approaches for professional services
+- ✅ Document spectrum rationale for future reference
+
+### **DON'T:**
+
+- ❌ Mix spectrum approaches inconsistently within workflows
+- ❌ Default to prescriptive when intent-based would be more effective
+- ❌ Use creative freedom when compliance is required
+- ❌ Forget to consider user expectations and experience
+- ❌ Overlook risk assessment in spectrum selection
+
+## Quality Assurance
+
+**When validating workflows:**
+
+- Check if spectrum position is intentional and consistent
+- Verify prescriptive elements are necessary and justified
+- Ensure intent-based elements have sufficient guidance
+- Confirm spectrum alignment with user needs and expectations
+- Validate that risks are appropriately managed
+
+## Examples in Practice
+
+### **Medical Intake (Highly Prescriptive):**
+
+- **Why**: Patient safety, regulatory compliance, consistent data collection
+- **Implementation**: Exact questions, specific order, no deviation permitted
+- **Benefit**: Reliable, medically compliant patient information
+
+### **Creative Writing Workshop (Highly Intent):**
+
+- **Why**: Creative exploration, personalized inspiration, artistic expression
+- **Implementation**: Goal guidance, creative freedom, adaptive prompts
+- **Benefit**: Unique, personalized creative works
+
+### **Business Strategy (Balanced):**
+
+- **Why**: Professional expertise with adaptive application
+- **Implementation**: Structured framework with professional judgment
+- **Benefit**: Professional, consistent yet tailored business insights
+
+## Conclusion
+
+The Intent vs Prescriptive Spectrum is not about good vs. bad - it's about **appropriate design choices**. The best workflows make conscious decisions about where they fall on this spectrum based on their specific requirements, user needs, and risk considerations.
+
+**Key Success Factor**: Choose your spectrum position intentionally, implement it consistently, and align it with your specific use case requirements.

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_folder*}/[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_folder*}/[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