bmad-method 6.0.0-alpha.9 → 6.0.2

package/tools/cli/lib/xml-handler.js

@@ -44,18 +44,7 @@ class XmlHandler {
    * @returns {Object} Parsed activation block
    */
   async loadActivationTemplate() {
-    const templatePath = getSourcePath('utility', 'models', 'agent-activation-ide.xml');
-
-    try {
-      const xmlContent = await fs.readFile(templatePath, 'utf8');
-
-      // Parse the XML directly (file is now pure XML)
-      const parsed = await this.parser.parseStringPromise(xmlContent);
-      return parsed.activation;
-    } catch (error) {
-      console.error('Failed to load activation template:', error);
-      return null;
-    }
+    console.error('Failed to load activation template:', error);
   }
 
   /**
@@ -136,51 +125,10 @@ class XmlHandler {
   }
 
   /**
-   * Simple string-based injection (fallback method for legacy XML agents)
-   * This preserves formatting better than XML parsing
+   * TODO: DELETE THIS METHOD
    */
   injectActivationSimple(agentContent, metadata = {}) {
-    // Check if already has activation
-    if (agentContent.includes('<activation')) {
-      return agentContent;
-    }
-
-    // Load template file
-    const templatePath = getSourcePath('utility', 'models', 'agent-activation-ide.xml');
-
-    try {
-      const templateContent = fs.readFileSync(templatePath, 'utf8');
-
-      // The file is now pure XML, use it directly with proper indentation
-      // Add 2 spaces of indentation for insertion into agent
-      let activationBlock = templateContent
-        .split('\n')
-        .map((line) => (line ? '  ' + line : ''))
-        .join('\n');
-
-      // Replace {agent-filename} with actual filename if metadata provided
-      if (metadata.module && metadata.name) {
-        const agentFilename = `${metadata.module}-${metadata.name}.md`;
-        activationBlock = activationBlock.replace('{agent-filename}', agentFilename);
-      }
-
-      // Find where to insert (after <agent> tag)
-      const agentMatch = agentContent.match(/(<agent[^>]*>)/);
-      if (!agentMatch) {
-        return agentContent;
-      }
-
-      const insertPos = agentMatch.index + agentMatch[0].length;
-
-      // Insert the activation block
-      const before = agentContent.slice(0, insertPos);
-      const after = agentContent.slice(insertPos);
-
-      return before + '\n' + activationBlock + after;
-    } catch (error) {
-      console.error('Error in simple injection:', error);
-      return agentContent;
-    }
+    console.error('Error in simple injection:', error);
   }
 
   /**
@@ -203,6 +151,7 @@ class XmlHandler {
         customizeHash: customizePath ? await this.yamlBuilder.calculateFileHash(customizePath) : null,
         builderVersion: '1.0.0',
         includeMetadata: metadata.includeMetadata !== false,
+        forWebBundle: metadata.forWebBundle || false, // Pass through forWebBundle flag
       };
 
       // Convert to XML

package/tools/cli/lib/yaml-format.js

@@ -1,6 +1,6 @@
 const fs = require('node:fs');
 const path = require('node:path');
-const yaml = require('js-yaml');
+const yaml = require('yaml');
 const { execSync } = require('node:child_process');
 
 // Dynamic import for ES module
@@ -57,11 +57,10 @@ async function formatYamlContent(content, filename) {
     }
 
     // Parse and re-dump YAML to format it
-    const parsed = yaml.load(fixedContent);
-    const formatted = yaml.dump(parsed, {
+    const parsed = yaml.parse(fixedContent);
+    const formatted = yaml.stringify(parsed, {
       indent: 2,
-      lineWidth: -1, // Disable line wrapping
-      noRefs: true,
+      lineWidth: 0, // Disable line wrapping
       sortKeys: false, // Preserve key order
     });
     // Ensure POSIX-compliant final newline
@@ -96,7 +95,6 @@ async function processMarkdownFile(filePath) {
     const [fullMatch, yamlContent] = match;
     const formatted = await formatYamlContent(yamlContent, filePath);
     if (formatted !== null) {
-      // Remove trailing newline that js-yaml adds
       const trimmedFormatted = formatted.replace(/\n$/, '');
 
       if (trimmedFormatted !== yamlContent) {

package/tools/cli/lib/yaml-xml-builder.js

@@ -1,9 +1,10 @@
-const yaml = require('js-yaml');
+const yaml = require('yaml');
 const fs = require('fs-extra');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { AgentAnalyzer } = require('./agent-analyzer');
 const { ActivationBuilder } = require('./activation-builder');
+const { escapeXml } = require('../../lib/xml-utils');
 
 /**
  * Converts agent YAML files to XML format with smart activation injection
@@ -63,13 +64,13 @@ class YamlXmlBuilder {
   async loadAndMergeAgent(agentYamlPath, customizeYamlPath = null) {
     // Load base agent
     const agentContent = await fs.readFile(agentYamlPath, 'utf8');
-    const agentYaml = yaml.load(agentContent);
+    const agentYaml = yaml.parse(agentContent);
 
     // Load customization if exists
     let merged = agentYaml;
     if (customizeYamlPath && (await fs.pathExists(customizeYamlPath))) {
       const customizeContent = await fs.readFile(customizeYamlPath, 'utf8');
-      const customizeYaml = yaml.load(customizeContent);
+      const customizeYaml = yaml.parse(customizeContent);
 
       if (customizeYaml) {
         // Special handling: persona fields are merged, but only non-empty values override
@@ -119,6 +120,16 @@ class YamlXmlBuilder {
         if (customizeYaml.critical_actions) {
           merged.agent.critical_actions = [...(merged.agent.critical_actions || []), ...customizeYaml.critical_actions];
         }
+
+        // Append prompts
+        if (customizeYaml.prompts) {
+          merged.agent.prompts = [...(merged.agent.prompts || []), ...customizeYaml.prompts];
+        }
+
+        // Append memories
+        if (customizeYaml.memories) {
+          merged.agent.memories = [...(merged.agent.memories || []), ...customizeYaml.memories];
+        }
       }
     }
 
@@ -202,6 +213,11 @@ class YamlXmlBuilder {
     // Persona section
     xml += this.buildPersonaXml(agent.persona);
 
+    // Memories section (if exists)
+    if (agent.memories) {
+      xml += this.buildMemoriesXml(agent.memories);
+    }
+
     // Prompts section (if exists)
     if (agent.prompts) {
       xml += this.buildPromptsXml(agent.prompts);
@@ -209,7 +225,7 @@ class YamlXmlBuilder {
 
     // Menu section (support both 'menu' and legacy 'commands')
     const menuItems = agent.menu || agent.commands || [];
-    xml += this.buildCommandsXml(menuItems);
+    xml += this.buildCommandsXml(menuItems, buildMetadata.forWebBundle);
 
     xml += '</agent>\n';
     xml += '```\n';
@@ -217,21 +233,6 @@ class YamlXmlBuilder {
     return xml;
   }
 
-  /**
-   * Build metadata comment
-   */
-  buildMetadataComment(metadata) {
-    const lines = ['<!-- BUILD-META', `  source: ${metadata.sourceFile || 'unknown'} (hash: ${metadata.sourceHash || 'unknown'})`];
-
-    if (metadata.customizeFile) {
-      lines.push(`  customize: ${metadata.customizeFile} (hash: ${metadata.customizeHash || 'unknown'})`);
-    }
-
-    lines.push(`  built: ${new Date().toISOString()}`, `  builder-version: ${metadata.builderVersion || '1.0.0'}`, '-->\n');
-
-    return lines.join('\n');
-  }
-
   /**
    * Build persona XML section
    */
@@ -241,15 +242,15 @@ class YamlXmlBuilder {
     let xml = '  <persona>\n';
 
     if (persona.role) {
-      xml += `    <role>${this.escapeXml(persona.role)}</role>\n`;
+      xml += `    <role>${escapeXml(persona.role)}</role>\n`;
     }
 
     if (persona.identity) {
-      xml += `    <identity>${this.escapeXml(persona.identity)}</identity>\n`;
+      xml += `    <identity>${escapeXml(persona.identity)}</identity>\n`;
     }
 
     if (persona.communication_style) {
-      xml += `    <communication_style>${this.escapeXml(persona.communication_style)}</communication_style>\n`;
+      xml += `    <communication_style>${escapeXml(persona.communication_style)}</communication_style>\n`;
     }
 
     if (persona.principles) {
@@ -260,7 +261,7 @@ class YamlXmlBuilder {
       } else {
         principlesText = persona.principles;
       }
-      xml += `    <principles>${this.escapeXml(principlesText)}</principles>\n`;
+      xml += `    <principles>${escapeXml(principlesText)}</principles>\n`;
     }
 
     xml += '  </persona>\n';
@@ -268,6 +269,23 @@ class YamlXmlBuilder {
     return xml;
   }
 
+  /**
+   * Build memories XML section
+   */
+  buildMemoriesXml(memories) {
+    if (!memories || memories.length === 0) return '';
+
+    let xml = '  <memories>\n';
+
+    for (const memory of memories) {
+      xml += `    <memory>${escapeXml(memory)}</memory>\n`;
+    }
+
+    xml += '  </memories>\n';
+
+    return xml;
+  }
+
   /**
    * Build prompts XML section
    * Handles both array format and object/dictionary format
@@ -296,9 +314,9 @@ class YamlXmlBuilder {
 
     for (const prompt of promptsArray) {
       xml += `    <prompt id="${prompt.id || ''}">\n`;
-      xml += `      <![CDATA[\n`;
-      xml += `      ${prompt.content || ''}\n`;
-      xml += `      ]]>\n`;
+      xml += `      <content>\n`;
+      xml += `${escapeXml(prompt.content || '')}\n`;
+      xml += `      </content>\n`;
       xml += `    </prompt>\n`;
     }
 
@@ -310,46 +328,67 @@ class YamlXmlBuilder {
   /**
    * Build menu XML section (renamed from commands for clarity)
    * Auto-injects *help and *exit, adds * prefix to all triggers
+   * Supports both legacy format and new multi format with nested handlers
+   * @param {Array} menuItems - Menu items from YAML
+   * @param {boolean} forWebBundle - Whether building for web bundle
    */
-  buildCommandsXml(menuItems) {
+  buildCommandsXml(menuItems, forWebBundle = false) {
     let xml = '  <menu>\n';
 
-    // Always inject *help first
-    xml += `    <item cmd="*help">Show numbered menu</item>\n`;
+    // Always inject menu display option first
+    xml += `    <item cmd="*menu">[M] Redisplay Menu Options</item>\n`;
 
     // Add user-defined menu items with * prefix
     if (menuItems && menuItems.length > 0) {
       for (const item of menuItems) {
-        // Build command attributes - add * prefix if not present
-        let trigger = item.trigger || '';
-        if (!trigger.startsWith('*')) {
-          trigger = '*' + trigger;
+        // Skip ide-only items when building for web bundles
+        if (forWebBundle && item['ide-only'] === true) {
+          continue;
+        }
+        // Skip web-only items when NOT building for web bundles (i.e., IDE/local installation)
+        if (!forWebBundle && item['web-only'] === true) {
+          continue;
         }
 
-        const attrs = [`cmd="${trigger}"`];
-
-        // Add handler attributes
-        // If workflow-install exists, use its value for workflow attribute (vendoring)
-        // workflow-install is build-time metadata - tells installer where to copy workflows
-        // The final XML should only have workflow pointing to the install location
-        if (item['workflow-install']) {
-          attrs.push(`workflow="${item['workflow-install']}"`);
-        } else if (item.workflow) {
-          attrs.push(`workflow="${item.workflow}"`);
+        // Handle multi format menu items with nested handlers
+        if (item.multi && item.triggers && Array.isArray(item.triggers)) {
+          xml += `    <item type="multi">${escapeXml(item.multi)}\n`;
+          xml += this.buildNestedHandlers(item.triggers);
+          xml += `    </item>\n`;
         }
+        // Handle legacy format menu items
+        else if (item.trigger) {
+          // For legacy items, keep using cmd with *<trigger> format
+          let trigger = item.trigger || '';
+          if (!trigger.startsWith('*')) {
+            trigger = '*' + trigger;
+          }
+
+          const attrs = [`cmd="${trigger}"`];
+
+          // Add handler attributes
+          // If workflow-install exists, use its value for workflow attribute (vendoring)
+          // workflow-install is build-time metadata - tells installer where to copy workflows
+          // The final XML should only have workflow pointing to the install location
+          if (item['workflow-install']) {
+            attrs.push(`workflow="${item['workflow-install']}"`);
+          } else if (item.workflow) {
+            attrs.push(`workflow="${item.workflow}"`);
+          }
 
-        if (item['validate-workflow']) attrs.push(`validate-workflow="${item['validate-workflow']}"`);
-        if (item.exec) attrs.push(`exec="${item.exec}"`);
-        if (item.tmpl) attrs.push(`tmpl="${item.tmpl}"`);
-        if (item.data) attrs.push(`data="${item.data}"`);
-        if (item.action) attrs.push(`action="${item.action}"`);
+          if (item['validate-workflow']) attrs.push(`validate-workflow="${item['validate-workflow']}"`);
+          if (item.exec) attrs.push(`exec="${item.exec}"`);
+          if (item.tmpl) attrs.push(`tmpl="${item.tmpl}"`);
+          if (item.data) attrs.push(`data="${item.data}"`);
+          if (item.action) attrs.push(`action="${item.action}"`);
 
-        xml += `    <item ${attrs.join(' ')}>${this.escapeXml(item.description || '')}</item>\n`;
+          xml += `    <item ${attrs.join(' ')}>${escapeXml(item.description || '')}</item>\n`;
+        }
       }
     }
 
-    // Always inject *exit last
-    xml += `    <item cmd="*exit">Exit with confirmation</item>\n`;
+    // Always inject dismiss last
+    xml += `    <item cmd="*dismiss">[D] Dismiss Agent</item>\n`;
 
     xml += '  </menu>\n';
 
@@ -357,16 +396,91 @@ class YamlXmlBuilder {
   }
 
   /**
-   * Escape XML special characters
+   * Build nested handlers for multi format menu items
+   * @param {Array} triggers - Triggers array from multi format
+   * @returns {string} Handler XML
    */
-  escapeXml(text) {
-    if (!text) return '';
-    return text
-      .replaceAll('&', '&amp;')
-      .replaceAll('<', '&lt;')
-      .replaceAll('>', '&gt;')
-      .replaceAll('"', '&quot;')
-      .replaceAll("'", '&apos;');
+  buildNestedHandlers(triggers) {
+    let xml = '';
+
+    for (const triggerGroup of triggers) {
+      for (const [triggerName, execArray] of Object.entries(triggerGroup)) {
+        // Build trigger with * prefix
+        let trigger = triggerName.startsWith('*') ? triggerName : '*' + triggerName;
+
+        // Extract the relevant execution data
+        const execData = this.processExecArray(execArray);
+
+        // For nested handlers in multi items, we don't need cmd attribute
+        // The match attribute will handle fuzzy matching
+        const attrs = [`match="${escapeXml(execData.description || '')}"`];
+
+        // Add handler attributes based on exec data
+        if (execData.route) attrs.push(`exec="${execData.route}"`);
+        if (execData.workflow) attrs.push(`workflow="${execData.workflow}"`);
+        if (execData['validate-workflow']) attrs.push(`validate-workflow="${execData['validate-workflow']}"`);
+        if (execData.action) attrs.push(`action="${execData.action}"`);
+        if (execData.data) attrs.push(`data="${execData.data}"`);
+        if (execData.tmpl) attrs.push(`tmpl="${execData.tmpl}"`);
+        // Only add type if it's not 'exec' (exec is already implied by the exec attribute)
+        if (execData.type && execData.type !== 'exec') attrs.push(`type="${execData.type}"`);
+
+        xml += `      <handler ${attrs.join(' ')}></handler>\n`;
+      }
+    }
+
+    return xml;
+  }
+
+  /**
+   * Process the execution array from multi format triggers
+   * Extracts relevant data for XML attributes
+   * @param {Array} execArray - Array of execution objects
+   * @returns {Object} Processed execution data
+   */
+  processExecArray(execArray) {
+    const result = {
+      description: '',
+      route: null,
+      workflow: null,
+      data: null,
+      action: null,
+      type: null,
+    };
+
+    if (!Array.isArray(execArray)) {
+      return result;
+    }
+
+    for (const exec of execArray) {
+      if (exec.input) {
+        // Use input as description if no explicit description is provided
+        result.description = exec.input;
+      }
+
+      if (exec.route) {
+        // Determine if it's a workflow or exec based on file extension or context
+        if (exec.route.endsWith('.yaml') || exec.route.endsWith('.yml')) {
+          result.workflow = exec.route;
+        } else {
+          result.route = exec.route;
+        }
+      }
+
+      if (exec.data !== null && exec.data !== undefined) {
+        result.data = exec.data;
+      }
+
+      if (exec.action) {
+        result.action = exec.action;
+      }
+
+      if (exec.type) {
+        result.type = exec.type;
+      }
+    }
+
+    return result;
   }
 
   /**
@@ -398,12 +512,14 @@ class YamlXmlBuilder {
 
     // Extract module from path (e.g., /path/to/modules/bmm/agents/pm.yaml -> bmm)
     // or /path/to/bmad/bmm/agents/pm.yaml -> bmm
+    // or /path/to/src/bmm/agents/pm.yaml -> bmm
     let module = 'core'; // default to core
     const pathParts = agentYamlPath.split(path.sep);
 
     // Look for module indicators in the path
     const modulesIndex = pathParts.indexOf('modules');
     const bmadIndex = pathParts.indexOf('bmad');
+    const srcIndex = pathParts.indexOf('src');
 
     if (modulesIndex !== -1 && pathParts[modulesIndex + 1]) {
       // Path contains /modules/{module}/
@@ -411,10 +527,16 @@ class YamlXmlBuilder {
     } else if (bmadIndex !== -1 && pathParts[bmadIndex + 1]) {
       // Path contains /bmad/{module}/
       const potentialModule = pathParts[bmadIndex + 1];
-      // Check if it's a known module, not 'agents' or '_cfg'
+      // Check if it's a known module, not 'agents' or '_config'
       if (['bmm', 'bmb', 'cis', 'core'].includes(potentialModule)) {
         module = potentialModule;
       }
+    } else if (srcIndex !== -1 && pathParts[srcIndex + 1]) {
+      // Path contains /src/{module}/ (bmm and core are directly under src/)
+      const potentialModule = pathParts[srcIndex + 1];
+      if (potentialModule === 'bmm' || potentialModule === 'core') {
+        module = potentialModule;
+      }
     }
 
     // Build metadata

package/tools/docs/_prompt-external-modules-page.md

@@ -0,0 +1,59 @@
+# Prompt: Generate External Modules Reference Page
+
+## Goal
+
+Create a reference documentation page at `docs/reference/modules.md` that lists all official external BMad modules with descriptions and links.
+
+## Source of Truth
+
+Read `tools/cli/external-official-modules.yaml` — this is the authoritative registry of official external modules. Use the module names, codes, npm package names, and repository URLs from this file.
+
+## Research Step
+
+For each module in the registry, visit its GitHub repository (url in the YAML record) 
+and read its README to get:
+- A 1-2 sentence description of what the module does
+- The key agents and workflows it provides (if listed)
+- Any notable features or use cases
+
+## Output Format
+
+Create `docs/reference/modules.md` following the project's Reference Catalog structure (see `docs/_STYLE_GUIDE.md`):
+
+```
+1. Title + Hook
+2. Items (## for each module)
+   - Brief description (one sentence)
+   - **Key Info:** as flat list (code, npm package, GitHub link)
+3. Installation note
+```
+
+## Style
+use @docs/_STYLE_GUIDE.md
+
+## Frontmatter
+
+```yaml
+---
+title: Official Modules
+---
+```
+
+## Content Requirements
+
+- Start with a brief intro explaining that BMad extends through official modules selected during installation
+- For each module include:
+  - `##` header with module name
+  - 1-2 sentence description (sourced from GitHub README, not just the registry's short description)
+  - Key info list: module code, npm package (linked), GitHub repo (linked)
+  - Brief bullet list of what it provides (agents, workflows, key features) — keep to 3-5 bullets
+- Include a `:::tip` admonition about how to install modules (via `npx bmad-method` installer)
+- Mention that community modules and a marketplace are coming
+- Do NOT include built-in modules (core, bmm) — this page is specifically for external/add-on modules
+
+## Existing Pages for Reference
+
+Look at these files to match the tone and style of existing reference docs:
+- `docs/reference/agents.md`
+- `docs/reference/commands.md`
+- `docs/reference/testing.md`

package/tools/docs/fix-refs.md

@@ -0,0 +1,91 @@
+---
+title: Fix Documentation References
+description: Corrects workflow, agent, and command references in BMad documentation
+---
+
+# Fix Documentation References
+
+## Scope
+
+Fix reference patterns ONLY. Do not modify links, formatting, structure, or other content.
+
+## Purpose
+
+Fix incorrect references to workflows, agents, and commands in BMad documentation files.
+
+## Step 1: Establish Target Audience
+
+Before fixing references, determine who the document is for:
+
+| Audience | Indicators | Style |
+|----------|------------|-------|
+| **Newbies** | tutorials/, getting-started, installation/, "What You'll Learn" | Keep "workflow", include platform hints |
+| **Experienced** | reference/, explanation/ | Drop "workflow", no platform hints |
+| **How-To** | how-to/ | **Ask** — depends on the task |
+
+**How-To guides require judgment**: Don't assume experienced. Ask: "Does this task require prior BMad knowledge?" Early-journey tasks (first PRD, first sprint) are newbie docs. Customization and advanced features are experienced.
+
+**If unclear**: Ask the user "Who is the target audience for this document — new users learning BMad, or experienced users who know the system?"
+
+This determines whether helper words like "workflow" and platform hints are helpful context or just noise.
+
+## Reference Patterns to Fix
+
+### Always Wrong
+
+| Pattern | Example | Problem |
+|---------|---------|---------|
+| `*workflow` | `*prd` | Obsolete menu shortcut notation |
+| `/workflow` | `/workflow-init` | Platform-specific slash command |
+| `bmad_bmm_*` | `bmad_bmm_workflow-init` | Internal slash command name, platform-specific |
+
+### Correct Format
+
+Use backticks with plain workflow name:
+- **Wrong**: Run `/workflow-init`
+- **Wrong**: Run `*prd`
+
+**When to say "workflow"**:
+- **Newbie docs** (getting-started): "Run the `prd` workflow" — helps them learn what it is
+- **Other docs**: "Run `prd`" — they already know, so "workflow" is noise
+
+**Platform hint**: Only in newbie docs, and only on the **first** workflow mention:
+- First mention: Run the `help` workflow (`/bmad-help` on most platforms)
+- Subsequent mentions: Run `prd` — no hint, no "workflow" needed after they've seen the pattern
+
+In experienced docs, the hint is always noise — just use the workflow name.
+
+### Workflow Name Changes
+
+| Old Name | New Name | Notes |
+|----------|----------|-------|
+| `workflow-init` | `bmad-help` | DEPRECATED - help system replaces initialization |
+| `workflow-status` | `bmad-help` | DEPRECATED - help system replaces status checking |
+
+### The Help System
+
+The `bmad-help` workflow is the modern replacement for both `workflow-init` and `workflow-status`:
+- **Universal**: Works regardless of workflow state or module
+- **Contextual**: Infers completion from artifacts and conversation
+- **Adaptive**: Guides users through workflows based on phase ordering
+- **Anytime**: Can be run at any point, no pre-initialization needed
+
+Users can run `bmad-help` to get guidance on what to do next. It detects:
+- What workflows have been completed (by checking for output artifacts)
+- What module is active
+- What the next recommended/required step is
+
+## Lessons Learned
+
+1. **Platform-agnostic**: Docs should never include platform-specific invocation patterns (slashes, prefixes)
+2. **Backtick the name**: Use backticks around workflow names: `workflow-name`
+3. **Simple names**: Just the workflow name, no `bmad_bmm_` prefix, no `/` prefix
+
+## Self-Check
+
+Before finishing, verify you ONLY changed reference patterns:
+
+- [ ] Did I change any hyperlinks? **If yes, revert.**
+- [ ] Did I change any formatting (horizontal rules, whitespace, structure)? **If yes, revert.**
+- [ ] Did I remove or add any sections? **If yes, revert.**
+- [ ] Did I modify anything not matching the patterns in "Reference Patterns to Fix"? **If yes, revert.**