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

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

@@ -438,23 +438,16 @@ function compileToXml(agentYaml, agentName = '', targetPath = '') {
  * @param {Object} answers - Answers from install_config questions (or defaults)
  * @param {string} agentName - Optional final agent name (user's custom persona name)
  * @param {string} targetPath - Optional target path for agent ID
+ * @param {Object} options - Additional options including config
  * @returns {Object} { xml: string, metadata: Object }
  */
-function compileAgent(yamlContent, answers = {}, agentName = '', targetPath = '') {
+function compileAgent(yamlContent, answers = {}, agentName = '', targetPath = '', options = {}) {
   // Parse YAML
   const agentYaml = yaml.parse(yamlContent);
 
-  // Inject custom agent name into metadata.name if provided
-  // This is the user's chosen persona name (e.g., "Fred" instead of "Inkwell Von Comitizen")
-  if (agentName && agentYaml.agent && agentYaml.agent.metadata) {
-    // Convert kebab-case to title case for the name field
-    // e.g., "fred-commit-poet" → "Fred Commit Poet"
-    const titleCaseName = agentName
-      .split('-')
-      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-      .join(' ');
-    agentYaml.agent.metadata.name = titleCaseName;
-  }
+  // Note: agentName parameter is for UI display only, not for modifying the YAML
+  // The persona name (metadata.name) should always come from the YAML file
+  // We should NEVER modify metadata.name as it's part of the agent's identity
 
   // Extract install_config
   const installConfig = extractInstallConfig(agentYaml);
@@ -466,14 +459,22 @@ function compileAgent(yamlContent, answers = {}, agentName = '', targetPath = ''
     finalAnswers = { ...defaults, ...answers };
   }
 
+  // Add agent_sidecar_folder to answers if provided in config
+  if (options.config && options.config.agent_sidecar_folder) {
+    finalAnswers.agent_sidecar_folder = options.config.agent_sidecar_folder;
+  }
+
   // Process templates with answers
   const processedYaml = processAgentYaml(agentYaml, finalAnswers);
 
   // Strip install_config from output
   const cleanYaml = stripInstallConfig(processedYaml);
 
-  // Compile to XML
-  const xml = compileToXml(cleanYaml, agentName, targetPath);
+  // Replace {agent_sidecar_folder} in XML content
+  let xml = compileToXml(cleanYaml, agentName, targetPath);
+  if (finalAnswers.agent_sidecar_folder) {
+    xml = xml.replaceAll('{agent_sidecar_folder}', finalAnswers.agent_sidecar_folder);
+  }
 
   return {
     xml,
@@ -482,10 +483,39 @@ function compileAgent(yamlContent, answers = {}, agentName = '', targetPath = ''
   };
 }
 
+/**
+ * Process TTS injection markers in content
+ * @param {string} content - Content to process
+ * @param {boolean} enableAgentVibes - Whether AgentVibes is enabled
+ * @returns {Object} { content: string, hadInjection: boolean }
+ */
+function processTTSInjectionPoints(content, enableAgentVibes) {
+  const hasAgentTTS = content.includes('<!-- TTS_INJECTION:agent-tts -->');
+
+  if (enableAgentVibes && hasAgentTTS) {
+    // Replace agent-tts injection marker with TTS rule
+    content = content.replaceAll(
+      '<!-- TTS_INJECTION:agent-tts -->',
+      `- When responding to user messages, speak your responses using TTS:
+   Call: \`.claude/hooks/bmad-speak.sh '{agent-id}' '{response-text}'\` after each response
+   Replace {agent-id} with YOUR agent ID from <agent id="..."> tag at top of this file
+   Replace {response-text} with the text you just output to the user
+   IMPORTANT: Use single quotes as shown - do NOT escape special characters like ! or $ inside single quotes
+   Run in background (&) to avoid blocking`,
+    );
+    return { content, hadInjection: true };
+  } else if (!enableAgentVibes && hasAgentTTS) {
+    // Strip injection markers when disabled
+    content = content.replaceAll(/<!-- TTS_INJECTION:agent-tts -->\n?/g, '');
+  }
+
+  return { content, hadInjection: false };
+}
+
 /**
  * Compile agent file to .md
  * @param {string} yamlPath - Path to agent YAML file
- * @param {Object} options - { answers: {}, outputPath: string }
+ * @param {Object} options - { answers: {}, outputPath: string, enableAgentVibes: boolean }
  * @returns {Object} Compilation result
  */
 function compileAgentFile(yamlPath, options = {}) {
@@ -501,13 +531,24 @@ function compileAgentFile(yamlPath, options = {}) {
     outputPath = path.join(dir, `${basename}.md`);
   }
 
+  // Process TTS injection points if enableAgentVibes option is provided
+  let xml = result.xml;
+  let ttsInjected = false;
+  if (options.enableAgentVibes !== undefined) {
+    const ttsResult = processTTSInjectionPoints(xml, options.enableAgentVibes);
+    xml = ttsResult.content;
+    ttsInjected = ttsResult.hadInjection;
+  }
+
   // Write compiled XML
-  fs.writeFileSync(outputPath, result.xml, 'utf8');
+  fs.writeFileSync(outputPath, xml, 'utf8');
 
   return {
     ...result,
+    xml,
     outputPath,
     sourcePath: yamlPath,
+    ttsInjected,
   };
 }
 

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

@@ -46,7 +46,7 @@ function resolvePath(pathStr, context) {
 }
 
 /**
- * Discover available agents in the custom agent location
+ * Discover available agents in the custom agent location recursively
  * @param {string} searchPath - Path to search for agents
  * @returns {Array} List of agent info objects
  */
@@ -56,35 +56,58 @@ function discoverAgents(searchPath) {
   }
 
   const agents = [];
-  const entries = fs.readdirSync(searchPath, { withFileTypes: true });
 
-  for (const entry of entries) {
-    const fullPath = path.join(searchPath, entry.name);
-
-    if (entry.isFile() && entry.name.endsWith('.agent.yaml')) {
-      // Simple agent (single file)
-      agents.push({
-        type: 'simple',
-        name: entry.name.replace('.agent.yaml', ''),
-        path: fullPath,
-        yamlFile: fullPath,
-      });
-    } else if (entry.isDirectory()) {
-      // Check for agent with sidecar (folder containing .agent.yaml)
-      const yamlFiles = fs.readdirSync(fullPath).filter((f) => f.endsWith('.agent.yaml'));
-      if (yamlFiles.length === 1) {
-        const agentYamlPath = path.join(fullPath, yamlFiles[0]);
+  // Helper function to recursively search
+  function searchDirectory(dir, relativePath = '') {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const agentRelativePath = relativePath ? path.join(relativePath, entry.name) : entry.name;
+
+      if (entry.isFile() && entry.name.endsWith('.agent.yaml')) {
+        // Simple agent (single file)
+        // The agent name is based on the filename
+        const agentName = entry.name.replace('.agent.yaml', '');
         agents.push({
-          type: 'expert',
-          name: entry.name,
+          type: 'simple',
+          name: agentName,
           path: fullPath,
-          yamlFile: agentYamlPath,
-          hasSidecar: true,
+          yamlFile: fullPath,
+          relativePath: agentRelativePath.replace('.agent.yaml', ''),
         });
+      } else if (entry.isDirectory()) {
+        // Check if this directory contains an .agent.yaml file
+        try {
+          const dirContents = fs.readdirSync(fullPath);
+          const yamlFiles = dirContents.filter((f) => f.endsWith('.agent.yaml'));
+
+          if (yamlFiles.length > 0) {
+            // Found .agent.yaml files in this directory
+            for (const yamlFile of yamlFiles) {
+              const agentYamlPath = path.join(fullPath, yamlFile);
+              const agentName = path.basename(yamlFile, '.agent.yaml');
+
+              agents.push({
+                type: 'expert',
+                name: agentName,
+                path: fullPath,
+                yamlFile: agentYamlPath,
+                relativePath: agentRelativePath,
+              });
+            }
+          } else {
+            // No .agent.yaml in this directory, recurse deeper
+            searchDirectory(fullPath, agentRelativePath);
+          }
+        } catch {
+          // Skip directories we can't read
+        }
       }
     }
   }
 
+  searchDirectory(searchPath);
   return agents;
 }
 
@@ -103,12 +126,15 @@ function loadAgentConfig(yamlPath) {
   // These take precedence over defaults
   const savedAnswers = agentYaml?.saved_answers || {};
 
+  const metadata = agentYaml?.agent?.metadata || {};
+
   return {
     yamlContent: content,
     agentYaml,
     installConfig,
     defaults: { ...defaults, ...savedAnswers }, // saved_answers override defaults
-    metadata: agentYaml?.agent?.metadata || {},
+    metadata,
+    hasSidecar: metadata.hasSidecar === true,
   };
 }
 
@@ -208,14 +234,16 @@ async function promptInstallQuestions(installConfig, defaults, presetAnswers = {
  * @param {Object} agentInfo - Agent discovery info
  * @param {Object} answers - User answers for install_config
  * @param {string} targetPath - Target installation directory
+ * @param {Object} options - Additional options including config
  * @returns {Object} Installation result
  */
-function installAgent(agentInfo, answers, targetPath) {
+function installAgent(agentInfo, answers, targetPath, options = {}) {
   // Compile the agent
   const { xml, metadata, processedYaml } = compileAgent(fs.readFileSync(agentInfo.yamlFile, 'utf8'), answers);
 
   // Determine target agent folder name
-  const agentFolderName = metadata.name ? metadata.name.toLowerCase().replaceAll(/\s+/g, '-') : agentInfo.name;
+  // Use the folder name from agentInfo, NOT the persona name from metadata
+  const agentFolderName = agentInfo.name;
 
   const agentTargetDir = path.join(targetPath, agentFolderName);
 
@@ -237,11 +265,27 @@ function installAgent(agentInfo, answers, targetPath) {
     sidecarCopied: false,
   };
 
-  // Copy sidecar files for expert agents
-  if (agentInfo.hasSidecar && agentInfo.type === 'expert') {
-    const sidecarFiles = copySidecarFiles(agentInfo.path, agentTargetDir, agentInfo.yamlFile);
+  // Handle sidecar files for agents with hasSidecar flag
+  if (agentInfo.hasSidecar === true && agentInfo.type === 'expert') {
+    // Get agent sidecar folder from config or use default
+    const agentSidecarFolder = options.config?.agent_sidecar_folder || '{project-root}/.myagent-data';
+
+    // Resolve path variables
+    const resolvedSidecarFolder = agentSidecarFolder
+      .replaceAll('{project-root}', options.projectRoot || process.cwd())
+      .replaceAll('{bmad_folder}', options.bmadFolder || '.bmad');
+
+    // Create sidecar directory for this agent
+    const agentSidecarDir = path.join(resolvedSidecarFolder, agentFolderName);
+    if (!fs.existsSync(agentSidecarDir)) {
+      fs.mkdirSync(agentSidecarDir, { recursive: true });
+    }
+
+    // Find and copy sidecar folder
+    const sidecarFiles = copyAgentSidecarFiles(agentInfo.path, agentSidecarDir, agentInfo.yamlFile);
     result.sidecarCopied = true;
     result.sidecarFiles = sidecarFiles;
+    result.sidecarDir = agentSidecarDir;
   }
 
   return result;
@@ -285,6 +329,62 @@ function copySidecarFiles(sourceDir, targetDir, excludeYaml) {
   return copied;
 }
 
+/**
+ * Find and copy agent sidecar folders
+ * @param {string} sourceDir - Source agent directory
+ * @param {string} targetSidecarDir - Target sidecar directory for the agent
+ * @param {string} excludeYaml - The .agent.yaml file to exclude
+ * @returns {Array} List of copied files
+ */
+function copyAgentSidecarFiles(sourceDir, targetSidecarDir, excludeYaml) {
+  const copied = [];
+  const preserved = [];
+
+  // Find folders with "sidecar" in the name
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name.toLowerCase().includes('sidecar')) {
+      const sidecarSourcePath = path.join(sourceDir, entry.name);
+
+      // Recursively sync the sidecar folder contents (preserve existing, add new)
+      function syncSidecarDir(src, dest) {
+        if (!fs.existsSync(dest)) {
+          fs.mkdirSync(dest, { recursive: true });
+        }
+
+        // Get all files in source
+        const sourceEntries = fs.readdirSync(src, { withFileTypes: true });
+
+        for (const sourceEntry of sourceEntries) {
+          const srcPath = path.join(src, sourceEntry.name);
+          const destPath = path.join(dest, sourceEntry.name);
+
+          if (sourceEntry.isDirectory()) {
+            // Recursively sync subdirectories
+            syncSidecarDir(srcPath, destPath);
+          } else {
+            // Check if file already exists in destination
+            if (fs.existsSync(destPath)) {
+              // File exists - preserve it
+              preserved.push(destPath);
+            } else {
+              // File doesn't exist - copy it
+              fs.copyFileSync(srcPath, destPath);
+              copied.push(destPath);
+            }
+          }
+        }
+      }
+
+      syncSidecarDir(sidecarSourcePath, targetSidecarDir);
+    }
+  }
+
+  // Return info about what was preserved and what was copied
+  return { copied, preserved };
+}
+
 /**
  * Update agent metadata ID to reflect installed location
  * @param {string} compiledContent - Compiled XML content
@@ -721,6 +821,7 @@ module.exports = {
   promptInstallQuestions,
   installAgent,
   copySidecarFiles,
+  copyAgentSidecarFiles,
   updateAgentId,
   detectBmadProject,
   addToManifest,

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

@@ -3,6 +3,7 @@ const boxen = require('boxen');
 const wrapAnsi = require('wrap-ansi');
 const figlet = require('figlet');
 const path = require('node:path');
+const os = require('node:os');
 
 const CLIUtils = {
   /**
@@ -84,8 +85,8 @@ const CLIUtils = {
   /**
    * 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
+   * @param {string} header - Custom header from module.yaml
+   * @param {string} subheader - Custom subheader from module.yaml
    */
   displayModuleConfigHeader(moduleName, header = null, subheader = null) {
     // Simple blue banner with custom header/subheader if provided
@@ -100,8 +101,8 @@ const CLIUtils = {
   /**
    * 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
+   * @param {string} header - Custom header from module.yaml
+   * @param {string} subheader - Custom subheader from module.yaml
    */
   displayModuleNoConfig(moduleName, header = null, subheader = null) {
     // Show full banner with header/subheader, just like modules with config
@@ -205,6 +206,22 @@ const CLIUtils = {
     // No longer clear screen or show boxes - just a simple completion message
     // This is deprecated but kept for backwards compatibility
   },
+
+  /**
+   * Expand path with ~ expansion
+   * @param {string} inputPath - Path to expand
+   * @returns {string} Expanded path
+   */
+  expandPath(inputPath) {
+    if (!inputPath) return inputPath;
+
+    // Expand ~ to home directory
+    if (inputPath.startsWith('~')) {
+      return path.join(os.homedir(), inputPath.slice(1));
+    }
+
+    return inputPath;
+  },
 };
 
 module.exports = { CLIUtils };

package/tools/cli/lib/config.js

@@ -1,6 +1,7 @@
 const fs = require('fs-extra');
 const yaml = require('js-yaml');
 const path = require('node:path');
+const packageJson = require('../../../package.json');
 
 /**
  * Configuration utility class
@@ -50,7 +51,7 @@ class Config {
     const standardReplacements = {
       '{project-root}': replacements.root || '',
       '{module}': replacements.module || '',
-      '{version}': replacements.version || '5.0.0',
+      '{version}': replacements.version || packageJson.version,
       '{date}': new Date().toISOString().split('T')[0],
     };