bmad-method 6.0.0-alpha.1 → 6.0.0-alpha.11

package/tools/cli/lib/agent/template-engine.js

@@ -0,0 +1,152 @@
+/**
+ * Template Engine for BMAD Agent Install Configuration
+ * Processes {{variable}}, {{#if}}, {{#unless}}, and {{/if}} blocks
+ */
+
+/**
+ * Process all template syntax in a string
+ * @param {string} content - Content with template syntax
+ * @param {Object} variables - Key-value pairs from install_config answers
+ * @returns {string} Processed content
+ */
+function processTemplate(content, variables = {}) {
+  let result = content;
+
+  // Process conditionals first (they may contain variables)
+  result = processConditionals(result, variables);
+
+  // Then process simple variable replacements
+  result = processVariables(result, variables);
+
+  // Clean up any empty lines left by removed conditionals
+  result = cleanupEmptyLines(result);
+
+  return result;
+}
+
+/**
+ * Process {{#if}}, {{#unless}}, {{/if}}, {{/unless}} blocks
+ */
+function processConditionals(content, variables) {
+  let result = content;
+
+  // Process {{#if variable == "value"}} blocks
+  // Handle both regular quotes and JSON-escaped quotes (\")
+  const ifEqualsPattern = /\{\{#if\s+(\w+)\s*==\s*\\?"([^"\\]+)\\?"\s*\}\}([\s\S]*?)\{\{\/if\}\}/g;
+  result = result.replaceAll(ifEqualsPattern, (match, varName, value, block) => {
+    return variables[varName] === value ? block : '';
+  });
+
+  // Process {{#if variable}} blocks (boolean or truthy check)
+  const ifBoolPattern = /\{\{#if\s+(\w+)\s*\}\}([\s\S]*?)\{\{\/if\}\}/g;
+  result = result.replaceAll(ifBoolPattern, (match, varName, block) => {
+    const val = variables[varName];
+    // Treat as truthy: true, non-empty string, non-zero number
+    const isTruthy = val === true || (typeof val === 'string' && val.length > 0) || (typeof val === 'number' && val !== 0);
+    return isTruthy ? block : '';
+  });
+
+  // Process {{#unless variable}} blocks (inverse of if)
+  const unlessPattern = /\{\{#unless\s+(\w+)\s*\}\}([\s\S]*?)\{\{\/unless\}\}/g;
+  result = result.replaceAll(unlessPattern, (match, varName, block) => {
+    const val = variables[varName];
+    const isFalsy = val === false || val === '' || val === null || val === undefined || val === 0;
+    return isFalsy ? block : '';
+  });
+
+  return result;
+}
+
+/**
+ * Process {{variable}} replacements
+ */
+function processVariables(content, variables) {
+  let result = content;
+
+  // Replace {{variable}} with value
+  const varPattern = /\{\{(\w+)\}\}/g;
+  result = result.replaceAll(varPattern, (match, varName) => {
+    if (Object.hasOwn(variables, varName)) {
+      return String(variables[varName]);
+    }
+    // If variable not found, leave as-is (might be runtime variable like {user_name})
+    return match;
+  });
+
+  return result;
+}
+
+/**
+ * Clean up excessive empty lines left after removing conditional blocks
+ */
+function cleanupEmptyLines(content) {
+  // Replace 3+ consecutive newlines with 2
+  return content.replaceAll(/\n{3,}/g, '\n\n');
+}
+
+/**
+ * Extract install_config from agent YAML object
+ * @param {Object} agentYaml - Parsed agent YAML
+ * @returns {Object|null} install_config section or null
+ */
+function extractInstallConfig(agentYaml) {
+  return agentYaml?.agent?.install_config || null;
+}
+
+/**
+ * Remove install_config from agent YAML (after processing)
+ * @param {Object} agentYaml - Parsed agent YAML
+ * @returns {Object} Agent YAML without install_config
+ */
+function stripInstallConfig(agentYaml) {
+  const result = structuredClone(agentYaml);
+  if (result.agent) {
+    delete result.agent.install_config;
+  }
+  return result;
+}
+
+/**
+ * Process entire agent YAML object with template variables
+ * @param {Object} agentYaml - Parsed agent YAML
+ * @param {Object} variables - Answers from install_config questions
+ * @returns {Object} Processed agent YAML
+ */
+function processAgentYaml(agentYaml, variables) {
+  // Convert to JSON string, process templates, parse back
+  const jsonString = JSON.stringify(agentYaml, null, 2);
+  const processed = processTemplate(jsonString, variables);
+  return JSON.parse(processed);
+}
+
+/**
+ * Get default values from install_config questions
+ * @param {Object} installConfig - install_config section
+ * @returns {Object} Default values keyed by variable name
+ */
+function getDefaultValues(installConfig) {
+  const defaults = {};
+
+  if (!installConfig?.questions) {
+    return defaults;
+  }
+
+  for (const question of installConfig.questions) {
+    if (question.var && question.default !== undefined) {
+      defaults[question.var] = question.default;
+    }
+  }
+
+  return defaults;
+}
+
+module.exports = {
+  processTemplate,
+  processConditionals,
+  processVariables,
+  extractInstallConfig,
+  stripInstallConfig,
+  processAgentYaml,
+  getDefaultValues,
+  cleanupEmptyLines,
+};

package/tools/cli/lib/cli-utils.js

@@ -2,13 +2,31 @@ const chalk = require('chalk');
 const boxen = require('boxen');
 const wrapAnsi = require('wrap-ansi');
 const figlet = require('figlet');
+const path = require('node:path');
 
 const CLIUtils = {
+  /**
+   * Get version from package.json
+   */
+  getVersion() {
+    try {
+      const packageJson = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+      return packageJson.version || 'Unknown';
+    } catch {
+      return 'Unknown';
+    }
+  },
+
   /**
    * Display BMAD logo
+   * @param {boolean} clearScreen - Whether to clear the screen first (default: true for initial display only)
    */
-  displayLogo() {
-    console.clear();
+  displayLogo(clearScreen = true) {
+    if (clearScreen) {
+      console.clear();
+    }
+
+    const version = this.getVersion();
 
     // ASCII art logo
     const logo = `
@@ -20,7 +38,7 @@ const CLIUtils = {
     ╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝╚═════╝`;
 
     console.log(chalk.cyan(logo));
-    console.log(chalk.dim('    Build More, Architect Dreams\n'));
+    console.log(chalk.dim(`    Build More, Architect Dreams`) + chalk.cyan.bold(` v${version}`) + '\n');
   },
 
   /**
@@ -64,18 +82,35 @@ const CLIUtils = {
   },
 
   /**
-   * Display prompt section
-   * @param {string|Array} prompts - Prompts to display
+   * Display module configuration header
+   * @param {string} moduleName - Module name (fallback if no custom header)
+   * @param {string} header - Custom header from install-config.yaml
+   * @param {string} subheader - Custom subheader from install-config.yaml
    */
-  displayPromptSection(prompts) {
-    const promptArray = Array.isArray(prompts) ? prompts : [prompts];
-
-    const formattedPrompts = promptArray.map((p) => wrapAnsi(p, 76, { hard: true, wordWrap: true }));
+  displayModuleConfigHeader(moduleName, header = null, subheader = null) {
+    // Simple blue banner with custom header/subheader if provided
+    console.log('\n' + chalk.cyan('─'.repeat(80)));
+    console.log(chalk.cyan(header || `Configuring ${moduleName.toUpperCase()} Module`));
+    if (subheader) {
+      console.log(chalk.dim(`${subheader}`));
+    }
+    console.log(chalk.cyan('─'.repeat(80)) + '\n');
+  },
 
-    this.displayBox(formattedPrompts, {
-      borderColor: 'yellow',
-      borderStyle: 'double',
-    });
+  /**
+   * Display module with no custom configuration
+   * @param {string} moduleName - Module name (fallback if no custom header)
+   * @param {string} header - Custom header from install-config.yaml
+   * @param {string} subheader - Custom subheader from install-config.yaml
+   */
+  displayModuleNoConfig(moduleName, header = null, subheader = null) {
+    // Show full banner with header/subheader, just like modules with config
+    console.log('\n' + chalk.cyan('─'.repeat(80)));
+    console.log(chalk.cyan(header || `${moduleName.toUpperCase()} Module - No Custom Configuration`));
+    if (subheader) {
+      console.log(chalk.dim(`${subheader}`));
+    }
+    console.log(chalk.cyan('─'.repeat(80)) + '\n');
   },
 
   /**
@@ -164,44 +199,11 @@ const CLIUtils = {
   /**
    * Display module completion message
    * @param {string} moduleName - Name of the completed module
-   * @param {boolean} clearScreen - Whether to clear the screen first
+   * @param {boolean} clearScreen - Whether to clear the screen first (deprecated, always false now)
    */
-  displayModuleComplete(moduleName, clearScreen = true) {
-    if (clearScreen) {
-      console.clear();
-      this.displayLogo();
-    }
-
-    let message;
-
-    // Special messages for specific modules
-    if (moduleName.toLowerCase() === 'bmm') {
-      message = `Thank you for configuring the BMAD™ Method Module (BMM)!
-
-Your responses have been saved and will be used to configure your installation.`;
-    } else if (moduleName.toLowerCase() === 'cis') {
-      message = `Thank you for choosing the BMAD™ Creative Innovation Suite, an early beta
-release with much more planned!
-
-With this BMAD™ Creative Innovation Suite Configuration, remember that all
-paths are relative to project root, with no leading slash.`;
-    } else if (moduleName.toLowerCase() === 'core') {
-      message = `Thank you for choosing the BMAD™ Method, your gateway to dreaming, planning
-and building with real world proven techniques.
-
-All paths are relative to project root, with no leading slash.`;
-    } else {
-      message = `Thank you for configuring the BMAD™ ${moduleName.toUpperCase()} module!
-
-Your responses have been saved and will be used to configure your installation.`;
-    }
-
-    this.displayBox(message, {
-      borderColor: 'yellow',
-      borderStyle: 'double',
-      padding: 1,
-      margin: 1,
-    });
+  displayModuleComplete(moduleName, clearScreen = false) {
+    // No longer clear screen or show boxes - just a simple completion message
+    // This is deprecated but kept for backwards compatibility
   },
 };
 

package/tools/cli/lib/config.js

@@ -33,7 +33,9 @@ class Config {
     });
 
     await fs.ensureDir(path.dirname(configPath));
-    await fs.writeFile(configPath, yamlContent, 'utf8');
+    // Ensure POSIX-compliant final newline
+    const content = yamlContent.endsWith('\n') ? yamlContent : yamlContent + '\n';
+    await fs.writeFile(configPath, content, 'utf8');
   }
 
   /**

package/tools/cli/lib/ui.js

@@ -17,14 +17,26 @@ class UI {
    */
   async promptInstall() {
     CLIUtils.displayLogo();
-    CLIUtils.displaySection('BMAD™ Setup', 'Build More, Architect Dreams');
+    const version = CLIUtils.getVersion();
+    CLIUtils.displaySection('BMAD™ Setup', `Build More, Architect Dreams v${version}`);
 
     const confirmedDirectory = await this.getConfirmedDirectory();
 
+    // Preflight: Check for legacy BMAD v4 footprints immediately after getting directory
+    const { Detector } = require('../installers/lib/core/detector');
+    const { Installer } = require('../installers/lib/core/installer');
+    const detector = new Detector();
+    const installer = new Installer();
+    const legacyV4 = await detector.detectLegacyV4(confirmedDirectory);
+    if (legacyV4.hasLegacyV4) {
+      await installer.handleLegacyV4Migration(confirmedDirectory, legacyV4);
+    }
+
     // Check if there's an existing BMAD installation
     const fs = require('fs-extra');
     const path = require('node:path');
-    const bmadDir = path.join(confirmedDirectory, 'bmad');
+    // Use findBmadDir to detect any custom folder names (V6+)
+    const bmadDir = await installer.findBmadDir(confirmedDirectory);
     const hasExistingInstall = await fs.pathExists(bmadDir);
 
     // Track action type (only set if there's an existing installation)
@@ -82,25 +94,23 @@ class UI {
       // If actionType === 'update' or 'reinstall', continue with normal flow below
     }
 
-    // Collect IDE tool selection EARLY (before module configuration)
-    // This allows users to make all decisions upfront before file copying begins
-    const toolSelection = await this.promptToolSelection(confirmedDirectory, []);
-
     const { installedModuleIds } = await this.getExistingInstallation(confirmedDirectory);
     const coreConfig = await this.collectCoreConfig(confirmedDirectory);
     const moduleChoices = await this.getModuleChoices(installedModuleIds);
     const selectedModules = await this.selectModules(moduleChoices);
 
-    console.clear();
-    CLIUtils.displayLogo();
-    CLIUtils.displayModuleComplete('core', false); // false = don't clear the screen again
+    // Collect IDE tool selection AFTER configuration prompts (fixes Windows/PowerShell hang)
+    // This allows text-based prompts to complete before the checkbox prompt
+    const toolSelection = await this.promptToolSelection(confirmedDirectory, selectedModules);
+
+    // No more screen clearing - keep output flowing
 
     return {
       actionType: actionType || 'update', // Preserve reinstall or update action
       directory: confirmedDirectory,
       installCore: true, // Always install core
       modules: selectedModules,
-      // IDE selection collected early, will be configured later
+      // IDE selection collected after config, will be configured later
       ides: toolSelection.ides,
       skipIde: toolSelection.skipIde,
       coreConfig: coreConfig, // Pass collected core config to installer
@@ -114,10 +124,12 @@ class UI {
    * @returns {Object} Tool configuration
    */
   async promptToolSelection(projectDir, selectedModules) {
-    // Check for existing configured IDEs
+    // Check for existing configured IDEs - use findBmadDir to detect custom folder names
     const { Detector } = require('../installers/lib/core/detector');
+    const { Installer } = require('../installers/lib/core/installer');
     const detector = new Detector();
-    const bmadDir = path.join(projectDir || process.cwd(), 'bmad');
+    const installer = new Installer();
+    const bmadDir = await installer.findBmadDir(projectDir || process.cwd());
     const existingInstall = await detector.detect(bmadDir);
     const configuredIdes = existingInstall.ides || [];
 
@@ -322,8 +334,10 @@ class UI {
    */
   async getExistingInstallation(directory) {
     const { Detector } = require('../installers/lib/core/detector');
+    const { Installer } = require('../installers/lib/core/installer');
     const detector = new Detector();
-    const bmadDir = path.join(directory, 'bmad');
+    const installer = new Installer();
+    const bmadDir = await installer.findBmadDir(directory);
     const existingInstall = await detector.detect(bmadDir);
     const installedModuleIds = new Set(existingInstall.modules.map((mod) => mod.id));
 
@@ -421,17 +435,20 @@ class UI {
       if (stats.isDirectory()) {
         const files = await fs.readdir(directory);
         if (files.length > 0) {
+          // Check for any bmad installation (any folder with _cfg/manifest.yaml)
+          const { Installer } = require('../installers/lib/core/installer');
+          const installer = new Installer();
+          const bmadDir = await installer.findBmadDir(directory);
+          const hasBmadInstall = (await fs.pathExists(bmadDir)) && (await fs.pathExists(path.join(bmadDir, '_cfg', 'manifest.yaml')));
+
           console.log(
             chalk.gray(`Directory exists and contains ${files.length} item(s)`) +
-              (files.includes('bmad') ? chalk.yellow(' including existing bmad installation') : ''),
+              (hasBmadInstall ? chalk.yellow(` including existing BMAD installation (${path.basename(bmadDir)})`) : ''),
           );
         } else {
           console.log(chalk.gray('Directory exists and is empty'));
         }
       }
-    } else {
-      const existingParent = await this.findExistingParent(directory);
-      console.log(chalk.gray(`Will create in: ${existingParent}`));
     }
   }
 

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

@@ -203,6 +203,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

@@ -64,7 +64,8 @@ async function formatYamlContent(content, filename) {
       noRefs: true,
       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`));

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

@@ -119,6 +119,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 +212,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 +224,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';
@@ -268,19 +283,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>${this.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 += `${this.escapeXml(prompt.content || '')}\n`;
+      xml += `      </content>\n`;
       xml += `    </prompt>\n`;
     }
 
@@ -292,8 +342,10 @@ class YamlXmlBuilder {
   /**
    * Build menu XML section (renamed from commands for clarity)
    * Auto-injects *help and *exit, adds * prefix to all triggers
+   * @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
@@ -302,6 +354,14 @@ class YamlXmlBuilder {
     // Add user-defined menu items with * prefix
     if (menuItems && menuItems.length > 0) {
       for (const item of menuItems) {
+        // 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;
+        }
         // Build command attributes - add * prefix if not present
         let trigger = item.trigger || '';
         if (!trigger.startsWith('*')) {
@@ -311,7 +371,15 @@ class YamlXmlBuilder {
         const attrs = [`cmd="${trigger}"`];
 
         // Add handler attributes
-        if (item.workflow) attrs.push(`workflow="${item.workflow}"`);
+        // 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}"`);

package/tools/schema/agent.js

@@ -88,6 +88,7 @@ function buildAgentSchema(expectedModule) {
       critical_actions: z.array(createNonEmptyString('agent.critical_actions[]')).optional(),
       menu: z.array(buildMenuItemSchema()).min(1, { message: 'agent.menu must include at least one entry' }),
       prompts: z.array(buildPromptSchema()).optional(),
+      webskip: z.boolean().optional(),
     })
     .strict();
 }
@@ -142,9 +143,12 @@ function buildPersonaSchema() {
       role: createNonEmptyString('agent.persona.role'),
       identity: createNonEmptyString('agent.persona.identity'),
       communication_style: createNonEmptyString('agent.persona.communication_style'),
-      principles: z
-        .array(createNonEmptyString('agent.persona.principles[]'))
-        .min(1, { message: 'agent.persona.principles must include at least one entry' }),
+      principles: z.union([
+        createNonEmptyString('agent.persona.principles'),
+        z
+          .array(createNonEmptyString('agent.persona.principles[]'))
+          .min(1, { message: 'agent.persona.principles must include at least one entry' }),
+      ]),
     })
     .strict();
 }
@@ -170,12 +174,17 @@ function buildMenuItemSchema() {
       trigger: createNonEmptyString('agent.menu[].trigger'),
       description: createNonEmptyString('agent.menu[].description'),
       workflow: createNonEmptyString('agent.menu[].workflow').optional(),
+      'workflow-install': createNonEmptyString('agent.menu[].workflow-install').optional(),
       'validate-workflow': createNonEmptyString('agent.menu[].validate-workflow').optional(),
       exec: createNonEmptyString('agent.menu[].exec').optional(),
       action: createNonEmptyString('agent.menu[].action').optional(),
       tmpl: createNonEmptyString('agent.menu[].tmpl').optional(),
       data: createNonEmptyString('agent.menu[].data').optional(),
       'run-workflow': createNonEmptyString('agent.menu[].run-workflow').optional(),
+      checklist: createNonEmptyString('agent.menu[].checklist').optional(),
+      document: createNonEmptyString('agent.menu[].document').optional(),
+      'ide-only': z.boolean().optional(),
+      'web-only': z.boolean().optional(),
     })
     .strict()
     .superRefine((value, ctx) => {