BMAD-METHOD/src/modules/bmb/workflows/convert-legacy/instructions.md

Convert Legacy - v4 to v5 Conversion Instructions

The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md You MUST have already loaded and processed: {project_root}/bmad/bmb/workflows/convert-legacy/workflow.yaml

Ask user for the path to the v4 item to convert (agent, workflow, or module) Load the complete file/folder structure Detect item type based on structure and content patterns: - Agent: Contains `` or `` XML tags, single file - Workflow: Contains workflow YAML or instruction patterns, usually folder - Module: Contains multiple agents/workflows in organized structure - Task: Contains `` XML tags Confirm detected type or allow user to correct: "Detected as [type]. Is this correct? (y/n)" Parse the v4 structure and extract key components:

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

Create a conversion map of what needs to be transformed 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 with proper handlers
• v4 Dependencies → v5 workflow references or data files

Which module should this belong to? (eg. bmm, bmb, cis, bmm-legacy, or custom) If custom module: Enter custom module code (kebab-case): Determine installation path based on type and module IMPORTANT: All paths must use final BMAD installation locations, not src paths! Show user the target location: {project-root}/bmad/{{target_module}}/{{item_type}}/{{item_name}} Note: Files will be created in bmad/ but all internal paths will reference {project-root}/bmad/ locations Proceed with this location? (y/n) Based on item type and complexity, choose approach:

If agent conversion: If simple agent (basic persona + commands): Use direct conversion to v5 agent XML format Direct Agent Conversion If complex agent with embedded workflows: Plan to invoke create-agent workflow Workflow-Assisted Agent Creation

If template or task conversion to workflow: Analyze the v4 item to determine workflow type:

• 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

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:

If template conversion: Template-to-Workflow Conversion If task conversion: Task-to-Workflow Conversion

If full module conversion: Plan to invoke create-module workflow Module Creation

Transform v4 YAML agent to v5 XML format:

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/

Generate the converted v5 agent file with proper XML structure 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" Save to: bmad/{{target_module}}/agents/{{agent_name}}.md (physical location) But agent will reference: {project-root}/bmad/{{target_module}}/agents/{{agent_name}}.md Continue to Validation

Extract key information from v4 agent: - Name and purpose - Commands and functionality - Persona traits - Any special behaviors 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}}

Continue to Validation

Convert v4 Template (YAML) to v5 Workflow:

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

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}}

Continue to Validation

Analyze module structure and components Create module blueprint with all components workflow: {project-root}/bmad/bmb/workflows/build-module/workflow.yaml inputs: - module_name: {{module_name}} - components: {{component_list}}

Continue to Validation

Convert v4 Task (Markdown) to v5 Workflow:

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: If Document workflow:

   • Create template.md from output patterns
   • Map generation steps to instructions
   • Add tags for sections

   If Action workflow:

   • 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
   • Agent permissions → note in instructions
   • YOLO mode → autonomous flag or optional steps
   • Critical notices → workflow.yaml comments

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}}

Continue to Validation

Run validation checks on converted item:

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

Show validation results to user Any issues to fix before finalizing? (y/n) If yes: Address specific issues Re-validate

Generate conversion report showing: - Original v4 location - New v5 location - Items converted - Any manual adjustments needed - Warnings or notes

Save report to: {output_folder}/conversion-report-{{date}}.md

Archive original v4 files? (y/n) If yes: Move v4 files to: {project-root}/archive/v4-legacy/{{date}}/

Show user the final converted items and their locations Provide any post-conversion instructions or recommendations

Would you like to convert another legacy item? (y/n) If yes: Start new conversion