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

package/tools/cli/installers/lib/core/installer.js

@@ -14,7 +14,7 @@
  * @architecture Orchestrator pattern - coordinates Detector, ModuleManager, IdeManager, and file operations to build complete BMAD installation
  * @dependencies fs-extra, ora, chalk, detector.js, module-manager.js, ide-manager.js, config.js
  * @entrypoints Called by install.js command via installer.install(config)
- * @patterns Injection point processing (AgentVibes), placeholder replacement ({bmad_folder}), module dependency resolution
+ * @patterns Injection point processing (AgentVibes), placeholder replacement (.bmad), module dependency resolution
  * @related GitHub AgentVibes#34 (injection points), ui.js (user prompts), copyFileWithPlaceholderReplacement()
  */
 
@@ -22,6 +22,7 @@ const path = require('node:path');
 const fs = require('fs-extra');
 const chalk = require('chalk');
 const ora = require('ora');
+const inquirer = require('inquirer');
 const { Detector } = require('./detector');
 const { Manifest } = require('./manifest');
 const { ModuleManager } = require('../modules/manager');
@@ -38,6 +39,7 @@ const { CLIUtils } = require('../../../lib/cli-utils');
 const { ManifestGenerator } = require('./manifest-generator');
 const { IdeConfigManager } = require('./ide-config-manager');
 const { replaceAgentSidecarFolders } = require('./post-install-sidecar-replacement');
