BoMB updates

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

@@ -17,18 +17,19 @@
 
 - [ ] Agent name, id, title, and icon transferred
 - [ ] All persona elements mapped to v5 structure
-- [ ] All commands converted to v5 <cmds> format
+- [ ] All commands converted to v5 menu array (YAML)
 - [ ] Dependencies properly referenced or converted
 - [ ] Activation instructions adapted to v5 patterns
 
-#### v5 Compliance
+#### v5 Compliance (YAML Format)
 
-- [ ] 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
+- [ ] Valid YAML structure with proper indentation
+- [ ] agent.metadata has all required fields (id, name, title, icon, module)
+- [ ] agent.persona has all sections (role, identity, communication_style, principles)
+- [ ] agent.menu uses proper handlers (workflow, action, exec, tmpl, data)
+- [ ] agent.critical_actions array present when needed
+- [ ] agent.prompts defined for any action: "#id" references
+- [ ] File extension is .agent.yaml (will be compiled to .md later)
 
 #### Best Practices
 

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

@@ -58,8 +58,8 @@ For Modules:
 <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 Agent YAML → v5 Agent YAML format
+- v4 Commands → v5 <menu> with proper handlers
 - v4 Dependencies → v5 workflow references or data files
   </action>
   </step>
@@ -80,7 +80,7 @@ For Modules:
 
 <check>If agent conversion:</check>
 <check>If simple agent (basic persona + commands):</check>
-<action>Use direct conversion to v5 agent XML format</action>
+<action>Use direct conversion to v5 agent YAML 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>
@@ -114,45 +114,50 @@ For Modules:
 </step>
 
 <step n="5a" goal="Direct Agent Conversion" optional="true">
-<action>Transform v4 YAML agent to v5 XML format:</action>
+<action>Transform v4 YAML agent to v5 YAML 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="">`
+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:
-   - v4 `persona.role` → v5 `<role>`
-   - v4 `persona.style` → v5 `<communication_style>`
-   - v4 `persona.identity` → v5 `<identity>`
-   - v4 `persona.core_principles` → v5 `<principles>`
+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:
-   - v4 YAML commands list → v5 `<cmds>` with `<c cmd="">` entries
-   - Map task references to `run-workflow` handlers
+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:
-   - 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
+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 exec/data/run-workflow paths must use {project-root}/bmad/{{module}}/ NOT src/
+   - CRITICAL: All paths must use {project-root}/bmad/{{module}}/ NOT src/
 
-<action>Generate the converted v5 agent file with proper XML structure</action>
+<action>Generate the converted v5 agent YAML file (.agent.yaml)</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>
+  <action>Save to: bmad/{{target_module}}/agents/{{agent_name}}.agent.yaml (physical location)</action>
+  <action>Note: The build process will later compile this to .md with XML format</action>
   <goto step="6">Continue to Validation</goto>
   </step>
 
@@ -275,10 +280,10 @@ For Modules:
 
 For Agents:
 
-- [ ] Valid XML structure
-- [ ] All required sections present
-- [ ] Commands properly formatted
-- [ ] Activation sequence correct
+- [ ] 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:
 

src/modules/bmb/workflows/create-agent/agent-architecture.md

@@ -18,10 +18,10 @@ _LLM-Optimized Technical Documentation for Agent Building_
     <communication_style>How I interact</communication_style>
     <principles>My core beliefs and methodology</principles>
   </persona>
-  <cmds>
-    <c cmd="*help">Show numbered cmd list</c>
-    <c cmd="*exit">Exit with confirmation</c>
-  </cmds>
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
 </agent>
 ```
 
@@ -94,12 +94,12 @@ _LLM-Optimized Technical Documentation for Agent Building_
 - **Sidecar file loading (Expert agents) - MUST be explicit and CRITICAL**
 - **Domain restrictions (Expert agents) - MUST be enforced**
 
-#### 3. Commands Section (REQUIRED)
+#### 3. Menu Section (REQUIRED)
 
 ```xml
-<cmds>
-  <c cmd="*trigger" [attributes]>Description</c>
-</cmds>
+<menu>
+  <item cmd="*trigger" [attributes]>Description</item>
+</menu>
 ```
 
 **Command Attributes:**
@@ -109,7 +109,7 @@ _LLM-Optimized Technical Documentation for Agent Building_
 - `tmpl="{path}"` - Template reference
 - `data="{path}"` - Data file reference
 
-**Required Commands:**
+**Required Menu Items:**
 
 - `*help` - Always first, shows command list
 - `*exit` - Always last, exits agent
@@ -154,7 +154,7 @@ _LLM-Optimized Technical Documentation for Agent Building_
   </critical-actions>
 
   <persona>...</persona>
-  <cmds>...</cmds>
+  <menu>...</menu>
 </agent>
 ```
 
@@ -197,42 +197,42 @@ Bad:  ../../../relative/paths/
 
 ```xml
 <!-- Full path -->
-<c cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
+<item cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
   Create Product Requirements Document
-</c>
+</item>
 
 <!-- Placeholder for future -->
-<c cmd="*analyze" run-workflow="todo">
+<item cmd="*analyze" run-workflow="todo">
   Perform analysis (workflow to be created)
-</c>
+</item>
 ```
 
 ### Task Commands
 
 ```xml
-<c cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.xml">
+<item cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.xml">
   Validate document
-</c>
+</item>
 ```
 
 ### Template Commands
 
 ```xml
-<c cmd="*brief"
+<item cmd="*brief"
    exec="{project-root}/bmad/core/tasks/create-doc.md"
    tmpl="{project-root}/bmad/bmm/templates/brief.md">
   Create project brief
-</c>
+</item>
 ```
 
 ### Data-Driven Commands
 
 ```xml
-<c cmd="*standup"
+<item cmd="*standup"
    exec="{project-root}/bmad/bmm/tasks/daily-standup.xml"
    data="{project-root}/bmad/_cfg/agent-party.xml">
   Run daily standup
-</c>
+</item>
 ```
 
 ## Agent Type Specific Patterns
@@ -270,17 +270,17 @@ Bad:  ../../../relative/paths/
 </persona>
 
 <!-- Hard-coded paths -->
-<c cmd="*run" exec="/Users/john/project/task.md">
+<item cmd="*run" exec="/Users/john/project/task.md">
 
 <!-- No help command -->
-<cmds>
-  <c cmd="*do-something">Action</c>
+<menu>
+  <item cmd="*do-something">Action</item>
   <!-- Missing *help -->
-</cmds>
+</menu>
 
 <!-- Duplicate command triggers -->
-<c cmd="*analyze">First</c>
-<c cmd="*analyze">Second</c>
+<item cmd="*analyze">First</item>
+<item cmd="*analyze">Second</item>
 ```
 
 ### ✅ Good Practices
@@ -295,14 +295,14 @@ Bad:  ../../../relative/paths/
 </persona>
 
 <!-- Variable-based paths -->
-<c cmd="*run" exec="{project-root}/bmad/module/task.md">
+<item cmd="*run" exec="{project-root}/bmad/module/task.md">
 
 <!-- Required commands present -->
-<cmds>
-  <c cmd="*help">Show commands</c>
-  <c cmd="*analyze">Perform analysis</c>
-  <c cmd="*exit">Exit</c>
-</cmds>
+<menu>
+  <item cmd="*help">Show commands</item>
+  <item cmd="*analyze">Perform analysis</item>
+  <item cmd="*exit">Exit</item>
+</menu>
 ```
 
 ## Agent Lifecycle
@@ -378,10 +378,10 @@ When building agents:
 ### Minimal Commands
 
 ```xml
-<cmds>
-  <c cmd="*help">Show numbered cmd list</c>
-  <c cmd="*exit">Exit with confirmation</c>
-</cmds>
+<menu>
+  <item cmd="*help">Show numbered cmd list</item>
+  <item cmd="*exit">Exit with confirmation</item>
+</menu>
 ```
 
 ### Standard Critical Actions
@@ -403,10 +403,10 @@ When building agents:
        icon="{emoji}">
   <persona>...</persona>
   <critical-actions>...</critical-actions>
-  <cmds>
-    <c cmd="*help">...</c>
-    <c cmd="*{command}" run-workflow="{path}">...</c>
-    <c cmd="*exit">...</c>
-  </cmds>
+  <menu>
+    <item cmd="*help">...</item>
+    <item cmd="*{command}" run-workflow="{path}">...</item>
+    <item cmd="*exit">...</item>
+  </menu>
 </agent>
 ```

