bmad-method 5.1.2 → 6.0.0-alpha.0

package/src/modules/bmb/workflows/convert-legacy/checklist.md

@@ -0,0 +1,204 @@
+# Convert Legacy - Validation Checklist
+
+## Pre-Conversion Validation
+
+### Source Analysis
+
+- [ ] Original v4 file(s) fully loaded and parsed
+- [ ] Item type correctly identified (agent/template/task/module)
+- [ ] All dependencies documented and accounted for
+- [ ] No critical content overlooked in source files
+
+## Conversion Completeness
+
+### For Agent Conversions
+
+#### Content Preservation
+
+- [ ] Agent name, id, title, and icon transferred
+- [ ] All persona elements mapped to v5 structure
+- [ ] All commands converted to v5 <cmds> format
+- [ ] Dependencies properly referenced or converted
+- [ ] Activation instructions adapted to v5 patterns
+
+#### v5 Compliance
+
+- [ ] Valid XML structure with proper nesting
+- [ ] <agent> tag has all required attributes (id, name, title, icon)
+- [ ] NO <activation> section included (auto-inserted from agent-activation-ide.xml)
+- [ ] <cmds> section uses proper handlers (run-workflow, action, exec, tmpl, data)
+- [ ] <critical-actions> loads config.yaml when needed
+- [ ] Persona sections (<role>, <identity>, <communication_style>, <principles>) are present
+
+#### Best Practices
+
+- [ ] Commands use appropriate workflow references instead of direct task calls
+- [ ] File paths use {project-root} variables
+- [ ] Config values use {config_source}: pattern
+- [ ] Agent follows naming conventions (kebab-case for files)
+- [ ] ALL paths reference {project-root}/bmad/{{module}}/ locations, NOT src/
+- [ ] exec, data, run-workflow commands point to final BMAD installation paths
+
+### For Template/Workflow Conversions
+
+#### Content Preservation
+
+- [ ] Template metadata (name, description, output) transferred
+- [ ] All sections converted to workflow steps
+- [ ] Section hierarchy maintained in instructions
+- [ ] Variables ({{var}}) preserved in template.md
+- [ ] Elicitation points (elicit: true) converted to <elicit-required/>
+- [ ] Conditional sections preserved with if="" attributes
+- [ ] Repeatable sections converted to repeat="" attributes
+
+#### v5 Compliance
+
+- [ ] workflow.yaml follows structure from workflow-creation-guide.md
+- [ ] instructions.md has critical headers referencing workflow engine
+- [ ] Steps numbered sequentially with clear goals
+- [ ] Template variables match between instructions and template.md
+- [ ] Proper use of XML tags (<action>, <check>, <ask>, <template-output>)
+- [ ] File structure follows v5 pattern (folder with yaml/md files)
+
+#### Best Practices
+
+- [ ] Steps are focused with single goals
+- [ ] Instructions are specific ("Write 1-2 paragraphs" not "Write about")
+- [ ] Examples provided where helpful
+- [ ] Limits set where appropriate ("3-5 items maximum")
+- [ ] Save checkpoints with <template-output> at logical points
+- [ ] Variables use descriptive snake_case names
+
+### For Task Conversions
+
+#### Content Preservation
+
+- [ ] Task logic fully captured in workflow instructions
+- [ ] Execution flow maintained
+- [ ] User interaction points preserved
+- [ ] Decision trees converted to workflow logic
+- [ ] All processing steps accounted for
+- [ ] Document generation patterns identified and preserved
+
+#### Type Determination
+
+- [ ] Workflow type correctly identified (document/action/interactive/meta)
+- [ ] If generates documents, template.md created
+- [ ] If performs actions only, marked as action workflow
+- [ ] Output patterns properly analyzed
+
+#### v5 Compliance
+
+- [ ] Converted to proper workflow format (not standalone task)
+- [ ] Follows workflow execution engine patterns
+- [ ] Interactive elements use proper v5 tags
+- [ ] Flow control uses v5 patterns (goto, check, loop)
+- [ ] 1-9 elicitation menus converted to v5 elicitation
+- [ ] Critical notices preserved in workflow.yaml
+- [ ] YOLO mode converted to appropriate v5 patterns
+
+### Module-Level Validation
+
+#### Structure
+
+- [ ] Module follows v5 directory structure
+- [ ] All components in correct locations:
+  - Agents in /agents/
+  - Workflows in /workflows/
+  - Data files in appropriate locations
+- [ ] Config files properly formatted
+
+#### Integration
+
+- [ ] Cross-references between components work
+- [ ] Workflow invocations use correct paths
+- [ ] Data file references are valid
+- [ ] No broken dependencies
+
+## Technical Validation
+
+### Syntax and Format
+
+- [ ] YAML files have valid syntax (no parsing errors)
+- [ ] XML structures properly formed and closed
+- [ ] Markdown files render correctly
+- [ ] File encoding is UTF-8
+- [ ] Line endings consistent (LF)
+
+### Path Resolution
+
+- [ ] All file paths resolve correctly
+- [ ] Variable substitutions work ({project-root}, {installed_path}, etc.)
+- [ ] Config references load properly
+- [ ] No hardcoded absolute paths (unless intentional)
+
+## Functional Validation
+
+### Execution Testing
+
+- [ ] Converted item can be loaded without errors
+- [ ] Agents activate properly when invoked
+- [ ] Workflows execute through completion
+- [ ] User interaction points function correctly
+- [ ] Output generation works as expected
+
+### Behavioral Validation
+
+- [ ] Converted item behaves similarly to v4 version
+- [ ] Core functionality preserved
+- [ ] User experience maintains or improves
+- [ ] No functionality regression
+
+## Documentation and Cleanup
+
+### Documentation
+
+- [ ] Conversion report generated with all changes
+- [ ] Any manual adjustments documented
+- [ ] Known limitations or differences noted
+- [ ] Migration instructions provided if needed
+
+### Post-Conversion
+
+- [ ] Original v4 files archived (if requested)
+- [ ] File permissions set correctly
+- [ ] Git tracking updated if applicable
+- [ ] User informed of new locations
+
+## Final Verification
+
+### Quality Assurance
+
+- [ ] Converted item follows ALL v5 best practices
+- [ ] Code/config is clean and maintainable
+- [ ] No TODO or FIXME items remain
+- [ ] Ready for production use
+
+### User Acceptance
+
+- [ ] User reviewed conversion output
+- [ ] User tested basic functionality
+- [ ] User approved final result
+- [ ] Any user feedback incorporated
+
+## Notes Section
+
+### Conversion Issues Found:
+
+_List any issues encountered during validation_
+
+### Manual Interventions Required:
+
+_Document any manual fixes needed_
+
+### Recommendations:
+
+_Suggestions for further improvements or considerations_
+
+---
+
+**Validation Result:** [ ] PASSED / [ ] FAILED
+
+**Validator:** {{user_name}}
+**Date:** {{date}}
+**Items Converted:** {{conversion_summary}}