+const { CustomHandler } = require('../custom/handler');
 
 class Installer {
   constructor() {
@@ -65,7 +67,7 @@ class Installer {
     // Check if project directory exists
     if (!(await fs.pathExists(projectDir))) {
       // Project doesn't exist yet, return default
-      return path.join(projectDir, 'bmad');
+      return path.join(projectDir, '.bmad');
     }
 
     // V6+ strategy: Look for ANY directory with _cfg/manifest.yaml
@@ -87,13 +89,13 @@ class Installer {
 
     // No V6+ installation found, return default
     // This will be used for new installations
-    return path.join(projectDir, 'bmad');
+    return path.join(projectDir, '.bmad');
   }
 
   /**
    * @function copyFileWithPlaceholderReplacement
    * @intent Copy files from BMAD source to installation directory with dynamic content transformation
-   * @why Enables installation-time customization: {bmad_folder} replacement + optional AgentVibes TTS injection
+   * @why Enables installation-time customization: .bmad replacement + optional AgentVibes TTS injection
    * @param {string} sourcePath - Absolute path to source file in BMAD repository
    * @param {string} targetPath - Absolute path to destination file in user's project
    * @param {string} bmadFolderName - User's chosen bmad folder name (default: 'bmad')
@@ -103,11 +105,6 @@ class Installer {
    * @calledby installCore(), installModule(), IDE installers during file vendoring
    * @calls processTTSInjectionPoints(), fs.readFile(), fs.writeFile(), fs.copy()
    *
-   * AI NOTE: This is the core transformation pipeline for ALL BMAD installation file copies.
-   * It performs two transformations in sequence:
-   * 1. {bmad_folder} → user's custom folder name (e.g., ".bmad" or "bmad")
-   * 2. <!-- TTS_INJECTION:* --> → TTS bash calls (if enabled) OR stripped (if disabled)
-   *
    * The injection point processing enables loose coupling between BMAD and TTS providers:
    * - BMAD source contains injection markers (not actual TTS code)
    * - At install-time, markers are replaced OR removed based on user preference
@@ -129,7 +126,7 @@ class Installer {
    */
   async copyFileWithPlaceholderReplacement(sourcePath, targetPath, bmadFolderName) {
     // 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 textExtensions = ['.md', '.yaml', '.yml', '.txt', '.json', '.js', '.ts', '.html', '.css', '.sh', '.bat', '.csv', '.xml'];
     const ext = path.extname(sourcePath).toLowerCase();
 
     // Check if this is a text file that might contain placeholders
@@ -138,16 +135,6 @@ class Installer {
         // Read the file content
         let content = await fs.readFile(sourcePath, 'utf8');
 
-        // Replace {bmad_folder} placeholder with actual folder name
-        if (content.includes('{bmad_folder}')) {
-          content = content.replaceAll('{bmad_folder}', bmadFolderName);
-        }
-
-        // Replace escape sequence {*bmad_folder*} with literal {bmad_folder}
-        if (content.includes('{*bmad_folder*}')) {
-          content = content.replaceAll('{*bmad_folder*}', '{bmad_folder}');
-        }
-
         // Process AgentVibes injection points (pass targetPath for tracking)
         content = this.processTTSInjectionPoints(content, targetPath);
 
@@ -406,7 +393,10 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
    * @param {string[]} config.ides - IDEs to configure
    * @param {boolean} config.skipIde - Skip IDE configuration
    */
-  async install(config) {
+  async install(originalConfig) {
+    // Clone config to avoid mutating the caller's object
+    const config = { ...originalConfig };
+
     // Display BMAD logo
     CLIUtils.displayLogo();
 
@@ -434,12 +424,56 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
       // Quick update already collected all configs, use them directly
       moduleConfigs = this.configCollector.collectedConfig;
     } else {
+      // Build custom module paths map from customContent
+      const customModulePaths = new Map();
+
+      // Handle selectedFiles (from existing install path or manual directory input)
+      if (config.customContent && config.customContent.selected && config.customContent.selectedFiles) {
+        const customHandler = new CustomHandler();
+        for (const customFile of config.customContent.selectedFiles) {
+          const customInfo = await customHandler.getCustomInfo(customFile, path.resolve(config.directory));
+          if (customInfo && customInfo.id) {
+            customModulePaths.set(customInfo.id, customInfo.path);
+          }
+        }
+      }
+
+      // Handle cachedModules (from new install path where modules are cached)
+      // Only include modules that were actually selected for installation
+      if (config.customContent && config.customContent.cachedModules) {
+        // Get selected cached module IDs (if available)
+        const selectedCachedIds = config.customContent.selectedCachedModules || [];
+        // If no selection info, include all cached modules (for backward compatibility)
+        const shouldIncludeAll = selectedCachedIds.length === 0 && config.customContent.selected;
+
+        for (const cachedModule of config.customContent.cachedModules) {
+          // For cached modules, the path is the cachePath which contains the module.yaml
+          if (
+            cachedModule.id &&
+            cachedModule.cachePath && // Include if selected or if we should include all
+            (shouldIncludeAll || selectedCachedIds.includes(cachedModule.id))
+          ) {
+            customModulePaths.set(cachedModule.id, cachedModule.cachePath);
+          }
+        }
+      }
+
+      // Get list of all modules including custom modules
+      const allModulesForConfig = [...(config.modules || [])];
+      for (const [moduleId] of customModulePaths) {
+        if (!allModulesForConfig.includes(moduleId)) {
+          allModulesForConfig.push(moduleId);
+        }
+      }
+
       // Regular install - collect configurations (core was already collected in UI.promptInstall if interactive)
-      moduleConfigs = await this.configCollector.collectAllConfigurations(config.modules || [], path.resolve(config.directory));
+      moduleConfigs = await this.configCollector.collectAllConfigurations(allModulesForConfig, path.resolve(config.directory), {
+        customModulePaths,
+      });
     }
 
-    // Get bmad_folder from config (default to 'bmad' for backwards compatibility)
-    const bmadFolderName = moduleConfigs.core && moduleConfigs.core.bmad_folder ? moduleConfigs.core.bmad_folder : 'bmad';
+    // Always use .bmad as the folder name
+    const bmadFolderName = '.bmad';
     this.bmadFolderName = bmadFolderName; // Store for use in other methods
 
     // Store AgentVibes configuration for injection point processing
@@ -458,7 +492,6 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
       // Resolve target directory (path.resolve handles platform differences)
       const projectDir = path.resolve(config.directory);
 
-      // Check if bmad_folder has changed from existing installation (only if project dir exists)
       let existingBmadDir = null;
       let existingBmadFolderName = null;
 
@@ -467,54 +500,6 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
         existingBmadFolderName = path.basename(existingBmadDir);
       }
 
-      const targetBmadDir = path.join(projectDir, bmadFolderName);
-
-      // If bmad_folder changed during update/upgrade, back up old folder and do fresh install
-      if (existingBmadDir && (await fs.pathExists(existingBmadDir)) && existingBmadFolderName !== bmadFolderName) {
-        spinner.stop();
-        console.log(chalk.yellow(`\n⚠️  bmad_folder has changed: ${existingBmadFolderName} → ${bmadFolderName}`));
-        console.log(chalk.yellow('This will result in a fresh installation to the new folder.'));
-
-        const inquirer = require('inquirer');
-        const { confirmFreshInstall } = await inquirer.prompt([
-          {
-            type: 'confirm',
-            name: 'confirmFreshInstall',
-            message: chalk.cyan('Proceed with fresh install? (Your old folder will be backed up)'),
-            default: true,
-          },
-        ]);
-
-        if (!confirmFreshInstall) {
-          console.log(chalk.yellow('Installation cancelled.'));
-          return { success: false, cancelled: true };
-        }
-
-        spinner.start('Backing up existing installation...');
-
-        // Find a unique backup name
-        let backupDir = `${existingBmadDir}-bak`;
-        let counter = 1;
-        while (await fs.pathExists(backupDir)) {
-          backupDir = `${existingBmadDir}-bak-${counter}`;
-          counter++;
-        }
-
-        // Rename the old folder to backup
-        await fs.move(existingBmadDir, backupDir);
-
-        spinner.succeed(`Backed up ${existingBmadFolderName} → ${path.basename(backupDir)}`);
-        console.log(chalk.cyan('\n📋 Important:'));
-        console.log(chalk.dim(`  - Your old installation has been backed up to: ${path.basename(backupDir)}`));
-        console.log(chalk.dim(`  - If you had custom agents or configurations, copy them from:`));
-        console.log(chalk.dim(`    ${path.basename(backupDir)}/_cfg/`));
-        console.log(chalk.dim(`  - To the new location:`));
-        console.log(chalk.dim(`    ${bmadFolderName}/_cfg/`));
-        console.log('');
-
-        spinner.start('Starting fresh installation...');
-      }
-
       // Create a project directory if it doesn't exist (user already confirmed)
       if (!(await fs.pathExists(projectDir))) {
         spinner.text = 'Creating installation directory...';
@@ -750,13 +735,80 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
       spinner.text = 'Creating directory structure...';
       await this.createDirectoryStructure(bmadDir);
 
-      // Resolve dependencies for selected modules
-      spinner.text = 'Resolving dependencies...';
+      // Get project root
       const projectRoot = getProjectRoot();
-      const modulesToInstall = config.installCore ? ['core', ...config.modules] : config.modules;
+
+      // Step 1: Install core module first (if requested)
+      if (config.installCore) {
+        spinner.start('Installing BMAD core...');
+        await this.installCoreWithDependencies(bmadDir, { core: {} });
+        spinner.succeed('Core installed');
+
+        // Generate core config file
+        await this.generateModuleConfigs(bmadDir, { core: config.coreConfig || {} });
+      }
+
+      // Custom content is already handled in UI before module selection
+      let finalCustomContent = config.customContent;
+
+      // Step 3: Prepare modules list including cached custom modules
+      let allModules = [...(config.modules || [])];
+
+      // During quick update, we might have custom module sources from the manifest
+      if (config._customModuleSources) {
+        // Add custom modules from stored sources
+        for (const [moduleId, customInfo] of config._customModuleSources) {
+          if (!allModules.includes(moduleId) && (await fs.pathExists(customInfo.sourcePath))) {
+            allModules.push(moduleId);
+          }
+        }
+      }
+
+      // Add cached custom modules
+      if (finalCustomContent && finalCustomContent.cachedModules) {
+        for (const cachedModule of finalCustomContent.cachedModules) {
+          if (!allModules.includes(cachedModule.id)) {
+            allModules.push(cachedModule.id);
+          }
+        }
+      }
+
+      // Regular custom content from user input (non-cached)
+      if (finalCustomContent && finalCustomContent.selected && finalCustomContent.selectedFiles) {
+        // Add custom modules to the installation list
+        const customHandler = new CustomHandler();
+        for (const customFile of finalCustomContent.selectedFiles) {
+          const customInfo = await customHandler.getCustomInfo(customFile, projectDir);
+          if (customInfo && customInfo.id) {
+            allModules.push(customInfo.id);
+          }
+        }
+      }
+
+      // Don't include core again if already installed
+      if (config.installCore) {
+        allModules = allModules.filter((m) => m !== 'core');
+      }
+
+      const modulesToInstall = allModules;
 
       // For dependency resolution, we need to pass the project root
-      const resolution = await this.dependencyResolver.resolve(projectRoot, config.modules || [], { verbose: config.verbose });
+      // Create a temporary module manager that knows about custom content locations
+      const tempModuleManager = new ModuleManager({
+        scanProjectForModules: true,
+        bmadDir: bmadDir, // Pass bmadDir so we can check cache
+      });
+
+      // Make sure custom modules are discoverable
+      if (config.customContent && config.customContent.selected && config.customContent.selectedFiles) {
+        // The dependency resolver needs to know about these modules
+        // We'll handle custom modules separately in the installation loop
+      }
+
+      const resolution = await this.dependencyResolver.resolve(projectRoot, allModules, {
+        verbose: config.verbose,
+        moduleManager: tempModuleManager,
+      });
 
       if (config.verbose) {
         spinner.succeed('Dependencies resolved');
@@ -764,24 +816,182 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
         spinner.succeed('Dependencies resolved');
       }
 
-      // Install core if requested or if dependencies require it
-      if (config.installCore || resolution.byModule.core) {
-        spinner.start('Installing BMAD core...');
-        await this.installCoreWithDependencies(bmadDir, resolution.byModule.core);
-        spinner.succeed('Core installed');
-      }
+      // Core is already installed above, skip if included in resolution
 
       // Install modules with their dependencies
-      if (config.modules && config.modules.length > 0) {
-        for (const moduleName of config.modules) {
+      if (allModules && allModules.length > 0) {
+        const installedModuleNames = new Set();
+
+        for (const moduleName of allModules) {
+          // Skip if already installed
+          if (installedModuleNames.has(moduleName)) {
+            continue;
+          }
+          installedModuleNames.add(moduleName);
+
           spinner.start(`Installing module: ${moduleName}...`);
-          await this.installModuleWithDependencies(moduleName, bmadDir, resolution.byModule[moduleName]);
+
+          // Check if this is a custom module
+          let isCustomModule = false;
+          let customInfo = null;
+          let useCache = false;
+
+          // First check if we have a cached version
+          if (finalCustomContent && finalCustomContent.cachedModules) {
+            const cachedModule = finalCustomContent.cachedModules.find((m) => m.id === moduleName);
+            if (cachedModule) {
+              isCustomModule = true;
+              customInfo = {
+                id: moduleName,
+                path: cachedModule.cachePath,
+                config: {},
+              };
+              useCache = true;
+            }
+          }
+
+          // Then check if we have custom module sources from the manifest (for quick update)
+          if (!isCustomModule && config._customModuleSources && config._customModuleSources.has(moduleName)) {
+            customInfo = config._customModuleSources.get(moduleName);
+            isCustomModule = true;
+
+            // Check if this is a cached module (source path starts with _cfg)
+            if (customInfo.sourcePath && (customInfo.sourcePath.startsWith('_cfg') || customInfo.sourcePath.includes('_cfg/custom'))) {
+              useCache = true;
+              // Make sure we have the right path structure
+              if (!customInfo.path) {
+                customInfo.path = customInfo.sourcePath;
+              }
+            }
+          }
+
+          // Finally check regular custom content
+          if (!isCustomModule && finalCustomContent && finalCustomContent.selected && finalCustomContent.selectedFiles) {
+            const customHandler = new CustomHandler();
+            for (const customFile of finalCustomContent.selectedFiles) {
+              const info = await customHandler.getCustomInfo(customFile, projectDir);
+              if (info && info.id === moduleName) {
+                isCustomModule = true;
+                customInfo = info;
+                break;
+              }
+            }
+          }
+
+          if (isCustomModule && customInfo) {
+            // Install custom module using CustomHandler but as a proper module
+            const customHandler = new CustomHandler();
+
+            // Install to module directory instead of custom directory
+            const moduleTargetPath = path.join(bmadDir, moduleName);
+            await fs.ensureDir(moduleTargetPath);
+
+            // Get collected config for this custom module (from module.yaml prompts)
+            const collectedModuleConfig = moduleConfigs[moduleName] || {};
+
+            const result = await customHandler.install(
+              customInfo.path,
+              path.join(bmadDir, 'temp-custom'),
+              { ...config.coreConfig, ...customInfo.config, ...collectedModuleConfig, _bmadDir: bmadDir },
+              (filePath) => {
+                // Track installed files with correct path
+                const relativePath = path.relative(path.join(bmadDir, 'temp-custom'), filePath);
+                const finalPath = path.join(moduleTargetPath, relativePath);
+                this.installedFiles.push(finalPath);
+              },
+            );
+
+            // Move from temp-custom to actual module directory
+            const tempCustomPath = path.join(bmadDir, 'temp-custom');
+            if (await fs.pathExists(tempCustomPath)) {
+              const customDir = path.join(tempCustomPath, 'custom');
+              if (await fs.pathExists(customDir)) {
+                // Move contents to module directory
+                const items = await fs.readdir(customDir);
+                const movedItems = [];
+                try {
+                  for (const item of items) {
+                    const srcPath = path.join(customDir, item);
+                    const destPath = path.join(moduleTargetPath, item);
+
+                    // If destination exists, remove it first (or we could merge)
+                    if (await fs.pathExists(destPath)) {
+                      await fs.remove(destPath);
+                    }
+
+                    await fs.move(srcPath, destPath);
+                    movedItems.push({ src: srcPath, dest: destPath });
+                  }
+                } catch (moveError) {
+                  // Rollback: restore any successfully moved items
+                  for (const moved of movedItems) {
+                    try {
+                      await fs.move(moved.dest, moved.src);
+                    } catch {
+                      // Best-effort rollback - log if it fails
+                      console.error(`Failed to rollback ${moved.dest} during cleanup`);
+                    }
+                  }
+                  throw new Error(`Failed to move custom module files: ${moveError.message}`);
+                }
+              }
+              try {
+                await fs.remove(tempCustomPath);
+              } catch (cleanupError) {
+                // Non-fatal: temp directory cleanup failed but files were moved successfully
+                console.warn(`Warning: Could not clean up temp directory: ${cleanupError.message}`);
+              }
+            }
+
+            // Create module config (include collected config from module.yaml prompts)
+            await this.generateModuleConfigs(bmadDir, {
+              [moduleName]: { ...config.coreConfig, ...customInfo.config, ...collectedModuleConfig },
+            });
+
+            // Store custom module info for later manifest update
+            if (!config._customModulesToTrack) {
+              config._customModulesToTrack = [];
+            }
+
+            // For cached modules, use appropriate path handling
+            let sourcePath;
+            if (useCache) {
+              // Check if we have cached modules info (from initial install)
+              if (finalCustomContent && finalCustomContent.cachedModules) {
+                sourcePath = finalCustomContent.cachedModules.find((m) => m.id === moduleName)?.relativePath;
+              } else {
+                // During update, the sourcePath is already cache-relative if it starts with _cfg
+                sourcePath =
+                  customInfo.sourcePath && customInfo.sourcePath.startsWith('_cfg')
+                    ? customInfo.sourcePath
+                    : path.relative(bmadDir, customInfo.path || customInfo.sourcePath);
+              }
+            } else {
+              sourcePath = path.resolve(customInfo.path || customInfo.sourcePath);
+            }
+
+            config._customModulesToTrack.push({
+              id: customInfo.id,
+              name: customInfo.name,
+              sourcePath: sourcePath,
+              installDate: new Date().toISOString(),
+            });
+          } else {
+            // Regular module installation
+            // Special case for core module
+            if (moduleName === 'core') {
+              await this.installCoreWithDependencies(bmadDir, resolution.byModule[moduleName]);
+            } else {
+              await this.installModuleWithDependencies(moduleName, bmadDir, resolution.byModule[moduleName]);
+            }
+          }
+
           spinner.succeed(`Module installed: ${moduleName}`);
         }
 
         // Install partial modules (only dependencies)
         for (const [module, files] of Object.entries(resolution.byModule)) {
-          if (!config.modules.includes(module) && module !== 'core') {
+          if (!allModules.includes(module) && module !== 'core') {
             const totalFiles =
               files.agents.length +
               files.tasks.length +
@@ -798,6 +1008,70 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
         }
       }
 
+      // Install custom content if provided AND selected
+      // Process custom content that wasn't installed as modules
+      // This is now handled in the module installation loop above
+      // This section is kept for backward compatibility with any custom content
+      // that doesn't have a module structure
+      const remainingCustomContent = [];
+      if (
+        config.customContent &&
+        config.customContent.hasCustomContent &&
+        config.customContent.customPath &&
+        config.customContent.selected &&
+        config.customContent.selectedFiles
+      ) {
+        // Filter out custom modules that were already installed
+        const customHandler = new CustomHandler();
+        for (const customFile of config.customContent.selectedFiles) {
+          const customInfo = await customHandler.getCustomInfo(customFile, projectDir);
+
+          // Skip if this was installed as a module
+          if (!customInfo || !customInfo.id || !allModules.includes(customInfo.id)) {
+            remainingCustomContent.push(customFile);
+          }
+        }
+      }
+
+      if (remainingCustomContent.length > 0) {
+        spinner.start('Installing remaining custom content...');
+        const customHandler = new CustomHandler();
+
+        // Use the remaining files
+        const customFiles = remainingCustomContent;
+
+        if (customFiles.length > 0) {
+          console.log(chalk.cyan(`\n  Found ${customFiles.length} custom content file(s):`));
+          for (const customFile of customFiles) {
+            const customInfo = await customHandler.getCustomInfo(customFile, projectDir);
+            if (customInfo) {
+              console.log(chalk.dim(`    • ${customInfo.name} (${customInfo.relativePath})`));
+
+              // Install the custom content
+              const result = await customHandler.install(
+                customInfo.path,
+                bmadDir,
+                { ...config.coreConfig, ...customInfo.config },
+                (filePath) => {
+                  // Track installed files
+                  this.installedFiles.push(filePath);
+                },
+              );
+
+              if (result.errors.length > 0) {
+                console.log(chalk.yellow(`    ⚠️  ${result.errors.length} error(s) occurred`));
+                for (const error of result.errors) {
+                  console.log(chalk.dim(`      - ${error}`));
+                }
+              } else {
+                console.log(chalk.green(`    ✓ Installed ${result.agentsInstalled} agents, ${result.workflowsInstalled} workflows`));
+              }
+            }
+          }
+        }
+        spinner.succeed('Custom content installed');
+      }
+
       // Generate clean config.yaml files for each installed module
       spinner.start('Generating module configurations...');
       await this.generateModuleConfigs(bmadDir, moduleConfigs);
@@ -820,14 +1094,37 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
       spinner.start('Generating workflow and agent manifests...');
       const manifestGen = new ManifestGenerator();
 
-      // Include preserved modules (from quick update) in the manifest
-      const allModulesToList = config._preserveModules ? [...(config.modules || []), ...config._preserveModules] : config.modules || [];
+      // For quick update, we need ALL installed modules in the manifest
+      // Not just the ones being updated
+      const allModulesForManifest = config._quickUpdate
+        ? config._existingModules || allModules || []
+        : config._preserveModules
+          ? [...allModules, ...config._preserveModules]
+          : allModules || [];
+
+      // For regular installs (including when called from quick update), use what we have
+      let modulesForCsvPreserve;
+      if (config._quickUpdate) {
+        // Quick update - use existing modules or fall back to modules being updated
+        modulesForCsvPreserve = config._existingModules || allModules || [];
+      } else {
+        // Regular install - use the modules we're installing plus any preserved ones
+        modulesForCsvPreserve = config._preserveModules ? [...allModules, ...config._preserveModules] : allModules;
+      }
 
-      const manifestStats = await manifestGen.generateManifests(bmadDir, config.modules || [], this.installedFiles, {
+      const manifestStats = await manifestGen.generateManifests(bmadDir, allModulesForManifest, this.installedFiles, {
         ides: config.ides || [],
-        preservedModules: config._preserveModules || [], // Scan these from installed bmad/ dir
+        preservedModules: modulesForCsvPreserve, // Scan these from installed bmad/ dir
       });
 
+      // Add custom modules to manifest (now that it exists)
+      if (config._customModulesToTrack && config._customModulesToTrack.length > 0) {
+        spinner.text = 'Storing custom module sources...';
+        for (const customModule of config._customModulesToTrack) {
+          await this.manifest.addCustomModule(bmadDir, customModule);
+        }
+      }
+
       spinner.succeed(
         `Manifests generated: ${manifestStats.workflows} workflows, ${manifestStats.agents} agents, ${manifestStats.tasks} tasks, ${manifestStats.tools} tools, ${manifestStats.files} files`,
       );
@@ -1090,6 +1387,30 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
       const currentVersion = existingInstall.version;
       const newVersion = require(path.join(getProjectRoot(), 'package.json')).version;
 
+      // Check for custom modules with missing sources before update
+      const customModuleSources = new Map();
+      if (existingInstall.customModules) {
+        for (const customModule of existingInstall.customModules) {
+          customModuleSources.set(customModule.id, customModule);
+        }
+      }
+
+      if (customModuleSources.size > 0) {
+        spinner.stop();
+        console.log(chalk.yellow('\nChecking custom module sources before update...'));
+
+        const projectRoot = getProjectRoot();
+        await this.handleMissingCustomSources(
+          customModuleSources,
+          bmadDir,
+          projectRoot,
+          'update',
+          existingInstall.modules.map((m) => m.id),
+        );
+
+        spinner.start('Preparing update...');
+      }
+
       if (config.dryRun) {
         spinner.stop();
         console.log(chalk.cyan('\n🔍 Update Preview (Dry Run)\n'));
@@ -1547,6 +1868,9 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
         // DO NOT replace {project-root} - LLMs understand this placeholder at runtime
         // const processedContent = xmlContent.replaceAll('{project-root}', projectDir);
 
+        // Replace .bmad with actual folder name
+        xmlContent = xmlContent.replaceAll('.bmad', this.bmadFolderName || 'bmad');
+
         // Replace {agent_sidecar_folder} if configured
         const coreConfig = this.configCollector.collectedConfig.core || {};
         if (coreConfig.agent_sidecar_folder && xmlContent.includes('{agent_sidecar_folder}')) {
@@ -1592,7 +1916,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
           // Resolve path variables
           const resolvedSidecarFolder = agentSidecarFolder
             .replaceAll('{project-root}', projectDir)
-            .replaceAll('{bmad_folder}', this.bmadFolderName || 'bmad');
+            .replaceAll('.bmad', this.bmadFolderName || 'bmad');
 
           // Create sidecar directory for this agent
           const agentSidecarDir = path.join(resolvedSidecarFolder, agentName);
@@ -1858,6 +2182,24 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
         throw new Error(`BMAD not installed at ${bmadDir}`);
       }
 
+      // Check for custom modules with missing sources
+      const manifest = await this.manifest.read(bmadDir);
+      if (manifest && manifest.customModules && manifest.customModules.length > 0) {
+        spinner.stop();
+        console.log(chalk.yellow('\nChecking custom module sources before compilation...'));
+
+        const customModuleSources = new Map();
+        for (const customModule of manifest.customModules) {
+          customModuleSources.set(customModule.id, customModule);
+        }
+
+        const projectRoot = getProjectRoot();
+        const installedModules = manifest.modules || [];
+        await this.handleMissingCustomSources(customModuleSources, bmadDir, projectRoot, 'compile-agents', installedModules);
+
+        spinner.start('Rebuilding agent files...');
+      }
+
       let agentCount = 0;
       let taskCount = 0;
 
@@ -2002,17 +2344,234 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
       const existingInstall = await this.detector.detect(bmadDir);
       const installedModules = existingInstall.modules.map((m) => m.id);
       const configuredIdes = existingInstall.ides || [];
+      const projectRoot = path.dirname(bmadDir);
+
+      // Get custom module sources from manifest
+      const customModuleSources = new Map();
+      if (existingInstall.customModules) {
+        for (const customModule of existingInstall.customModules) {
+          // Ensure we have an absolute sourcePath
+          let absoluteSourcePath = customModule.sourcePath;
+
+          // Check if sourcePath is a cache-relative path (starts with _cfg/)
+          if (absoluteSourcePath && absoluteSourcePath.startsWith('_cfg')) {
+            // Convert cache-relative path to absolute path
+            absoluteSourcePath = path.join(bmadDir, absoluteSourcePath);
+          }
+          // If no sourcePath but we have relativePath, convert it
+          else if (!absoluteSourcePath && customModule.relativePath) {
+            // relativePath is relative to the project root (parent of bmad dir)
+            absoluteSourcePath = path.resolve(projectRoot, customModule.relativePath);
+          }
+          // Ensure sourcePath is absolute for anything else
+          else if (absoluteSourcePath && !path.isAbsolute(absoluteSourcePath)) {
+            absoluteSourcePath = path.resolve(absoluteSourcePath);
+          }
+
+          // Update the custom module object with the absolute path
+          const updatedModule = {
+            ...customModule,
+            sourcePath: absoluteSourcePath,
+          };
+
+          customModuleSources.set(customModule.id, updatedModule);
+        }
+      }
 
       // Load saved IDE configurations
       const savedIdeConfigs = await this.ideConfigManager.loadAllIdeConfigs(bmadDir);
 
       // Get available modules (what we have source for)
-      const availableModules = await this.moduleManager.listAvailable();
-      const availableModuleIds = new Set(availableModules.map((m) => m.id));
+      const availableModulesData = await this.moduleManager.listAvailable();
+      const availableModules = [...availableModulesData.modules, ...availableModulesData.customModules];
+
+      // Add custom modules from manifest if their sources exist
+      for (const [moduleId, customModule] of customModuleSources) {
+        // Use the absolute sourcePath
+        const sourcePath = customModule.sourcePath;
+
+        // Check if source exists at the recorded path
+        if (
+          sourcePath &&
+          (await fs.pathExists(sourcePath)) && // Add to available modules if not already there
+          !availableModules.some((m) => m.id === moduleId)
+        ) {
+          availableModules.push({
+            id: moduleId,
+            name: customModule.name || moduleId,
+            path: sourcePath,
+            isCustom: true,
+            fromManifest: true,
+          });
+        }
+      }
+
+      // Check for untracked custom modules (installed but not in manifest)
+      const untrackedCustomModules = [];
+      for (const installedModule of installedModules) {
+        // Skip standard modules and core
+        const standardModuleIds = ['bmb', 'bmgd', 'bmm', 'cis', 'core'];
+        if (standardModuleIds.includes(installedModule)) {
+          continue;
+        }
+
+        // Check if this installed module is not tracked in customModules
+        if (!customModuleSources.has(installedModule)) {
+          const modulePath = path.join(bmadDir, installedModule);
+          if (await fs.pathExists(modulePath)) {
+            untrackedCustomModules.push({
+              id: installedModule,
+              name: installedModule, // We don't have the original name
+              path: modulePath,
+              untracked: true,
+            });
+          }
+        }
+      }
+
+      // If we found untracked custom modules, offer to track them
+      if (untrackedCustomModules.length > 0) {
+        spinner.stop();
+        console.log(chalk.yellow(`\n⚠️  Found ${untrackedCustomModules.length} custom module(s) not tracked in manifest:`));
+
+        for (const untracked of untrackedCustomModules) {
+          console.log(chalk.dim(`  • ${untracked.id} (installed at ${path.relative(projectRoot, untracked.path)})`));
+        }
+
+        const { trackModules } = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'trackModules',
+            message: chalk.cyan('Would you like to scan for their source locations?'),
+            default: true,
+          },
+        ]);
+
+        if (trackModules) {
+          const { scanDirectory } = await inquirer.prompt([
+            {
+              type: 'input',
+              name: 'scanDirectory',
+              message: 'Enter directory to scan for custom module sources (or leave blank to skip):',
+              default: projectRoot,
+              validate: async (input) => {
+                if (input && input.trim() !== '') {
+                  const expandedPath = path.resolve(input.trim());
+                  if (!(await fs.pathExists(expandedPath))) {
+                    return 'Directory does not exist';
+                  }
+                  const stats = await fs.stat(expandedPath);
+                  if (!stats.isDirectory()) {
+                    return 'Path must be a directory';
+                  }
+                }
+                return true;
+              },
+            },
+          ]);
+
+          if (scanDirectory && scanDirectory.trim() !== '') {
+            console.log(chalk.dim('\nScanning for custom module sources...'));
+
+            // Scan for all module.yaml files
+            const allModulePaths = await this.moduleManager.findModulesInProject(scanDirectory);
+            const { ModuleManager } = require('../modules/manager');
+            const mm = new ModuleManager({ scanProjectForModules: true });
+
+            for (const untracked of untrackedCustomModules) {
+              let foundSource = null;
+
+              // Try to find by module ID
+              for (const modulePath of allModulePaths) {
+                try {
+                  const moduleInfo = await mm.getModuleInfo(modulePath);
+                  if (moduleInfo && moduleInfo.id === untracked.id) {
+                    foundSource = {
+                      path: modulePath,
+                      info: moduleInfo,
+                    };
+                    break;
+                  }
+                } catch {
+                  // Continue searching
+                }
+              }
+
+              if (foundSource) {
+                console.log(chalk.green(`  ✓ Found source for ${untracked.id}: ${path.relative(projectRoot, foundSource.path)}`));
+
+                // Add to manifest
+                await this.manifest.addCustomModule(bmadDir, {
+                  id: untracked.id,
+                  name: foundSource.info.name || untracked.name,
+                  sourcePath: path.resolve(foundSource.path),
+                  installDate: new Date().toISOString(),
+                  tracked: true,
+                });
+
+                // Add to customModuleSources for processing
+                customModuleSources.set(untracked.id, {
+                  id: untracked.id,
+                  name: foundSource.info.name || untracked.name,
+                  sourcePath: path.resolve(foundSource.path),
+                });
+              } else {
+                console.log(chalk.yellow(`  ⚠ Could not find source for ${untracked.id}`));
+              }
+            }
+          }
+        }
+
+        console.log(chalk.dim('\nUntracked custom modules will remain installed but cannot be updated without their source.'));
+        spinner.start('Preparing update...');
+      }
+
+      // Handle missing custom module sources using shared method
+      const customModuleResult = await this.handleMissingCustomSources(
+        customModuleSources,
+        bmadDir,
+        projectRoot,
+        'update',
+        installedModules,
+      );
+
+      const { validCustomModules, keptModulesWithoutSources } = customModuleResult;
+
+      const customModulesFromManifest = validCustomModules.map((m) => ({
+        ...m,
+        isCustom: true,
+        hasUpdate: true,
+      }));
+
+      // Add untracked modules to the update list but mark them as untrackable
+      for (const untracked of untrackedCustomModules) {
+        if (!customModuleSources.has(untracked.id)) {
+          customModulesFromManifest.push({
+            ...untracked,
+            isCustom: true,
+            hasUpdate: false, // Can't update without source
+            untracked: true,
+          });
+        }
+      }
+
+      const allAvailableModules = [...availableModules, ...customModulesFromManifest];
+      const availableModuleIds = new Set(allAvailableModules.map((m) => m.id));
+
+      // Core module is special - never include it in update flow
+      const nonCoreInstalledModules = installedModules.filter((id) => id !== 'core');
 
       // Only update modules that are BOTH installed AND available (we have source for)
-      const modulesToUpdate = installedModules.filter((id) => availableModuleIds.has(id));
-      const skippedModules = installedModules.filter((id) => !availableModuleIds.has(id));
+      const modulesToUpdate = nonCoreInstalledModules.filter((id) => availableModuleIds.has(id));
+      const skippedModules = nonCoreInstalledModules.filter((id) => !availableModuleIds.has(id));
+
+      // Add custom modules that were kept without sources to the skipped modules
+      // This ensures their agents are preserved in the manifest
+      for (const keptModule of keptModulesWithoutSources) {
+        if (!skippedModules.includes(keptModule)) {
+          skippedModules.push(keptModule);
+        }
+      }
 
       spinner.succeed(`Found ${modulesToUpdate.length} module(s) to update and ${configuredIdes.length} configured tool(s)`);
 
@@ -2051,7 +2610,6 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
         lastModified: new Date().toISOString(),
       };
 
-      // Check if bmad_folder has changed
       const existingBmadFolderName = path.basename(bmadDir);
       const newBmadFolderName = this.configCollector.collectedConfig.core?.bmad_folder || existingBmadFolderName;
 
@@ -2077,6 +2635,8 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
         _quickUpdate: true, // Flag to skip certain prompts
         _preserveModules: skippedModules, // Preserve these in manifest even though we didn't update them
         _savedIdeConfigs: savedIdeConfigs, // Pass saved IDE configs to installer
+        _customModuleSources: customModuleSources, // Pass custom module sources for updates
+        _existingModules: installedModules, // Pass all installed modules for manifest generation
       };
 
       // Call the standard install method
@@ -2647,7 +3207,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
             const agentSidecarFolder = config.coreConfig?.agent_sidecar_folder;
 
             // Resolve path variables
-            const resolvedSidecarFolder = agentSidecarFolder.replaceAll('{project-root}', projectDir).replaceAll('{bmad_folder}', bmadDir);
+            const resolvedSidecarFolder = agentSidecarFolder.replaceAll('{project-root}', projectDir).replaceAll('.bmad', bmadDir);
 
             // Create sidecar directory for this agent
             const agentSidecarDir = path.join(resolvedSidecarFolder, finalAgentName);
@@ -2716,6 +3276,233 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
       }
     }
   }
+
+  /**
+   * Handle missing custom module sources interactively
+   * @param {Map} customModuleSources - Map of custom module ID to info
+   * @param {string} bmadDir - BMAD directory
+   * @param {string} projectRoot - Project root directory
+   * @param {string} operation - Current operation ('update', 'compile', etc.)
+   * @param {Array} installedModules - Array of installed module IDs (will be modified)
+   * @returns {Object} Object with validCustomModules array and keptModulesWithoutSources array
+   */
+  async handleMissingCustomSources(customModuleSources, bmadDir, projectRoot, operation, installedModules) {
+    const validCustomModules = [];
+    const keptModulesWithoutSources = []; // Track modules kept without sources
+    const customModulesWithMissingSources = [];
+
+    // Check which sources exist
+    for (const [moduleId, customInfo] of customModuleSources) {
+      if (await fs.pathExists(customInfo.sourcePath)) {
+        validCustomModules.push({
+          id: moduleId,
+          name: customInfo.name,
+          path: customInfo.sourcePath,
+          info: customInfo,
+        });
+      } else {
+        customModulesWithMissingSources.push({
+          id: moduleId,
+          name: customInfo.name,
+          sourcePath: customInfo.sourcePath,
+          relativePath: customInfo.relativePath,
+          info: customInfo,
+        });
+      }
+    }
+
+    // If no missing sources, return immediately
+    if (customModulesWithMissingSources.length === 0) {
+      return {
+        validCustomModules,
+        keptModulesWithoutSources: [],
+      };
+    }
+
+    // Stop any spinner for interactive prompts
+    const currentSpinner = ora();
+    if (currentSpinner.isSpinning) {
+      currentSpinner.stop();
+    }
+
+    console.log(chalk.yellow(`\n⚠️  Found ${customModulesWithMissingSources.length} custom module(s) with missing sources:`));
+
+    const inquirer = require('inquirer');
+    let keptCount = 0;
+    let updatedCount = 0;
+    let removedCount = 0;
+
+    for (const missing of customModulesWithMissingSources) {
+      console.log(chalk.dim(`  • ${missing.name} (${missing.id})`));
+      console.log(chalk.dim(`    Original source: ${missing.relativePath}`));
+      console.log(chalk.dim(`    Full path: ${missing.sourcePath}`));
+
+      const choices = [
+        {
+          name: 'Keep installed (will not be processed)',
+          value: 'keep',
+          short: 'Keep',
+        },
+        {
+          name: 'Specify new source location',
+          value: 'update',
+          short: 'Update',
+        },
+      ];
+
+      // Only add remove option if not just compiling agents
+      if (operation !== 'compile-agents') {
+        choices.push({
+          name: '⚠️  REMOVE module completely (destructive!)',
+          value: 'remove',
+          short: 'Remove',
+        });
+      }
+
+      const { action } = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'action',
+          message: `How would you like to handle "${missing.name}"?`,
+          choices,
+        },
+      ]);
+
+      switch (action) {
+        case 'update': {
+          const { newSourcePath } = await inquirer.prompt([
+            {
+              type: 'input',
+              name: 'newSourcePath',
+              message: 'Enter the new path to the custom module:',
+              default: missing.sourcePath,
+              validate: async (input) => {
+                if (!input || input.trim() === '') {
+                  return 'Please enter a path';
+                }
+                const expandedPath = path.resolve(input.trim());
+                if (!(await fs.pathExists(expandedPath))) {
+                  return 'Path does not exist';
+                }
+                // Check if it looks like a valid module
+                const moduleYamlPath = path.join(expandedPath, 'module.yaml');
+                const agentsPath = path.join(expandedPath, 'agents');
+                const workflowsPath = path.join(expandedPath, 'workflows');
+
+                if (!(await fs.pathExists(moduleYamlPath)) && !(await fs.pathExists(agentsPath)) && !(await fs.pathExists(workflowsPath))) {
+                  return 'Path does not appear to contain a valid custom module';
+                }
+                return true;
+              },
+            },
+          ]);
+
+          // Update the source in manifest
+          const resolvedPath = path.resolve(newSourcePath.trim());
+          missing.info.sourcePath = resolvedPath;
+          // Remove relativePath - we only store absolute sourcePath now
+          delete missing.info.relativePath;
+          await this.manifest.addCustomModule(bmadDir, missing.info);
+
+          validCustomModules.push({
+            id: moduleId,
+            name: missing.name,
+            path: resolvedPath,
+            info: missing.info,
+          });
+
+          updatedCount++;
+          console.log(chalk.green(`✓ Updated source location`));
+
+          break;
+        }
+        case 'remove': {
+          // Extra confirmation for destructive remove
+          console.log(chalk.red.bold(`\n⚠️  WARNING: This will PERMANENTLY DELETE "${missing.name}" and all its files!`));
+          console.log(chalk.red(`  Module location: ${path.join(bmadDir, moduleId)}`));
+
+          const { confirm } = await inquirer.prompt([
+            {
+              type: 'confirm',
+              name: 'confirm',
+              message: chalk.red.bold('Are you absolutely sure you want to delete this module?'),
+              default: false,
+            },
+          ]);
+
+          if (confirm) {
+            const { typedConfirm } = await inquirer.prompt([
+              {
+                type: 'input',
+                name: 'typedConfirm',
+                message: chalk.red.bold('Type "DELETE" to confirm permanent deletion:'),
+                validate: (input) => {
+                  if (input !== 'DELETE') {
+                    return chalk.red('You must type "DELETE" exactly to proceed');
+                  }
+                  return true;
+                },
+              },
+            ]);
+
+            if (typedConfirm === 'DELETE') {
+              // Remove the module from filesystem and manifest
+              const modulePath = path.join(bmadDir, moduleId);
+              if (await fs.pathExists(modulePath)) {
+                const fsExtra = require('fs-extra');
+                await fsExtra.remove(modulePath);
+                console.log(chalk.yellow(`  ✓ Deleted module directory: ${path.relative(projectRoot, modulePath)}`));
+              }
+
+              await this.manifest.removeModule(bmadDir, moduleId);
+              await this.manifest.removeCustomModule(bmadDir, moduleId);
+              console.log(chalk.yellow(`  ✓ Removed from manifest`));
+
+              // Also remove from installedModules list
+              if (installedModules && installedModules.includes(moduleId)) {
+                const index = installedModules.indexOf(moduleId);
+                if (index !== -1) {
+                  installedModules.splice(index, 1);
+                }
+              }
+
+              removedCount++;
+              console.log(chalk.red.bold(`✓ "${missing.name}" has been permanently removed`));
+            } else {
+              console.log(chalk.dim('  Removal cancelled - module will be kept'));
+              keptCount++;
+            }
+          } else {
+            console.log(chalk.dim('  Removal cancelled - module will be kept'));
+            keptCount++;
+          }
+
+          break;
+        }
+        case 'keep': {
+          keptCount++;
+          keptModulesWithoutSources.push(moduleId);
+          console.log(chalk.dim(`  Module will be kept as-is`));
+
+          break;
+        }
+        // No default
+      }
+    }
+
+    // Show summary
+    if (keptCount > 0 || updatedCount > 0 || removedCount > 0) {
+      console.log(chalk.dim(`\nSummary for custom modules with missing sources:`));
+      if (keptCount > 0) console.log(chalk.dim(`  • ${keptCount} module(s) kept as-is`));
+      if (updatedCount > 0) console.log(chalk.dim(`  • ${updatedCount} module(s) updated with new sources`));
+      if (removedCount > 0) console.log(chalk.red(`  • ${removedCount} module(s) permanently deleted`));
+    }
+
+    return {
+      validCustomModules,
+      keptModulesWithoutSources,
+    };
+  }
 }
 
 module.exports = { Installer };