src/modules/bmb/workflows/create-agent/agent-command-patterns.md

@@ -8,15 +8,15 @@ When executing agent commands, understand these reference patterns:
 
 ```xml
 <!-- Pattern 1: Inline action -->
-<c cmd="*example" action="do this specific thing">
+<item cmd="*example" action="do this specific thing">Description</item>
 → Execute the text "do this specific thing" directly
 
 <!-- Pattern 2: Internal reference with # prefix -->
-<c cmd="*example" action="#prompt-id">
+<item cmd="*example" action="#prompt-id">Description</item>
 → Find <prompt id="prompt-id"> in the current agent and execute its content
 
 <!-- Pattern 3: External file reference -->
-<c cmd="*example" exec="{project-root}/path/to/file.md">
+<item cmd="*example" exec="{project-root}/path/to/file.md">Description</item>
 → Load and execute the external file
 ```
 
@@ -27,7 +27,9 @@ When executing agent commands, understand these reference patterns:
 ### Basic Structure
 
 ```xml
-<c cmd="*trigger" [attributes]>Description</c>
+<menu>
+  <item cmd="*trigger" [attributes]>Description</item>
+</menu>
 ```
 
 **Components:**
@@ -64,29 +66,29 @@ Execute complete multi-step processes
 
 ```xml
 <!-- Standard workflow -->
-<c cmd="*create-prd"
-   run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
+<item cmd="*create-prd"
+     run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
   Create Product Requirements Document
-</c>
+</item>
 
 <!-- Workflow with validation -->
-<c cmd="*validate-prd"
-   validate-workflow="{output_folder}/prd-draft.md"
-   workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
+<item cmd="*validate-prd"
+     validate-workflow="{output_folder}/prd-draft.md"
+     workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
   Validate PRD Against Checklist
-</c>
+</item>
 
 <!-- Auto-discover validation workflow from document -->
-<c cmd="*validate-doc"
-   validate-workflow="{output_folder}/document.md">
+<item cmd="*validate-doc"
+     validate-workflow="{output_folder}/document.md">
   Validate Document (auto-discover checklist)
-</c>
+</item>
 
 <!-- Placeholder for future development -->
-<c cmd="*analyze-data"
-   run-workflow="todo">
+<item cmd="*analyze-data"
+     run-workflow="todo">
   Analyze dataset (workflow coming soon)
-</c>
+</item>
 ```
 
 **Workflow Attributes:**
@@ -109,17 +111,17 @@ Execute single operations
 
 ```xml
 <!-- Simple task -->
-<c cmd="*validate"
+<item cmd="*validate"
    exec="{project-root}/bmad/core/tasks/validate-workflow.xml">
   Validate document against checklist
-</c>
+</item>
 
 <!-- Task with data -->
-<c cmd="*standup"
+<item cmd="*standup"
    exec="{project-root}/bmad/mmm/tasks/daily-standup.xml"
    data="{project-root}/bmad/_cfg/agent-party.xml">
   Run agile team standup
-</c>
+</item>
 ```
 
 **Data Property:**
@@ -134,18 +136,18 @@ Execute single operations
 Generate documents from templates
 
 ```xml
-<c cmd="*brief"
+<item cmd="*brief"
    exec="{project-root}/bmad/core/tasks/create-doc.md"
    tmpl="{project-root}/bmad/bmm/templates/brief.md">
   Produce Project Brief
-</c>
+</item>
 
-<c cmd="*competitor-analysis"
+<item cmd="*competitor-analysis"
    exec="{project-root}/bmad/core/tasks/create-doc.md"
    tmpl="{project-root}/bmad/bmm/templates/competitor.md"
    data="{project-root}/bmad/_data/market-research.csv">
   Produce Competitor Analysis
-</c>
+</item>
 ```
 
 ### 4. Meta Commands
@@ -154,13 +156,13 @@ Agent control and information
 
 ```xml
 <!-- Required meta commands -->
-<c cmd="*help">Show numbered cmd list</c>
-<c cmd="*exit">Exit with confirmation</c>
+<item cmd="*help">Show numbered cmd list</item>
+<item cmd="*exit">Exit with confirmation</item>
 
 <!-- Optional meta commands -->
-<c cmd="*yolo">Toggle Yolo Mode</c>
-<c cmd="*status">Show current status</c>
-<c cmd="*config">Show configuration</c>
+<item cmd="*yolo">Toggle Yolo Mode</item>
+<item cmd="*status">Show current status</item>
+<item cmd="*config">Show configuration</item>
 ```
 
 ### 5. Action Commands
@@ -171,15 +173,15 @@ Direct prompts embedded in commands (Simple agents)
 
 ```xml
 <!-- Short action attribute with embedded prompt -->
-<c cmd="*list-tasks"
+<item cmd="*list-tasks"
    action="list all tasks from {project-root}/bmad/_cfg/task-manifest.csv">
   List Available Tasks
-</c>
+</item>
 
-<c cmd="*summarize"
+<item cmd="*summarize"
    action="summarize the key points from the current document">
   Summarize Document
-</c>
+</item>
 ```
 
 #### Complex Action (Referenced)
@@ -214,23 +216,23 @@ For multiline/complex prompts, define them separately and reference by id:
   </prompts>
 
   <!-- Commands reference the prompts by id -->
-  <cmds>
-    <c cmd="*help">Show numbered cmd list</c>
+  <menu>
+    <item cmd="*help">Show numbered cmd list</item>
 
-    <c cmd="*deep-analyze"
+    <item cmd="*deep-analyze"
        action="#deep-analysis">
       <!-- The # means: use the <prompt id="deep-analysis"> defined above -->
       Perform Deep Analysis
-    </c>
+    </item>
 
-    <c cmd="*review-literature"
+    <item cmd="*review-literature"
        action="#literature-review"
        data="{project-root}/bmad/_data/sources.csv">
       Conduct Literature Review
-    </c>
+    </item>
 
-    <c cmd="*exit">Exit with confirmation</c>
-  </cmds>
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
 </agent>
 ```
 
@@ -261,9 +263,9 @@ Logic embedded in agent persona (Simple agents)
 
 ```xml
 <!-- No exec/run-workflow/action attribute -->
-<c cmd="*calculate">Perform calculation</c>
-<c cmd="*convert">Convert format</c>
-<c cmd="*generate">Generate output</c>
+<item cmd="*calculate">Perform calculation</item>
+<item cmd="*convert">Convert format</item>
+<item cmd="*generate">Generate output</item>
 ```
 
 ## Command Naming Conventions
@@ -295,16 +297,16 @@ Logic embedded in agent persona (Simple agents)
 
 ```xml
 <!-- ❌ Too vague -->
-<c cmd="*do">Do something</c>
+<item cmd="*do">Do something</item>
 
 <!-- ❌ Too long -->
-<c cmd="*create-comprehensive-product-requirements-document-with-analysis">
+<item cmd="*create-comprehensive-product-requirements-document-with-analysis">
 
 <!-- ❌ No verb -->
-<c cmd="*prd">Product Requirements</c>
+<item cmd="*prd">Product Requirements</item>
 
 <!-- ✅ Clear and concise -->
-<c cmd="*create-prd">Create Product Requirements Document</c>
+<item cmd="*create-prd">Create Product Requirements Document</item>
 ```
 
 ## Command Organization
@@ -312,25 +314,25 @@ Logic embedded in agent persona (Simple agents)
 ### Standard Order
 
 ```xml
-<cmds>
+<menu>
   <!-- 1. Always first -->
-  <c cmd="*help">Show numbered cmd list</c>
+  <item cmd="*help">Show numbered cmd list</item>
 
   <!-- 2. Primary workflows -->
-  <c cmd="*create-prd" run-workflow="...">Create PRD</c>
-  <c cmd="*create-module" run-workflow="...">Build module</c>
+  <item cmd="*create-prd" run-workflow="...">Create PRD</item>
+  <item cmd="*create-module" run-workflow="...">Build module</item>
 
   <!-- 3. Secondary actions -->
