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

package/src/modules/bmb/workflows/edit-module/workflow.yaml

@@ -0,0 +1,36 @@
+# Edit Module - Module Editor Configuration
+name: "edit-module"
+description: "Edit existing BMAD modules (structure, agents, workflows, documentation) while following all best practices"
+author: "BMad"
+
+# Critical variables load from config_source
+config_source: "{project-root}/bmad/bmb/config.yaml"
+communication_language: "{config_source}:communication_language"
+user_name: "{config_source}:user_name"
+
+# Required Data Files - Critical for understanding module conventions
+module_structure_guide: "{project-root}/bmad/bmb/workflows/create-module/module-structure.md"
+
+# Related workflow editors
+agent_editor: "{project-root}/bmad/bmb/workflows/edit-agent/workflow.yaml"
+workflow_editor: "{project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml"
+
+# Optional docs that can be used to understand the target module
+recommended_inputs:
+  - target_module: "Path to the module directory to edit"
+  - bmm_module: "{project-root}/bmad/bmm/"
+  - bmb_module: "{project-root}/bmad/bmb/"
+  - 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/edit-module"
+template: false # This is an action workflow - no template needed
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+standalone: true
+
+# Web bundle configuration
+web_bundle: false # BMB workflows run locally in BMAD-METHOD project

package/src/modules/bmb/workflows/edit-workflow/README.md

@@ -43,8 +43,64 @@ Or through a BMAD agent:
 2. **Prioritized Issues**: Identifies and ranks issues by importance
 3. **Guided Editing**: Step-by-step process with explanations
 4. **Best Practices**: Ensures all edits follow BMAD conventions
-5. **Validation**: Checks all changes for correctness
-6. **Change Tracking**: Documents what was modified and why
+5. **Instruction Style Optimization**: Convert between intent-based and prescriptive styles
+6. **Validation**: Checks all changes for correctness
+7. **Change Tracking**: Documents what was modified and why
+
+## Understanding Instruction Styles
+
+When editing workflows, one powerful option is **adjusting the instruction style** to better match the workflow's purpose.
+
+### Intent-Based vs Prescriptive Instructions
+
+**Intent-Based (Recommended for most workflows)**
+
+Guides the AI with goals and principles, allowing flexible conversation.
+
+- **More flexible and conversational** - AI adapts to user responses
+- **Better for complex discovery** - Requirements gathering, creative exploration
+- **Quality over consistency** - Deep understanding matters more
+- **Example**: `<action>Guide user to define their target audience with specific demographics and needs</action>`
+
+**When to use:**
+
+- Complex discovery processes (user research, requirements)
+- Creative brainstorming and ideation
+- Iterative refinement workflows
+- Workflows requiring nuanced understanding
+
+**Prescriptive**
+
+Provides exact questions with structured options.
+
+- **More controlled and predictable** - Consistent questions every time
+- **Better for simple data collection** - Platform, format, yes/no choices
+- **Consistency over quality** - Same execution every run
+- **Example**: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
+
+**When to use:**
+
+- Simple data collection (platform, format, binary choices)
+- Compliance verification and standards adherence
+- Configuration with finite options
+- Quick setup wizards
+
+### Edit Workflow's Style Adjustment Feature
+
+The **"Adjust instruction style"** editing option (menu option 11) helps you:
+
+1. **Analyze current style** - Identifies whether workflow is primarily intent-based or prescriptive
+2. **Convert between styles** - Transform prescriptive steps to intent-based (or vice versa)
+3. **Optimize the mix** - Intelligently recommend the best style for each step
+4. **Step-by-step control** - Review and decide on each step individually
+
+**Common scenarios:**
+
+- **Make workflow more conversational**: Convert rigid <ask> tags to flexible <action> tags for complex steps
+- **Make workflow more consistent**: Convert open-ended <action> tags to structured <ask> tags for simple data collection
+- **Balance both approaches**: Use intent-based for discovery, prescriptive for simple choices
+
+This feature is especially valuable when converting legacy workflows or adapting workflows for different use cases.
 
 ## Workflow Steps
 

package/src/modules/bmb/workflows/edit-workflow/instructions.md

@@ -1,170 +1,342 @@
 # Edit Workflow - Workflow Editor Instructions
 