package/src/modules/bmb/workflows/convert-legacy/instructions.md

@@ -0,0 +1,328 @@
+# Convert Legacy - v4 to v5 Conversion Instructions
+
+<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
+<critical>You MUST have already loaded and processed: {project_root}/bmad/bmb/workflows/convert-legacy/workflow.yaml</critical>
+
+<workflow>
+
+<step n="1" goal="Identify and Load Legacy Item">
+<action>Ask user for the path to the v4 item to convert (agent, workflow, or module)</action>
+<action>Load the complete file/folder structure</action>
+<action>Detect item type based on structure and content patterns:</action>
+  - Agent: Contains `<agent>` or `<prompt>` XML tags, single file
+  - Workflow: Contains workflow YAML or instruction patterns, usually folder
+  - Module: Contains multiple agents/workflows in organized structure
+  - Task: Contains `<task>` XML tags
+<ask>Confirm detected type or allow user to correct: "Detected as [type]. Is this correct? (y/n)"</ask>
+</step>
+
+<step n="2" goal="Analyze Legacy Structure">
+<action>Parse the v4 structure and extract key components:</action>
+
+For v4 Agents (YAML-based in markdown):
+
+- Agent metadata (name, id, title, icon, whenToUse)
+- Persona block (role, style, identity, focus, core_principles)
+- Commands list with task/template references
+- Dependencies (tasks, templates, checklists, data files)
+- Activation instructions and workflow rules
+- IDE file resolution patterns
+
+For v4 Templates (YAML-based document generators):
+
+- Template metadata (id, name, version, output)
+- Workflow mode and elicitation settings
+- Sections hierarchy with:
+  - Instructions for content generation
+  - Elicit flags for user interaction
+  - Templates with {{variables}}
+  - Conditional sections
+  - Repeatable sections
+
+For v4 Tasks (Markdown with execution instructions):
+
+- Critical execution notices
+- Step-by-step workflows
+- Elicitation requirements (1-9 menu format)
+- Processing flows and decision trees
+- Agent permission rules
+
+For Modules:
+
+- Module metadata
+- Component list (agents, workflows, tasks)
+- Dependencies
+- Installation requirements
+
+<action>Create a conversion map of what needs to be transformed</action>
+<action>Map v4 patterns to v5 equivalents:
+
+- v4 Task + Template → v5 Workflow (folder with workflow.yaml, instructions.md, template.md)
+- v4 Agent YAML → v5 Agent XML format
+- v4 Commands → v5 <cmds> with proper handlers
+- v4 Dependencies → v5 workflow references or data files
+  </action>
+  </step>
+
+<step n="3" goal="Determine Target Module and Location">
+<ask>Which module should this belong to? (eg. bmm, bmb, cis, bmm-legacy, or custom)</ask>
+<check>If custom module:</check>
+  <ask>Enter custom module code (kebab-case):</ask>
+<action>Determine installation path based on type and module</action>
+<critical>IMPORTANT: All paths must use final BMAD installation locations, not src paths!</critical>
+<action>Show user the target location: {project-root}/bmad/{{target_module}}/{{item_type}}/{{item_name}}</action>
+<action>Note: Files will be created in bmad/ but all internal paths will reference {project-root}/bmad/ locations</action>
+<ask>Proceed with this location? (y/n)</ask>
+</step>
+
+<step n="4" goal="Choose Conversion Strategy">
+<action>Based on item type and complexity, choose approach:</action>
+
+<check>If agent conversion:</check>
+<check>If simple agent (basic persona + commands):</check>
+<action>Use direct conversion to v5 agent XML format</action>
+<goto step="5a">Direct Agent Conversion</goto>
+<check>If complex agent with embedded workflows:</check>
+<action>Plan to invoke create-agent workflow</action>
+<goto step="5b">Workflow-Assisted Agent Creation</goto>
+
+<check>If template or task conversion to workflow:</check>
+<action>Analyze the v4 item to determine workflow type:</action>
+
+- Does it generate a specific document type? → Document workflow
+- Does it produce structured output files? → Document workflow
+- Does it perform actions without output? → Action workflow
+- Does it coordinate other tasks? → Meta-workflow
+- Does it guide user interaction? → Interactive workflow
+
+<ask>Based on analysis, this appears to be a {{detected_workflow_type}} workflow. Confirm or correct:
+
+1. Document workflow (generates documents with template)
+2. Action workflow (performs actions, no template)
+3. Interactive workflow (guided session)
+4. Meta-workflow (coordinates other workflows)
+   Select 1-4:</ask>
+
+<check>If template conversion:</check>
+<goto step="5c">Template-to-Workflow Conversion</goto>
+<check>If task conversion:</check>
+<goto step="5e">Task-to-Workflow Conversion</goto>
+
+<check>If full module conversion:</check>
+<action>Plan to invoke create-module workflow</action>
+<goto step="5d">Module Creation</goto>
+</step>
+
+<step n="5a" goal="Direct Agent Conversion" optional="true">
+<action>Transform v4 YAML agent to v5 XML format:</action>
+
+1. Convert agent metadata:
+   - v4 `agent.name` → v5 `<agent name="">`
+   - v4 `agent.id` → v5 `<agent id="">`
+   - v4 `agent.title` → v5 `<agent title="">`
+   - v4 `agent.icon` → v5 `<agent icon="">`
+
+2. Transform persona:
+   - v4 `persona.role` → v5 `<role>`
+   - v4 `persona.style` → v5 `<communication_style>`
+   - v4 `persona.identity` → v5 `<identity>`
+   - v4 `persona.core_principles` → v5 `<principles>`
+
+3. Convert commands:
+   - v4 YAML commands list → v5 `<cmds>` with `<c cmd="">` entries
+   - Map task references to `run-workflow` handlers
+   - Map template references to workflow invocations
+
+4. Add v5-specific sections:
+   - DO NOT include `<activation>` block (inserted automatically from agent-activation-ide.xml)
+   - Add `<critical-actions>` for config loading and startup requirements
+   - Structure proper XML hierarchy with agent attributes and persona
+
+5. Handle dependencies and paths:
+   - Convert task dependencies to workflow references
+   - Map template dependencies to v5 workflows
+   - Preserve checklist and data file references
+   - CRITICAL: All exec/data/run-workflow paths must use {project-root}/bmad/{{module}}/ NOT src/
+
+<action>Generate the converted v5 agent file with proper XML structure</action>
+<action>Example path conversions:
+
+- exec="{project-root}/bmad/{{target_module}}/tasks/task-name.md"
+- run-workflow="{project-root}/bmad/{{target_module}}/workflows/workflow-name/workflow.yaml"
+- data="{project-root}/bmad/{{target_module}}/data/data-file.yaml"
+  </action>
+  <action>Save to: bmad/{{target_module}}/agents/{{agent_name}}.md (physical location)</action>
+  <action>But agent will reference: {project-root}/bmad/{{target_module}}/agents/{{agent_name}}.md</action>
+  <goto step="6">Continue to Validation</goto>
+  </step>
+
+<step n="5b" goal="Workflow-Assisted Agent Creation" optional="true">
+<action>Extract key information from v4 agent:</action>
+- Name and purpose
+- Commands and functionality
+- Persona traits
+- Any special behaviors
+
+<invoke-workflow>
+  workflow: {project-root}/bmad/bmb/workflows/build-agent/workflow.yaml
+  inputs:
+    - agent_name: {{extracted_name}}
+    - agent_purpose: {{extracted_purpose}}
+    - commands: {{extracted_commands}}
+    - persona: {{extracted_persona}}
+</invoke-workflow>
+
+<goto step="6">Continue to Validation</goto>
+</step>
+
+<step n="5c" goal="Template-to-Workflow Conversion" optional="true">
+<action>Convert v4 Template (YAML) to v5 Workflow:</action>
+
+1. Extract template metadata:
+   - Template id, name, version → workflow.yaml name/description
+   - Output settings → default_output_file
+   - Workflow mode (interactive/yolo) → workflow settings
+
+2. Convert template sections to instructions.md:
+   - Each YAML section → workflow step
+   - `elicit: true` → `<elicit-required/>` tag
+   - Conditional sections → `if="condition"` attribute
+   - Repeatable sections → `repeat="for-each"` attribute
+   - Section instructions → step content
+
+3. Extract template structure to template.md:
+   - Section content fields → template structure
+   - {{variables}} → preserve as-is
+   - Nested sections → hierarchical markdown
+
+4. Handle v4 create-doc.md task integration:
+   - Elicitation methods (1-9 menu) → convert to v5 elicitation
+   - Agent permissions → note in instructions
+   - Processing flow → integrate into workflow steps
+
+<invoke-workflow>
+  workflow: {project-root}/bmad/bmb/workflows/build-workflow/workflow.yaml
+  inputs:
+    - workflow_name: {{template_name}}
+    - workflow_type: document
+    - template_structure: {{extracted_template}}
+    - instructions: {{converted_sections}}
+</invoke-workflow>
+
+<goto step="6">Continue to Validation</goto>
+</step>
+
+<step n="5d" goal="Module Creation" optional="true">
+<action>Analyze module structure and components</action>
+<action>Create module blueprint with all components</action>
+
+<invoke-workflow>
+  workflow: {project-root}/bmad/bmb/workflows/build-module/workflow.yaml
+  inputs:
+    - module_name: {{module_name}}
+    - components: {{component_list}}
+</invoke-workflow>
+
+<goto step="6">Continue to Validation</goto>
+</step>
+
+<step n="5e" goal="Task-to-Workflow Conversion" optional="true">
+<action>Convert v4 Task (Markdown) to v5 Workflow:</action>
+
+1. Analyze task purpose and output:
+   - Does it generate documents? → Create template.md
+   - Does it process data? → Action workflow
+   - Does it guide user interaction? → Interactive workflow
+   - Check for file outputs, templates, or document generation
+
+2. Extract task components:
+   - Execution notices and critical rules → workflow.yaml metadata
+   - Step-by-step instructions → instructions.md steps
+   - Decision trees and branching → flow control tags
+   - User interaction patterns → appropriate v5 tags
+
+3. Based on confirmed workflow type:
+   <check>If Document workflow:</check>
+   - Create template.md from output patterns
+   - Map generation steps to instructions
+   - Add <template-output> tags for sections
+
+   <check>If Action workflow:</check>
+   - Set template: false in workflow.yaml
+   - Focus on action sequences in instructions
+   - Preserve execution logic
+
+4. Handle special v4 patterns:
+   - 1-9 elicitation menus → v5 <elicit-required/>
+   - Agent permissions → note in instructions
+   - YOLO mode → autonomous flag or optional steps
+   - Critical notices → workflow.yaml comments
+
+<invoke-workflow>
+  workflow: {project-root}/bmad/bmb/workflows/build-workflow/workflow.yaml
+  inputs:
+    - workflow_name: {{task_name}}
+    - workflow_type: {{confirmed_workflow_type}}
+    - instructions: {{extracted_task_logic}}
+    - template: {{generated_template_if_document}}
+</invoke-workflow>
+
+<goto step="6">Continue to Validation</goto>
+</step>
+
+<step n="6" goal="Validate Conversion">
+<action>Run validation checks on converted item:</action>
+
+For Agents:
+
+- [ ] Valid XML structure
+- [ ] All required sections present
+- [ ] Commands properly formatted
+- [ ] Activation sequence correct
+
+For Workflows:
+
+- [ ] Valid YAML syntax
+- [ ] Instructions follow v5 conventions
+- [ ] Template variables match
+- [ ] File structure correct
+
+For Modules:
+
+- [ ] All components converted
+- [ ] Proper folder structure
+- [ ] Config files valid
+- [ ] Installation ready
+
+<action>Show validation results to user</action>
+<ask>Any issues to fix before finalizing? (y/n)</ask>
+<check>If yes:</check>
+<action>Address specific issues</action>
+<goto step="6">Re-validate</goto>
+</step>
+
+<step n="7" goal="Migration Report">
+<action>Generate conversion report showing:</action>
+- Original v4 location
+- New v5 location
+- Items converted
+- Any manual adjustments needed
+- Warnings or notes
+
+<action>Save report to: {output_folder}/conversion-report-{{date}}.md</action>
+</step>
+
+<step n="8" goal="Cleanup and Finalize">
+<ask>Archive original v4 files? (y/n)</ask>
+<check>If yes:</check>
+  <action>Move v4 files to: {project-root}/archive/v4-legacy/{{date}}/</action>
+
+<action>Show user the final converted items and their locations</action>
+<action>Provide any post-conversion instructions or recommendations</action>
+
+<ask>Would you like to convert another legacy item? (y/n)</ask>
+<check>If yes:</check>
+<goto step="1">Start new conversion</goto>
+</step>
+
+</workflow>