-  <c cmd="*validate" exec="...">Validate document</c>
-  <c cmd="*analyze" exec="...">Analyze code</c>
+  <item cmd="*validate" exec="...">Validate document</item>
+  <item cmd="*analyze" exec="...">Analyze code</item>
 
   <!-- 4. Utility commands -->
-  <c cmd="*config">Show configuration</c>
-  <c cmd="*yolo">Toggle Yolo Mode</c>
+  <item cmd="*config">Show configuration</item>
+  <item cmd="*yolo">Toggle Yolo Mode</item>
 
   <!-- 5. Always last -->
-  <c cmd="*exit">Exit with confirmation</c>
-</cmds>
+  <item cmd="*exit">Exit with confirmation</item>
+</menu>
 ```
 
 ### Grouping Strategies
@@ -338,34 +340,34 @@ Logic embedded in agent persona (Simple agents)
 **By Lifecycle:**
 
 ```xml
-<cmds>
-  <c cmd="*help">Help</c>
+<menu>
+  <item cmd="*help">Help</item>
   <!-- Planning -->
-  <c cmd="*brainstorm">Brainstorm ideas</c>
-  <c cmd="*plan">Create plan</c>
+  <item cmd="*brainstorm">Brainstorm ideas</item>
+  <item cmd="*plan">Create plan</item>
   <!-- Building -->
-  <c cmd="*build">Build component</c>
-  <c cmd="*test">Test component</c>
+  <item cmd="*build">Build component</item>
+  <item cmd="*test">Test component</item>
   <!-- Deployment -->
-  <c cmd="*deploy">Deploy to production</c>
-  <c cmd="*monitor">Monitor system</c>
-  <c cmd="*exit">Exit</c>
-</cmds>
+  <item cmd="*deploy">Deploy to production</item>
+  <item cmd="*monitor">Monitor system</item>
+  <item cmd="*exit">Exit</item>
+</menu>
 ```
 
 **By Complexity:**
 
 ```xml
-<cmds>
-  <c cmd="*help">Help</c>
+<menu>
+  <item cmd="*help">Help</item>
   <!-- Simple -->
-  <c cmd="*quick-review">Quick review</c>
+  <item cmd="*quick-review">Quick review</item>
   <!-- Standard -->
-  <c cmd="*create-doc">Create document</c>
+  <item cmd="*create-doc">Create document</item>
   <!-- Complex -->
-  <c cmd="*full-analysis">Comprehensive analysis</c>
-  <c cmd="*exit">Exit</c>
-</cmds>
+  <item cmd="*full-analysis">Comprehensive analysis</item>
+  <item cmd="*exit">Exit</item>
+</menu>
 ```
 
 ## Command Descriptions
@@ -374,26 +376,26 @@ Logic embedded in agent persona (Simple agents)
 
 ```xml
 <!-- Clear action and object -->
-<c cmd="*create-prd">Create Product Requirements Document</c>
+<item cmd="*create-prd">Create Product Requirements Document</item>
 
 <!-- Specific outcome -->
-<c cmd="*analyze-security">Perform security vulnerability analysis</c>
+<item cmd="*analyze-security">Perform security vulnerability analysis</item>
 
 <!-- User benefit -->
-<c cmd="*optimize">Optimize code for performance</c>
+<item cmd="*optimize">Optimize code for performance</item>
 ```
 
 ### Poor Descriptions
 
 ```xml
 <!-- Too vague -->
-<c cmd="*process">Process</c>
+<item cmd="*process">Process</item>
 
 <!-- Technical jargon -->
-<c cmd="*exec-wf-123">Execute WF123</c>
+<item cmd="*exec-wf-123">Execute WF123</item>
 
 <!-- Missing context -->
-<c cmd="*run">Run</c>
+<item cmd="*run">Run</item>
 ```
 
 ## The Data Property
@@ -404,26 +406,26 @@ The `data` attribute can be added to ANY command type to provide supplementary i
 
 ```xml
 <!-- Workflow with data -->
-<c cmd="*brainstorm"
+<item cmd="*brainstorm"
    run-workflow="{project-root}/bmad/cis/workflows/brainstorming/workflow.yaml"
    data="{project-root}/bmad/cis/workflows/brainstorming/brain-methods.csv">
   Creative Brainstorming Session
-</c>
+</item>
 
 <!-- Action with data -->
-<c cmd="*analyze-metrics"
+<item cmd="*analyze-metrics"
    action="analyze these metrics and identify trends"
    data="{project-root}/bmad/_data/performance-metrics.json">
   Analyze Performance Metrics
-</c>
+</item>
 
 <!-- Template with data -->
-<c cmd="*report"
+<item cmd="*report"
    exec="{project-root}/bmad/core/tasks/create-doc.md"
    tmpl="{project-root}/bmad/bmm/templates/report.md"
    data="{project-root}/bmad/_data/quarterly-results.csv">
   Generate Quarterly Report
-</c>
+</item>
 ```
 
 **Common Data Uses:**
@@ -441,39 +443,39 @@ The `data` attribute can be added to ANY command type to provide supplementary i
 
 ```xml
 <!-- Only show if certain conditions met -->
-<c cmd="*advanced-mode"
+<item cmd="*advanced-mode"
    if="user_level == 'expert'"
    run-workflow="...">
   Advanced configuration mode
-</c>
+</item>
 
 <!-- Environment specific -->
-<c cmd="*deploy-prod"
+<item cmd="*deploy-prod"
    if="environment == 'production'"
    exec="...">
   Deploy to production
-</c>
+</item>
 ```
 
 ### Parameterized Commands
 
 ```xml
 <!-- Accept runtime parameters -->
-<c cmd="*create-agent"
+<item cmd="*create-agent"
    run-workflow="..."
    params="agent_type,agent_name">
   Create new agent with parameters
-</c>
+</item>
 ```
 
 ### Command Aliases
 
 ```xml
 <!-- Multiple triggers for same action -->
-<c cmd="*prd|*create-prd|*product-requirements"
+<item cmd="*prd|*create-prd|*product-requirements"
    run-workflow="...">
   Create Product Requirements Document
-</c>
+</item>
 ```
 
 ## Module-Specific Patterns
@@ -481,27 +483,27 @@ The `data` attribute can be added to ANY command type to provide supplementary i
 ### BMM (Business Management)
 
 ```xml
-<c cmd="*create-prd">Product Requirements</c>
-<c cmd="*market-research">Market Research</c>
-<c cmd="*competitor-analysis">Competitor Analysis</c>
-<c cmd="*brief">Project Brief</c>
+<item cmd="*create-prd">Product Requirements</item>
+<item cmd="*market-research">Market Research</item>
+<item cmd="*competitor-analysis">Competitor Analysis</item>
+<item cmd="*brief">Project Brief</item>
 ```
 
 ### BMB (Builder)
 
 ```xml
-<c cmd="*create-agent">Build Agent</c>
-<c cmd="*create-module">Build Module</c>
-<c cmd="*create-workflow">Create Workflow</c>
-<c cmd="*module-brief">Module Brief</c>
+<item cmd="*create-agent">Build Agent</item>
+<item cmd="*create-module">Build Module</item>
+<item cmd="*create-workflow">Create Workflow</item>
+<item cmd="*module-brief">Module Brief</item>
 ```
 
 ### CIS (Creative Intelligence)
 
 ```xml
-<c cmd="*brainstorm">Brainstorming Session</c>
-<c cmd="*ideate">Ideation Workshop</c>
-<c cmd="*storytell">Story Creation</c>
+<item cmd="*brainstorm">Brainstorming Session</item>
+<item cmd="*ideate">Ideation Workshop</item>
+<item cmd="*storytell">Story Creation</item>
 ```
 
 ## Command Menu Presentation
@@ -520,10 +522,10 @@ The `data` attribute can be added to ANY command type to provide supplementary i
 
 ```xml
 <!-- Group separator (visual only) -->
-<c cmd="---">━━━━━━━━━━━━━━━━━━━━</c>
+<item cmd="---">━━━━━━━━━━━━━━━━━━━━</item>
 
 <!-- Section header (non-executable) -->
