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

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

@@ -1,9 +1,10 @@
 const path = require('node:path');
 const fs = require('fs-extra');
-const yaml = require('js-yaml');
+const yaml = require('yaml');
 const chalk = require('chalk');
 const { XmlHandler } = require('../../../lib/xml-handler');
 const { getProjectRoot, getSourcePath, getModulePath } = require('../../../lib/project-root');
+const { filterCustomizationData } = require('../../../lib/agent/compiler');
 
 /**
  * Manages the installation, updating, and removal of BMAD modules.
@@ -12,7 +13,7 @@ const { getProjectRoot, getSourcePath, getModulePath } = require('../../../lib/p
  *
  * @class ModuleManager
  * @requires fs-extra
- * @requires js-yaml
+ * @requires yaml
  * @requires chalk
  * @requires XmlHandler
  *
@@ -27,7 +28,7 @@ class ModuleManager {
     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
+    this.customModulePaths = new Map(); // Initialize custom module paths
   }
 
   /**
@@ -47,50 +48,30 @@ class ModuleManager {
   }
 
   /**
-   * Copy a file and replace {bmad_folder} placeholder with actual folder name
+   * Set custom module paths for priority lookup
+   * @param {Map<string, string>} customModulePaths - Map of module ID to source path
+   */
+  setCustomModulePaths(customModulePaths) {
+    this.customModulePaths = customModulePaths;
+  }
+
+  /**
+   * Copy a file to the target location
    * @param {string} sourcePath - Source file path
    * @param {string} targetPath - Target file path
+   * @param {boolean} overwrite - Whether to overwrite existing files (default: true)
    */
-  async copyFileWithPlaceholderReplacement(sourcePath, targetPath) {
-    // List of text file extensions that should have placeholder replacement
-    const textExtensions = ['.md', '.yaml', '.yml', '.txt', '.json', '.js', '.ts', '.html', '.css', '.sh', '.bat', '.csv'];
-    const ext = path.extname(sourcePath).toLowerCase();
-
-    // Check if this is a text file that might contain placeholders
-    if (textExtensions.includes(ext)) {
-      try {
-        // 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 {bmad_folder} placeholder with actual folder name
-        if (content.includes('{bmad_folder}')) {
-          content = content.replaceAll('{bmad_folder}', this.bmadFolderName);
-        }
-
-        // Write to target with replaced content
-        await fs.ensureDir(path.dirname(targetPath));
-        await fs.writeFile(targetPath, content, 'utf8');
-      } catch {
-        // If reading as text fails (might be binary despite extension), fall back to regular copy
-        await fs.copy(sourcePath, targetPath, { overwrite: true });
-      }
-    } else {
-      // Binary file or other file type - just copy directly
-      await fs.copy(sourcePath, targetPath, { overwrite: true });
-    }
+  async copyFileWithPlaceholderReplacement(sourcePath, targetPath, overwrite = true) {
+    await fs.copy(sourcePath, targetPath, { overwrite });
   }
 
   /**
-   * Copy a directory recursively with placeholder replacement
+   * Copy a directory recursively
    * @param {string} sourceDir - Source directory path
    * @param {string} targetDir - Target directory path
+   * @param {boolean} overwrite - Whether to overwrite existing files (default: true)
    */
-  async copyDirectoryWithPlaceholderReplacement(sourceDir, targetDir) {
+  async copyDirectoryWithPlaceholderReplacement(sourceDir, targetDir, overwrite = true) {
     await fs.ensureDir(targetDir);
     const entries = await fs.readdir(sourceDir, { withFileTypes: true });
 
@@ -99,81 +80,108 @@ class ModuleManager {
       const targetPath = path.join(targetDir, entry.name);
 
       if (entry.isDirectory()) {
-        await this.copyDirectoryWithPlaceholderReplacement(sourcePath, targetPath);
+        await this.copyDirectoryWithPlaceholderReplacement(sourcePath, targetPath, overwrite);
       } else {
-        await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath);
+        await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath, overwrite);
       }
     }
   }
 
   /**
-   * Find all modules in the project by searching for module.yaml files
-   * @returns {Array} List of module paths
+   * Copy sidecar directory to _bmad/_memory location with update-safe handling
+   * @param {string} sourceSidecarPath - Source sidecar directory path
+   * @param {string} agentName - Name of the agent (for naming)
+   * @param {string} bmadMemoryPath - This should ALWAYS be _bmad/_memory
+   * @param {boolean} isUpdate - Whether this is an update (default: false)
+   * @param {string} bmadDir - BMAD installation directory
+   * @param {Object} installer - Installer instance for file tracking
    */