-<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.md</critical>
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml</critical>
-<critical>Study the workflow creation guide thoroughly at: {workflow_creation_guide}</critical>
+<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication based on context and user needs</critical>
+<critical>The goal is COLLABORATIVE IMPROVEMENT - work WITH the user, not FOR them</critical>
+<critical>Communicate all responses in {communication_language}</critical>
 
 <workflow>
 
-<step n="1" goal="Load and analyze target workflow">
-<ask>What is the path to the workflow you want to edit? (provide path to workflow.yaml or workflow folder)</ask>
+<step n="1" goal="Load and deeply understand the target workflow">
+<ask>What is the path to the workflow you want to edit? (provide path to workflow.yaml or workflow directory)</ask>
 
-<action>Load the workflow.yaml file from the provided path</action>
-<action>Identify the workflow type (document, action, interactive, autonomous, meta)</action>
-<action>List all associated files (template.md, instructions.md, checklist.md, data files)</action>
-<action>Load any existing instructions.md and template.md files if present</action>
+<action>Load the target workflow completely:
 
-Display a summary:
+- workflow.yaml configuration
+- instructions.md (if exists)
+- template.md (if exists)
+- checklist.md (if exists)
+- Any additional data files referenced
+  </action>
 
-- Workflow name and description
-- Type of workflow
-- Files present
-- Current structure overview
-  </step>
+<action>Load ALL workflow documentation to inform understanding:
 
-<step n="2" goal="Analyze against best practices">
-<action>Load the complete workflow creation guide from: {workflow_creation_guide}</action>
-<action>Check the workflow against the guide's best practices:</action>
+- Workflow creation guide: {workflow_creation_guide}
+- Workflow execution engine: {workflow_execution_engine}
+- Study example workflows from: {project-root}/bmad/bmm/workflows/
+  </action>
 
-Analyze for:
+<action>Analyze the workflow deeply:
 
-- **Critical headers**: Are workflow engine references present?
-- **File structure**: Are all expected files present for this workflow type?
-- **Variable consistency**: Do variable names match between files?
-- **Step structure**: Are steps properly numbered and focused?
-- **XML tags**: Are tags used correctly and consistently?
-- **Instructions clarity**: Are instructions specific with examples and limits?
-- **Template variables**: Use snake_case and descriptive names?
-- **Validation criteria**: Are checklist items measurable and specific?
+- Identify workflow type (document, action, interactive, autonomous, meta)
+- Understand purpose and user journey
+- Map out step flow and logic
+- Check variable consistency across files
+- Evaluate instruction style (intent-based vs prescriptive)
+- Assess template structure (if applicable)
+- Review validation criteria
+- Identify config dependencies
+- Check for web bundle configuration
+- Evaluate against best practices from loaded guides
+  </action>
 
-<action>Create a list of identified issues or improvement opportunities</action>
-<action>Prioritize issues by importance (critical, important, nice-to-have)</action>
-</step>
+<action>Reflect understanding back to {user_name}:
 
-<step n="3" goal="Select editing focus">
-Present the editing menu to the user:
+Present a warm, conversational summary adapted to the workflow's complexity:
 
-**What aspect would you like to edit?**
+- What this workflow accomplishes (its purpose and value)
+- How it's structured (type, steps, interactive points)
+- What you notice (strengths, potential improvements, issues)
+- Your initial assessment based on best practices
+- How it fits in the larger BMAD ecosystem
 
-1. **Fix critical issues** - Address missing headers, broken references
-2. **Update workflow.yaml** - Modify configuration, paths, metadata
-3. **Refine instructions** - Improve steps, add detail, fix flow
-4. **Update template** - Fix variables, improve structure (if applicable)
-5. **Enhance validation** - Make checklist more specific and measurable
-6. **Add new features** - Add steps, optional sections, or capabilities
-7. **Optimize for clarity** - Improve descriptions, add examples
-8. **Full review and update** - Comprehensive improvements across all files
+Be conversational and insightful. Help {user_name} see their workflow through your eyes.
+</action>
 
-<ask>Select an option (1-8) or describe a custom edit:</ask>
+<ask>Does this match your understanding of what this workflow should accomplish?</ask>
+<template-output>workflow_understanding</template-output>
 </step>
 