-<c cmd="SECTION">═══ Workflows ═══</c>
+<item cmd="SECTION">═══ Workflows ═══</item>
 ```
 
 ## Error Handling
@@ -532,16 +534,16 @@ The `data` attribute can be added to ANY command type to provide supplementary i
 
 ```xml
 <!-- Workflow not yet created -->
-<c cmd="*future-feature"
+<item cmd="*future-feature"
    run-workflow="todo">
   Coming soon: Advanced feature
-</c>
+</item>
 
 <!-- Graceful degradation -->
-<c cmd="*analyze"
+<item cmd="*analyze"
    run-workflow="{optional-path|fallback-path}">
   Analyze with available tools
-</c>
+</item>
 ```
 
 ## Testing Commands
@@ -569,36 +571,36 @@ The `data` attribute can be added to ANY command type to provide supplementary i
 
 ```xml
 <!-- Create document -->
-<c cmd="*{action}-{object}"
+<item cmd="*{action}-{object}"
    run-workflow="{project-root}/bmad/{module}/workflows/{workflow}/workflow.yaml">
   {Action} {Object Description}
-</c>
+</item>
 
 <!-- Validate document -->
-<c cmd="*validate-{object}"
+<item cmd="*validate-{object}"
    validate-workflow="{output_folder}/{document}.md"
    workflow="{project-root}/bmad/{module}/workflows/{workflow}/workflow.yaml">
   Validate {Object Description}
-</c>
+</item>
 ```
 
 ### Task Command
 
 ```xml
-<c cmd="*{action}"
+<item cmd="*{action}"
    exec="{project-root}/bmad/{module}/tasks/{task}.md">
   {Action Description}
-</c>
+</item>
 ```
 
 ### Template Command
 
 ```xml
-<c cmd="*{document}"
+<item cmd="*{document}"
    exec="{project-root}/bmad/core/tasks/create-doc.md"
    tmpl="{project-root}/bmad/{module}/templates/{template}.md">
   Create {Document Name}
-</c>
+</item>
 ```
 
 ## Self-Contained Agent Patterns
@@ -669,36 +671,36 @@ The `data` attribute can be added to ANY command type to provide supplementary i
     </prompt>
   </prompts>
 
-  <cmds>
-    <c cmd="*help">Show numbered cmd list</c>
+  <menu>
+    <item cmd="*help">Show numbered cmd list</item>
 
     <!-- Simple inline actions -->
-    <c cmd="*summarize"
+    <item cmd="*summarize"
        action="create executive summary of findings">
       Create Executive Summary
-    </c>
+    </item>
 
     <!-- Complex referenced prompts -->
-    <c cmd="*swot"
+    <item cmd="*swot"
        action="#swot-analysis">
       Perform SWOT Analysis
-    </c>
+    </item>
 
-    <c cmd="*compete"
+    <item cmd="*compete"
        action="#competitive-intel"
        data="{project-root}/bmad/_data/market-data.csv">
       Analyze Competition
-    </c>
+    </item>
 
     <!-- Hybrid: external task with internal data -->
-    <c cmd="*report"
+    <item cmd="*report"
        exec="{project-root}/bmad/core/tasks/create-doc.md"
        tmpl="{project-root}/bmad/research/templates/report.md">
       Generate Research Report
-    </c>
+    </item>
 
-    <c cmd="*exit">Exit with confirmation</c>
-  </cmds>
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
 </agent>
 ```
 
@@ -708,32 +710,32 @@ For agents that primarily use embedded logic:
 
 ```xml
 <agent name="Data Analyst">
-  <cmds>
-    <c cmd="*help">Show numbered cmd list</c>
+  <menu>
+    <item cmd="*help">Show numbered cmd list</item>
 
     <!-- Action commands for direct operations -->
-    <c cmd="*list-metrics"
+    <item cmd="*list-metrics"
        action="list all available metrics from the dataset">
       List Available Metrics
-    </c>
+    </item>
 
-    <c cmd="*analyze"
+    <item cmd="*analyze"
        action="perform statistical analysis on the provided data"
        data="{project-root}/bmad/_data/dataset.csv">
       Analyze Dataset
-    </c>
+    </item>
 
-    <c cmd="*visualize"
+    <item cmd="*visualize"
        action="create visualization recommendations for this data">
       Suggest Visualizations
-    </c>
+    </item>
 
     <!-- Embedded logic commands -->
-    <c cmd="*calculate">Perform calculations</c>
-    <c cmd="*interpret">Interpret results</c>
+    <item cmd="*calculate">Perform calculations</item>
+    <item cmd="*interpret">Interpret results</item>
 
-    <c cmd="*exit">Exit with confirmation</c>
-  </cmds>
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
 </agent>
 ```
 

src/modules/bmb/workflows/create-agent/agent-types.md

@@ -37,11 +37,11 @@ BMAD agents come in three distinct types, each designed for different use cases
   <embedded-data>
     <!-- Optional embedded data/logic -->
   </embedded-data>
-  <cmds>
-    <c cmd="*help">Show commands</c>
-    <c cmd="*calculate">Perform calculation</c>
-    <c cmd="*exit">Exit</c>
-  </cmds>
+  <menu>
+    <item cmd="*help">Show commands</item>
+    <item cmd="*calculate">Perform calculation</item>
+    <item cmd="*exit">Exit</item>
+  </menu>
 </agent>
 ```
 
@@ -79,7 +79,7 @@ BMAD agents come in three distinct types, each designed for different use cases
     <i critical="MANDATORY">Load COMPLETE file {agent-folder}/memories.md into permanent context</i>
     <i critical="MANDATORY">ONLY access {user-folder}/diary/ - NO OTHER FOLDERS</i>
   </critical-actions>
-  <cmds>...</cmds>
+  <menu>...</menu>
 </agent>
 ```
 
@@ -124,12 +124,12 @@ expert-agent/
   <critical-actions>
     <i>Load config from {project-root}/bmad/{module}/config.yaml</i>
   </critical-actions>
