bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.20

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,14 +57,14 @@ 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
     });
-    return formatted;
+    // Ensure POSIX-compliant final newline
+    return formatted.endsWith('\n') ? formatted : formatted + '\n';
   } catch (error) {
     console.error(chalk.red(`❌ YAML syntax error in ${filename}:`), error.message);
     console.error(chalk.yellow(`💡 Try manually fixing the YAML structure first`));
@@ -95,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,19 +269,54 @@ 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
    */
   buildPromptsXml(prompts) {
-    if (!prompts || prompts.length === 0) return '';
+    if (!prompts) return '';
+
+    // Handle object/dictionary format: { promptId: 'content', ... }
+    // Convert to array format for processing
+    let promptsArray = prompts;
+    if (!Array.isArray(prompts)) {
+      // Check if it's an object with no length property (dictionary format)
+      if (typeof prompts === 'object' && prompts.length === undefined) {
+        promptsArray = Object.entries(prompts).map(([id, content]) => ({
+          id: id,
+          content: content,
+        }));
+      } else {
+        return ''; // Not a valid prompts format
+      }
+    }
+
+    if (promptsArray.length === 0) return '';
 
     let xml = '  <prompts>\n';
 
-    for (const prompt of prompts) {
+    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`;
     }
 
@@ -292,38 +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;
+        }
+
+        // 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}"`];
 
-        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}"`);
+          }
 
-        // Add handler attributes
-        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';
 
@@ -331,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
+   */
+  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
    */
-  escapeXml(text) {
-    if (!text) return '';
-    return text
-      .replaceAll('&', '&amp;')
-      .replaceAll('<', '&lt;')
-      .replaceAll('>', '&gt;')
-      .replaceAll('"', '&quot;')
-      .replaceAll("'", '&apos;');
+  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;
   }
 
   /**
@@ -385,7 +525,7 @@ 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;
       }

package/tools/flattener/ignoreRules.js

@@ -6,7 +6,7 @@ const ignore = require('ignore');
 // These complement .gitignore and are applied regardless of VCS presence.
 const DEFAULT_PATTERNS = [
   // Project/VCS
-  '**/.bmad-method/**',
+  '**/_bmad/**',
   '**/.git/**',
   '**/.svn/**',
   '**/.hg/**',

package/tools/flattener/xml.js

@@ -1,11 +1,5 @@
 const fs = require('fs-extra');
-
-function escapeXml(string_) {
-  if (typeof string_ !== 'string') {
-    return String(string_);
-  }
-  return string_.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll("'", '&apos;');
-}
+const { escapeXml } = require('../lib/xml-utils');
 
 function indentFileContent(content) {
   if (typeof content !== 'string') {

package/tools/lib/xml-utils.js

@@ -0,0 +1,13 @@
+/**
+ * Escape XML special characters in a string
+ * @param {string} text - The text to escape
+ * @returns {string} The escaped text
+ */
+function escapeXml(text) {
+  if (!text) return '';
+  return text.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+}
+
+module.exports = {
+  escapeXml,
+};

package/tools/maintainer/review-pr-README.md

@@ -0,0 +1,55 @@
+# Raven's Verdict - Deep PR Review Tool
+
+Adversarial code review for GitHub PRs. Works with any LLM agent.
+
+> **Status: Experimental.** We're still figuring out how to use this effectively. Expect the workflow to evolve.
+
+## How It Works
+
+Point your agent at `review-pr.md` and ask it to review a specific PR:
+
+> "Read tools/maintainer/review-pr.md and apply it to PR #123"
+
+The tool will:
+
+1. Check out the PR branch locally
+2. Run an adversarial review (find at least 5 issues)
+3. Transform findings into professional tone
+4. Preview the review and ask before posting
+
+See `review-pr.md` for full prompt structure, severity ratings, and sandboxing rules.
+
+## When to Use
+
+**Good candidates:**
+
+- PRs with meaningful logic changes
+- Refactors touching multiple files
+- New features or architectural changes
+
+**Skip it for:**
+
+- Trivial PRs (typo fixes, version bumps, single-line changes)
+- PRs you've already reviewed manually
+- PRs where you haven't agreed on the approach yet — fix the direction before the implementation
+
+## Workflow Tips
+
+**Always review before posting.** The preview step exists for a reason:
+
+- **[y] Yes** — Post as-is (only if you're confident)
+- **[e] Edit** — Modify findings before posting
+- **[s] Save only** — Write to file, don't post
+
+The save option is useful when you want to:
+
+- Hand-edit the review before posting
+- Use the findings as input for a second opinion ("Hey Claude, here's what Raven found — what do you think?")
+- Cherry-pick specific findings
+
+**Trust but verify.** LLM reviews can miss context or flag non-issues. Skim the findings before they hit the PR.
+
+## Prerequisites
+
+- `gh` CLI installed and authenticated (`gh auth status`)
+- Any LLM agent capable of running bash commands