-<step n="4" goal="Load relevant documentation">
-Based on the selected edit type, load appropriate reference materials:
+<step n="2" goal="Discover improvement goals collaboratively">
+<critical>Understand WHAT the user wants to improve and WHY before diving into edits</critical>
+
+<action>Engage in collaborative discovery:
+
+Ask open-ended questions to understand their goals:
+
+- What prompted you to want to edit this workflow?
+- What feedback have you gotten from users running it?
+- Are there specific steps that feel clunky or confusing?
+- Is the workflow achieving its intended outcome?
+- Are there new capabilities you want to add?
+- Is the instruction style working well for your users?
+
+Listen for clues about:
+
+- User experience issues (confusing steps, unclear instructions)
+- Functional issues (broken references, missing validation)
+- Performance issues (too many steps, repetitive, tedious)
+- Maintainability issues (hard to update, bloated, inconsistent variables)
+- Instruction style mismatch (too prescriptive when should be adaptive, or vice versa)
+- Integration issues (doesn't work well with other workflows)
+  </action>
+
+<action>Based on their responses and your analysis from step 1, identify improvement opportunities:
+
+Organize by priority and user goals:
+
+- CRITICAL issues blocking successful runs
+- IMPORTANT improvements enhancing user experience
+- NICE-TO-HAVE enhancements for polish
+
+Present these conversationally, explaining WHY each matters and HOW it would help.
+</action>
+
+<action>Assess instruction style fit:
+
+Based on the workflow's purpose and your analysis:
+
+- Is the current style (intent-based vs prescriptive) appropriate?
+- Would users benefit from more/less structure?
+- Are there steps that should be more adaptive?
+- Are there steps that need more specificity?
+
+Discuss style as part of improvement discovery, not as a separate concern.
+</action>
+
+<action>Collaborate on priorities:
 
-<check>If editing instructions or adding features:</check>
-<action>Review the "Writing Instructions" section of the creation guide</action>
-<action>Load example workflows from {project-root}/bmad/bmm/workflows/ for patterns</action>
+Don't just list options - discuss them:
 
-<check>If editing templates:</check>
-<action>Review the "Templates & Variables" section of the creation guide</action>
-<action>Ensure variable naming conventions are followed</action>
+- "I noticed {{issue}} - this could make users feel {{problem}}. Want to address this?"
+- "The workflow could be more {{improvement}} which would help when {{use_case}}. Worth exploring?"
+- "Based on what you said about {{user_goal}}, we might want to {{suggestion}}. Thoughts?"
 
-<check>If editing validation:</check>
-<action>Review the "Validation" section and measurable criteria examples</action>
+Let the conversation flow naturally. Build a shared vision of what "better" looks like.
+</action>
 
-<check>If fixing critical issues:</check>
-<action>Load the workflow execution engine documentation</action>
-<action>Verify all required elements are present</action>
+<template-output>improvement_goals</template-output>
 </step>
 
-<step n="5" goal="Perform edits" repeat="until-complete">
-Based on the selected focus area:
+<step n="3" goal="Facilitate improvements collaboratively" repeat="until-user-satisfied">
+<critical>Work iteratively - improve, review, refine. Never dump all changes at once.</critical>
 
-<action>Show the current content that will be edited</action>
-<action>Explain the proposed changes and why they improve the workflow</action>
-<action>Generate the updated content following all conventions from the guide</action>
+<action>For each improvement area, facilitate collaboratively:
 
-<ask>Review the proposed changes. Options:
+1. **Explain the current state and why it matters**
+   - Show relevant sections of the workflow
+   - Explain how it works now and implications
+   - Connect to user's goals from step 2
 
-- [a] Accept and apply
-- [e] Edit/modify the changes
-- [s] Skip this change
-- [n] Move to next file/section
-- [d] Done with edits
-  </ask>
+2. **Propose improvements with rationale**
+   - Suggest specific changes that align with best practices
+   - Explain WHY each change helps
+   - Provide examples from the loaded guides when helpful
+   - Show before/after comparisons for clarity
+   - Reference the creation guide's patterns naturally
+
+3. **Collaborate on the approach**
+   - Ask if the proposed change addresses their need
+   - Invite modifications or alternative approaches
+   - Explain tradeoffs when relevant
+   - Adapt based on their feedback
+
+4. **Apply changes iteratively**
+   - Make one focused improvement at a time
+   - Show the updated section
+   - Confirm it meets their expectation
+   - Move to next improvement or refine current one
+     </action>
+
+<action>Common improvement patterns to facilitate:
+
+**If refining instruction style:**
+
+- Discuss where the workflow feels too rigid or too loose
+- Identify steps that would benefit from intent-based approach
+- Identify steps that need prescriptive structure
+- Convert between styles thoughtfully, explaining tradeoffs
+- Show how each style serves the user differently
+- Test proposed changes by reading them aloud
+
+**If improving step flow:**
+
+- Walk through the user journey step by step
+- Identify friction points or redundancy
+- Propose streamlined flow
+- Consider where steps could merge or split
+- Ensure each step has clear goal and value
+- Check that repeat conditions make sense
+
+**If fixing variable consistency:**
+
+- Identify variables used across files
+- Find mismatches in naming or usage
+- Propose consistent naming scheme
+- Update all files to match
+- Verify variables are defined in workflow.yaml
+
+**If enhancing validation:**
+
+- Review current checklist (if exists)
+- Discuss what "done well" looks like
+- Make criteria specific and measurable
+- Add validation for new features
+- Remove outdated or vague criteria
+
+**If updating configuration:**
+
+- Review standard config pattern
+- Check if user context variables are needed
+- Ensure output_folder, user_name, communication_language are used appropriately
+- Add missing config dependencies
+- Clean up unused config fields
 
-<check>If user selects 'a':</check>
-<action>Apply the changes to the file</action>
-<action>Log the change for the summary</action>
+**If adding/updating templates:**
 
-<check>If user selects 'e':</check>
-<ask>What modifications would you like to make?</ask>
-<goto step="5">Regenerate with modifications</goto>
+- Understand the document structure needed
+- Design template variables that match instruction outputs
+- Ensure variable names are descriptive snake_case
+- Include proper metadata headers
+- Test that all variables can be filled
 
-<check>If user selects 'd':</check>
-<continue>Proceed to validation</continue>
+**If configuring web bundle:**
+
+- Identify all files the workflow depends on
+- Check for invoked workflows (must be included)
+- Verify paths are bmad/-relative
+- Remove config_source dependencies
+- Build complete file list
+
+**If improving user interaction:**
+
+- Find places where <ask> could be more open-ended
+- Add educational context where users might be lost
+- Remove unnecessary confirmation steps
+- Make questions clearer and more purposeful
+- Balance guidance with user autonomy
+  </action>
+
+<action>Throughout improvements, educate when helpful:
+
+Share insights from the guides naturally:
+
+- "The creation guide recommends {{pattern}} for workflows like this"
+- "Looking at examples in BMM, this type of step usually {{approach}}"
+- "The execution engine expects {{structure}} for this to work properly"
+
+Connect improvements to broader BMAD principles without being preachy.
+</action>
+
+<ask>After each significant change:
+
+- "Does this flow feel better for what you're trying to achieve?"
+- "Want to refine this further, or move to the next improvement?"
+- "How does this change affect the user experience?"
+  </ask>
+
+<template-output>improvement_implementation</template-output>
 </step>
 
-<step n="6" goal="Validate all changes" optional="true">
-<action>Run a comprehensive validation check:</action>
-
-Validation checks:
-
-- [ ] All file paths resolve correctly
-- [ ] Variable names are consistent across files
-- [ ] Step numbering is sequential and logical
-- [ ] Required XML tags are properly formatted
-- [ ] No placeholders remain (like {TITLE} or {WORKFLOW_CODE})
-- [ ] Instructions match the workflow type
-- [ ] Template variables match instruction outputs (if applicable)
-- [ ] Checklist criteria are measurable (if present)
-- [ ] Critical headers are present in instructions
-- [ ] YAML syntax is valid
-
-<check>If any validation fails:</check>
-<ask>Issues found. Would you like to fix them? (y/n)</ask>
-<check>If yes:</check>
-<goto step="5">Return to editing</goto>
+<step n="4" goal="Validate improvements holistically">
+<action>Run comprehensive validation conversationally:
+
+Don't just check boxes - explain what you're validating and why it matters:
+
+- "Let me verify all file references resolve correctly..."
+- "Checking that variables are consistent across all files..."
+- "Making sure the step flow is logical and complete..."
+- "Validating template variables match instruction outputs..."
+- "Ensuring config dependencies are properly set up..."
+  </action>
+
+<action>Load validation checklist: {installed_path}/checklist.md</action>
+<action>Check all items from checklist systematically</action>
+
+<check if="validation_issues_found">
+  <action>Present issues conversationally:
+
+Explain what's wrong and implications:
+
+- "I found {{issue}} which could cause {{problem}} when users run this"
+- "The {{component}} needs {{fix}} because {{reason}}"
+
+Propose fixes immediately:
+
+- "I can fix this by {{solution}}. Should I?"
+- "We have a couple options here: {{option1}} or {{option2}}. Thoughts?"
+  </action>
+
+<action>Fix approved issues and re-validate</action>
+</check>
+
+<check if="validation_passes">
+  <action>Confirm success warmly:
+
+"Excellent! Everything validates cleanly:
+
+- All file references resolve
+- Variables are consistent throughout
+- Step flow is logical and complete
+- Template aligns with instructions (if applicable)
+- Config dependencies are set up correctly
+- Web bundle is complete (if applicable)
+
+Your workflow is in great shape."
+</action>
+</check>
+
+<template-output>validation_results</template-output>
 </step>
 
-<step n="7" goal="Generate change summary">
-Create a summary of all changes made:
+<step n="5" goal="Review improvements and guide next steps">
+<action>Create a conversational summary of what improved:
+
+Tell the story of the transformation:
+
+- "We started with {{initial_state}}"
+- "You wanted to {{user_goals}}"
+- "We made these key improvements: {{changes_list}}"
+- "Now your workflow {{improved_capabilities}}"
 
-## Workflow Edit Summary
+Highlight the impact:
 
-**Workflow:** {{workflow_name}}
-**Date:** {{date}}
-**Editor:** {{user_name}}
+- "This means users will experience {{benefit}}"
+- "The workflow is now more {{quality}}"
+- "It follows best practices for {{patterns}}"
+  </action>
 
-### Changes Made:
+<action>Guide next steps based on changes made:
 
-<action>List each file that was modified with a brief description of changes</action>
+If instruction style changed:
 
-### Improvements:
+- "Since we made the workflow more {{style}}, you might want to test it with a real user to see how it feels"
 
-<action>Summarize how the workflow is now better aligned with best practices</action>
+If template was updated:
 
-### Files Modified:
+- "The template now has {{new_variables}} - run the workflow to generate a sample document"
 
-<action>List all modified files with their paths</action>
+If this is part of larger module work:
 
-### Next Steps:
+- "This workflow is part of {{module}} - consider if other workflows need similar improvements"
 
-<action>Suggest any additional improvements or testing that could be done</action>
+If web bundle was configured:
+
+- "The web bundle is now set up - you can test deploying this workflow standalone"
+
+Be a helpful guide to what comes next, not just a task completer.
+</action>
 
 <ask>Would you like to:
 
-- Save this summary to: {change_log_output}
-- Test the edited workflow
-- Make additional edits
-- Exit
+- Test the edited workflow by running it
+- Edit another workflow
+- Make additional refinements to this one
+- Return to your module work
   </ask>
 
-<check>If save summary:</check>
-<action>Write the summary to the change log file</action>
-
-<check>If test workflow:</check>
-<invoke-workflow>{{workflow_name}}</invoke-workflow>
+<template-output>completion_summary</template-output>
 </step>
 
 </workflow>

package/src/modules/bmb/workflows/edit-workflow/workflow.yaml

@@ -5,15 +5,12 @@ author: "BMad"
 
 # Critical variables load from config_source
 config_source: "{project-root}/bmad/bmb/config.yaml"
-output_folder: "{config_source}:output_folder"
-src_impact: "{config_source}:src_impact"
 communication_language: "{config_source}:communication_language"
 user_name: "{config_source}:user_name"
-date: system-generated
 
 # Required Data Files - Critical for understanding workflow conventions
-workflow_creation_guide: "{project-root}/bmad/bmb/workflows/build-workflow/workflow-creation-guide.md"
-workflow_execution_engine: "{project-root}/bmad/core/tasks/workflow.md"
+workflow_creation_guide: "{project-root}/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md"
+workflow_execution_engine: "{project-root}/bmad/core/tasks/workflow.xml"
 
 # Optional docs that can be used to understand the target workflow
 recommended_inputs:
@@ -26,9 +23,7 @@ template: false # This is an action workflow - no template needed
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 
-# No output file for action workflows
-# But we may generate a change log
-change_log_output: "{output_folder}/workflow-edit-log-{{date}}.md"
+standalone: true
 
-# No special tools required for editing workflows
-required_tools: []
+# Web bundle configuration
+web_bundle: false # BMB workflows run locally in BMAD-METHOD project