-  <cmds>
-    <c cmd="*help">Show numbered cmd list</c>
-    <c cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">Create PRD</c>
-    <c cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.xml">Validate document</c>
-    <c cmd="*exit">Exit</c>
-  </cmds>
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    <item cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">Create PRD</item>
+    <item cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.xml">Validate document</item>
+    <item cmd="*exit">Exit</item>
+  </menu>
 </agent>
 ```
 

src/modules/bmb/workflows/create-agent/instructions.md

@@ -29,63 +29,85 @@ If no, proceed directly to Step 0.
 <action>Understand the differences between Simple, Expert, and Module agents</action>
 </step>
 
-<step n="1" goal="Choose agent type and gather basic identity">
-<action>If brainstorming was completed in Step -1, reference those results to guide agent type and identity decisions</action>
+<step n="1" goal="Discover the agent's purpose">
+<action>If brainstorming was completed in Step -1, reference those results to guide the conversation</action>
 
-Ask the user about their agent:
+Start with discovery:
 
-**What type of agent do you want to create?**
+**"What would you like your agent to help with?"**
 
-1. **Simple Agent** - Self-contained, standalone agent with embedded capabilities in a single file
-2. **Expert Agent** - Specialized agent with sidecar files/folders for domain expertise and task files
-3. **Module Agent** - Full-featured agent belonging to a module with external tasks, workflows and resources
+Listen to their vision and explore:
 
-Based on their choice, gather:
+- What problems will it solve?
+- What tasks will it handle?
+- Who will interact with it?
+- What makes this agent special?
 
-- Agent filename (kebab-case, e.g., "data-analyst", "diary-keeper")
-- Agent name (e.g., "Sarah", "Max", or descriptive like "Data Wizard")
-- Agent title (e.g., "Data Analyst", "Personal Assistant")
-- Agent icon (single emoji, e.g., "📊", "🤖", "🧙")
+As the purpose becomes clear, guide toward agent type:
 
-For Module agents also ask:
+**"Based on what you've described, I'm thinking this could be..."**
 
-- Which module? (bmm, bmb, cis, or custom)
-- Store as {{target_module}} for output path determination (used in metadata.module and id)
+1. **Simple Agent** - "A focused, self-contained helper" (if single-purpose, straightforward)
+2. **Expert Agent** - "A specialist with its own knowledge base" (if domain-specific with data needs)
+3. **Module Agent** - "A full-featured system component" (if complex with multiple workflows)
 
-For Expert agents also ask:
+Present the recommendation naturally: _"Given that your agent will [summarize purpose], a [type] agent would work perfectly because..."_
 
-- What sidecar resources? (folder paths, data files, memory files)
-- What domain restrictions? (e.g., "only reads/writes to diary folder")
+For Module agents, discover:
+
+- "Which system would this fit best with?" (bmm, bmb, cis, or custom)
+- Store as {{target_module}} for path determination
+
+For Expert agents, explore:
+
+- "What kind of information will it need to access?"
+- "Are there specific folders or data it should work with?"
 
 <critical>Check {src_impact} variable to determine output location:</critical>
 
 - If {src_impact} = true: Agent will be saved to {src_output_file}
 - If {src_impact} = false: Agent will be saved to {default_output_file}
 
-Store these for later use.
+<note>Keep agent naming/identity details for later - let them emerge naturally through the creation process</note>
 </step>
 
-<step n="2" goal="Define agent persona">
-<action>If brainstorming was completed, use the personality insights and character concepts from the brainstorming session</action>
+<step n="2" goal="Shape the agent's personality through conversation">
+<action>If brainstorming was completed, weave personality insights naturally into the conversation</action>
 
-Work with user to craft the agent's personality:
+Now that we understand what the agent will do, let's discover who it is:
 
-**Role** (1-2 lines):
+**"Let's bring this agent to life! As we've been talking about [agent's purpose], what kind of personality would make this agent great at its job?"**
 
-- Professional title and primary expertise
-- Example: "Strategic Business Analyst + Requirements Expert"
+Explore through questions like:
 
-**Identity** (3-5 lines):
+- "Should it be more analytical or creative?"
+- "Formal and professional, or friendly and casual?"
+- "Would it be better as a mentor, a peer, or an assistant?"
 
-- Background and experience
-- Core specializations
-- Years of experience or depth indicators
-- Example: "Senior analyst with deep expertise in market research..."
+As personality traits emerge, help shape them:
+
+**Role** - Let this emerge from the conversation:
+
+- "So it sounds like we're creating a [emerging role]..."
+- Guide toward a 1-2 line professional title
+- Example emerges: "Strategic Business Analyst + Requirements Expert"
+
+**Identity** - Build this through discovery:
+
+- "What kind of background would give it credibility?"
+- "What specializations would be most valuable?"
+- Let the 3-5 line identity form naturally
+- Example emerges: "Senior analyst with deep expertise in market research..."
 
 <action>Load the communication styles guide: {communication_styles}</action>
-<action>Present the communication style options to the user</action>
 
-**Communication Style** - Choose a preset or create your own!
+**Communication Style** - Now for the fun part!
+
+"I'm seeing this agent's personality really taking shape! For how it communicates, we could go with something..."
+
+<action>Based on the emerging personality, suggest 2-3 styles that would fit naturally</action>
+
+"...or would you like to see all the options?"
 
 **Fun Presets:**
 
@@ -108,193 +130,243 @@ Or describe your own unique style! (3-5 lines)
 <action>Show relevant sections from {communication_styles} guide</action>
 <action>Help them craft their unique communication style</action>
 
-**Principles** (5-8 lines):
+**Principles** - These often reveal themselves through our conversation:
 
-- Core beliefs about their work
-- Methodology and approach
-- What drives their decisions
-- Start with "I believe..." or "I operate..."
-- Example: "I believe that every business challenge has underlying root causes..."
+"Based on everything we've discussed, what core principles should guide this agent's decisions?"
+
+Help them articulate 5-8 lines:
+
+- "From what you've said, it seems like this agent believes..."
+- "I'm hearing that it values..."
+- Shape into "I believe..." or "I operate..." statements
+- Example emerges: "I believe that every business challenge has underlying root causes..."
 
 <template-output>agent_persona</template-output>
 </step>
 
-<step n="3" goal="Setup optional additions" optional="true">
-Ask: **Do you want to add prompts or critical actions? [Yes/no]** (default: No)
+<step n="3" goal="Build capabilities through natural progression">
 
-If yes, collect:
+"Now let's give our agent some capabilities! What should it be able to do?"
 
-- Prompts: id + content (referenced with action: "#id" in menu items)
-- Critical actions: plain text steps appended to activation during build
+Start with the core commands they've already mentioned, then explore:
 
-Represent these in YAML sections `prompts` and `critical_actions`.
+- "That's great! What else?"
+- "Would it be helpful if it could also..."
+- "I'm thinking it might need to..."
 
-<template-output>agent_enhancements</template-output>
+As capabilities emerge, subtly guide toward technical implementation without breaking the flow.
+
+<template-output>initial_capabilities</template-output>
 </step>
 
-<step n="4" goal="Build command structure">
+<step n="4" goal="Refine commands and discover advanced features">
 <critical>Help and Exit are auto-injected; do NOT add them. Triggers are auto-prefixed with * during build.</critical>
 
-Collect menu items in YAML (examples):
+"Let me help structure these capabilities into commands..."
 
-```
+Transform their natural language capabilities into technical structure, explaining as you go:
+
+- "When you said [capability], we can implement that as..."
+- "This would work great as a workflow that..."
+
+If they seem engaged, explore:
+
+- "Would you like to add any special prompts for complex analyses?"
+- "Should there be any critical setup steps when the agent activates?"
+
+Build the YAML structure naturally from the conversation:
+
+```yaml
 menu:
-  - trigger: product-brief
-    workflow: "{project-root}/bmad/bmm/workflows/1-analysis/product-brief/workflow.yaml"
-    description: Produce Project Brief
-
-  - trigger: validate-prd
-    workflow: "{project-root}/bmad/bmm/workflows/1-analysis/product-brief/workflow.yaml"
-    "validate-workflow": "{output_folder}/prd-draft.md"
-    description: Validate PRD Against Checklist
-
-  - trigger: summarize
-    action: "#deep-analysis"
-    description: Summarize current document
-
-  - trigger: generate-brief
-    exec: "{project-root}/bmad/core/tasks/create-doc.md"
-    tmpl: "{project-root}/bmad/bmm/templates/brief.md"
-    data: "{project-root}/bmad/_data/context.csv"
-    description: Generate Project Brief from template
+  # Commands emerge from discussion
+  - trigger: [emerging from conversation]
+    workflow: [path based on capability]
+    description: [user's words refined]
 ```
 
 <template-output>agent_commands</template-output>
 </step>
 
-<step n="5" goal="Activation behavior" optional="true">
-BMAD injects activation from fragments automatically based on used attributes (workflow/exec/tmpl/action). Most agents do not need custom activation.
+<step n="5" goal="Name the agent - The perfect moment!">
 
-If special steps are required, add them as `critical_actions` (Step 3) so they are appended during build.
+"Our agent is really coming together! It's got purpose, personality, and capabilities. Now it needs a name!"
 
-<template-output>activation_notes</template-output>
+This is where the naming feels natural and meaningful:
+
+**"Based on everything we've built, what should we call this agent?"**
+
+Guide the naming with context:
+
+- "Given its [personality trait], maybe something like..."
+- "Since it specializes in [capability], how about..."
+- "With that [communication style], it feels like a..."
+
+Explore options:
+
+- **Agent name**: "Sarah", "Max", "Data Wizard" (personality-driven)
+- **Agent title**: Based on the role we discovered earlier
+- **Agent icon**: "What emoji captures its essence?"
+- **Filename**: Auto-suggest based on name (kebab-case)
+
+Example flow:
+"So we have an analytical expert who helps with data... I'm thinking 'Sarah the Data Analyst' with a 📊 icon? Or maybe something more playful like 'Data Wizard' with 🧙?"
+
+Let them choose or create their own. The name now has meaning because they know who this agent IS.
+
+<template-output>agent_identity</template-output>
 </step>
 
-<step n="6" goal="Generate agent file (YAML)">
-Generate a YAML agent at the chosen path. The installer will compile it to `.md` inside `{project-root}/bmad/{{module}}/agents/`.
+<step n="6" goal="Bring it all together">
 