package/src/modules/bmb/workflows/convert-legacy/workflow.yaml

@@ -0,0 +1,35 @@
+# Convert Legacy - BMAD v4 to v5 Converter Configuration
+name: "convert-legacy"
+description: "Converts legacy BMAD v4 or similar items (agents, workflows, modules) to BMad Core compliant format with proper structure and conventions"
+author: "BMad"
+
+# Critical variables load from config_source
+config_source: "{project-root}/bmad/bmb/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+src_impact: "{config_source}:src_impact"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Optional docs that can be provided as input
+recommended_inputs:
+  - legacy_file: "Path to v4 agent, workflow, or module to convert"
+  - conversion_mappings: "{project-root}/bmad/bmb/data/v4-to-v5-mappings.yaml"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmb/workflows/convert-legacy"
+template: false # This is an action/meta workflow - no template needed
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration - Creates converted items in appropriate module locations
+default_output_folder: "{project-root}/bmad/{{target_module}}/{{item_type}}/{{item_name}}"
+
+# Sub-workflows that may be invoked for conversion
+sub_workflows:
+  - create_agent: "{project-root}/bmad/bmb/workflows/build-agent/workflow.yaml"
+  - create_workflow: "{project-root}/bmad/bmb/workflows/build-workflow/workflow.yaml"
+  - create_module: "{project-root}/bmad/bmb/workflows/build-module/workflow.yaml"
+
+# No special tools required beyond standard BMAD capabilities
+required_tools: []