Convert Legacy - v4 to v5 Conversion Instructions

The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml 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 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 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 YAML 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 YAML 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 YAML format:

1. Convert agent metadata structure:

   • v4 agent.name → v5 agent.metadata.name
   • v4 agent.id → v5 agent.metadata.id
   • v4 agent.title → v5 agent.metadata.title
   • v4 agent.icon → v5 agent.metadata.icon
   • Add v5 agent.metadata.module field

2. Transform persona structure:

   • v4 persona.role → v5 agent.persona.role (keep as YAML string)
   • v4 persona.style → v5 agent.persona.communication_style
   • v4 persona.identity → v5 agent.persona.identity
   • v4 persona.core_principles → v5 agent.persona.principles (as array)

3. Convert commands to menu:

   • v4 commands: list → v5 agent.menu: array
   • Each command becomes menu item with:
     • trigger: (without * prefix - added at build)
     • description:
     • Handler attributes (workflow:, exec:, action:, etc.)
   • Map task references to workflow paths
   • Map template references to workflow invocations

4. Add v5-specific sections (in YAML):

   • agent.prompts: array for inline prompts (if using action: “#id”)
   • agent.critical_actions: array for startup requirements
   • agent.activation_rules: for universal agent rules

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 paths must use {project-root}/bmad/{{module}}/ NOT src/

Generate the converted v5 agent YAML file (.agent.yaml) 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}}.agent.yaml (physical location) Note: The build process will later compile this to .md with XML format Continue to Validation

Extract key information from v4 agent: - Name and purpose - Commands and functionality - Persona traits - Any special behaviors

<invoke-workflow> workflow: {project-root}/bmad/bmb/workflows/create-agent/workflow.yaml inputs: - agent_name: {{extracted_name}} - agent_purpose: {{extracted_purpose}} - commands: {{extracted_commands}} - persona: {{extracted_persona}} </invoke-workflow>

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 → <invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task> 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/create-workflow/workflow.yaml inputs: - workflow_name: {{template_name}} - workflow_type: document - template_structure: {{extracted_template}} - instructions: {{converted_sections}} </invoke-workflow>

Continue to Validation

Analyze module structure and components Create module blueprint with all components

<invoke-workflow> workflow: {project-root}/bmad/bmb/workflows/create-module/workflow.yaml inputs: - module_name: {{module_name}} - components: {{component_list}} </invoke-workflow>

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 <template-output> 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 <invoke-task halt=“true”>{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
   • 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/create-workflow/workflow.yaml inputs: - workflow_name: {{task_name}} - workflow_type: {{confirmed_workflow_type}} - instructions: {{extracted_task_logic}} - template: {{generated_template_if_document}} </invoke-workflow>

Continue to Validation

Run validation checks on converted item:

For Agents:

• [ ] Valid YAML structure (.agent.yaml)
• [ ] All required sections present (metadata, persona, menu)
• [ ] Menu items properly formatted (trigger, description, handlers)
• [ ] Paths use {project-root} variables

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