-Example structure:
+"Perfect! Let me pull everything together into your agent..."
+
+Share the journey as you create:
+"We started with [initial purpose], discovered it needed [key personality traits], gave it [capabilities], and named it [agent name]. Here's your complete agent:"
+
+Generate the YAML incorporating everything discovered:
 
 ```yaml
 agent:
   metadata:
     id: bmad/{{target_module}}/agents/{{agent_filename}}.md
-    name: { { agent_name } }
-    title: { { agent_title } }
-    icon: { { agent_icon } }
+    name: { { agent_name } } # The name we chose together
+    title: { { agent_title } } # From the role that emerged
+    icon: { { agent_icon } } # The perfect emoji
     module: { { target_module } }
 
   persona:
     role: |
-      {{agent_persona.role}}
+      {{The role we discovered}}
     identity: |
-      {{agent_persona.identity}}
+      {{The background that emerged}}
     communication_style: |
-      {{agent_persona.communication_style}}
-    principles: { { agent_persona.principles } }
+      {{The style they loved}}
+    principles: { { The beliefs we articulated } }
 
-  # Optional (from Step 3)
-  prompts: []
-  critical_actions: []
+  # Features we explored
+  prompts: { { if discussed } }
+  critical_actions: { { if needed } }
 
-  menu: { { agent_commands } }
+  menu: { { The capabilities we built } }
 ```
 
-<critical>Determine save location based on {src_impact}:</critical>
+<critical>Save based on {src_impact}:</critical>
 
-- If {src_impact} = true: Save to {src_output_file} (src/modules/{{target_module}}/agents/{{agent_filename}}.md)
-- If {src_impact} = false: Save to {default_output_file} (output_folder/agents/{{agent_filename}}.md)
+- If {src_impact} = true: Save to {src_output_file}
+- If {src_impact} = false: Save to {default_output_file}
+
+"Your agent [name] is ready! It turned out even better than I expected!"
 
 <template-output>complete_agent</template-output>
 </step>
 
-<step n="7" goal="Create customize file" optional="true">
-Ask: **Create a customize YAML for overrides? [Yes/no]** (default: No)
+<step n="7" goal="Optional personalization">
 
-If yes, create at: {config_output_file}
+"Would you like to create a customization file? This lets you tweak [agent name]'s personality later without touching the core agent."
+
+If interested:
+"Great! This gives you a playground to experiment with different personality traits, add new commands, or adjust responses as you get to know [agent name] better."
+
+Create at: {config_output_file}
 
 ```yaml
-# Agent Customization (overrides are merged at build time)
+# Personal tweaks for {{agent_name}}
+# Experiment freely - changes merge at build time
 agent:
   metadata:
-    name: ''
+    name: '' # Try nicknames!
 persona:
   role: ''
   identity: ''
-  communication_style: ''
+  communication_style: '' # Switch styles anytime
   principles: []
 critical_actions: []
 prompts: []
-menu: []
+menu: [] # Add personal commands
 ```
 
-Note: The installer also auto-creates this file from a template if missing.
-
 <template-output>agent_config</template-output>
 </step>
 
-<step n="8" goal="Create sidecar resources" if="agent_type == 'expert'">
-For Expert agents, help setup sidecar resources:
+<step n="8" goal="Set up the agent's workspace" if="agent_type == 'expert'">
 
-1. Create folders for domain data
-2. Create memory/knowledge files
-3. Set up access patterns
-4. Document restrictions
+"Since [agent name] is an Expert agent, let's set up its personal workspace!"
+
+Make it feel like preparing an office:
+
+- "Where should [agent name] keep its notes and research?"
+- "What kind of information will it need quick access to?"
+- "Should it have its own data folders?"
+
+Create the resources as a natural extension:
+
+1. "Creating [agent name]'s knowledge base..."
+2. "Setting up its personal workspace..."
+3. "Giving it access to the resources it needs..."
 
 <template-output>sidecar_resources</template-output>
 </step>
 
-<step n="9" goal="Validate generated agent">
-Run validation checks:
+<step n="9" goal="Quality check with personality">
 
-1. **YAML structure:**
-   - Parses without errors
-   - `agent.metadata` has id, name, title, icon, module
-   - `agent.persona` complete; principles may be array
+"Let me make sure [agent name] is ready to go!"
 
-2. **Menu validation:**
-   - No `*` prefix in triggers (added at build)
-   - `description` present for each item
-   - Paths use `{project-root}` or valid variables
-   - No duplicate triggers
+Run validation but present it conversationally:
 
-3. **Build check:**
-   - Run installer compile to generate `.md` files
-   - Confirm `{project-root}/bmad/{{module}}/agents/{{agent_filename}}.md` exists
+- "Checking [agent name]'s configuration..." ✓
+- "Making sure all commands work..." ✓
+- "Verifying personality settings..." ✓
 
-4. **Type-specific:**
-   - Simple/Expert/Module fields make sense and referenced paths exist (or are `todo`)
+If issues found:
+"Hmm, looks like [agent name] needs a small adjustment to [issue]. Let me fix that..."
 
-Show validation results and fix any issues.
+If all good:
+"[Agent name] passed all checks! It's ready to help!"
+
+Technical checks (run behind the scenes):
+
+1. YAML structure validity
+2. Menu command validation
+3. Build compilation test
+4. Type-specific requirements
+
+<template-output>validation_results</template-output>
 </step>
 
-<step n="10" goal="Provide usage instructions">
-Provide the user with:
+<step n="10" goal="Celebrate and guide next steps">
 
-1. **Location of generated agent:**
-   - If {src_impact} = true: {{src_output_file}}
-   - If {src_impact} = false: {{default_output_file}}
+"🎉 Congratulations! [Agent name] is ready to join your team!"
 
-2. **Build to .md:**
-   - Run `npm run install:bmad` and choose "Compile Agents" (or `bmad install` → Compile)
-   - The installer merges YAML + customize and injects activation and menu handlers
+Share the accomplishment:
+"You've created [agent type] agent with [key characteristic]. [Agent name] can [top capabilities]."
 
-3. **Next steps:**
-   - Implement any "todo" workflows
-   - Test agent commands
-   - Refine persona based on usage
-   - Add more commands as needed
+**"Here's how to activate [agent name]:"**
 
-4. **For Expert agents:**
-   - Populate sidecar resources
-   - Test domain restrictions
-   - Verify data access patterns
+1. **Quick start:**
+   - "Run `npm run install:bmad` and select 'Compile Agents'"
+   - "Then you can call [agent name] anytime!"
 
-Ask if user wants to:
+2. **Location:**
+   - "I saved [agent name] here: {{output_file}}"
+   - "After compilation, it'll live at: {project-root}/bmad/{{module}}/agents/"
 
-- Test the agent now
-- Create another agent
-- Make adjustments
-  </step>
+3. **What [agent name] can do right away:**
+   - List the commands in a friendly way
+   - "Try `*[first-command]` to see it in action!"
+
+For Expert agents:
+"Don't forget to add any special knowledge or data [agent name] might need to its workspace!"
+
+**"What would you like to do next?"**
+
+- "Want to test [agent name] now?"
+- "Should we create a teammate for [agent name]?"
+- "Any tweaks to [agent name]'s personality?"
+
+End with enthusiasm:
+"I really enjoyed building [agent name] with you! I think it's going to be incredibly helpful for [main purpose]."
+
+<template-output>completion_message</template-output>
+</step>
 
 </workflow>

src/modules/bmb/workflows/create-module/instructions.md

@@ -46,12 +46,25 @@ If skip, proceed directly to module definition.
 
 Ask the user about their module vision:
 
-**Module Identity:**
+**"What kind of module do you want to create? Tell me about its purpose and what it will help with."**
 
-1. **Module code** (kebab-case, e.g., "rpg-toolkit", "data-viz", "team-collab")
-2. **Module name** (friendly name, e.g., "RPG Toolkit", "Data Visualization Suite")
-3. **Module purpose** (1-2 sentences describing what it does)
-4. **Target audience** (who will use this module?)
+Listen to their description and then:
+
+<action>Based on their description, intelligently propose module details:</action>
+
+**Module Identity (AI Proposed):**
+
+1. **Module name** - Extract from their description (e.g., "Data Visualization Suite", "RPG Toolkit")
+2. **Module code** - Generate kebab-case from name:
+   - "Data Visualization Suite" → propose: "data-viz"
+   - "RPG Game Master Tools" → propose: "rpg-toolkit"
+   - "Team Collaboration System" → propose: "team-collab"
+   - "Personal Finance Manager" → propose: "fin-manager"
+
+   Present as: _"Based on what you described, I suggest the module code: `{{proposed-code}}`. This will be used in paths like bmad/{{proposed-code}}/agents/. Does this work or would you prefer something different?"_
+
+3. **Module purpose** - Refine their description into 1-2 clear sentences
+4. **Target audience** - Infer from context or ask if unclear
 
 **Module Theme Examples:**
 
