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

package/tools/cli/lib/agent/compiler.js

@@ -49,9 +49,10 @@ You must fully embody this agent's persona and follow all activation instruction
  * Build simple activation block for custom agents
  * @param {Array} criticalActions - Agent-specific critical actions
  * @param {Array} menuItems - Menu items to determine which handlers to include
+ * @param {string} deploymentType - 'ide' or 'web' - filters commands based on ide-only/web-only flags
  * @returns {string} Activation XML
  */
-function buildSimpleActivation(criticalActions = [], menuItems = []) {
+function buildSimpleActivation(criticalActions = [], menuItems = [], deploymentType = 'ide') {
   let activation = '<activation critical="MANDATORY">\n';
 
   let stepNum = 1;
@@ -75,13 +76,28 @@ function buildSimpleActivation(criticalActions = [], menuItems = []) {
   activation += `  <step n="${stepNum++}">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user
       to clarify | No match → show "Not recognized"</step>\n`;
 
-  // Detect which handlers are actually used
+  // Filter menu items based on deployment type
+  const filteredMenuItems = menuItems.filter((item) => {
+    // Skip web-only commands for IDE deployment
+    if (deploymentType === 'ide' && item['web-only'] === true) {
+      return false;
+    }
+    // Skip ide-only commands for web deployment
+    if (deploymentType === 'web' && item['ide-only'] === true) {
+      return false;
+    }
+    return true;
+  });
+
+  // Detect which handlers are actually used in the filtered menu
   const usedHandlers = new Set();
-  for (const item of menuItems) {
+  for (const item of filteredMenuItems) {
     if (item.action) usedHandlers.add('action');
     if (item.workflow) usedHandlers.add('workflow');
     if (item.exec) usedHandlers.add('exec');
     if (item.tmpl) usedHandlers.add('tmpl');
+    if (item.data) usedHandlers.add('data');
+    if (item['validate-workflow']) usedHandlers.add('validate-workflow');
   }
 
   // Only include menu-handlers section if handlers are used
@@ -124,6 +140,25 @@ function buildSimpleActivation(criticalActions = [], menuItems = []) {
       </handler>\n`;
     }
 
+    if (usedHandlers.has('data')) {
+      activation += `      <handler type="data">
+        When menu item has: data="path/to/x.json|yaml|yml"
+        Load the file, parse as JSON/YAML, make available as {data} to subsequent operations
+      </handler>\n`;
+    }
+
+    if (usedHandlers.has('validate-workflow')) {
+      activation += `      <handler type="validate-workflow">
+        When menu item has: validate-workflow="path/to/workflow.yaml"
+        1. CRITICAL: Always LOAD {project-root}/{bmad_folder}/core/tasks/validate-workflow.xml
+        2. Read the complete file - this is the CORE OS for validating BMAD workflows
+        3. Pass the workflow.yaml path as 'workflow' parameter to those instructions
+        4. Pass any checklist.md from the workflow location as 'checklist' parameter if available
+        5. Execute validate-workflow.xml instructions precisely following all steps
+        6. Generate validation report with thorough analysis
+      </handler>\n`;
+    }
+
     activation += `    </handlers>
   </menu-handlers>\n`;
   }
@@ -208,42 +243,141 @@ function buildPromptsXml(prompts) {
 
 /**
  * Build menu XML section
+ * Supports both legacy and multi format menu items
+ * Multi items display as a single menu item with nested handlers
  * @param {Array} menuItems - Menu items
  * @returns {string} Menu XML
  */
 function buildMenuXml(menuItems) {
   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
   if (menuItems && menuItems.length > 0) {
     for (const item of menuItems) {
-      let trigger = item.trigger || '';
-      if (!trigger.startsWith('*')) {
-        trigger = '*' + trigger;
+      // 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 += 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 (item.workflow) attrs.push(`workflow="${item.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(' ')}>${escapeXml(item.description || '')}</item>\n`;
+      }
+    }
+  }
+
+  // Always inject dismiss last
+  xml += `    <item cmd="*dismiss">[D] Dismiss Agent</item>\n`;
+
+  xml += '  </menu>\n';
+
+  return xml;
+}
+
+/**
+ * Build nested handlers for multi format menu items
+ * @param {Array} triggers - Triggers array from multi format
+ * @returns {string} Handler XML
+ */
+function 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;
 
-      const attrs = [`cmd="${trigger}"`];
+      // Extract the relevant execution data
+      const execData = processExecArray(execArray);
 
-      // Add handler attributes
-      if (item.workflow) attrs.push(`workflow="${item.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}"`);
+      // For nested handlers in multi items, we use match attribute for fuzzy matching
+      const attrs = [`match="${escapeXml(execData.description || '')}"`];
 
-      xml += `    <item ${attrs.join(' ')}>${escapeXml(item.description || '')}</item>\n`;
+      // 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`;
     }
   }
 
