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

package/bmad/bmb/workflows/edit-module/instructions.md

@@ -1,339 +0,0 @@
-# Edit Module - Module Editor Instructions
-
-<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-module/workflow.yaml</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 deeply understand the target module">
-<ask>What is the path to the module you want to edit? (provide path to module directory like bmad/bmm/ or src/modules/bmm/)</ask>
-
-<action>Load the module directory structure completely:
-
-- Scan all directories and files
-- Load config.yaml
-- Load README.md
-- List all agents in agents/ directory
-- List all workflows in workflows/ directory
-- Check for installer files (if in src/modules/)
-- Identify any custom structure or patterns
-  </action>
-
-<action>Load ALL module documentation to inform understanding:
-
-- Module structure guide: {module_structure_guide}
-- Study reference modules: BMM, BMB, CIS
-- Understand BMAD module patterns and conventions
-  </action>
-
-<action>Analyze the module deeply:
-
-- Identify module purpose and role in BMAD ecosystem
-- Understand agent organization and relationships
-- Map workflow organization and dependencies
-- Evaluate config structure and completeness
-- Check documentation quality and currency
-- Assess installer configuration (if source module)
-- Identify cross-module integrations
-- Evaluate against best practices from loaded guides
-  </action>
-
-<action>Reflect understanding back to {user_name}:
-
-Present a warm, conversational summary adapted to the module's complexity:
-
-- What this module provides (its purpose and value in BMAD)
-- How it's organized (agents, workflows, structure)
-- What you notice (strengths, potential improvements, issues)
-- How it fits in the larger BMAD ecosystem
-- Your initial assessment based on best practices
-
-Be conversational and insightful. Help {user_name} see their module through your eyes.
-</action>
-
-<ask>Does this match your understanding of what this module should provide?</ask>
-<template-output>module_understanding</template-output>
-</step>
-
-<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 module?
-- What feedback have you gotten from users of this module?
-- Are there specific agents or workflows that need attention?
-- Is the module fulfilling its intended purpose?
-- Are there new capabilities you want to add?
-- How well does it integrate with other modules?
-- Is the documentation helping users understand and use the module?
-
-Listen for clues about:
-
-- Structural issues (poor organization, hard to navigate)
-- Agent/workflow issues (outdated, broken, missing functionality)
-- Configuration issues (missing fields, incorrect setup)
-- Documentation issues (outdated, incomplete, unclear)
-- Integration issues (doesn't work well with other modules)
-- Installer issues (installation problems, missing files)
-- User experience issues (confusing, hard to use)
-  </action>
-
-<action>Based on their responses and your analysis from step 1, identify improvement opportunities:
-
-Organize by priority and user goals:
-
-- CRITICAL issues blocking module functionality
-- 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>Collaborate on priorities:
-
-Don't just list options - discuss them:
-
-- "I noticed {{issue}} - this could make it hard for users to {{problem}}. Want to address this?"
-- "The module 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?"
-
-Let the conversation flow naturally. Build a shared vision of what "better" looks like.
-</action>
-
-<template-output>improvement_goals</template-output>
-</step>
-
-<step n="3" goal="Facilitate improvements collaboratively" repeat="until-user-satisfied">
-<critical>Work iteratively - improve, review, refine. Never dump all changes at once.</critical>
-<critical>For agent and workflow edits, invoke specialized workflows rather than doing inline</critical>
-
-<action>For each improvement area, facilitate collaboratively:
-
-1. **Explain the current state and why it matters**
-   - Show relevant sections of the module
-   - Explain how it works now and implications
-   - Connect to user's goals from step 2
-
-2. **Propose improvements with rationale**
-   - Suggest specific changes that align with best practices
-   - Explain WHY each change helps
-   - Provide examples from reference modules when helpful
-   - Reference the structure 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 appropriately**
-   - For agent edits: Invoke edit-agent workflow
-   - For workflow edits: Invoke edit-workflow workflow
-   - For module-level changes: Make directly and iteratively
-   - Show updates and confirm satisfaction
-     </action>
-
-<action>Common improvement patterns to facilitate:
-
-**If improving module organization:**
-
-- Discuss how the current structure serves (or doesn't serve) users
-- Propose reorganization that aligns with mental models
-- Consider feature-based vs type-based organization
-- Plan the reorganization steps
-- Update all references after moving files
-
-**If updating module configuration:**
-
-- Review current config.yaml fields
-- Check for missing standard fields (user_name, communication_language, output_folder)
-- Add module-specific fields as needed
-- Remove unused or outdated fields
-- Ensure config is properly documented
-
-**If managing agents:**
-
-- Ask which agent needs attention and why
-- For editing existing agent: <invoke-workflow path="{agent_editor}">
-- For adding new agent: Guide creation and integration
-- For removing agent: Confirm, remove, update references
-- Ensure all agent references in workflows remain valid
-
-**If managing workflows:**
-
-- Ask which workflow needs attention and why
-- For editing existing workflow: <invoke-workflow path="{workflow_editor}">
-- For adding new workflow: Guide creation and integration
-- For removing workflow: Confirm, remove, update agent references
-- Ensure all workflow files are properly organized
-
-**If improving documentation:**
-
-- Review current README and identify gaps
-- Discuss what users need to know
-- Update module overview and purpose
-- List agents and workflows with clear descriptions
-- Add usage examples if helpful
-- Ensure installation/setup instructions are clear
-
-**If setting up cross-module integration:**
-
-- Identify which workflows from other modules are needed
-- Show how to reference workflows properly: {project-root}/bmad/{{module}}/workflows/{{workflow}}/workflow.yaml
-- Document the integration in README
-- Ensure dependencies are clear
-- Consider adding example usage
-
-**If updating installer (source modules only):**
-
-- Review installer script for correctness
-- Check web bundle configurations
-- Verify all files are included
-- Test installation paths
-- Update module metadata
-  </action>
-
-<action>When invoking specialized workflows:
-
-Explain why you're handing off:
-
-- "This agent needs detailed attention. Let me invoke the edit-agent workflow to give it proper focus."
-- "The workflow editor can handle this more thoroughly. I'll pass control there."
-
-After the specialized workflow completes, return and continue:
-
-- "Great! That agent/workflow is updated. Want to work on anything else in the module?"
-  </action>
-
-<action>Throughout improvements, educate when helpful:
-
-Share insights from the guides naturally:
-
-- "The module structure guide recommends {{pattern}} for this scenario"
-- "Looking at how BMM organized this, we could use {{approach}}"
-- "The BMAD convention is to {{pattern}} which helps with {{benefit}}"
-
-Connect improvements to broader BMAD principles without being preachy.
-</action>
-
-<ask>After each significant change:
-
-- "Does this organization feel more intuitive?"
-- "Want to refine this further, or move to the next improvement?"
-- "How does this change affect users of the module?"
-  </ask>
-
-<template-output>improvement_implementation</template-output>
-</step>
-
-<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 the module structure is solid..."
-- "Checking that all agent workflow references are valid..."
-- "Making sure config.yaml has all necessary fields..."
-- "Validating documentation is complete and accurate..."
-- "Ensuring cross-module references work correctly..."
-  </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}} for users"
-- "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:
-
-- Module structure is well-organized
-- All agent and workflow references are valid
-- Configuration is complete
-- Documentation is thorough and current
-- Cross-module integrations work properly
-- Installer is correct (if applicable)
-
-Your module is in great shape."
-</action>
-</check>
-
-<template-output>validation_results</template-output>
-</step>
-
-<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 module {{improved_capabilities}}"
-
-Highlight the impact:
-
-- "This means users will experience {{benefit}}"
-- "The module is now more {{quality}}"
-- "It follows best practices for {{patterns}}"
-  </action>
-
-<action>Guide next steps based on changes made:
-
-If structure changed significantly:
-
-- "Since we reorganized the structure, you should update any external references to this module"
-
-If agents or workflows were updated:
-
-- "The updated agents/workflows should be tested with real user interactions"
-
-If cross-module integration was added:
-
-- "Test the integration with {{other_module}} to ensure it works smoothly"
-
-If installer was updated:
-
-- "Test the installation process to verify all files are included correctly"
-
-If this is part of larger BMAD work:
-
-- "Consider if patterns from this module could benefit other modules"
-
-Be a helpful guide to what comes next, not just a task completer.
-</action>
-
-<ask>Would you like to:
-
-- Test the edited module by invoking one of its agents
-- Edit a specific agent or workflow in more detail
-- Make additional refinements to the module
-- Work on a different module
-  </ask>
-
-<template-output>completion_summary</template-output>
-</step>
-
-</workflow>

