bmad-method 6.0.0-alpha.14 → 6.0.0-alpha.16

package/tools/cli/installers/lib/ide/shared/workflow-command-generator.js

@@ -109,7 +109,7 @@ class WorkflowCommandGenerator {
 
     // Convert source path to installed path
     // From: /Users/.../src/modules/bmm/workflows/.../workflow.yaml
-    // To: {project-root}/{bmad_folder}/bmm/workflows/.../workflow.yaml
+    // To: {project-root}/.bmad/bmm/workflows/.../workflow.yaml
     let workflowPath = workflow.path;
 
     // Extract the relative path from source
@@ -131,8 +131,8 @@ class WorkflowCommandGenerator {
       .replaceAll('{{module}}', workflow.module)
       .replaceAll('{{description}}', workflow.description)
       .replaceAll('{{workflow_path}}', workflowPath)
-      .replaceAll('{bmad_folder}', this.bmadFolderName)
-      .replaceAll('{*bmad_folder*}', '{bmad_folder}');
+      .replaceAll('.bmad', this.bmadFolderName)
+      .replaceAll('.bmad', '.bmad');
   }
 
   /**

package/tools/cli/installers/lib/ide/templates/agent-command-template.md

@@ -6,7 +6,7 @@ description: '{{description}}'
 You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
 
 <agent-activation CRITICAL="TRUE">
-1. LOAD the FULL agent file from @{bmad_folder}/{{module}}/agents/{{path}}
+1. LOAD the FULL agent file from @.bmad/{{module}}/agents/{{path}}
 2. READ its entire contents - this contains the complete agent persona, menu, and instructions
 3. Execute ALL activation steps exactly as written in the agent file
 4. Follow the agent's persona and menu system precisely

package/tools/cli/installers/lib/ide/templates/gemini-agent-command.toml

@@ -3,12 +3,12 @@ prompt = """
 CRITICAL: You are now the BMad '{{title}}' agent.
 
 PRE-FLIGHT CHECKLIST:
-1.  [ ] IMMEDIATE ACTION: Load and parse @{{bmad_folder}}/{{module}}/config.yaml - store ALL config values in memory for use throughout the session.
-2.  [ ] IMMEDIATE ACTION: Read and internalize the full agent definition at @{{bmad_folder}}/{{module}}/agents/{{name}}.md.
+1.  [ ] IMMEDIATE ACTION: Load and parse @{.bmad}/{{module}}/config.yaml - store ALL config values in memory for use throughout the session.
+2.  [ ] IMMEDIATE ACTION: Read and internalize the full agent definition at @{.bmad}/{{module}}/agents/{{name}}.md.
 3.  [ ] CONFIRM: The user's name from config is {user_name}.
 
 Only after all checks are complete, greet the user by name and display the menu.
 Acknowledge this checklist is complete in your first response.
 
-AGENT DEFINITION: @{{bmad_folder}}/{{module}}/agents/{{name}}.md
+AGENT DEFINITION: @{.bmad}/{{module}}/agents/{{name}}.md
 """

package/tools/cli/installers/lib/ide/templates/gemini-task-command.toml

@@ -3,10 +3,10 @@ prompt = """
 Execute the following BMad Method task workflow:
 
 PRE-FLIGHT CHECKLIST:
-1.  [ ] IMMEDIATE ACTION: Load and parse @{{bmad_folder}}/{{module}}/config.yaml.
-2.  [ ] IMMEDIATE ACTION: Read and load the task definition at @{{bmad_folder}}/{{module}}/tasks/{{filename}}.
+1.  [ ] IMMEDIATE ACTION: Load and parse @{.bmad}/{{module}}/config.yaml.
+2.  [ ] IMMEDIATE ACTION: Read and load the task definition at @{.bmad}/{{module}}/tasks/{{filename}}.
 
 Follow all instructions and complete the task as defined.
 
-TASK DEFINITION: @{{bmad_folder}}/{{module}}/tasks/{{filename}}
+TASK DEFINITION: @{.bmad}/{{module}}/tasks/{{filename}}
 """

package/tools/cli/installers/lib/ide/templates/workflow-command-template.md

@@ -5,7 +5,7 @@ description: '{{description}}'
 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
 
 <steps CRITICAL="TRUE">
-1. Always LOAD the FULL @{bmad_folder}/core/tasks/workflow.xml
+1. Always LOAD the FULL @.bmad/core/tasks/workflow.xml
 2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @{{workflow_path}}
 3. Pass the yaml path {{workflow_path}} as 'workflow-config' parameter to the workflow.xml instructions
 4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions

package/tools/cli/installers/lib/modules/manager.js

@@ -22,11 +22,12 @@ const { getProjectRoot, getSourcePath, getModulePath } = require('../../../lib/p
  * await manager.install('core-module', '/path/to/bmad');
  */
 class ModuleManager {
-  constructor() {
+  constructor(options = {}) {
     // Path to source modules directory
     this.modulesSourcePath = getSourcePath('modules');
     this.xmlHandler = new XmlHandler();
     this.bmadFolderName = 'bmad'; // Default, can be overridden
+    this.scanProjectForModules = options.scanProjectForModules !== false; // Default to true for backward compatibility
   }
 
   /**
@@ -46,7 +47,7 @@ class ModuleManager {
   }
 
   /**
-   * Copy a file and replace {bmad_folder} placeholder with actual folder name
+   * Copy a file and replace .bmad placeholder with actual folder name
    * @param {string} sourcePath - Source file path
    * @param {string} targetPath - Target file path
    */
@@ -61,14 +62,14 @@ class ModuleManager {
         // Read the file content
         let content = await fs.readFile(sourcePath, 'utf8');
 
-        // Replace escape sequence {*bmad_folder*} with literal {bmad_folder}
-        if (content.includes('{*bmad_folder*}')) {
-          content = content.replaceAll('{*bmad_folder*}', '{bmad_folder}');
+        // Replace escape sequence .bmad with literal .bmad
+        if (content.includes('.bmad')) {
+          content = content.replaceAll('.bmad', '.bmad');
         }
 
-        // Replace {bmad_folder} placeholder with actual folder name
-        if (content.includes('{bmad_folder}')) {
-          content = content.replaceAll('{bmad_folder}', this.bmadFolderName);
+        // Replace .bmad placeholder with actual folder name
+        if (content.includes('.bmad')) {
+          content = content.replaceAll('.bmad', this.bmadFolderName);
         }
 
         // Write to target with replaced content
@@ -106,7 +107,7 @@ class ModuleManager {
   }
 
   /**
-   * Find all modules in the project by searching for install-config.yaml files
+   * Find all modules in the project by searching for module.yaml files
    * @returns {Array} List of module paths
    */
   async findModulesInProject() {
@@ -143,12 +144,14 @@ class ModuleManager {
               continue;
             }
 
-            // Check if this directory contains a module (install-config.yaml OR custom.yaml)
-            const installerConfigPath = path.join(fullPath, '_module-installer', 'install-config.yaml');
+            // Check if this directory contains a module (module.yaml OR custom.yaml)
+            const moduleConfigPath = path.join(fullPath, 'module.yaml');
+            const installerConfigPath = path.join(fullPath, '_module-installer', 'module.yaml');
             const customConfigPath = path.join(fullPath, '_module-installer', 'custom.yaml');
             const rootCustomConfigPath = path.join(fullPath, 'custom.yaml');
 
             if (
+              (await fs.pathExists(moduleConfigPath)) ||
               (await fs.pathExists(installerConfigPath)) ||
               (await fs.pathExists(customConfigPath)) ||
               (await fs.pathExists(rootCustomConfigPath))
@@ -175,10 +178,11 @@ class ModuleManager {
 
   /**
    * List all available modules (excluding core which is always installed)
-   * @returns {Array} List of available modules with metadata
+   * @returns {Object} Object with modules array and customModules array
    */
   async listAvailable() {
     const modules = [];
+    const customModules = [];
 
     // First, scan src/modules (the standard location)
     if (await fs.pathExists(this.modulesSourcePath)) {
@@ -187,12 +191,17 @@ class ModuleManager {
       for (const entry of entries) {
         if (entry.isDirectory()) {
           const modulePath = path.join(this.modulesSourcePath, entry.name);
-          // Check for module structure (install-config.yaml OR custom.yaml)
-          const installerConfigPath = path.join(modulePath, '_module-installer', 'install-config.yaml');
+          // Check for module structure (module.yaml OR custom.yaml)
+          const moduleConfigPath = path.join(modulePath, 'module.yaml');
+          const installerConfigPath = path.join(modulePath, '_module-installer', 'module.yaml');
           const customConfigPath = path.join(modulePath, '_module-installer', 'custom.yaml');
 
           // Skip if this doesn't look like a module
-          if (!(await fs.pathExists(installerConfigPath)) && !(await fs.pathExists(customConfigPath))) {
+          if (
+            !(await fs.pathExists(moduleConfigPath)) &&
+            !(await fs.pathExists(installerConfigPath)) &&
+            !(await fs.pathExists(customConfigPath))
+          ) {
             continue;
           }
 
@@ -209,25 +218,50 @@ class ModuleManager {
       }
     }
 
-    // Then, find all other modules in the project
-    const otherModulePaths = await this.findModulesInProject();
-    for (const modulePath of otherModulePaths) {
-      const moduleName = path.basename(modulePath);
-      const relativePath = path.relative(getProjectRoot(), modulePath);
+    // Then, find all other modules in the project (only if scanning is enabled)
+    if (this.scanProjectForModules) {
+      const otherModulePaths = await this.findModulesInProject();
+      for (const modulePath of otherModulePaths) {
+        const moduleName = path.basename(modulePath);
+        const relativePath = path.relative(getProjectRoot(), modulePath);
 
-      // Skip core module - it's always installed first and not selectable
-      if (moduleName === 'core') {
-        continue;
+        // Skip core module - it's always installed first and not selectable
+        if (moduleName === 'core') {
+          continue;
+        }
+
+        const moduleInfo = await this.getModuleInfo(modulePath, moduleName, relativePath);
+        if (moduleInfo && !modules.some((m) => m.id === moduleInfo.id) && !customModules.some((m) => m.id === moduleInfo.id)) {
+          // Avoid duplicates - skip if we already have this module ID
+          if (moduleInfo.isCustom) {
+            customModules.push(moduleInfo);
+          } else {
+            modules.push(moduleInfo);
+          }
+        }
       }
 
-      const moduleInfo = await this.getModuleInfo(modulePath, moduleName, relativePath);
-      if (moduleInfo && !modules.some((m) => m.id === moduleInfo.id)) {
-        // Avoid duplicates - skip if we already have this module ID
-        modules.push(moduleInfo);
+      // Also check for cached custom modules in _cfg/custom/
+      if (this.bmadDir) {
+        const customCacheDir = path.join(this.bmadDir, '_cfg', 'custom');
+        if (await fs.pathExists(customCacheDir)) {
+          const cacheEntries = await fs.readdir(customCacheDir, { withFileTypes: true });
+          for (const entry of cacheEntries) {
+            if (entry.isDirectory()) {
+              const cachePath = path.join(customCacheDir, entry.name);
+              const moduleInfo = await this.getModuleInfo(cachePath, entry.name, '_cfg/custom');
+              if (moduleInfo && !modules.some((m) => m.id === moduleInfo.id) && !customModules.some((m) => m.id === moduleInfo.id)) {
+                moduleInfo.isCustom = true;
+                moduleInfo.fromCache = true;
+                customModules.push(moduleInfo);
+              }
+            }
+          }
+        }
       }
     }
 
-    return modules;
+    return { modules, customModules };
   }
 
   /**
@@ -238,13 +272,16 @@ class ModuleManager {
    * @returns {Object|null} Module info or null if not a valid module
    */
   async getModuleInfo(modulePath, defaultName, sourceDescription) {
-    // Check for module structure (install-config.yaml OR custom.yaml)
-    const installerConfigPath = path.join(modulePath, '_module-installer', 'install-config.yaml');
+    // Check for module structure (module.yaml OR custom.yaml)
+    const moduleConfigPath = path.join(modulePath, 'module.yaml');
+    const installerConfigPath = path.join(modulePath, '_module-installer', 'module.yaml');
     const customConfigPath = path.join(modulePath, '_module-installer', 'custom.yaml');
     const rootCustomConfigPath = path.join(modulePath, 'custom.yaml');
     let configPath = null;
 
-    if (await fs.pathExists(installerConfigPath)) {
+    if (await fs.pathExists(moduleConfigPath)) {
+      configPath = moduleConfigPath;
+    } else if (await fs.pathExists(installerConfigPath)) {
       configPath = installerConfigPath;
     } else if (await fs.pathExists(customConfigPath)) {
       configPath = customConfigPath;
@@ -305,10 +342,11 @@ class ModuleManager {
     // First, check src/modules
     const srcModulePath = path.join(this.modulesSourcePath, moduleName);
     if (await fs.pathExists(srcModulePath)) {
-      // Check if this looks like a module (has install-config.yaml)
-      const installerConfigPath = path.join(srcModulePath, '_module-installer', 'install-config.yaml');
+      // Check if this looks like a module (has module.yaml)
+      const moduleConfigPath = path.join(srcModulePath, 'module.yaml');
+      const installerConfigPath = path.join(srcModulePath, '_module-installer', 'module.yaml');
 
-      if (await fs.pathExists(installerConfigPath)) {
+      if ((await fs.pathExists(moduleConfigPath)) || (await fs.pathExists(installerConfigPath))) {
         return srcModulePath;
       }
 
@@ -330,12 +368,15 @@ class ModuleManager {
     // Also check by module ID (not just folder name)
     // Need to read configs to match by ID
     for (const modulePath of allModulePaths) {
-      const installerConfigPath = path.join(modulePath, '_module-installer', 'install-config.yaml');
+      const moduleConfigPath = path.join(modulePath, 'module.yaml');
+      const installerConfigPath = path.join(modulePath, '_module-installer', 'module.yaml');
       const customConfigPath = path.join(modulePath, '_module-installer', 'custom.yaml');
       const rootCustomConfigPath = path.join(modulePath, 'custom.yaml');
 
       let configPath = null;
-      if (await fs.pathExists(installerConfigPath)) {
+      if (await fs.pathExists(moduleConfigPath)) {
+        configPath = moduleConfigPath;
+      } else if (await fs.pathExists(installerConfigPath)) {
         configPath = installerConfigPath;
       } else if (await fs.pathExists(customConfigPath)) {
         configPath = customConfigPath;
@@ -350,8 +391,8 @@ class ModuleManager {
           if (config.code === moduleName) {
             return modulePath;
           }
-        } catch {
-          // Skip if can't read config
+        } catch (error) {
+          throw new Error(`Failed to parse module.yaml at ${configPath}: ${error.message}`);
         }
       }
     }
@@ -576,7 +617,7 @@ class ModuleManager {
       }
 
       // Skip _module-installer directory - it's only needed at install time
-      if (file.startsWith('_module-installer/')) {
+      if (file.startsWith('_module-installer/') || file === 'module.yaml') {
         continue;
       }
 
@@ -654,8 +695,8 @@ class ModuleManager {
 
     // IMPORTANT: Replace escape sequence and placeholder BEFORE parsing YAML
     // Otherwise parsing will fail on the placeholder
-    yamlContent = yamlContent.replaceAll('{*bmad_folder*}', '{bmad_folder}');
-    yamlContent = yamlContent.replaceAll('{bmad_folder}', this.bmadFolderName);
+    yamlContent = yamlContent.replaceAll('.bmad', '.bmad');
+    yamlContent = yamlContent.replaceAll('.bmad', this.bmadFolderName);
 
     try {
       // First check if web_bundle exists by parsing
@@ -812,8 +853,13 @@ class ModuleManager {
         // Compile with customizations if any
         const { xml } = compileAgent(yamlContent, {}, agentName, relativePath, { config: this.coreConfig });
 
-        // Write the compiled MD file
-        await fs.writeFile(targetMdPath, xml, 'utf8');
+        // Replace .bmad placeholder if needed
+        if (xml.includes('.bmad') && this.bmadFolderName) {
+          const processedXml = xml.replaceAll('.bmad', this.bmadFolderName);
+          await fs.writeFile(targetMdPath, processedXml, 'utf8');
+        } else {
+          await fs.writeFile(targetMdPath, xml, 'utf8');
+        }
 
         // Copy sidecar files if agent has hasSidecar flag
         if (hasSidecar) {
@@ -826,7 +872,7 @@ class ModuleManager {
           const projectDir = path.dirname(bmadDir);
           const resolvedSidecarFolder = agentSidecarFolder
             .replaceAll('{project-root}', projectDir)
-            .replaceAll('{bmad_folder}', path.basename(bmadDir));
+            .replaceAll('.bmad', path.basename(bmadDir));
 
           // Create sidecar directory for this agent
           const agentSidecarDir = path.join(resolvedSidecarFolder, agentName);
@@ -984,10 +1030,10 @@ class ModuleManager {
         const installWorkflowPath = item['workflow-install']; // Where to copy TO
 
         // Parse SOURCE workflow path
-        // Handle both {bmad_folder} placeholder and hardcoded 'bmad'
-        // Example: {project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story/workflow.yaml
+        // Handle both .bmad placeholder and hardcoded 'bmad'
+        // Example: {project-root}/.bmad/bmm/workflows/4-implementation/create-story/workflow.yaml
         // Or: {project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml
-        const sourceMatch = sourceWorkflowPath.match(/\{project-root\}\/(?:\{bmad_folder\}|bmad)\/([^/]+)\/workflows\/(.+)/);
+        const sourceMatch = sourceWorkflowPath.match(/\{project-root\}\/(?:\.bmad)\/([^/]+)\/workflows\/(.+)/);
         if (!sourceMatch) {
           console.warn(chalk.yellow(`      Could not parse workflow path: ${sourceWorkflowPath}`));
           continue;
@@ -996,9 +1042,9 @@ class ModuleManager {
         const [, sourceModule, sourceWorkflowSubPath] = sourceMatch;
 
         // Parse INSTALL workflow path
-        // Handle both {bmad_folder} placeholder and hardcoded 'bmad'
-        // Example: {project-root}/{bmad_folder}/bmgd/workflows/4-production/create-story/workflow.yaml
-        const installMatch = installWorkflowPath.match(/\{project-root\}\/(?:\{bmad_folder\}|bmad)\/([^/]+)\/workflows\/(.+)/);
+        // Handle.bmad
+        // Example: {project-root}/.bmad/bmgd/workflows/4-production/create-story/workflow.yaml
+        const installMatch = installWorkflowPath.match(/\{project-root\}\/(\.bmad)\/([^/]+)\/workflows\/(.+)/);
         if (!installMatch) {
           console.warn(chalk.yellow(`      Could not parse workflow-install path: ${installWorkflowPath}`));
           continue;
@@ -1050,9 +1096,9 @@ class ModuleManager {
   async updateWorkflowConfigSource(workflowYamlPath, newModuleName) {
     let yamlContent = await fs.readFile(workflowYamlPath, 'utf8');
 
-    // Replace config_source: "{project-root}/{bmad_folder}/OLD_MODULE/config.yaml"
-    // with config_source: "{project-root}/{bmad_folder}/NEW_MODULE/config.yaml"
-    // Note: At this point {bmad_folder} has already been replaced with actual folder name
+    // Replace config_source: "{project-root}/.bmad/OLD_MODULE/config.yaml"
+    // with config_source: "{project-root}/.bmad/NEW_MODULE/config.yaml"
+    // Note: At this point .bmad has already been replaced with actual folder name
     const configSourcePattern = /config_source:\s*["']?\{project-root\}\/[^/]+\/[^/]+\/config\.yaml["']?/g;
     const newConfigSource = `config_source: "{project-root}/${this.bmadFolderName}/${newModuleName}/config.yaml"`;
 

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

@@ -59,7 +59,7 @@ function buildSimpleActivation(criticalActions = [], menuItems = [], deploymentT
 
   // Standard steps
   activation += `  <step n="${stepNum++}">Load persona from this current agent file (already in context)</step>\n`;
-  activation += `  <step n="${stepNum++}">Load and read {project-root}/{bmad_folder}/core/config.yaml to get {user_name}, {communication_language}, {output_folder}</step>\n`;
+  activation += `  <step n="${stepNum++}">Load and read {project-root}/.bmad/core/config.yaml to get {user_name}, {communication_language}, {output_folder}</step>\n`;
   activation += `  <step n="${stepNum++}">Remember: user's name is {user_name}</step>\n`;
 
   // Agent-specific steps from critical_actions
@@ -119,7 +119,7 @@ function buildSimpleActivation(criticalActions = [], menuItems = [], deploymentT
     if (usedHandlers.has('workflow')) {
       activation += `      <handler type="workflow">
         When menu item has: workflow="path/to/workflow.yaml"
-        1. CRITICAL: Always LOAD {project-root}/{bmad_folder}/core/tasks/workflow.xml
+        1. CRITICAL: Always LOAD {project-root}/.bmad/core/tasks/workflow.xml
         2. Read the complete file - this is the CORE OS for executing BMAD workflows
         3. Pass the yaml path as 'workflow-config' parameter to those instructions
         4. Execute workflow.xml instructions precisely following all steps
@@ -150,7 +150,7 @@ function buildSimpleActivation(criticalActions = [], menuItems = [], deploymentT
     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
+        1. CRITICAL: Always LOAD {project-root}/.bmad/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
@@ -445,17 +445,9 @@ function compileAgent(yamlContent, answers = {}, agentName = '', targetPath = ''
   // 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);

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

@@ -242,7 +242,8 @@ function installAgent(agentInfo, answers, targetPath, options = {}) {
   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);
 
@@ -272,7 +273,7 @@ function installAgent(agentInfo, answers, targetPath, options = {}) {
     // Resolve path variables
     const resolvedSidecarFolder = agentSidecarFolder
       .replaceAll('{project-root}', options.projectRoot || process.cwd())
-      .replaceAll('{bmad_folder}', options.bmadFolder || '.bmad');
+      .replaceAll('.bmad', options.bmadFolder || '.bmad');
 
     // Create sidecar directory for this agent
     const agentSidecarDir = path.join(resolvedSidecarFolder, agentFolderName);
@@ -406,7 +407,7 @@ function detectBmadProject(targetPath) {
 
   // Walk up directory tree looking for BMAD installation
   while (checkPath !== root) {
-    const possibleNames = ['.bmad', 'bmad'];
+    const possibleNames = ['.bmad'];
     for (const name of possibleNames) {
       const bmadFolder = path.join(checkPath, name);
       const cfgFolder = path.join(bmadFolder, '_cfg');

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 };