-  // Always inject *exit last
-  xml += `    <item cmd="*exit">Exit with confirmation</item>\n`;
+  return xml;
+}
 
-  xml += '  </menu>\n';
+/**
+ * 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
+ */
+function processExecArray(execArray) {
+  const result = {
+    description: '',
+    route: null,
+    workflow: null,
+    data: null,
+    action: null,
+    type: null,
+  };
 
-  return xml;
+  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;
 }
 
 /**
@@ -275,8 +409,8 @@ function compileToXml(agentYaml, agentName = '', targetPath = '') {
 
   xml += `<agent ${agentAttrs.join(' ')}>\n`;
 
-  // Activation block - pass menu items to determine which handlers to include
-  xml += buildSimpleActivation(agent.critical_actions || [], agent.menu || []);
+  // Activation block - pass menu items and deployment type to determine which handlers to include
+  xml += buildSimpleActivation(agent.critical_actions || [], agent.menu || [], 'ide');
 
   // Persona section
   xml += buildPersonaXml(agent.persona);

package/tools/cli/lib/agent/installer.js

@@ -677,6 +677,12 @@ function extractManifestData(xmlContent, metadata, agentPath, moduleName = 'cust
     return match[1].trim().replaceAll(/\n+/g, ' ').replaceAll(/\s+/g, ' ').trim();
   };
 
+  // Extract attributes from agent tag
+  const extractAgentAttribute = (attr) => {
+    const match = xmlContent.match(new RegExp(`<agent[^>]*\\s${attr}=["']([^"']+)["']`));
+    return match ? match[1] : '';
+  };
+
   const extractPrinciples = () => {
     const match = xmlContent.match(/<principles>([\s\S]*?)<\/principles>/);
     if (!match) return '';
@@ -689,11 +695,15 @@ function extractManifestData(xmlContent, metadata, agentPath, moduleName = 'cust
     return principles;
   };
 
+  // Prioritize XML extraction over metadata for agent persona info
+  const xmlTitle = extractAgentAttribute('title') || extractTag('name');
+  const xmlIcon = extractAgentAttribute('icon');
+
   return {
     name: metadata.id ? path.basename(metadata.id, '.md') : metadata.name.toLowerCase().replaceAll(/\s+/g, '-'),
-    displayName: metadata.name || '',
-    title: metadata.title || '',
-    icon: metadata.icon || '',
+    displayName: xmlTitle || metadata.name || '',
+    title: xmlTitle || metadata.title || '',
+    icon: xmlIcon || metadata.icon || '',
     role: extractTag('role'),
     identity: extractTag('identity'),
     communicationStyle: extractTag('communication_style'),

package/tools/cli/lib/agent-analyzer.js

@@ -29,24 +29,52 @@ class AgentAnalyzer {
       // Track the menu item
       profile.menuItems.push(item);
 
-      // Check for each possible attribute
-      if (item.workflow) {
-        profile.usedAttributes.add('workflow');
-      }
-      if (item['validate-workflow']) {
-        profile.usedAttributes.add('validate-workflow');
-      }
-      if (item.exec) {
-        profile.usedAttributes.add('exec');
-      }
-      if (item.tmpl) {
-        profile.usedAttributes.add('tmpl');
-      }
-      if (item.data) {
-        profile.usedAttributes.add('data');
-      }
-      if (item.action) {
-        profile.usedAttributes.add('action');
+      // Check for multi format items
+      if (item.multi && item.triggers) {
+        profile.usedAttributes.add('multi');
+
+        // Also check attributes in nested handlers
+        for (const triggerGroup of item.triggers) {
+          for (const [triggerName, execArray] of Object.entries(triggerGroup)) {
+            if (Array.isArray(execArray)) {
+              for (const exec of execArray) {
+                if (exec.route) {
+                  // Check if route is a workflow or exec
+                  if (exec.route.endsWith('.yaml') || exec.route.endsWith('.yml')) {
+                    profile.usedAttributes.add('workflow');
+                  } else {
+                    profile.usedAttributes.add('exec');
+                  }
+                }
+                if (exec.workflow) profile.usedAttributes.add('workflow');
+                if (exec.action) profile.usedAttributes.add('action');
+                if (exec.type && ['exec', 'action', 'workflow'].includes(exec.type)) {
+                  profile.usedAttributes.add(exec.type);
+                }
+              }
+            }
+          }
+        }
+      } else {
+        // Check for each possible attribute in legacy items
+        if (item.workflow) {
+          profile.usedAttributes.add('workflow');
+        }
+        if (item['validate-workflow']) {
+          profile.usedAttributes.add('validate-workflow');
+        }
+        if (item.exec) {
+          profile.usedAttributes.add('exec');
+        }
+        if (item.tmpl) {
+          profile.usedAttributes.add('tmpl');
+        }
+        if (item.data) {
+          profile.usedAttributes.add('data');
+        }
+        if (item.action) {
+          profile.usedAttributes.add('action');
+        }
       }
     }
 

package/tools/cli/lib/ui.js

@@ -1,3 +1,23 @@
+/**
+ * File: tools/cli/lib/ui.js
+ *
+ * BMAD Method - Business Model Agile Development Method
+ * Repository: https://github.com/paulpreibisch/BMAD-METHOD
+ *
+ * Copyright (c) 2025 Paul Preibisch
+ * Licensed under the Apache License, Version 2.0
+ *
+ * ---
+ *
+ * @fileoverview Interactive installation prompts and user input collection for BMAD CLI
+ * @context Guides users through installation configuration including core settings, modules, IDEs, and optional AgentVibes TTS
+ * @architecture Facade pattern - presents unified installation flow, delegates to Detector/ConfigCollector/IdeManager for specifics
+ * @dependencies inquirer (prompts), chalk (formatting), detector.js (existing installation detection)
+ * @entrypoints Called by install.js command via ui.promptInstall(), returns complete configuration object
+ * @patterns Progressive disclosure (prompts in order), early IDE selection (Windows compat), AgentVibes auto-detection
+ * @related installer.js (consumes config), AgentVibes#34 (TTS integration), promptAgentVibes()
+ */
+
 const chalk = require('chalk');
 const inquirer = require('inquirer');
 const path = require('node:path');