package/bmad/bmb/workflows/edit-module/workflow.yaml

@@ -1,34 +0,0 @@
-# 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

package/bmad/bmb/workflows/edit-workflow/README.md

@@ -1,119 +0,0 @@
-# Edit Workflow
-
-## Purpose
-
-An intelligent workflow editor that helps you modify existing BMAD workflows while adhering to all best practices and conventions documented in the workflow creation guide.
-
-## Use Case
-
-When you need to:
-
-- Fix issues in existing workflows
-- Update workflow configuration or metadata
-- Improve instruction clarity and specificity
-- Add new features or capabilities
-- Ensure compliance with BMAD workflow conventions
-
-## How to Invoke
-
-```
-workflow edit-workflow
-```
-
-Or through a BMAD agent:
-
-```
-*edit-workflow
-```
-
-## Expected Inputs
-
-- **Target workflow path**: Path to the workflow.yaml file or workflow folder you want to edit
-- **Edit type selection**: Choice of what aspect to modify
-- **User approval**: For each proposed change
-
-## Generated Outputs
-
-- Modified workflow files (in place)
-- Optional change log at: `{output_folder}/workflow-edit-log-{date}.md`
-
-## Features
-
-1. **Comprehensive Analysis**: Checks workflows against the official creation guide
-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. **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
-
-1. Load and analyze target workflow
-2. Check against best practices
-3. Select editing focus
-4. Load relevant documentation
-5. Perform edits with user approval
-6. Validate all changes (optional)
-7. Generate change summary
-
-## Requirements
-
-- Access to workflow creation guide
-- Read/write permissions for target workflow
-- Understanding of BMAD workflow types