@@ -72,32 +85,52 @@ Store module identity for scaffolding.
 </step>
 
 <step n="2" goal="Plan module components">
-Gather the module's component architecture:
+<action>Based on the module purpose, propose an initial component architecture:</action>
 
-**Agents Planning:**
-Ask: How many agents will this module have? (typically 1-5)
+**"Based on your {{module_name}}, here's what I think would make a great module structure:"**
 
-For each agent, gather:
+**Agents Planning (AI Proposed):**
 
-- Agent name and purpose
-- Will it be Simple, Expert, or Module type?
-- Key commands it should have
-- Create now or placeholder for later?
+<action>Intelligently suggest agents based on module purpose:</action>
 
-Example for RPG module:
+For a Data Visualization module, suggest:
 
-1. DM Agent - Dungeon Master assistant (Module type)
-2. NPC Agent - Character simulation (Expert type)
-3. Story Writer Agent - Adventure creation (Module type)
+- "Data Analyst" - Interprets and analyzes datasets (Module type)
+- "Chart Designer" - Creates visualization specs (Simple type)
+- "Report Builder" - Generates comprehensive reports (Module type)
 
-**Workflows Planning:**
-Ask: How many workflows? (typically 2-10)
+For an RPG Toolkit, suggest:
 
-For each workflow, gather:
+- "Dungeon Master" - Runs game sessions (Module type)
+- "NPC Generator" - Creates characters (Expert type)
+- "Story Weaver" - Builds adventures (Module type)
+
+For a Team Collaboration module, suggest:
+
+- "Project Manager" - Coordinates tasks (Module type)
+- "Meeting Facilitator" - Runs standups/retros (Simple type)
+- "Documentation Lead" - Maintains team docs (Expert type)
+
+Present as: _"I'm thinking your module could have these agents: [list]. We can start with the core ones and add others later. Which of these resonate with your vision?"_
+
+**Workflows Planning (AI Proposed):**
+
+<action>Intelligently suggest workflows based on module purpose:</action>
+
+For a Data Visualization module, suggest workflows like:
+
+- "analyze-dataset" - Statistical analysis workflow
+- "create-dashboard" - Interactive dashboard builder
+- "generate-report" - Automated report generation
+
+For an RPG Toolkit, suggest workflows like:
+
+- "session-prep" - Prepare game session materials
+- "generate-encounter" - Create combat/social encounters
+- "world-building" - Design locations and lore
+
+Present as: _"For workflows, these would complement your agents well: [list]. Each can be created as we need them. Which are most important to start with?"_
 
-- Workflow name and purpose
-- Document, Action, or Interactive type?
-- Complexity (simple/complex)
 - Create now or placeholder?
 
 Example workflows:
@@ -118,6 +151,33 @@ For each task:
 <template-output>module_components</template-output>
 </step>
 
+<step n="2b" goal="Determine module complexity">
+<action>Based on components, intelligently determine module type:</action>
+
+**Simple Module** (auto-select if):
+
+- 1-2 agents, all Simple type
+- 1-3 workflows
+- No complex integrations
+
+**Standard Module** (auto-select if):
+
+- 2-4 agents with mixed types
+- 3-8 workflows
+- Some shared resources
+
+**Complex Module** (auto-select if):
+
+- 4+ agents or multiple Module-type agents
+- 8+ workflows
+- Complex interdependencies
+- External integrations
+
+Present as: _"Based on your planned components, this looks like a {{determined_type}} module. This means we'll set up {{structure_description}}."_
+
+<template-output>module_type</template-output>
+</step>
+
 <step n="3" goal="Create module directory structure">
 <critical>Determine base module path based on {src_impact}:</critical>
 - If {src_impact} = true: Use {src_output_folder}

src/modules/bmb/workflows/create-workflow/checklist.md

@@ -57,12 +57,34 @@
 - [ ] Output location is writable
 - [ ] Dependencies (if any) are available
 
+## Web Bundle Configuration (if applicable)
+
+- [ ] web_bundle section present if needed
+- [ ] Name, description, author copied from main config
+- [ ] All file paths converted to bmad/-relative format
+- [ ] NO {config_source} variables in web bundle
+- [ ] NO {project-root} prefixes in paths
+- [ ] Instructions path listed correctly
+- [ ] Validation/checklist path listed correctly
+- [ ] Template path listed (if document workflow)
+- [ ] All data files referenced in instructions are listed
+- [ ] All sub-workflows are included
+- [ ] web_bundle_files array is complete:
+  - [ ] Instructions.md included
+  - [ ] Checklist.md included
+  - [ ] Template.md included (if applicable)
+  - [ ] All CSV/JSON data files included
+  - [ ] All referenced templates included
+  - [ ] All sub-workflow files included
+- [ ] No external dependencies outside bundle
+
 ## Documentation
 
 - [ ] README created (if requested)
 - [ ] Usage instructions clear
 - [ ] Example command provided
 - [ ] Special requirements noted
+- [ ] Web bundle deployment noted (if applicable)
 
 ## Final Validation
 

src/modules/bmb/workflows/create-workflow/instructions.md

@@ -247,6 +247,64 @@ Ask if they want to:
 - Add additional steps or features
   </step>
 
+<step n="9b" goal="Configure web bundle (optional)">
+<ask>Will this workflow need to be deployable as a web bundle? [yes/no]</ask>
+
+If yes:
+<action>Explain web bundle requirements:</action>
+
+- Web bundles are self-contained and cannot use config_source variables
+- All files must be explicitly listed in web_bundle_files
+- File paths use bmad/ root (not {project-root})
+
+<action>Configure web_bundle section in workflow.yaml:</action>
+
+1. Copy core workflow metadata (name, description, author)
+2. Convert all file paths to bmad/-relative paths:
+   - Remove {project-root}/ prefix
+   - Remove {config_source} references (use hardcoded values)
+   - Example: "{project-root}/bmad/bmm/workflows/x" → "bmad/bmm/workflows/x"
+
+3. List ALL referenced files:
+   - Scan instructions.md for any file paths
+   - Scan template.md for any includes or references
+   - Include all data files (CSV, JSON, etc.)
+   - Include any sub-workflow YAML files
+   - Include any shared templates
+
+4. Create web_bundle_files array with complete list
+
+Example:
+
+```yaml
+web_bundle:
+  name: '{workflow_name}'
+  description: '{workflow_description}'
+  author: '{author}'
+  instructions: 'bmad/{module}/workflows/{workflow}/instructions.md'
+  validation: 'bmad/{module}/workflows/{workflow}/checklist.md'
+  template: 'bmad/{module}/workflows/{workflow}/template.md'
+
+  # Any data files (no config_source)
+  data_file: 'bmad/{module}/workflows/{workflow}/data.csv'
+
+  web_bundle_files:
+    - 'bmad/{module}/workflows/{workflow}/instructions.md'
+    - 'bmad/{module}/workflows/{workflow}/checklist.md'
+    - 'bmad/{module}/workflows/{workflow}/template.md'
+    - 'bmad/{module}/workflows/{workflow}/data.csv'
+    # Add every single file referenced anywhere
+```
+
+<action>Validate web bundle completeness:</action>
+
+- Ensure no {config_source} variables remain
+- Verify all file paths are listed
+- Check that paths are bmad/-relative
+
+<template-output>web_bundle_config</template-output>
+</step>
+
 <step n="10" goal="Document and finalize">
 Create a brief README for the workflow folder explaining:
 - Purpose and use case

src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md

@@ -422,6 +422,105 @@ Check requirements against goals.
 - **No checkpoints** - Add `<template-output>` tags
 - **Vague instructions** - Be explicit about expectations
 