@@ -99,6 +119,9 @@ class UI {
     const moduleChoices = await this.getModuleChoices(installedModuleIds);
     const selectedModules = await this.selectModules(moduleChoices);
 
+    // Prompt for AgentVibes TTS integration
+    const agentVibesConfig = await this.promptAgentVibes(confirmedDirectory);
+
     // 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);
@@ -114,6 +137,8 @@ class UI {
       ides: toolSelection.ides,
       skipIde: toolSelection.skipIde,
       coreConfig: coreConfig, // Pass collected core config to installer
+      enableAgentVibes: agentVibesConfig.enabled, // AgentVibes TTS integration
+      agentVibesInstalled: agentVibesConfig.alreadyInstalled,
     };
   }
 
@@ -201,15 +226,51 @@ class UI {
 
     CLIUtils.displaySection('Tool Integration', 'Select AI coding assistants and IDEs to configure');
 
-    const answers = await inquirer.prompt([
-      {
-        type: 'checkbox',
-        name: 'ides',
-        message: 'Select tools to configure:',
-        choices: ideChoices,
-        pageSize: 15,
-      },
-    ]);
+    let answers;
+    let userConfirmedNoTools = false;
+
+    // Loop until user selects at least one tool OR explicitly confirms no tools
+    while (!userConfirmedNoTools) {
+      answers = await inquirer.prompt([
+        {
+          type: 'checkbox',
+          name: 'ides',
+          message: 'Select tools to configure:',
+          choices: ideChoices,
+          pageSize: 15,
+        },
+      ]);
+
+      // If tools were selected, we're done
+      if (answers.ides && answers.ides.length > 0) {
+        break;
+      }
+
+      // Warn that no tools were selected - users often miss the spacebar requirement
+      console.log();
+      console.log(chalk.red.bold('⚠️  WARNING: No tools were selected!'));
+      console.log(chalk.red('   You must press SPACEBAR to select items, then ENTER to confirm.'));
+      console.log(chalk.red('   Simply highlighting an item does NOT select it.'));
+      console.log();
+
+      const { goBack } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'goBack',
+          message: chalk.yellow('Would you like to go back and select at least one tool?'),
+          default: true,
+        },
+      ]);
+
+      if (goBack) {
+        // Re-display the section header before looping back
+        console.log();
+        CLIUtils.displaySection('Tool Integration', 'Select AI coding assistants and IDEs to configure');
+      } else {
+        // User explicitly chose to proceed without tools
+        userConfirmedNoTools = true;
+      }
+    }
 
     return {
       ides: answers.ides || [],
@@ -603,6 +664,140 @@ class UI {
     // Resolve to the absolute path relative to the current working directory
     return path.resolve(expanded);
   }
+
+  /**
+   * @function promptAgentVibes
+   * @intent Ask user if they want AgentVibes TTS integration during BMAD installation
+   * @why Enables optional voice features without forcing TTS on users who don't want it
+   * @param {string} projectDir - Absolute path to user's project directory
+   * @returns {Promise<Object>} Configuration object: { enabled: boolean, alreadyInstalled: boolean }
+   * @sideeffects None - pure user input collection, no files written
+   * @edgecases Shows warning if user enables TTS but AgentVibes not detected
+   * @calledby promptInstall() during installation flow, after core config, before IDE selection
+   * @calls checkAgentVibesInstalled(), inquirer.prompt(), chalk.green/yellow/dim()
+   *
+   * AI NOTE: This prompt is strategically positioned in installation flow:
+   * - AFTER core config (bmad_folder, user_name, etc)
+   * - BEFORE IDE selection (which can hang on Windows/PowerShell)
+   *
+   * Flow Logic:
+   * 1. Auto-detect if AgentVibes already installed (checks for hook files)
+   * 2. Show detection status to user (green checkmark or gray "not detected")
+   * 3. Prompt: "Enable AgentVibes TTS?" (defaults to true if detected)
+   * 4. If user says YES but AgentVibes NOT installed:
+   *    → Show warning with installation link (graceful degradation)
+   * 5. Return config to promptInstall(), which passes to installer.install()
+   *
+   * State Flow:
+   * promptAgentVibes() → { enabled, alreadyInstalled }
+   *                    ↓
+   * promptInstall() → config.enableAgentVibes
+   *                    ↓
+   * installer.install() → this.enableAgentVibes
+   *                    ↓
+   * processTTSInjectionPoints() → injects OR strips markers
+   *
+   * RELATED:
+   * ========
+   * - Detection: checkAgentVibesInstalled() - looks for bmad-speak.sh and play-tts.sh
+   * - Processing: installer.js::processTTSInjectionPoints()
+   * - Markers: src/core/workflows/party-mode/instructions.md:101, src/modules/bmm/agents/*.md
+   * - GitHub Issue: paulpreibisch/AgentVibes#36
+   */
+  async promptAgentVibes(projectDir) {
+    CLIUtils.displaySection('🎤 Voice Features', 'Enable TTS for multi-agent conversations');
+
+    // Check if AgentVibes is already installed
+    const agentVibesInstalled = await this.checkAgentVibesInstalled(projectDir);
+
+    if (agentVibesInstalled) {
+      console.log(chalk.green('  ✓ AgentVibes detected'));
+    } else {
+      console.log(chalk.dim('  AgentVibes not detected'));
+    }
+
+    const answers = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'enableTts',
+        message: 'Enable Agents to Speak Out loud (powered by Agent Vibes? Claude Code only currently)',
+        default: false, // Default to yes - recommended for best experience
+      },
+    ]);
+
+    if (answers.enableTts && !agentVibesInstalled) {
+      console.log(chalk.yellow('\n  ⚠️  AgentVibes not installed'));
+      console.log(chalk.dim('  Install AgentVibes separately to enable TTS:'));
+      console.log(chalk.dim('  https://github.com/paulpreibisch/AgentVibes\n'));
+    }
+
+    return {
+      enabled: answers.enableTts,
+      alreadyInstalled: agentVibesInstalled,
+    };
+  }
+
+  /**
+   * @function checkAgentVibesInstalled
+   * @intent Detect if AgentVibes TTS hooks are present in user's project
+   * @why Allows auto-enabling TTS and showing helpful installation guidance
+   * @param {string} projectDir - Absolute path to user's project directory
+   * @returns {Promise<boolean>} true if both required AgentVibes hooks exist, false otherwise
+   * @sideeffects None - read-only file existence checks
+   * @edgecases Returns false if either hook missing (both required for functional TTS)
+   * @calledby promptAgentVibes() to determine default value and show detection status
+   * @calls fs.pathExists() twice (bmad-speak.sh, play-tts.sh)
+   *
+   * AI NOTE: This checks for the MINIMUM viable AgentVibes installation.
+   *
+   * Required Files:
+   * ===============
+   * 1. .claude/hooks/bmad-speak.sh
+   *    - Maps agent display names → agent IDs → voice profiles
+   *    - Calls play-tts.sh with agent's assigned voice
+   *    - Created by AgentVibes installer
+   *
+   * 2. .claude/hooks/play-tts.sh
+   *    - Core TTS router (ElevenLabs or Piper)
+   *    - Provider-agnostic interface
+   *    - Required by bmad-speak.sh
+   *
+   * Why Both Required:
+   * ==================
+   * - bmad-speak.sh alone: No TTS backend
+   * - play-tts.sh alone: No BMAD agent voice mapping
+   * - Both together: Full party mode TTS integration
+   *
+   * Detection Strategy:
+   * ===================
+   * We use simple file existence (not version checks) because:
+   * - Fast and reliable
+   * - Works across all AgentVibes versions
+   * - User will discover version issues when TTS runs (fail-fast)
+   *
+   * PATTERN: Adding New Detection Criteria
+   * =======================================
+   * If future AgentVibes features require additional files:
+   * 1. Add new pathExists check to this function
+   * 2. Update documentation in promptAgentVibes()
+   * 3. Consider: should missing file prevent detection or just log warning?
+   *
+   * RELATED:
+   * ========
+   * - AgentVibes Installer: creates these hooks
+   * - bmad-speak.sh: calls play-tts.sh with agent voices
+   * - Party Mode: uses bmad-speak.sh for agent dialogue
+   */
+  async checkAgentVibesInstalled(projectDir) {
+    const fs = require('fs-extra');
+    const path = require('node:path');
+
+    // Check for AgentVibes hook files
+    const hookPath = path.join(projectDir, '.claude', 'hooks', 'bmad-speak.sh');
+    const playTtsPath = path.join(projectDir, '.claude', 'hooks', 'play-tts.sh');
+
+    return (await fs.pathExists(hookPath)) && (await fs.pathExists(playTtsPath));
+  }
 }
 
 module.exports = { UI };