-  async findModulesInProject() {
-    const projectRoot = getProjectRoot();
-    const modulePaths = new Set();
-
-    // Helper function to recursively scan directories
-    async function scanDirectory(dir, excludePaths = []) {
-      try {
-        const entries = await fs.readdir(dir, { withFileTypes: true });
-
-        for (const entry of entries) {
-          const fullPath = path.join(dir, entry.name);
+  async copySidecarToMemory(sourceSidecarPath, agentName, bmadMemoryPath, isUpdate = false, bmadDir = null, installer = null) {
+    const crypto = require('node:crypto');
+    const sidecarTargetDir = path.join(bmadMemoryPath, `${agentName}-sidecar`);
+
+    // Ensure target directory exists
+    await fs.ensureDir(bmadMemoryPath);
+    await fs.ensureDir(sidecarTargetDir);
+
+    // Get existing files manifest for update checking
+    let existingFilesManifest = [];
+    if (isUpdate && installer) {
+      existingFilesManifest = await installer.readFilesManifest(bmadDir);
+    }
 
-          // Skip hidden directories, node_modules, and literal placeholder directories
-          if (
-            entry.name.startsWith('.') ||
-            entry.name === 'node_modules' ||
-            entry.name === 'dist' ||
-            entry.name === 'build' ||
-            entry.name === '{project-root}'
-          ) {
-            continue;
-          }
+    // Build map of existing sidecar files with their hashes
+    const existingSidecarFiles = new Map();
+    for (const fileEntry of existingFilesManifest) {
+      if (fileEntry.path && fileEntry.path.includes(`${agentName}-sidecar/`)) {
+        existingSidecarFiles.set(fileEntry.path, fileEntry.hash);
+      }
+    }
 
-          // Skip excluded paths
-          if (excludePaths.some((exclude) => fullPath.startsWith(exclude))) {
-            continue;
-          }
+    // Get all files in source sidecar
+    const sourceFiles = await this.getFileList(sourceSidecarPath);
 
-          if (entry.isDirectory()) {
-            // Skip core module - it's always installed first and not selectable
-            if (entry.name === 'core') {
-              continue;
+    for (const file of sourceFiles) {
+      const sourceFilePath = path.join(sourceSidecarPath, file);
+      const targetFilePath = path.join(sidecarTargetDir, file);
+
+      // Calculate current source file hash
+      const sourceHash = crypto
+        .createHash('sha256')
+        .update(await fs.readFile(sourceFilePath))
+        .digest('hex');
+
+      // Path relative to bmad directory
+      const relativeToBmad = path.join('_memory', `${agentName}-sidecar`, file);
+
+      if (isUpdate && (await fs.pathExists(targetFilePath))) {
+        // Calculate current target file hash
+        const currentTargetHash = crypto
+          .createHash('sha256')
+          .update(await fs.readFile(targetFilePath))
+          .digest('hex');
+
+        // Get the last known hash from files-manifest
+        const lastKnownHash = existingSidecarFiles.get(relativeToBmad);
+
+        if (lastKnownHash) {
+          // We have a record of this file
+          if (currentTargetHash === lastKnownHash) {
+            // File hasn't been modified by user, safe to update
+            await this.copyFileWithPlaceholderReplacement(sourceFilePath, targetFilePath, true);
+            if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+              console.log(chalk.dim(`    Updated sidecar file: ${relativeToBmad}`));
             }
-
-            // 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))
-            ) {
-              modulePaths.add(fullPath);
-              // Don't scan inside modules - they might have their own nested structures
-              continue;
+          } else {
+            // User has modified the file, preserve it
+            if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+              console.log(chalk.dim(`    Preserving user-modified file: ${relativeToBmad}`));
             }
-
-            // Recursively scan subdirectories
-            await scanDirectory(fullPath, excludePaths);
           }
+        } else {
+          // First time seeing this file in manifest, copy it
+          await this.copyFileWithPlaceholderReplacement(sourceFilePath, targetFilePath, true);
+          if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+            console.log(chalk.dim(`    Added new sidecar file: ${relativeToBmad}`));
+          }
+        }
+      } else {
+        // New installation
+        await this.copyFileWithPlaceholderReplacement(sourceFilePath, targetFilePath, true);
+        if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+          console.log(chalk.dim(`    Copied sidecar file: ${relativeToBmad}`));
         }
-      } catch {
-        // Ignore errors (e.g., permission denied)
       }
-    }
 
-    // Scan the entire project, but exclude src/modules since we handle it separately
-    await scanDirectory(projectRoot, [this.modulesSourcePath]);
+      // Track the file in the installer's file tracking system
+      if (installer && installer.installedFiles) {
+        installer.installedFiles.add(targetFilePath);
+      }
+    }
 
-    return [...modulePaths];
+    // Return list of files that were processed
+    const processedFiles = sourceFiles.map((file) => path.join('_memory', `${agentName}-sidecar`, file));
+    return processedFiles;
   }
 
   /**
@@ -218,43 +226,19 @@ class ModuleManager {
       }
     }
 
-    // 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;
-        }
-
-        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);
-          }
-        }
-      }
-
-      // 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);
-              }
+    // Check for cached custom modules in _config/custom/
+    if (this.bmadDir) {
+      const customCacheDir = path.join(this.bmadDir, '_config', '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, '_config/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);
             }
           }
         }
@@ -312,7 +296,7 @@ class ModuleManager {
     // Read module config for metadata
     try {
       const configContent = await fs.readFile(configPath, 'utf8');
-      const config = yaml.load(configContent);
+      const config = yaml.parse(configContent);
 
       // Use the code property as the id if available
       if (config.code) {
@@ -333,66 +317,50 @@ class ModuleManager {
 
   /**
    * Find the source path for a module by searching all possible locations
-   * @param {string} moduleName - Name of the module to find
+   * @param {string} moduleCode - Code of the module to find (from module.yaml)
    * @returns {string|null} Path to the module source or null if not found
    */
-  async findModuleSource(moduleName) {
+  async findModuleSource(moduleCode) {
     const projectRoot = getProjectRoot();
 
-    // First, check src/modules
-    const srcModulePath = path.join(this.modulesSourcePath, moduleName);
-    if (await fs.pathExists(srcModulePath)) {
-      // 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(moduleConfigPath)) || (await fs.pathExists(installerConfigPath))) {
-        return srcModulePath;
-      }
-
-      // Also check for custom.yaml in src/modules/_module-installer
-      const customConfigPath = path.join(srcModulePath, '_module-installer', 'custom.yaml');
-      if (await fs.pathExists(customConfigPath)) {
-        return srcModulePath;
-      }
+    // First check custom module paths if they exist
+    if (this.customModulePaths && this.customModulePaths.has(moduleCode)) {
+      return this.customModulePaths.get(moduleCode);
     }
 
-    // If not found in src/modules, search the entire project
-    const allModulePaths = await this.findModulesInProject();
-    for (const modulePath of allModulePaths) {
-      if (path.basename(modulePath) === moduleName) {
-        return modulePath;
-      }
-    }
+    // Search in src/modules by READING module.yaml files to match by code
+    if (await fs.pathExists(this.modulesSourcePath)) {
+      const entries = await fs.readdir(this.modulesSourcePath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const modulePath = path.join(this.modulesSourcePath, entry.name);
 
-    // Also check by module ID (not just folder name)
-    // Need to read configs to match by ID
-    for (const modulePath of allModulePaths) {
-      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(moduleConfigPath)) {
-        configPath = moduleConfigPath;
-      } else if (await fs.pathExists(installerConfigPath)) {
-        configPath = installerConfigPath;
-      } else if (await fs.pathExists(customConfigPath)) {
-        configPath = customConfigPath;
-      } else if (await fs.pathExists(rootCustomConfigPath)) {
-        configPath = rootCustomConfigPath;
-      }
+          // Read module.yaml to get the code
+          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');
 
-      if (configPath) {
-        try {
-          const configContent = await fs.readFile(configPath, 'utf8');
-          const config = yaml.load(configContent);
-          if (config.code === moduleName) {
-            return modulePath;
+          let configPath = null;
+          if (await fs.pathExists(moduleConfigPath)) {
+            configPath = moduleConfigPath;
+          } else if (await fs.pathExists(installerConfigPath)) {
+            configPath = installerConfigPath;
+          } else if (await fs.pathExists(customConfigPath)) {
+            configPath = customConfigPath;
+          }
+
+          if (configPath) {
+            try {
+              const configContent = await fs.readFile(configPath, 'utf8');
+              const config = yaml.parse(configContent);
+              if (config.code === moduleCode) {
+                return modulePath;
+              }
+            } catch (error) {
+              // Continue to next module if parse fails
+              console.warn(`Warning: Failed to parse module config at ${configPath}: ${error.message}`);
+            }
           }
-        } catch {
-          // Skip if can't read config
         }
       }
     }
@@ -402,7 +370,7 @@ class ModuleManager {
 
   /**
    * Install a module
-   * @param {string} moduleName - Name of the module to install
+   * @param {string} moduleName - Code of the module to install (from module.yaml)
    * @param {string} bmadDir - Target bmad directory
    * @param {Function} fileTrackingCallback - Optional callback to track installed files
    * @param {Object} options - Additional installation options
@@ -416,7 +384,10 @@ class ModuleManager {
 
     // Check if source module exists
     if (!sourcePath) {
-      throw new Error(`Module '${moduleName}' not found in any source location`);
+      // Provide a more user-friendly error message
+      throw new Error(
+        `Source for module '${moduleName}' is not available. It will be retained but cannot be updated without its source files.`,
+      );
     }
 
     // Check if this is a custom module and read its custom.yaml values
@@ -427,14 +398,14 @@ class ModuleManager {
     if (await fs.pathExists(rootCustomConfigPath)) {
       try {
         const customContent = await fs.readFile(rootCustomConfigPath, 'utf8');
-        customConfig = yaml.load(customContent);
+        customConfig = yaml.parse(customContent);
       } catch (error) {
         console.warn(chalk.yellow(`Warning: Failed to read custom.yaml for ${moduleName}:`, error.message));
       }
     } else if (await fs.pathExists(moduleInstallerCustomPath)) {
       try {
         const customContent = await fs.readFile(moduleInstallerCustomPath, 'utf8');
-        customConfig = yaml.load(customContent);
+        customConfig = yaml.parse(customContent);
       } catch (error) {
         console.warn(chalk.yellow(`Warning: Failed to read custom.yaml for ${moduleName}:`, error.message));
       }
@@ -450,7 +421,6 @@ class ModuleManager {
 
     // Check if already installed
     if (await fs.pathExists(targetPath)) {
-      console.log(chalk.yellow(`Module '${moduleName}' already installed, updating...`));
       await fs.remove(targetPath);
     }
 
@@ -462,7 +432,7 @@ class ModuleManager {
     await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
 
     // Compile any .agent.yaml files to .md format
-    await this.compileModuleAgents(sourcePath, targetPath, moduleName, bmadDir);
+    await this.compileModuleAgents(sourcePath, targetPath, moduleName, bmadDir, options.installer);
 
     // Process agent files to inject activation block
     await this.processAgentFiles(targetPath, moduleName);
@@ -506,6 +476,10 @@ class ModuleManager {
     } else {
       // Selective update - preserve user modifications
       await this.syncModule(sourcePath, targetPath);
+
+      // Recompile agents (#1133)
+      await this.compileModuleAgents(sourcePath, targetPath, moduleName, bmadDir, options.installer);
+      await this.processAgentFiles(targetPath, moduleName);
     }
 
     return {
@@ -569,7 +543,7 @@ class ModuleManager {
     if (await fs.pathExists(configPath)) {
       try {
         const configContent = await fs.readFile(configPath, 'utf8');
-        const config = yaml.load(configContent);
+        const config = yaml.parse(configContent);
         Object.assign(moduleInfo, config);
       } catch (error) {
         console.warn(`Failed to read installed module config:`, error.message);
@@ -590,29 +564,21 @@ class ModuleManager {
     // Get all files in source
     const sourceFiles = await this.getFileList(sourcePath);
 
-    // Game development files to conditionally exclude
-    const gameDevFiles = [
-      'agents/game-architect.agent.yaml',
-      'agents/game-designer.agent.yaml',
-      'agents/game-dev.agent.yaml',
-      'workflows/1-analysis/brainstorm-game',
-      'workflows/1-analysis/game-brief',
-      'workflows/2-plan-workflows/gdd',
-    ];
-
     for (const file of sourceFiles) {
       // Skip sub-modules directory - these are IDE-specific and handled separately
       if (file.startsWith('sub-modules/')) {
         continue;
       }
 
-      // Skip sidecar directories - they are handled separately during agent compilation
-      if (
-        path
-          .dirname(file)
-          .split('/')
-          .some((dir) => dir.toLowerCase().includes('sidecar'))
-      ) {
+      // Only skip sidecar directories - they are handled separately during agent compilation
+      // But still allow other files in agent directories
+      const isInAgentDirectory = file.startsWith('agents/');
+      const isInSidecarDirectory = path
+        .dirname(file)
+        .split('/')
+        .some((dir) => dir.toLowerCase().endsWith('-sidecar'));
+
+      if (isInSidecarDirectory) {
         continue;
       }
 
@@ -622,8 +588,7 @@ class ModuleManager {
       }
 
       // Skip config.yaml templates - we'll generate clean ones with actual values
-      // Also skip custom.yaml files - their values will be merged into core config
-      if (file === 'config.yaml' || file.endsWith('/config.yaml') || file === 'custom.yaml' || file.endsWith('/custom.yaml')) {
+      if (file === 'config.yaml' || file.endsWith('/config.yaml')) {
         continue;
       }
 
@@ -632,25 +597,6 @@ class ModuleManager {
         continue;
       }
 
-      // Skip user documentation if install_user_docs is false
-      if (moduleConfig.install_user_docs === false && (file.startsWith('docs/') || file.startsWith('docs\\'))) {
-        console.log(chalk.dim(`  Skipping user documentation: ${file}`));
-        continue;
-      }
-
-      // Skip game development content if include_game_planning is false
-      if (moduleConfig.include_game_planning === false) {
-        const shouldSkipGameDev = gameDevFiles.some((gamePath) => {
-          // Check if file path starts with or is within any game dev directory
-          return file === gamePath || file.startsWith(gamePath + '/') || file.startsWith(gamePath + '\\');
-        });
-
-        if (shouldSkipGameDev) {
-          console.log(chalk.dim(`  Skipping game dev content: ${file}`));
-          continue;
-        }
-      }
-
       const sourceFile = path.join(sourcePath, file);
       const targetFile = path.join(targetPath, file);
 
@@ -695,12 +641,12 @@ 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
-      const workflowConfig = yaml.load(yamlContent);
+      const workflowConfig = yaml.parse(yamlContent);
 
       if (workflowConfig.web_bundle === undefined) {
         // No web_bundle section, just write (placeholders already replaced above)
@@ -780,11 +726,12 @@ class ModuleManager {
    * @param {string} targetPath - Target module path
    * @param {string} moduleName - Module name
    * @param {string} bmadDir - BMAD installation directory
+   * @param {Object} installer - Installer instance for file tracking
    */
-  async compileModuleAgents(sourcePath, targetPath, moduleName, bmadDir) {
+  async compileModuleAgents(sourcePath, targetPath, moduleName, bmadDir, installer = null) {
     const sourceAgentsPath = path.join(sourcePath, 'agents');
     const targetAgentsPath = path.join(targetPath, 'agents');
-    const cfgAgentsDir = path.join(bmadDir, '_cfg', 'agents');
+    const cfgAgentsDir = path.join(bmadDir, '_config', 'agents');
 
     // Check if agents directory exists in source
     if (!(await fs.pathExists(sourceAgentsPath))) {
@@ -815,84 +762,133 @@ class ModuleManager {
         // Create customize template if it doesn't exist
         if (!(await fs.pathExists(customizePath))) {
           const { getSourcePath } = require('../../../lib/project-root');
-          const genericTemplatePath = getSourcePath('utility', 'templates', 'agent.customize.template.yaml');
+          const genericTemplatePath = getSourcePath('utility', 'agent-components', 'agent.customize.template.yaml');
           if (await fs.pathExists(genericTemplatePath)) {
             await this.copyFileWithPlaceholderReplacement(genericTemplatePath, customizePath);
-            console.log(chalk.dim(`  Created customize: ${moduleName}-${agentName}.customize.yaml`));
+            // Only show customize creation in verbose mode
+            if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+              console.log(chalk.dim(`  Created customize: ${moduleName}-${agentName}.customize.yaml`));
+            }
+
+            // Store original hash for modification detection
+            const crypto = require('node:crypto');
+            const customizeContent = await fs.readFile(customizePath, 'utf8');
+            const originalHash = crypto.createHash('sha256').update(customizeContent).digest('hex');
+
+            // Store in main manifest
+            const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml');
+            let manifestData = {};
+            if (await fs.pathExists(manifestPath)) {
+              const manifestContent = await fs.readFile(manifestPath, 'utf8');
+              const yaml = require('yaml');
+              manifestData = yaml.parse(manifestContent);
+            }
+            if (!manifestData.agentCustomizations) {
+              manifestData.agentCustomizations = {};
+            }
+            manifestData.agentCustomizations[path.relative(bmadDir, customizePath)] = originalHash;
+
+            // Write back to manifest
+            const yaml = require('yaml');
+            // Clean the manifest data to remove any non-serializable values
+            const cleanManifestData = structuredClone(manifestData);
+
+            const updatedContent = yaml.stringify(cleanManifestData, {
+              indent: 2,
+              lineWidth: 0,
+            });
+            await fs.writeFile(manifestPath, updatedContent, 'utf8');
           }
         }
 
-        // Check for customizations
+        // Check for customizations and build answers object
         let customizedFields = [];
+        let answers = {};
         if (await fs.pathExists(customizePath)) {
           const customizeContent = await fs.readFile(customizePath, 'utf8');
-          const customizeData = yaml.load(customizeContent);
+          const customizeData = yaml.parse(customizeContent);
           customizedFields = customizeData.customized_fields || [];
-        }
-
-        // Load core config to get agent_sidecar_folder
-        const coreConfigPath = path.join(bmadDir, 'bmb', 'config.yaml');
-        let coreConfig = {};
 
-        if (await fs.pathExists(coreConfigPath)) {
-          const yamlLib = require('yaml');
-          const coreConfigContent = await fs.readFile(coreConfigPath, 'utf8');
-          coreConfig = yamlLib.parse(coreConfigContent);
+          // Build answers object from customizations (filter empty values)
+          if (customizeData.persona) {
+            Object.assign(answers, filterCustomizationData(customizeData.persona));
+          }
+          if (customizeData.agent?.metadata) {
+            const filteredMetadata = filterCustomizationData(customizeData.agent.metadata);
+            if (Object.keys(filteredMetadata).length > 0) {
+              Object.assign(answers, { metadata: filteredMetadata });
+            }
+          }
+          if (customizeData.critical_actions && customizeData.critical_actions.length > 0) {
+            answers.critical_actions = customizeData.critical_actions;
+          }
+          if (customizeData.memories && customizeData.memories.length > 0) {
+            answers.memories = customizeData.memories;
+          }
         }
 
         // Check if agent has sidecar
         let hasSidecar = false;
         try {
-          const yamlLib = require('yaml');
-          const agentYaml = yamlLib.parse(yamlContent);
+          const agentYaml = yaml.parse(yamlContent);
           hasSidecar = agentYaml?.agent?.metadata?.hasSidecar === true;
         } catch {
           // Continue without sidecar processing
         }
 
         // Compile with customizations if any
-        const { xml } = compileAgent(yamlContent, {}, agentName, relativePath, { config: this.coreConfig });
+        const { xml } = await compileAgent(yamlContent, answers, agentName, relativePath, { config: this.coreConfig || {} });
 
-        // Replace {bmad_folder} placeholder if needed
-        if (xml.includes('{bmad_folder}') && this.bmadFolderName) {
-          const processedXml = xml.replaceAll('{bmad_folder}', this.bmadFolderName);
-          await fs.writeFile(targetMdPath, processedXml, 'utf8');
-        } else {
-          await fs.writeFile(targetMdPath, xml, 'utf8');
-        }
+        // Write the compiled agent
+        await fs.writeFile(targetMdPath, xml, 'utf8');
 
-        // Copy sidecar files if agent has hasSidecar flag
+        // Handle sidecar copying if present
         if (hasSidecar) {
-          const { copyAgentSidecarFiles } = require('../../../lib/agent/installer');
-
-          // Get agent sidecar folder from core config (should always be set)
-          const agentSidecarFolder = this.coreConfig?.agent_sidecar_folder;
+          // Get the agent's directory to look for sidecar
+          const agentDir = path.dirname(agentFile);
+          const sidecarDirName = `${agentName}-sidecar`;
+          const sourceSidecarPath = path.join(agentDir, sidecarDirName);
 
-          // Resolve path variables
-          const projectDir = path.dirname(bmadDir);
-          const resolvedSidecarFolder = agentSidecarFolder
-            .replaceAll('{project-root}', projectDir)
-            .replaceAll('{bmad_folder}', path.basename(bmadDir));
+          // Check if sidecar directory exists
+          if (await fs.pathExists(sourceSidecarPath)) {
+            // Memory is always in _bmad/_memory
+            const bmadMemoryPath = path.join(bmadDir, '_memory');
 
-          // Create sidecar directory for this agent
-          const agentSidecarDir = path.join(resolvedSidecarFolder, agentName);
-          await fs.ensureDir(agentSidecarDir);
+            // Determine if this is an update (by checking if agent already exists)
+            const isUpdate = await fs.pathExists(targetMdPath);
 
-          // Copy sidecar files (preserve existing, add new)
-          const sidecarResult = copyAgentSidecarFiles(path.dirname(sourceYamlPath), agentSidecarDir, sourceYamlPath);
-          const totalFiles = sidecarResult.copied.length + sidecarResult.preserved.length;
+            // Copy sidecar to memory location with update-safe handling
+            const copiedFiles = await this.copySidecarToMemory(sourceSidecarPath, agentName, bmadMemoryPath, isUpdate, bmadDir, installer);
 
-          if (sidecarResult.copied.length > 0) {
-            console.log(chalk.dim(`    Copied ${sidecarResult.copied.length} new sidecar file(s) to: ${agentSidecarDir}`));
+            if (process.env.BMAD_VERBOSE_INSTALL === 'true' && copiedFiles.length > 0) {
+              console.log(chalk.dim(`    Sidecar files processed: ${copiedFiles.length} files`));
+            }
+          } else if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+            console.log(chalk.yellow(`    Warning: Agent marked as having sidecar but ${sidecarDirName} directory not found`));
           }
-          if (sidecarResult.preserved.length > 0) {
-            console.log(chalk.dim(`    Preserved ${sidecarResult.preserved.length} existing sidecar file(s)`));
+        }
+
+        // Copy any non-sidecar files from agent directory (e.g., foo.md)
+        const agentDir = path.dirname(agentFile);
+        const agentEntries = await fs.readdir(agentDir, { withFileTypes: true });
+
+        for (const entry of agentEntries) {
+          if (entry.isFile() && !entry.name.endsWith('.agent.yaml') && !entry.name.endsWith('.md')) {
+            // Copy additional files (like foo.md) to the agent target directory
+            const sourceFile = path.join(agentDir, entry.name);
+            const targetFile = path.join(targetDir, entry.name);
+            await this.copyFileWithPlaceholderReplacement(sourceFile, targetFile);
           }
         }
 
-        console.log(
-          chalk.dim(`    Compiled agent: ${agentName} -> ${path.relative(targetPath, targetMdPath)}${hasSidecar ? ' (with sidecar)' : ''}`),
-        );
+        // Only show compilation details in verbose mode
+        if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+          console.log(
+            chalk.dim(
+              `    Compiled agent: ${agentName} -> ${path.relative(targetPath, targetMdPath)}${hasSidecar ? ' (with sidecar)' : ''}`,
+            ),
+          );
+        }
       } catch (error) {
         console.warn(chalk.yellow(`    Failed to compile agent ${agentName}:`, error.message));
       }
@@ -931,28 +927,23 @@ class ModuleManager {
    * @param {string} moduleName - Module name
    */
   async processAgentFiles(modulePath, moduleName) {
-    const agentsPath = path.join(modulePath, 'agents');
-
-    // Check if agents directory exists
-    if (!(await fs.pathExists(agentsPath))) {
-      return; // No agents to process
-    }
-
-    // Get all agent MD files recursively
-    const agentFiles = await this.findAgentMdFiles(agentsPath);
-
-    for (const agentFile of agentFiles) {
-      if (!agentFile.endsWith('.md')) continue;
-
-      let content = await fs.readFile(agentFile, 'utf8');
-
-      // Check if content has agent XML and no activation block
-      if (content.includes('<agent') && !content.includes('<activation')) {
-        // Inject the activation block using XML handler
-        content = this.xmlHandler.injectActivationSimple(content);
-        await fs.writeFile(agentFile, content, 'utf8');
-      }
-    }
+    // const agentsPath = path.join(modulePath, 'agents');
+    // // Check if agents directory exists
+    // if (!(await fs.pathExists(agentsPath))) {
+    //   return; // No agents to process
+    // }
+    // // Get all agent MD files recursively
+    // const agentFiles = await this.findAgentMdFiles(agentsPath);
+    // for (const agentFile of agentFiles) {
+    //   if (!agentFile.endsWith('.md')) continue;
+    //   let content = await fs.readFile(agentFile, 'utf8');
+    //   // Check if content has agent XML and no activation block
+    //   if (content.includes('<agent') && !content.includes('<activation')) {
+    //     // Inject the activation block using XML handler
+    //     content = this.xmlHandler.injectActivationSimple(content);
+    //     await fs.writeFile(agentFile, content, 'utf8');
+    //   }
+    // }
   }
 
   /**
@@ -1008,7 +999,7 @@ class ModuleManager {
 
     for (const agentFile of yamlFiles) {
       const agentPath = path.join(sourceAgentsPath, agentFile);
-      const agentYaml = yaml.load(await fs.readFile(agentPath, 'utf8'));
+      const agentYaml = yaml.parse(await fs.readFile(agentPath, 'utf8'));
 
       // Check if agent has menu items with workflow-install
       const menuItems = agentYaml?.agent?.menu || [];
@@ -1030,10 +1021,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;
@@ -1042,9 +1033,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;
@@ -1096,9 +1087,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"`;