+## Web Bundles
+
+Web bundles allow workflows to be deployed as self-contained packages for web environments.
+
+### When to Use Web Bundles
+
+- Deploying workflows to web-based AI platforms
+- Creating shareable workflow packages
+- Ensuring workflow portability without dependencies
+- Publishing workflows for public use
+
+### Web Bundle Requirements
+
+1. **Self-Contained**: No external dependencies
+2. **No Config Variables**: Cannot use `{config_source}` references
+3. **Complete File List**: Every referenced file must be listed
+4. **Relative Paths**: Use `bmad/` root paths (no `{project-root}`)
+
+### Creating a Web Bundle
+
+Add this section to your workflow.yaml:
+
+```yaml
+web_bundle:
+  name: 'workflow-name'
+  description: 'Workflow description'
+  author: 'Your Name'
+
+  # Core files (bmad/-relative paths)
+  instructions: 'bmad/module/workflows/workflow/instructions.md'
+  validation: 'bmad/module/workflows/workflow/checklist.md'
+  template: 'bmad/module/workflows/workflow/template.md'
+
+  # Data files (no config_source allowed)
+  data_file: 'bmad/module/workflows/workflow/data.csv'
+
+  # Complete file list - CRITICAL!
+  web_bundle_files:
+    - 'bmad/module/workflows/workflow/instructions.md'
+    - 'bmad/module/workflows/workflow/checklist.md'
+    - 'bmad/module/workflows/workflow/template.md'
+    - 'bmad/module/workflows/workflow/data.csv'
+    # Include ALL referenced files
+```
+
+### Converting Existing Workflows
+
+1. **Remove Config Dependencies**:
+   - Replace `{config_source}:variable` with hardcoded values
+   - Convert `{project-root}/bmad/` to `bmad/`
+
+2. **Inventory All Files**:
+   - Scan instructions.md for file references
+   - Check template.md for includes
+   - List all data files
+
+3. **Test Completeness**:
+   - Ensure no missing file references
+   - Verify all paths are relative to bmad/
+
+### Example: Complete Web Bundle
+
+```yaml
+web_bundle:
+  name: 'analyze-requirements'
+  description: 'Requirements analysis workflow'
+  author: 'BMad Team'
+
+  instructions: 'bmad/bmm/workflows/analyze-requirements/instructions.md'
+  validation: 'bmad/bmm/workflows/analyze-requirements/checklist.md'
+  template: 'bmad/bmm/workflows/analyze-requirements/template.md'
+
+  # Data files
+  techniques_data: 'bmad/bmm/workflows/analyze-requirements/techniques.csv'
+  patterns_data: 'bmad/bmm/workflows/analyze-requirements/patterns.json'
+
+  # Sub-workflow reference
+  validation_workflow: 'bmad/bmm/workflows/validate-requirements/workflow.yaml'
+
+  web_bundle_files:
+    # Core workflow files
+    - 'bmad/bmm/workflows/analyze-requirements/instructions.md'
+    - 'bmad/bmm/workflows/analyze-requirements/checklist.md'
+    - 'bmad/bmm/workflows/analyze-requirements/template.md'
+
+    # Data files
+    - 'bmad/bmm/workflows/analyze-requirements/techniques.csv'
+    - 'bmad/bmm/workflows/analyze-requirements/patterns.json'
+
+    # Sub-workflow and its files
+    - 'bmad/bmm/workflows/validate-requirements/workflow.yaml'
+    - 'bmad/bmm/workflows/validate-requirements/instructions.md'
+    - 'bmad/bmm/workflows/validate-requirements/checklist.md'
+
+    # Shared templates referenced in instructions
+    - 'bmad/bmm/templates/requirement-item.md'
+    - 'bmad/bmm/templates/validation-criteria.md'
+```
+
 ## Troubleshooting
 
 ### Variables Not Replaced

src/modules/bmb/workflows/create-workflow/workflow-template/workflow.yaml

@@ -33,3 +33,32 @@ required_tools: #optional, can be omitted
   - "Tool Name": #example, can be omitted if none
       description: "Description of why this tool is needed"
       link: "https://link-to-tool.com"
+
+# Web Bundle Configuration (optional - for web-deployable workflows)
+# IMPORTANT: Web bundles are self-contained and cannot use config_source variables
+# All referenced files must be listed in web_bundle_files
+web_bundle: #optional, can be omitted
+  name: "{WORKFLOW_CODE}"
+  description: "{WORKFLOW_DESCRIPTION}"
+  author: "BMad"
+
+  # Core workflow files (paths relative to bmad/ root)
+  instructions: "bmad/{module-code}/workflows/{workflow-code}/instructions.md"
+  validation: "bmad/{module-code}/workflows/{workflow-code}/checklist.md"
+  template: "bmad/{module-code}/workflows/{workflow-code}/template.md" # if document workflow
+
+  # Reference any data files or additional workflows (no config_source allowed)
+  # brain_techniques: "bmad/{module-code}/workflows/{workflow-code}/data-file.csv"
+  # sub_workflow: "bmad/{module-code}/workflows/other-workflow/workflow.yaml"
+
+  # CRITICAL: List ALL files used by this workflow
+  # This includes instructions, validation, templates, data files,
+  # and any files referenced within those files
+  web_bundle_files:
+    - "bmad/{module-code}/workflows/{workflow-code}/instructions.md"
+    - "bmad/{module-code}/workflows/{workflow-code}/checklist.md"
+    - "bmad/{module-code}/workflows/{workflow-code}/template.md"
+    # Add ALL referenced files here - examine instructions.md and template.md
+    # for any file paths and include them all
+    # - "bmad/{module-code}/workflows/{workflow-code}/data/example.csv"
+    # - "bmad/{module-code}/templates/shared-template.md"

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

@@ -52,10 +52,11 @@ Present the editing menu to the user:
 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
+7. **Configure web bundle** - Add/update web bundle for deployment
+8. **Optimize for clarity** - Improve descriptions, add examples
+9. **Full review and update** - Comprehensive improvements across all files
 
-<ask>Select an option (1-8) or describe a custom edit:</ask>
+<ask>Select an option (1-9) or describe a custom edit:</ask>
 </step>
 
 <step n="4" goal="Load relevant documentation">
@@ -72,6 +73,11 @@ Based on the selected edit type, load appropriate reference materials:
 <check>If editing validation:</check>
 <action>Review the "Validation" section and measurable criteria examples</action>
 
+<check>If configuring web bundle:</check>
+<action>Review the "Web Bundles" section of the creation guide</action>
+<action>Scan all workflow files for referenced resources</action>
+<action>Create inventory of all files that must be included</action>
+
 <check>If fixing critical issues:</check>
 <action>Load the workflow execution engine documentation</action>
 <action>Verify all required elements are present</action>
@@ -80,6 +86,30 @@ Based on the selected edit type, load appropriate reference materials:
 <step n="5" goal="Perform edits" repeat="until-complete">
 Based on the selected focus area:
 
+<check>If configuring web bundle (option 7):</check>
+<action>Check if web_bundle section exists in workflow.yaml</action>
+
+If creating new web bundle:
+
+1. Extract workflow metadata (name, description, author)
+2. Convert all file paths to bmad/-relative format
+3. Remove any {config_source} references
+4. Scan instructions.md for all file references:
+   - Data files (CSV, JSON)
+   - Sub-workflows
+   - Shared templates
+   - Any included files
+5. Scan template.md for any includes
+6. Create complete web_bundle_files array
+7. Generate web_bundle section
+
+If updating existing web bundle:
+
+1. Verify all paths are bmad/-relative
+2. Check for missing files in web_bundle_files
+3. Remove any config dependencies
+4. Update file list with newly referenced files
+
 <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>
@@ -121,6 +151,15 @@ Validation checks:
 - [ ] Critical headers are present in instructions
 - [ ] YAML syntax is valid
 
+Web bundle validation (if applicable):
+
+- [ ] web_bundle section present if needed
+- [ ] All paths are bmad/-relative (no {project-root})
+- [ ] No {config_source} variables in web bundle
+- [ ] All referenced files listed in web_bundle_files
+- [ ] Instructions, validation, template paths correct
+- [ ] Complete file inventory verified
+
 <check>If any validation fails:</check>
 <ask>Issues found. Would you like to fix them? (y/n)</ask>
 <check>If yes:</check>