package/bmad/bmb/workflows/edit-workflow/checklist.md

@@ -1,70 +0,0 @@
-# Edit Workflow - Validation Checklist
-
-## Pre-Edit Analysis
-
-- [ ] Target workflow.yaml file successfully loaded and parsed
-- [ ] All referenced workflow files identified and accessible
-- [ ] Workflow type correctly determined (document/action/interactive/autonomous/meta)
-- [ ] Best practices guide loaded and available for reference
-
-## Edit Execution Quality
-
-- [ ] User clearly informed of identified issues with priority levels
-- [ ] Edit menu presented with all 8 standard options
-- [ ] Selected edit type matches the actual changes made
-- [ ] All proposed changes explained with reasoning before application
-
-## File Integrity
-
-- [ ] All modified files maintain valid YAML/Markdown syntax
-- [ ] No placeholders like {TITLE} or {WORKFLOW_CODE} remain in edited files
-- [ ] File paths use proper variable substitution ({project-root}, {installed_path})
-- [ ] All file references resolve to actual paths
-
-## Convention Compliance
-
-- [ ] Instructions.md contains critical workflow engine reference header
-- [ ] Instructions.md contains workflow.yaml processing reference header
-- [ ] All step numbers are sequential (1, 2, 3... or 1a, 1b, 2a...)
-- [ ] Each step has both n= attribute and goal= attribute
-- [ ] Variable names use snake_case consistently
-- [ ] Template variables (if any) match <template-output> tags exactly
-
-## Instruction Quality
-
-- [ ] Each step has a single, clear goal stated
-- [ ] Instructions are specific with quantities (e.g., "3-5 items" not "several items")
-- [ ] Optional steps marked with optional="true" attribute
-- [ ] Repeating steps use proper repeat syntax (repeat="3" or repeat="until-complete")
-- [ ] User prompts use <ask> tags and wait for response
-- [ ] Actions use <action> tags for required operations
-
-## Validation Criteria (if checklist.md exists)
-
-- [ ] All checklist items are measurable and specific
-- [ ] No vague criteria like "Good documentation" present
-- [ ] Checklist organized into logical sections
-- [ ] Each criterion can be objectively verified as true/false
-
-## Change Documentation
-
-- [ ] All changes logged with description of what and why
-- [ ] Change summary includes list of modified files
-- [ ] Improvements clearly articulated in relation to best practices
-- [ ] Next steps or recommendations provided
-
-## Post-Edit Verification
-
-- [ ] Edited workflow follows patterns from production examples
-- [ ] No functionality broken by the edits
-- [ ] Workflow ready for testing or production use
-- [ ] User given option to test the edited workflow
-
-## Common Issues Resolved
-
-- [ ] Missing critical headers added if they were absent
-- [ ] Broken variable references fixed
-- [ ] Vague instructions made specific
-- [ ] Template-only workflows have template.md file
-- [ ] Action workflows have template: false in workflow.yaml
-- [ ] Step count reasonable (5-10 steps maximum unless justified)