bmad-method 6.0.0-alpha.0 → 6.0.0-alpha.10

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

@@ -16,6 +16,7 @@ const { getProjectRoot, getSourcePath, getModulePath } = require('../../../lib/p
 const { AgentPartyGenerator } = require('../../../lib/agent-party-generator');
 const { CLIUtils } = require('../../../lib/cli-utils');
 const { ManifestGenerator } = require('./manifest-generator');
+const { IdeConfigManager } = require('./ide-config-manager');
 
 class Installer {
   constructor() {
@@ -28,72 +29,192 @@ class Installer {
     this.xmlHandler = new XmlHandler();
     this.dependencyResolver = new DependencyResolver();
     this.configCollector = new ConfigCollector();
+    this.ideConfigManager = new IdeConfigManager();
     this.installedFiles = []; // Track all installed files
   }
 
+  /**
+   * Find the bmad installation directory in a project
+   * V6+ installations can use ANY folder name but ALWAYS have _cfg/manifest.yaml
+   * @param {string} projectDir - Project directory
+   * @returns {Promise<string>} Path to bmad directory
+   */
+  async findBmadDir(projectDir) {
+    // Check if project directory exists
+    if (!(await fs.pathExists(projectDir))) {
+      // Project doesn't exist yet, return default
+      return path.join(projectDir, 'bmad');
+    }
+
+    // V6+ strategy: Look for ANY directory with _cfg/manifest.yaml
+    // This is the definitive marker of a V6+ installation
+    try {
+      const entries = await fs.readdir(projectDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const manifestPath = path.join(projectDir, entry.name, '_cfg', 'manifest.yaml');
+          if (await fs.pathExists(manifestPath)) {
+            // Found a V6+ installation
+            return path.join(projectDir, entry.name);
+          }
+        }
+      }
+    } catch {
+      // Ignore errors, fall through to default
+    }
+
+    // No V6+ installation found, return default
+    // This will be used for new installations
+    return path.join(projectDir, 'bmad');
+  }
+
+  /**
+   * Copy a file and replace {bmad_folder} placeholder with actual folder name
+   * @param {string} sourcePath - Source file path
+   * @param {string} targetPath - Target file path
+   * @param {string} bmadFolderName - The bmad folder name to use for replacement
+   */
+  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 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 {bmad_folder} placeholder with actual folder name
+        if (content.includes('{bmad_folder}')) {
+          content = content.replaceAll('{bmad_folder}', 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 });
+    }
+  }
+
   /**
    * Collect Tool/IDE configurations after module configuration
    * @param {string} projectDir - Project directory
    * @param {Array} selectedModules - Selected modules from configuration
+   * @param {boolean} isFullReinstall - Whether this is a full reinstall
+   * @param {Array} previousIdes - Previously configured IDEs (for reinstalls)
+   * @param {Array} preSelectedIdes - Pre-selected IDEs from early prompt (optional)
    * @returns {Object} Tool/IDE selection and configurations
    */
-  async collectToolConfigurations(projectDir, selectedModules) {
-    // Prompt for tool selection
-    const { UI } = require('../../../lib/ui');
-    const ui = new UI();
-    const toolConfig = await ui.promptToolSelection(projectDir, selectedModules);
+  async collectToolConfigurations(projectDir, selectedModules, isFullReinstall = false, previousIdes = [], preSelectedIdes = null) {
+    // Use pre-selected IDEs if provided, otherwise prompt
+    let toolConfig;
+    if (preSelectedIdes === null) {
+      // Fallback: prompt for tool selection (backwards compatibility)
+      const { UI } = require('../../../lib/ui');
+      const ui = new UI();
+      toolConfig = await ui.promptToolSelection(projectDir, selectedModules);
+    } else {
+      // IDEs were already selected during initial prompts
+      toolConfig = {
+        ides: preSelectedIdes,
+        skipIde: !preSelectedIdes || preSelectedIdes.length === 0,
+      };
+    }
+
+    // Check for already configured IDEs
+    const { Detector } = require('./detector');
+    const detector = new Detector();
+    const bmadDir = path.join(projectDir, this.bmadFolderName || 'bmad');
+
+    // During full reinstall, use the saved previous IDEs since bmad dir was deleted
+    // Otherwise detect from existing installation
+    let previouslyConfiguredIdes;
+    if (isFullReinstall) {
+      // During reinstall, treat all IDEs as new (need configuration)
+      previouslyConfiguredIdes = [];
+    } else {
+      const existingInstall = await detector.detect(bmadDir);
+      previouslyConfiguredIdes = existingInstall.ides || [];
+    }
+
+    // Load saved IDE configurations for already-configured IDEs
+    const savedIdeConfigs = await this.ideConfigManager.loadAllIdeConfigs(bmadDir);
 
     // Collect IDE-specific configurations if any were selected
     const ideConfigurations = {};
-    const bmadDir = path.join(projectDir, 'bmad');
+
+    // First, add saved configs for already-configured IDEs
+    for (const ide of toolConfig.ides || []) {
+      if (previouslyConfiguredIdes.includes(ide) && savedIdeConfigs[ide]) {
+        ideConfigurations[ide] = savedIdeConfigs[ide];
+      }
+    }
 
     if (!toolConfig.skipIde && toolConfig.ides && toolConfig.ides.length > 0) {
-      console.log('\n'); // Add spacing before IDE questions
-
-      for (const ide of toolConfig.ides) {
-        // List of IDEs that have interactive prompts
-        const needsPrompts = ['claude-code', 'github-copilot', 'roo', 'cline', 'auggie', 'codex', 'qwen', 'gemini'].includes(ide);
-
-        if (needsPrompts) {
-          // Get IDE handler and collect configuration
-          try {
-            // Dynamically load the IDE setup module
-            const ideModule = require(`../ide/${ide}`);
-
-            // Get the setup class (handle different export formats)
-            let SetupClass;
-            const className =
-              ide
-                .split('-')
-                .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-                .join('') + 'Setup';
-
-            if (ideModule[className]) {
-              SetupClass = ideModule[className];
-            } else if (ideModule.default) {
-              SetupClass = ideModule.default;
-            } else {
-              // Skip if no setup class found
-              continue;
-            }
+      // Determine which IDEs are newly selected (not previously configured)
+      const newlySelectedIdes = toolConfig.ides.filter((ide) => !previouslyConfiguredIdes.includes(ide));
+
+      if (newlySelectedIdes.length > 0) {
+        console.log('\n'); // Add spacing before IDE questions
+
+        for (const ide of newlySelectedIdes) {
+          // List of IDEs that have interactive prompts
+          const needsPrompts = ['claude-code', 'github-copilot', 'roo', 'cline', 'auggie', 'codex', 'qwen', 'gemini'].includes(ide);
+
+          if (needsPrompts) {
+            // Get IDE handler and collect configuration
+            try {
+              // Dynamically load the IDE setup module
+              const ideModule = require(`../ide/${ide}`);
+
+              // Get the setup class (handle different export formats)
+              let SetupClass;
+              const className =
+                ide
+                  .split('-')
+                  .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+                  .join('') + 'Setup';
+
+              if (ideModule[className]) {
+                SetupClass = ideModule[className];
+              } else if (ideModule.default) {
+                SetupClass = ideModule.default;
+              } else {
+                // Skip if no setup class found
+                continue;
+              }
 
-            const ideSetup = new SetupClass();
+              const ideSetup = new SetupClass();
 
-            // Check if this IDE has a collectConfiguration method
-            if (typeof ideSetup.collectConfiguration === 'function') {
-              console.log(chalk.cyan(`\nConfiguring ${ide}...`));
-              ideConfigurations[ide] = await ideSetup.collectConfiguration({
-                selectedModules: selectedModules || [],
-                projectDir,
-                bmadDir,
-              });
+              // Check if this IDE has a collectConfiguration method
+              if (typeof ideSetup.collectConfiguration === 'function') {
+                console.log(chalk.cyan(`\nConfiguring ${ide}...`));
+                ideConfigurations[ide] = await ideSetup.collectConfiguration({
+                  selectedModules: selectedModules || [],
+                  projectDir,
+                  bmadDir,
+                });
+              }
+            } catch {
+              // IDE doesn't have a setup file or collectConfiguration method
+              console.warn(chalk.yellow(`Warning: Could not load configuration for ${ide}`));
             }
-          } catch {
-            // IDE doesn't have a setup file or collectConfiguration method
-            console.warn(chalk.yellow(`Warning: Could not load configuration for ${ide}`));
           }
         }
       }
+
+      // Log which IDEs are already configured and being kept
+      const keptIdes = toolConfig.ides.filter((ide) => previouslyConfiguredIdes.includes(ide));
+      if (keptIdes.length > 0) {
+        console.log(chalk.dim(`\nKeeping existing configuration for: ${keptIdes.join(', ')}`));
+      }
     }
 
     return {
@@ -119,13 +240,10 @@ class Installer {
     // Display welcome message
     CLIUtils.displaySection('BMAD™ Installation', 'Version ' + require(path.join(getProjectRoot(), 'package.json')).version);
 
-    // Preflight: Block legacy BMAD v4 footprints before any prompts/writes
+    // Note: Legacy V4 detection now happens earlier in UI.promptInstall()
+    // before any config collection, so we don't need to check again here
+
     const projectDir = path.resolve(config.directory);
-    const legacyV4 = await this.detector.detectLegacyV4(projectDir);
-    if (legacyV4.hasLegacyV4) {
-      const error = this.createLegacyV4Error(legacyV4);
-      throw error;
-    }
 
     // If core config was pre-collected (from interactive mode), use it
     if (config.coreConfig) {
@@ -137,15 +255,25 @@ class Installer {
       }
     }
 
-    // Collect configurations for modules (core was already collected in UI.promptInstall if interactive)
-    const moduleConfigs = await this.configCollector.collectAllConfigurations(config.modules || [], path.resolve(config.directory));
+    // Collect configurations for modules (skip if quick update already collected them)
+    let moduleConfigs;
+    if (config._quickUpdate) {
+      // Quick update already collected all configs, use them directly
+      moduleConfigs = this.configCollector.collectedConfig;
+    } else {
+      // Regular install - collect configurations (core was already collected in UI.promptInstall if interactive)
+      moduleConfigs = await this.configCollector.collectAllConfigurations(config.modules || [], path.resolve(config.directory));
+    }
+
+    // Get bmad_folder from config (default to 'bmad' for backwards compatibility)
+    const bmadFolderName = moduleConfigs.core && moduleConfigs.core.bmad_folder ? moduleConfigs.core.bmad_folder : 'bmad';
+    this.bmadFolderName = bmadFolderName; // Store for use in other methods
 
-    const toolSelection = await this.collectToolConfigurations(path.resolve(config.directory), config.modules);
+    // Set bmad folder name on module manager and IDE manager for placeholder replacement
+    this.moduleManager.setBmadFolderName(bmadFolderName);
+    this.ideManager.setBmadFolderName(bmadFolderName);
 
-    // Merge tool selection into config
-    config.ides = toolSelection.ides;
-    config.skipIde = toolSelection.skipIde;
-    const ideConfigurations = toolSelection.configurations;
+    // Tool selection will be collected after we determine if it's a reinstall/update/new install
 
     const spinner = ora('Preparing installation...').start();
 
@@ -153,6 +281,63 @@ class Installer {
       // 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;
+
+      if (await fs.pathExists(projectDir)) {
+        existingBmadDir = await this.findBmadDir(projectDir);
+        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...';
@@ -173,27 +358,217 @@ class Installer {
         }
       }
 
-      const bmadDir = path.join(projectDir, 'bmad');
+      const bmadDir = path.join(projectDir, bmadFolderName);
 
       // Check existing installation
       spinner.text = 'Checking for existing installation...';
       const existingInstall = await this.detector.detect(bmadDir);
 
-      if (existingInstall.installed && !config.force) {
+      if (existingInstall.installed && !config.force && !config._quickUpdate) {
         spinner.stop();
 
-        console.log(chalk.yellow('\n⚠️  Existing BMAD installation detected'));
-        console.log(chalk.dim(`  Location: ${bmadDir}`));
-        console.log(chalk.dim(`  Version: ${existingInstall.version}`));
+        // Check if user already decided what to do (from early menu in ui.js)
+        let action = null;
+        if (config._requestedReinstall) {
+          action = 'reinstall';
+        } else if (config.actionType === 'update') {
+          action = 'update';
+        } else {
+          // Fallback: Ask the user (backwards compatibility for other code paths)
+          console.log(chalk.yellow('\n⚠️  Existing BMAD installation detected'));
+          console.log(chalk.dim(`  Location: ${bmadDir}`));
+          console.log(chalk.dim(`  Version: ${existingInstall.version}`));
+
+          const promptResult = await this.promptUpdateAction();
+          action = promptResult.action;
+        }
 
-        // TODO: Handle update scenario
-        const { action } = await this.promptUpdateAction();
         if (action === 'cancel') {
           console.log('Installation cancelled.');
-          return;
+          return { success: false, cancelled: true };
+        }
+
+        if (action === 'reinstall') {
+          // Warn about destructive operation
+          console.log(chalk.red.bold('\n⚠️  WARNING: This is a destructive operation!'));
+          console.log(chalk.red('All custom files and modifications in the bmad directory will be lost.'));
+
+          const inquirer = require('inquirer');
+          const { confirmReinstall } = await inquirer.prompt([
+            {
+              type: 'confirm',
+              name: 'confirmReinstall',
+              message: chalk.yellow('Are you sure you want to delete and reinstall?'),
+              default: false,
+            },
+          ]);
+
+          if (!confirmReinstall) {
+            console.log('Installation cancelled.');
+            return { success: false, cancelled: true };
+          }
+
+          // Remember previously configured IDEs before deleting
+          config._previouslyConfiguredIdes = existingInstall.ides || [];
+
+          // Remove existing installation
+          await fs.remove(bmadDir);
+          console.log(chalk.green('✓ Removed existing installation\n'));
+
+          // Mark this as a full reinstall so we re-collect IDE configurations
+          config._isFullReinstall = true;
+        } else if (action === 'update') {
+          // Store that we're updating for later processing
+          config._isUpdate = true;
+          config._existingInstall = existingInstall;
+
+          // Detect custom and modified files BEFORE updating (compare current files vs files-manifest.csv)
+          const existingFilesManifest = await this.readFilesManifest(bmadDir);
+          console.log(chalk.dim(`DEBUG: Read ${existingFilesManifest.length} files from manifest`));
+          console.log(chalk.dim(`DEBUG: Manifest has hashes: ${existingFilesManifest.some((f) => f.hash)}`));
+
+          const { customFiles, modifiedFiles } = await this.detectCustomFiles(bmadDir, existingFilesManifest);
+
+          console.log(chalk.dim(`DEBUG: Found ${customFiles.length} custom files, ${modifiedFiles.length} modified files`));
+          if (modifiedFiles.length > 0) {
+            console.log(chalk.yellow('DEBUG: Modified files:'));
+            for (const f of modifiedFiles) console.log(chalk.dim(`  - ${f.path}`));
+          }
+
+          config._customFiles = customFiles;
+          config._modifiedFiles = modifiedFiles;
+
+          // If there are custom files, back them up temporarily
+          if (customFiles.length > 0) {
+            const tempBackupDir = path.join(projectDir, '.bmad-custom-backup-temp');
+            await fs.ensureDir(tempBackupDir);
+
+            spinner.start(`Backing up ${customFiles.length} custom files...`);
+            for (const customFile of customFiles) {
+              const relativePath = path.relative(bmadDir, customFile);
+              const backupPath = path.join(tempBackupDir, relativePath);
+              await fs.ensureDir(path.dirname(backupPath));
+              await fs.copy(customFile, backupPath);
+            }
+            spinner.succeed(`Backed up ${customFiles.length} custom files`);
+
+            config._tempBackupDir = tempBackupDir;
+          }
+
+          // For modified files, back them up to temp directory (will be restored as .bak files after install)
+          if (modifiedFiles.length > 0) {
+            const tempModifiedBackupDir = path.join(projectDir, '.bmad-modified-backup-temp');
+            await fs.ensureDir(tempModifiedBackupDir);
+
+            console.log(chalk.yellow(`\nDEBUG: Backing up ${modifiedFiles.length} modified files to temp location`));
+            spinner.start(`Backing up ${modifiedFiles.length} modified files...`);
+            for (const modifiedFile of modifiedFiles) {
+              const relativePath = path.relative(bmadDir, modifiedFile.path);
+              const tempBackupPath = path.join(tempModifiedBackupDir, relativePath);
+              console.log(chalk.dim(`DEBUG: Backing up ${relativePath} to temp`));
+              await fs.ensureDir(path.dirname(tempBackupPath));
+              await fs.copy(modifiedFile.path, tempBackupPath, { overwrite: true });
+            }
+            spinner.succeed(`Backed up ${modifiedFiles.length} modified files`);
+
+            config._tempModifiedBackupDir = tempModifiedBackupDir;
+          } else {
+            console.log(chalk.dim('DEBUG: No modified files detected'));
+          }
+        }
+      } else if (existingInstall.installed && config._quickUpdate) {
+        // Quick update mode - automatically treat as update without prompting
+        spinner.text = 'Preparing quick update...';
+        config._isUpdate = true;
+        config._existingInstall = existingInstall;
+
+        // Detect custom and modified files BEFORE updating
+        const existingFilesManifest = await this.readFilesManifest(bmadDir);
+        const { customFiles, modifiedFiles } = await this.detectCustomFiles(bmadDir, existingFilesManifest);
+
+        config._customFiles = customFiles;
+        config._modifiedFiles = modifiedFiles;
+
+        // Back up custom files
+        if (customFiles.length > 0) {
+          const tempBackupDir = path.join(projectDir, '.bmad-custom-backup-temp');
+          await fs.ensureDir(tempBackupDir);
+
+          spinner.start(`Backing up ${customFiles.length} custom files...`);
+          for (const customFile of customFiles) {
+            const relativePath = path.relative(bmadDir, customFile);
+            const backupPath = path.join(tempBackupDir, relativePath);
+            await fs.ensureDir(path.dirname(backupPath));
+            await fs.copy(customFile, backupPath);
+          }
+          spinner.succeed(`Backed up ${customFiles.length} custom files`);
+          config._tempBackupDir = tempBackupDir;
+        }
+
+        // Back up modified files
+        if (modifiedFiles.length > 0) {
+          const tempModifiedBackupDir = path.join(projectDir, '.bmad-modified-backup-temp');
+          await fs.ensureDir(tempModifiedBackupDir);
+
+          spinner.start(`Backing up ${modifiedFiles.length} modified files...`);
+          for (const modifiedFile of modifiedFiles) {
+            const relativePath = path.relative(bmadDir, modifiedFile.path);
+            const tempBackupPath = path.join(tempModifiedBackupDir, relativePath);
+            await fs.ensureDir(path.dirname(tempBackupPath));
+            await fs.copy(modifiedFile.path, tempBackupPath, { overwrite: true });
+          }
+          spinner.succeed(`Backed up ${modifiedFiles.length} modified files`);
+          config._tempModifiedBackupDir = tempModifiedBackupDir;
         }
       }
 
+      // Now collect tool configurations after we know if it's a reinstall
+      // Skip for quick update since we already have the IDE list
+      spinner.stop();
+      let toolSelection;
+      if (config._quickUpdate) {
+        // Quick update already has IDEs configured, use saved configurations
+        const preConfiguredIdes = {};
+        const savedIdeConfigs = config._savedIdeConfigs || {};
+
+        for (const ide of config.ides || []) {
+          // Use saved config if available, otherwise mark as already configured (legacy)
+          if (savedIdeConfigs[ide]) {
+            preConfiguredIdes[ide] = savedIdeConfigs[ide];
+          } else {
+            preConfiguredIdes[ide] = { _alreadyConfigured: true };
+          }
+        }
+        toolSelection = {
+          ides: config.ides || [],
+          skipIde: !config.ides || config.ides.length === 0,
+          configurations: preConfiguredIdes,
+        };
+      } else {
+        // Pass pre-selected IDEs from early prompt (if available)
+        // This allows IDE selection to happen before file copying, improving UX
+        const preSelectedIdes = config.ides && config.ides.length > 0 ? config.ides : null;
+        toolSelection = await this.collectToolConfigurations(
+          path.resolve(config.directory),
+          config.modules,
+          config._isFullReinstall || false,
+          config._previouslyConfiguredIdes || [],
+          preSelectedIdes,
+        );
+      }
+
+      // Merge tool selection into config (for both quick update and regular flow)
+      config.ides = toolSelection.ides;
+      config.skipIde = toolSelection.skipIde;
+      const ideConfigurations = toolSelection.configurations;
+
+      // Check if spinner is already running (e.g., from folder name change scenario)
+      if (spinner.isSpinning) {
+        spinner.text = 'Continuing installation...';
+      } else {
+        spinner.start('Continuing installation...');
+      }
+
       // Create bmad directory structure
       spinner.text = 'Creating directory structure...';
       await this.createDirectoryStructure(bmadDir);
@@ -230,7 +605,13 @@ class Installer {
         // Install partial modules (only dependencies)
         for (const [module, files] of Object.entries(resolution.byModule)) {
           if (!config.modules.includes(module) && module !== 'core') {
-            const totalFiles = files.agents.length + files.tasks.length + files.templates.length + files.data.length + files.other.length;
+            const totalFiles =
+              files.agents.length +
+              files.tasks.length +
+              files.tools.length +
+              files.templates.length +
+              files.data.length +
+              files.other.length;
             if (totalFiles > 0) {
               spinner.start(`Installing ${module} dependencies...`);
               await this.installPartialModule(module, bmadDir, files);
@@ -246,57 +627,102 @@ class Installer {
       spinner.succeed('Module configurations generated');
 
       // Create agent configuration files
-      spinner.start('Creating agent configurations...');
-      // Get user info from collected config if available
-      const userInfo = {
-        userName: moduleConfigs.core?.['user_name'] || null,
-        responseLanguage: moduleConfigs.core?.['communication_language'] || null,
-      };
-      const agentConfigResult = await this.createAgentConfigs(bmadDir, userInfo);
-      if (agentConfigResult.skipped > 0) {
-        spinner.succeed(`Agent configurations: ${agentConfigResult.created} created, ${agentConfigResult.skipped} preserved`);
-      } else {
-        spinner.succeed(`Agent configurations created: ${agentConfigResult.created}`);
-      }
+      // Note: Legacy createAgentConfigs removed - using YAML customize system instead
+      // Customize templates are now created in processAgentFiles when building YAML agents
+
+      // Pre-register manifest files that will be created (except files-manifest.csv to avoid recursion)
+      const cfgDir = path.join(bmadDir, '_cfg');
+      this.installedFiles.push(
+        path.join(cfgDir, 'manifest.yaml'),
+        path.join(cfgDir, 'workflow-manifest.csv'),
+        path.join(cfgDir, 'agent-manifest.csv'),
+        path.join(cfgDir, 'task-manifest.csv'),
+      );
 
-      // Generate CSV manifests for workflows, agents, and tasks BEFORE IDE setup
+      // Generate CSV manifests for workflows, agents, tasks AND ALL FILES with hashes BEFORE IDE setup
       spinner.start('Generating workflow and agent manifests...');
       const manifestGen = new ManifestGenerator();
-      const manifestStats = await manifestGen.generateManifests(bmadDir, config.modules || []);
+
+      // Include preserved modules (from quick update) in the manifest
+      const allModulesToList = config._preserveModules ? [...(config.modules || []), ...config._preserveModules] : config.modules || [];
+
+      const manifestStats = await manifestGen.generateManifests(bmadDir, config.modules || [], this.installedFiles, {
+        ides: config.ides || [],
+        preservedModules: config._preserveModules || [], // Scan these from installed bmad/ dir
+      });
+
       spinner.succeed(
-        `Manifests generated: ${manifestStats.workflows} workflows, ${manifestStats.agents} agents, ${manifestStats.tasks} tasks`,
+        `Manifests generated: ${manifestStats.workflows} workflows, ${manifestStats.agents} agents, ${manifestStats.tasks} tasks, ${manifestStats.tools} tools, ${manifestStats.files} files`,
       );
 
       // Configure IDEs and copy documentation
       if (!config.skipIde && config.ides && config.ides.length > 0) {
-        spinner.start('Configuring IDEs...');
+        // Filter out any undefined/null values from the IDE list
+        const validIdes = config.ides.filter((ide) => ide && typeof ide === 'string');
 
-        // Temporarily suppress console output if not verbose
-        const originalLog = console.log;
-        if (!config.verbose) {
-          console.log = () => {};
-        }
+        if (validIdes.length === 0) {
+          console.log(chalk.yellow('⚠️  No valid IDEs selected. Skipping IDE configuration.'));
+        } else {
+          // Check if any IDE might need prompting (no pre-collected config)
+          const needsPrompting = validIdes.some((ide) => !ideConfigurations[ide]);
 
-        for (const ide of config.ides) {
-          spinner.text = `Configuring ${ide}...`;
+          if (!needsPrompting) {
+            spinner.start('Configuring IDEs...');
+          }
 
-          // Pass pre-collected configuration to avoid re-prompting
-          await this.ideManager.setup(ide, projectDir, bmadDir, {
-            selectedModules: config.modules || [],
-            preCollectedConfig: ideConfigurations[ide] || null,
-            verbose: config.verbose,
-          });
-        }
+          // Temporarily suppress console output if not verbose
+          const originalLog = console.log;
+          if (!config.verbose) {
+            console.log = () => {};
+          }
+
+          for (const ide of validIdes) {
+            // Only show spinner if we have pre-collected config (no prompts expected)
+            if (ideConfigurations[ide] && !needsPrompting) {
+              spinner.text = `Configuring ${ide}...`;
+            } else if (!ideConfigurations[ide]) {
+              // Stop spinner before prompting
+              if (spinner.isSpinning) {
+                spinner.stop();
+              }
+              console.log(chalk.cyan(`\nConfiguring ${ide}...`));
+            }
+
+            // Pass pre-collected configuration to avoid re-prompting
+            await this.ideManager.setup(ide, projectDir, bmadDir, {
+              selectedModules: config.modules || [],
+              preCollectedConfig: ideConfigurations[ide] || null,
+              verbose: config.verbose,
+            });
 
-        // Restore console.log
-        console.log = originalLog;
+            // Save IDE configuration for future updates
+            if (ideConfigurations[ide] && !ideConfigurations[ide]._alreadyConfigured) {
+              await this.ideConfigManager.saveIdeConfig(bmadDir, ide, ideConfigurations[ide]);
+            }
+
+            // Restart spinner if we stopped it
+            if (!ideConfigurations[ide] && !spinner.isSpinning) {
+              spinner.start('Configuring IDEs...');
+            }
+          }
 
-        spinner.succeed(`Configured ${config.ides.length} IDE${config.ides.length > 1 ? 's' : ''}`);
+          // Restore console.log
+          console.log = originalLog;
+
+          if (spinner.isSpinning) {
+            spinner.succeed(`Configured ${validIdes.length} IDE${validIdes.length > 1 ? 's' : ''}`);
+          } else {
+            console.log(chalk.green(`✓ Configured ${validIdes.length} IDE${validIdes.length > 1 ? 's' : ''}`));
+          }
+        }
 
-        // Copy IDE-specific documentation
-        spinner.start('Copying IDE documentation...');
-        await this.copyIdeDocumentation(config.ides, bmadDir);
-        spinner.succeed('IDE documentation copied');
+        // Copy IDE-specific documentation (only for valid IDEs)
+        const validIdesForDocs = (config.ides || []).filter((ide) => ide && typeof ide === 'string');
+        if (validIdesForDocs.length > 0) {
+          spinner.start('Copying IDE documentation...');
+          await this.copyIdeDocumentation(validIdesForDocs, bmadDir);
+          spinner.succeed('IDE documentation copied');
+        }
       }
 
       // Run module-specific installers after IDE setup
@@ -337,24 +763,83 @@ class Installer {
 
       spinner.succeed('Module-specific installers completed');
 
-      // Create manifest
-      spinner.start('Creating installation manifest...');
-      const manifestResult = await this.manifest.create(
-        bmadDir,
-        {
-          version: require(path.join(getProjectRoot(), 'package.json')).version,
-          installDate: new Date().toISOString(),
-          core: config.installCore,
-          modules: config.modules || [],
-          ides: config.ides || [],
-          language: config.language || null,
-        },
-        this.installedFiles,
-      );
-      spinner.succeed(`Manifest created (${manifestResult.filesTracked} files tracked)`);
+      // Note: Manifest files are already created by ManifestGenerator above
+      // No need to create legacy manifest.csv anymore
+
+      // If this was an update, restore custom files
+      let customFiles = [];
+      let modifiedFiles = [];
+      if (config._isUpdate) {
+        if (config._customFiles && config._customFiles.length > 0) {
+          spinner.start(`Restoring ${config._customFiles.length} custom files...`);
+
+          for (const originalPath of config._customFiles) {
+            const relativePath = path.relative(bmadDir, originalPath);
+            const backupPath = path.join(config._tempBackupDir, relativePath);
+
+            if (await fs.pathExists(backupPath)) {
+              await fs.ensureDir(path.dirname(originalPath));
+              await fs.copy(backupPath, originalPath, { overwrite: true });
+            }
+          }
+
+          // Clean up temp backup
+          if (config._tempBackupDir && (await fs.pathExists(config._tempBackupDir))) {
+            await fs.remove(config._tempBackupDir);
+          }
+
+          spinner.succeed(`Restored ${config._customFiles.length} custom files`);
+          customFiles = config._customFiles;
+        }
+
+        if (config._modifiedFiles && config._modifiedFiles.length > 0) {
+          modifiedFiles = config._modifiedFiles;
+
+          // Restore modified files as .bak files
+          if (config._tempModifiedBackupDir && (await fs.pathExists(config._tempModifiedBackupDir))) {
+            spinner.start(`Restoring ${modifiedFiles.length} modified files as .bak...`);
+
+            for (const modifiedFile of modifiedFiles) {
+              const relativePath = path.relative(bmadDir, modifiedFile.path);
+              const tempBackupPath = path.join(config._tempModifiedBackupDir, relativePath);
+              const bakPath = modifiedFile.path + '.bak';
+
+              if (await fs.pathExists(tempBackupPath)) {
+                await fs.ensureDir(path.dirname(bakPath));
+                await fs.copy(tempBackupPath, bakPath, { overwrite: true });
+              }
+            }
+
+            // Clean up temp backup
+            await fs.remove(config._tempModifiedBackupDir);
+
+            spinner.succeed(`Restored ${modifiedFiles.length} modified files as .bak`);
+          }
+        }
+      }
 
       spinner.stop();
 
+      // Report custom and modified files if any were found
+      if (customFiles.length > 0) {
+        console.log(chalk.cyan(`\n📁 Custom files preserved: ${customFiles.length}`));
+        console.log(chalk.dim('The following custom files were found and restored:\n'));
+        for (const file of customFiles) {
+          console.log(chalk.dim(`  - ${path.relative(bmadDir, file)}`));
+        }
+        console.log('');
+      }
+
+      if (modifiedFiles.length > 0) {
+        console.log(chalk.yellow(`\n⚠️  Modified files detected: ${modifiedFiles.length}`));
+        console.log(chalk.dim('The following files were modified and backed up with .bak extension:\n'));
+        for (const file of modifiedFiles) {
+          console.log(chalk.dim(`  - ${file.relativePath} → ${file.relativePath}.bak`));
+        }
+        console.log(chalk.dim('\nThese files have been updated with the new version.'));
+        console.log(chalk.dim('Review the .bak files to see your changes and merge if needed.\n'));
+      }
+
       // Display completion message
       const { UI } = require('../../../lib/ui');
       const ui = new UI();
@@ -362,6 +847,7 @@ class Installer {
         path: bmadDir,
         modules: config.modules,
         ides: config.ides,
+        customFiles: customFiles.length > 0 ? customFiles : undefined,
       });
 
       return { success: true, path: bmadDir, modules: config.modules, ides: config.ides };
@@ -378,7 +864,8 @@ class Installer {
     const spinner = ora('Checking installation...').start();
 
     try {
-      const bmadDir = path.join(path.resolve(config.directory), 'bmad');
+      const projectDir = path.resolve(config.directory);
+      const bmadDir = await this.findBmadDir(projectDir);
       const existingInstall = await this.detector.detect(bmadDir);
 
       if (!existingInstall.installed) {
@@ -438,7 +925,8 @@ class Installer {
    * Get installation status
    */
   async getStatus(directory) {
-    const bmadDir = path.join(path.resolve(directory), 'bmad');
+    const projectDir = path.resolve(directory);
+    const bmadDir = await this.findBmadDir(projectDir);
     return await this.detector.detect(bmadDir);
   }
 
@@ -453,14 +941,15 @@ class Installer {
    * Uninstall BMAD
    */
   async uninstall(directory) {
-    const bmadDir = path.join(path.resolve(directory), 'bmad');
+    const projectDir = path.resolve(directory);
+    const bmadDir = await this.findBmadDir(projectDir);
 
     if (await fs.pathExists(bmadDir)) {
       await fs.remove(bmadDir);
     }
 
     // Clean up IDE configurations
-    await this.ideManager.cleanup(path.resolve(directory));
+    await this.ideManager.cleanup(projectDir);
 
     return { success: true };
   }
@@ -558,8 +1047,12 @@ class Installer {
           }
         }
 
-        // Write the clean config file
-        await fs.writeFile(configPath, header + yamlContent, 'utf8');
+        // Write the clean config file with POSIX-compliant final newline
+        const content = header + yamlContent;
+        await fs.writeFile(configPath, content.endsWith('\n') ? content : content + '\n', 'utf8');
+
+        // Track the config file in installedFiles
+        this.installedFiles.push(configPath);
       }
     }
   }
@@ -589,6 +1082,9 @@ class Installer {
    * @param {Object} moduleFiles - Module files to install
    */
   async installModuleWithDependencies(moduleName, bmadDir, moduleFiles) {
+    // Get module configuration for conditional installation
+    const moduleConfig = this.configCollector.collectedConfig[moduleName] || {};
+
     // Use existing module manager for full installation with file tracking
     // Note: Module-specific installers are called separately after IDE setup
     await this.moduleManager.install(
@@ -599,9 +1095,14 @@ class Installer {
       },
       {
         skipModuleInstaller: true, // We'll run it later after IDE setup
+        moduleConfig: moduleConfig, // Pass module config for conditional filtering
       },
     );
 
+    // Process agent files to build YAML agents and create customize templates
+    const modulePath = path.join(bmadDir, moduleName);
+    await this.processAgentFiles(modulePath, moduleName);
+
     // Dependencies are already included in full module install
   }
 
@@ -626,7 +1127,7 @@ class Installer {
         const targetPath = path.join(agentsDir, fileName);
 
         if (await fs.pathExists(sourcePath)) {
-          await fs.copy(sourcePath, targetPath);
+          await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath, this.bmadFolderName || 'bmad');
           this.installedFiles.push(targetPath);
         }
       }
@@ -642,7 +1143,23 @@ class Installer {
         const targetPath = path.join(tasksDir, fileName);
 
         if (await fs.pathExists(sourcePath)) {
-          await fs.copy(sourcePath, targetPath);
+          await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath, this.bmadFolderName || 'bmad');
+          this.installedFiles.push(targetPath);
+        }
+      }
+    }
+
+    if (files.tools && files.tools.length > 0) {
+      const toolsDir = path.join(targetBase, 'tools');
+      await fs.ensureDir(toolsDir);
+
+      for (const toolPath of files.tools) {
+        const fileName = path.basename(toolPath);
+        const sourcePath = path.join(sourceBase, 'tools', fileName);
+        const targetPath = path.join(toolsDir, fileName);
+
+        if (await fs.pathExists(sourcePath)) {
+          await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath, this.bmadFolderName || 'bmad');
           this.installedFiles.push(targetPath);
         }
       }
@@ -658,7 +1175,7 @@ class Installer {
         const targetPath = path.join(templatesDir, fileName);
 
         if (await fs.pathExists(sourcePath)) {
-          await fs.copy(sourcePath, targetPath);
+          await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath, this.bmadFolderName || 'bmad');
           this.installedFiles.push(targetPath);
         }
       }
@@ -673,7 +1190,7 @@ class Installer {
         await fs.ensureDir(path.dirname(targetPath));
 
         if (await fs.pathExists(dataPath)) {
-          await fs.copy(dataPath, targetPath);
+          await this.copyFileWithPlaceholderReplacement(dataPath, targetPath, this.bmadFolderName || 'bmad');
           this.installedFiles.push(targetPath);
         }
       }
@@ -733,9 +1250,8 @@ class Installer {
         }
       }
 
-      // Copy the file
-      await fs.ensureDir(path.dirname(targetFile));
-      await fs.copy(sourceFile, targetFile, { overwrite: true });
+      // Copy the file with placeholder replacement
+      await this.copyFileWithPlaceholderReplacement(sourceFile, targetFile, this.bmadFolderName || 'bmad');
 
       // Track the installed file
       this.installedFiles.push(targetFile);
@@ -771,8 +1287,8 @@ class Installer {
   }
 
   /**
-   * Process agent files to inject activation block
-   * @param {string} modulePath - Path to module
+   * Process agent files to build YAML agents and inject activation blocks
+   * @param {string} modulePath - Path to module in bmad/ installation
    * @param {string} moduleName - Module name
    */
   async processAgentFiles(modulePath, moduleName) {
@@ -783,24 +1299,375 @@ class Installer {
       return; // No agents to process
     }
 
+    // Determine project directory (parent of bmad/ directory)
+    const bmadDir = path.dirname(modulePath);
+    const projectDir = path.dirname(bmadDir);
+    const cfgAgentsDir = path.join(bmadDir, '_cfg', 'agents');
+
+    // Ensure _cfg/agents directory exists
+    await fs.ensureDir(cfgAgentsDir);
+
     // Get all agent files
     const agentFiles = await fs.readdir(agentsPath);
 
     for (const agentFile of agentFiles) {
-      if (!agentFile.endsWith('.md')) continue;
+      // Handle YAML agents - build them to .md
+      if (agentFile.endsWith('.agent.yaml')) {
+        const agentName = agentFile.replace('.agent.yaml', '');
+        const yamlPath = path.join(agentsPath, agentFile);
+        const mdPath = path.join(agentsPath, `${agentName}.md`);
+        const customizePath = path.join(cfgAgentsDir, `${moduleName}-${agentName}.customize.yaml`);
+
+        // Create customize template if it doesn't exist
+        if (!(await fs.pathExists(customizePath))) {
+          const genericTemplatePath = getSourcePath('utility', 'templates', 'agent.customize.template.yaml');
+          if (await fs.pathExists(genericTemplatePath)) {
+            await this.copyFileWithPlaceholderReplacement(genericTemplatePath, customizePath, this.bmadFolderName || 'bmad');
+            console.log(chalk.dim(`  Created customize: ${moduleName}-${agentName}.customize.yaml`));
+          }
+        }
+
+        // Build YAML + customize to .md
+        const customizeExists = await fs.pathExists(customizePath);
+        const xmlContent = await this.xmlHandler.buildFromYaml(yamlPath, customizeExists ? customizePath : null, {
+          includeMetadata: true,
+        });
+
+        // DO NOT replace {project-root} - LLMs understand this placeholder at runtime
+        // const processedContent = xmlContent.replaceAll('{project-root}', projectDir);
 
-      const agentPath = path.join(agentsPath, agentFile);
-      let content = await fs.readFile(agentPath, 'utf8');
+        // Write the built .md file to bmad/{module}/agents/ with POSIX-compliant final newline
+        const content = xmlContent.endsWith('\n') ? xmlContent : xmlContent + '\n';
+        await fs.writeFile(mdPath, content, 'utf8');
+        this.installedFiles.push(mdPath);
 
-      // 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(agentPath, content, 'utf8');
+        // Remove the source YAML file - we can regenerate from installer source if needed
+        await fs.remove(yamlPath);
+
+        console.log(chalk.dim(`  Built agent: ${agentName}.md`));
+      }
+      // Handle legacy .md agents - inject activation if needed
+      else if (agentFile.endsWith('.md')) {
+        const agentPath = path.join(agentsPath, agentFile);
+        let content = await fs.readFile(agentPath, '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);
+          // Ensure POSIX-compliant final newline
+          const finalContent = content.endsWith('\n') ? content : content + '\n';
+          await fs.writeFile(agentPath, finalContent, 'utf8');
+        }
       }
     }
   }
 
+  /**
+   * Build standalone agents in bmad/agents/ directory
+   * @param {string} bmadDir - Path to bmad directory
+   * @param {string} projectDir - Path to project directory
+   */
+  async buildStandaloneAgents(bmadDir, projectDir) {
+    const standaloneAgentsPath = path.join(bmadDir, 'agents');
+    const cfgAgentsDir = path.join(bmadDir, '_cfg', 'agents');
+
+    // Check if standalone agents directory exists
+    if (!(await fs.pathExists(standaloneAgentsPath))) {
+      return;
+    }
+
+    // Get all subdirectories in agents/
+    const agentDirs = await fs.readdir(standaloneAgentsPath, { withFileTypes: true });
+
+    for (const agentDir of agentDirs) {
+      if (!agentDir.isDirectory()) continue;
+
+      const agentDirPath = path.join(standaloneAgentsPath, agentDir.name);
+
+      // Find any .agent.yaml file in the directory
+      const files = await fs.readdir(agentDirPath);
+      const yamlFile = files.find((f) => f.endsWith('.agent.yaml'));
+
+      if (!yamlFile) continue;
+
+      const agentName = path.basename(yamlFile, '.agent.yaml');
+      const sourceYamlPath = path.join(agentDirPath, yamlFile);
+      const targetMdPath = path.join(agentDirPath, `${agentName}.md`);
+      const customizePath = path.join(cfgAgentsDir, `${agentName}.customize.yaml`);
+
+      // Check for customizations
+      const customizeExists = await fs.pathExists(customizePath);
+      let customizedFields = [];
+
+      if (customizeExists) {
+        const customizeContent = await fs.readFile(customizePath, 'utf8');
+        const yaml = require('js-yaml');
+        const customizeYaml = yaml.load(customizeContent);
+
+        // Detect what fields are customized (similar to rebuildAgentFiles)
+        if (customizeYaml) {
+          if (customizeYaml.persona) {
+            for (const [key, value] of Object.entries(customizeYaml.persona)) {
+              if (value !== '' && value !== null && !(Array.isArray(value) && value.length === 0)) {
+                customizedFields.push(`persona.${key}`);
+              }
+            }
+          }
+          if (customizeYaml.agent?.metadata) {
+            for (const [key, value] of Object.entries(customizeYaml.agent.metadata)) {
+              if (value !== '' && value !== null) {
+                customizedFields.push(`metadata.${key}`);
+              }
+            }
+          }
+          if (customizeYaml.critical_actions && customizeYaml.critical_actions.length > 0) {
+            customizedFields.push('critical_actions');
+          }
+          if (customizeYaml.menu && customizeYaml.menu.length > 0) {
+            customizedFields.push('menu');
+          }
+        }
+      }
+
+      // Build YAML to XML .md
+      const xmlContent = await this.xmlHandler.buildFromYaml(sourceYamlPath, customizeExists ? customizePath : null, {
+        includeMetadata: true,
+      });
+
+      // DO NOT replace {project-root} - LLMs understand this placeholder at runtime
+      // const processedContent = xmlContent.replaceAll('{project-root}', projectDir);
+
+      // Write the built .md file with POSIX-compliant final newline
+      const content = xmlContent.endsWith('\n') ? xmlContent : xmlContent + '\n';
+      await fs.writeFile(targetMdPath, content, 'utf8');
+
+      // Display result
+      if (customizedFields.length > 0) {
+        console.log(chalk.dim(`  Built standalone agent: ${agentName}.md `) + chalk.yellow(`(customized: ${customizedFields.join(', ')})`));
+      } else {
+        console.log(chalk.dim(`  Built standalone agent: ${agentName}.md`));
+      }
+    }
+  }
+
+  /**
+   * Rebuild agent files from installer source (for compile command)
+   * @param {string} modulePath - Path to module in bmad/ installation
+   * @param {string} moduleName - Module name
+   */
+  async rebuildAgentFiles(modulePath, moduleName) {
+    // Get source agents directory from installer
+    const sourceAgentsPath =
+      moduleName === 'core' ? path.join(getModulePath('core'), 'agents') : path.join(getSourcePath(`modules/${moduleName}`), 'agents');
+
+    if (!(await fs.pathExists(sourceAgentsPath))) {
+      return; // No source agents to rebuild
+    }
+
+    // Determine project directory (parent of bmad/ directory)
+    const bmadDir = path.dirname(modulePath);
+    const projectDir = path.dirname(bmadDir);
+    const cfgAgentsDir = path.join(bmadDir, '_cfg', 'agents');
+    const targetAgentsPath = path.join(modulePath, 'agents');
+
+    // Ensure target directory exists
+    await fs.ensureDir(targetAgentsPath);
+
+    // Get all YAML agent files from source
+    const sourceFiles = await fs.readdir(sourceAgentsPath);
+
+    for (const file of sourceFiles) {
+      if (file.endsWith('.agent.yaml')) {
+        const agentName = file.replace('.agent.yaml', '');
+        const sourceYamlPath = path.join(sourceAgentsPath, file);
+        const targetMdPath = path.join(targetAgentsPath, `${agentName}.md`);
+        const customizePath = path.join(cfgAgentsDir, `${moduleName}-${agentName}.customize.yaml`);
+
+        // Check for customizations
+        const customizeExists = await fs.pathExists(customizePath);
+        let customizedFields = [];
+
+        if (customizeExists) {
+          const customizeContent = await fs.readFile(customizePath, 'utf8');
+          const yaml = require('js-yaml');
+          const customizeYaml = yaml.load(customizeContent);
+
+          // Detect what fields are customized
+          if (customizeYaml) {
+            if (customizeYaml.persona) {
+              for (const [key, value] of Object.entries(customizeYaml.persona)) {
+                if (value !== '' && value !== null && !(Array.isArray(value) && value.length === 0)) {
+                  customizedFields.push(`persona.${key}`);
+                }
+              }
+            }
+            if (customizeYaml.agent?.metadata) {
+              for (const [key, value] of Object.entries(customizeYaml.agent.metadata)) {
+                if (value !== '' && value !== null) {
+                  customizedFields.push(`metadata.${key}`);
+                }
+              }
+            }
+            if (customizeYaml.critical_actions && customizeYaml.critical_actions.length > 0) {
+              customizedFields.push('critical_actions');
+            }
+            if (customizeYaml.memories && customizeYaml.memories.length > 0) {
+              customizedFields.push('memories');
+            }
+            if (customizeYaml.menu && customizeYaml.menu.length > 0) {
+              customizedFields.push('menu');
+            }
+            if (customizeYaml.prompts && customizeYaml.prompts.length > 0) {
+              customizedFields.push('prompts');
+            }
+          }
+        }
+
+        // Build YAML + customize to .md
+        const xmlContent = await this.xmlHandler.buildFromYaml(sourceYamlPath, customizeExists ? customizePath : null, {
+          includeMetadata: true,
+        });
+
+        // DO NOT replace {project-root} - LLMs understand this placeholder at runtime
+        // const processedContent = xmlContent.replaceAll('{project-root}', projectDir);
+
+        // Write the rebuilt .md file with POSIX-compliant final newline
+        const content = xmlContent.endsWith('\n') ? xmlContent : xmlContent + '\n';
+        await fs.writeFile(targetMdPath, content, 'utf8');
+
+        // Display result with customizations if any
+        if (customizedFields.length > 0) {
+          console.log(chalk.dim(`  Rebuilt agent: ${agentName}.md `) + chalk.yellow(`(customized: ${customizedFields.join(', ')})`));
+        } else {
+          console.log(chalk.dim(`  Rebuilt agent: ${agentName}.md`));
+        }
+      }
+    }
+  }
+
+  /**
+   * Compile/rebuild all agents and tasks for quick updates
+   * @param {Object} config - Compilation configuration
+   * @returns {Object} Compilation results
+   */
+  async compileAgents(config) {
+    const ora = require('ora');
+    const spinner = ora('Starting agent compilation...').start();
+
+    try {
+      const projectDir = path.resolve(config.directory);
+      const bmadDir = await this.findBmadDir(projectDir);
+
+      // Check if bmad directory exists
+      if (!(await fs.pathExists(bmadDir))) {
+        spinner.fail('No BMAD installation found');
+        throw new Error(`BMAD not installed at ${bmadDir}`);
+      }
+
+      let agentCount = 0;
+      let taskCount = 0;
+
+      // Process all modules in bmad directory
+      spinner.text = 'Rebuilding agent files...';
+      const entries = await fs.readdir(bmadDir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (entry.isDirectory() && entry.name !== '_cfg' && entry.name !== 'docs') {
+          const modulePath = path.join(bmadDir, entry.name);
+
+          // Special handling for standalone agents in bmad/agents/ directory
+          if (entry.name === 'agents') {
+            spinner.text = 'Building standalone agents...';
+            await this.buildStandaloneAgents(bmadDir, projectDir);
+
+            // Count standalone agents
+            const standaloneAgentsPath = path.join(bmadDir, 'agents');
+            const standaloneAgentDirs = await fs.readdir(standaloneAgentsPath, { withFileTypes: true });
+            for (const agentDir of standaloneAgentDirs) {
+              if (agentDir.isDirectory()) {
+                const agentDirPath = path.join(standaloneAgentsPath, agentDir.name);
+                const agentFiles = await fs.readdir(agentDirPath);
+                agentCount += agentFiles.filter((f) => f.endsWith('.md') && !f.endsWith('.agent.yaml')).length;
+              }
+            }
+          } else {
+            // Rebuild module agents from installer source
+            const agentsPath = path.join(modulePath, 'agents');
+            if (await fs.pathExists(agentsPath)) {
+              await this.rebuildAgentFiles(modulePath, entry.name);
+              const agentFiles = await fs.readdir(agentsPath);
+              agentCount += agentFiles.filter((f) => f.endsWith('.md')).length;
+            }
+
+            // Count tasks (already built)
+            const tasksPath = path.join(modulePath, 'tasks');
+            if (await fs.pathExists(tasksPath)) {
+              const taskFiles = await fs.readdir(tasksPath);
+              taskCount += taskFiles.filter((f) => f.endsWith('.md')).length;
+            }
+          }
+        }
+      }
+
+      // Regenerate manifests after compilation
+      spinner.start('Regenerating manifests...');
+      const installedModules = entries
+        .filter((e) => e.isDirectory() && e.name !== '_cfg' && e.name !== 'docs' && e.name !== 'agents' && e.name !== 'core')
+        .map((e) => e.name);
+      const manifestGen = new ManifestGenerator();
+
+      // Get existing IDE list from manifest
+      const existingManifestPath = path.join(bmadDir, '_cfg', 'manifest.yaml');
+      let existingIdes = [];
+      if (await fs.pathExists(existingManifestPath)) {
+        const manifestContent = await fs.readFile(existingManifestPath, 'utf8');
+        const yaml = require('js-yaml');
+        const manifest = yaml.load(manifestContent);
+        existingIdes = manifest.ides || [];
+      }
+
+      await manifestGen.generateManifests(bmadDir, installedModules, [], {
+        ides: existingIdes,
+      });
+      spinner.succeed('Manifests regenerated');
+
+      // Update IDE configurations using the existing IDE list from manifest
+      if (existingIdes && existingIdes.length > 0) {
+        spinner.start('Updating IDE configurations...');
+
+        for (const ide of existingIdes) {
+          spinner.text = `Updating ${ide}...`;
+
+          // Stop spinner before IDE setup to prevent blocking any potential prompts
+          // However, we pass _alreadyConfigured to skip all prompts during compile
+          spinner.stop();
+
+          await this.ideManager.setup(ide, projectDir, bmadDir, {
+            selectedModules: installedModules,
+            skipModuleInstall: true, // Skip module installation, just update IDE files
+            verbose: config.verbose,
+            preCollectedConfig: { _alreadyConfigured: true }, // Skip all interactive prompts during compile
+          });
+
+          // Restart spinner for next IDE
+          if (existingIdes.indexOf(ide) < existingIdes.length - 1) {
+            spinner.start('Updating IDE configurations...');
+          }
+        }
+
+        console.log(chalk.green('✓ IDE configurations updated'));
+      } else {
+        console.log(chalk.yellow('⚠️  No IDEs configured. Skipping IDE update.'));
+      }
+
+      return { agentCount, taskCount };
+    } catch (error) {
+      spinner.fail('Compilation failed');
+      throw error;
+    }
+  }
+
   /**
    * Private: Update core
    */
@@ -817,6 +1684,131 @@ class Installer {
     }
   }
 
+  /**
+   * Quick update method - preserves all settings and only prompts for new config fields
+   * @param {Object} config - Configuration with directory
+   * @returns {Object} Update result
+   */
+  async quickUpdate(config) {
+    const ora = require('ora');
+    const spinner = ora('Starting quick update...').start();
+
+    try {
+      const projectDir = path.resolve(config.directory);
+      const bmadDir = await this.findBmadDir(projectDir);
+
+      // Check if bmad directory exists
+      if (!(await fs.pathExists(bmadDir))) {
+        spinner.fail('No BMAD installation found');
+        throw new Error(`BMAD not installed at ${bmadDir}. Use regular install for first-time setup.`);
+      }
+
+      spinner.text = 'Detecting installed modules and configuration...';
+
+      // Detect existing installation
+      const existingInstall = await this.detector.detect(bmadDir);
+      const installedModules = existingInstall.modules.map((m) => m.id);
+      const configuredIdes = existingInstall.ides || [];
+
+      // 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));
+
+      // 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));
+
+      spinner.succeed(`Found ${modulesToUpdate.length} module(s) to update and ${configuredIdes.length} configured tool(s)`);
+
+      if (skippedModules.length > 0) {
+        console.log(chalk.yellow(`⚠️  Skipping ${skippedModules.length} module(s) - no source available: ${skippedModules.join(', ')}`));
+      }
+
+      // Load existing configs and collect new fields (if any)
+      console.log(chalk.cyan('\n📋 Checking for new configuration options...'));
+      await this.configCollector.loadExistingConfig(projectDir);
+
+      let promptedForNewFields = false;
+
+      // Check core config for new fields
+      const corePrompted = await this.configCollector.collectModuleConfigQuick('core', projectDir, true);
+      if (corePrompted) {
+        promptedForNewFields = true;
+      }
+
+      // Check each module we're updating for new fields (NOT skipped modules)
+      for (const moduleName of modulesToUpdate) {
+        const modulePrompted = await this.configCollector.collectModuleConfigQuick(moduleName, projectDir, true);
+        if (modulePrompted) {
+          promptedForNewFields = true;
+        }
+      }
+
+      if (!promptedForNewFields) {
+        console.log(chalk.green('✓ All configuration is up to date, no new options to configure'));
+      }
+
+      // Add metadata
+      this.configCollector.collectedConfig._meta = {
+        version: require(path.join(getProjectRoot(), 'package.json')).version,
+        installDate: new Date().toISOString(),
+        lastModified: new Date().toISOString(),
+      };
+
+      // Check if bmad_folder has changed
+      const existingBmadFolderName = path.basename(bmadDir);
+      const newBmadFolderName = this.configCollector.collectedConfig.core?.bmad_folder || existingBmadFolderName;
+
+      if (existingBmadFolderName === newBmadFolderName) {
+        // Normal quick update - start the spinner
+        spinner.start('Updating BMAD installation...');
+      } else {
+        // Folder name has changed - stop spinner and let install() handle it
+        spinner.stop();
+        console.log(chalk.yellow(`\n⚠️  Folder name will change: ${existingBmadFolderName} → ${newBmadFolderName}`));
+        console.log(chalk.yellow('The installer will handle the folder migration.\n'));
+      }
+
+      // Build the config object for the installer
+      const installConfig = {
+        directory: projectDir,
+        installCore: true,
+        modules: modulesToUpdate, // Only update modules we have source for
+        ides: configuredIdes,
+        skipIde: configuredIdes.length === 0,
+        coreConfig: this.configCollector.collectedConfig.core,
+        actionType: 'install', // Use regular install flow
+        _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
+      };
+
+      // Call the standard install method
+      const result = await this.install(installConfig);
+
+      // Only succeed the spinner if it's still spinning
+      // (install method might have stopped it if folder name changed)
+      if (spinner.isSpinning) {
+        spinner.succeed('Quick update complete!');
+      }
+
+      return {
+        success: true,
+        moduleCount: modulesToUpdate.length + 1, // +1 for core
+        hadNewFields: promptedForNewFields,
+        modules: ['core', ...modulesToUpdate],
+        skippedModules: skippedModules,
+        ides: configuredIdes,
+      };
+    } catch (error) {
+      spinner.fail('Quick update failed');
+      throw error;
+    }
+  }
+
   /**
    * Private: Prompt for update action
    */
@@ -837,36 +1829,236 @@ class Installer {
   }
 
   /**
-   * Private: Create formatted error for legacy BMAD v4 detection
+   * Handle legacy BMAD v4 migration with automatic backup
+   * @param {string} projectDir - Project directory
    * @param {Object} legacyV4 - Legacy V4 detection result with offenders array
-   * @returns {Error} Formatted error with fullMessage property
    */
-  createLegacyV4Error(legacyV4) {
-    const error = new Error('Legacy BMAD v4 artefacts detected in project. Remove them to continue.');
+  async handleLegacyV4Migration(projectDir, legacyV4) {
+    console.log(chalk.yellow.bold('\n⚠️  Legacy BMAD v4 detected'));
+    console.log(chalk.dim('The installer found legacy artefacts in your project.\n'));
+
+    // Separate .bmad* folders (auto-backup) from other offending paths (manual cleanup)
+    const bmadFolders = legacyV4.offenders.filter((p) => {
+      const name = path.basename(p);
+      return name.startsWith('.bmad'); // Only dot-prefixed folders get auto-backed up
+    });
+    const otherOffenders = legacyV4.offenders.filter((p) => {
+      const name = path.basename(p);
+      return !name.startsWith('.bmad'); // Everything else is manual cleanup
+    });
 
-    // Build the complete formatted message using template literals
-    const headerMessage = `
-${chalk.red.bold('Blocked: Legacy BMAD v4 detected')}
-The installer found legacy artefacts in your project.`;
+    const inquirer = require('inquirer');
 
-    const offendersMessage = `
-Offending paths:
-${legacyV4.offenders.map((p) => ` - ${p}`).join('\n')}
+    // Show warning for other offending paths FIRST
+    if (otherOffenders.length > 0) {
+      console.log(chalk.yellow('⚠️  Recommended cleanup:'));
+      console.log(chalk.dim('It is recommended to remove the following items before proceeding:\n'));
+      for (const p of otherOffenders) console.log(chalk.dim(` - ${p}`));
 
-Cleanup commands you can copy/paste:
-${chalk.cyan('macOS/Linux:')}
-${legacyV4.offenders.map((p) => `  rm -rf '${p}'`).join('\n')}
-${chalk.cyan('Windows:')}
-${legacyV4.offenders.map((p) => `  rmdir /S /Q "${p}"`).join('\n')}`;
+      console.log(chalk.cyan('\nCleanup commands you can copy/paste:'));
+      console.log(chalk.dim('macOS/Linux:'));
+      for (const p of otherOffenders) console.log(chalk.dim(`  rm -rf '${p}'`));
+      console.log(chalk.dim('Windows:'));
+      for (const p of otherOffenders) console.log(chalk.dim(`  rmdir /S /Q "${p}"`));
 
-    const footerMessage = `
-Remove the listed paths (case sensitive) and rerun install.
-Note: You may also want to remove other BMAD-related v4 files/folders left over in this project. If you have customizations, back them up or migrate them before deleting.`;
+      const { cleanedUp } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'cleanedUp',
+          message: 'Have you completed the recommended cleanup? (You can proceed without it, but it is recommended)',
+          default: false,
+        },
+      ]);
 
-    // Attach the complete formatted message
-    error.fullMessage = headerMessage + offendersMessage + footerMessage;
+      if (cleanedUp) {
+        console.log(chalk.green('✓ Cleanup acknowledged\n'));
+      } else {
+        console.log(chalk.yellow('⚠️  Proceeding without recommended cleanup\n'));
+      }
+    }
+
+    // Handle .bmad* folders with automatic backup
+    if (bmadFolders.length > 0) {
+      console.log(chalk.cyan('The following legacy folders will be moved to v4-backup:'));
+      for (const p of bmadFolders) console.log(chalk.dim(` - ${p}`));
+
+      const { proceed } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'proceed',
+          message: 'Proceed with backing up legacy v4 folders?',
+          default: true,
+        },
+      ]);
 
-    return error;
+      if (proceed) {
+        const backupDir = path.join(projectDir, 'v4-backup');
+        await fs.ensureDir(backupDir);
+
+        for (const folder of bmadFolders) {
+          const folderName = path.basename(folder);
+          const backupPath = path.join(backupDir, folderName);
+
+          // If backup already exists, add timestamp
+          let finalBackupPath = backupPath;
+          if (await fs.pathExists(backupPath)) {
+            const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-').split('T')[0];
+            finalBackupPath = path.join(backupDir, `${folderName}-${timestamp}`);
+          }
+
+          await fs.move(folder, finalBackupPath, { overwrite: false });
+          console.log(chalk.green(`✓ Moved ${folderName} to ${path.relative(projectDir, finalBackupPath)}`));
+        }
+      } else {
+        throw new Error('Installation cancelled by user');
+      }
+    }
+  }
+
+  /**
+   * Read files-manifest.csv
+   * @param {string} bmadDir - BMAD installation directory
+   * @returns {Array} Array of file entries from files-manifest.csv
+   */
+  async readFilesManifest(bmadDir) {
+    const filesManifestPath = path.join(bmadDir, '_cfg', 'files-manifest.csv');
+    if (!(await fs.pathExists(filesManifestPath))) {
+      return [];
+    }
+
+    try {
+      const content = await fs.readFile(filesManifestPath, 'utf8');
+      const lines = content.split('\n');
+      const files = [];
+
+      for (let i = 1; i < lines.length; i++) {
+        // Skip header
+        const line = lines[i].trim();
+        if (!line) continue;
+
+        // Parse CSV line properly handling quoted values
+        const parts = [];
+        let current = '';
+        let inQuotes = false;
+
+        for (const char of line) {
+          if (char === '"') {
+            inQuotes = !inQuotes;
+          } else if (char === ',' && !inQuotes) {
+            parts.push(current);
+            current = '';
+          } else {
+            current += char;
+          }
+        }
+        parts.push(current); // Add last part
+
+        if (parts.length >= 4) {
+          files.push({
+            type: parts[0],
+            name: parts[1],
+            module: parts[2],
+            path: parts[3],
+            hash: parts[4] || null, // Hash may not exist in old manifests
+          });
+        }
+      }
+
+      return files;
+    } catch (error) {
+      console.warn('Warning: Could not read files-manifest.csv:', error.message);
+      return [];
+    }
+  }
+
+  /**
+   * Detect custom and modified files
+   * @param {string} bmadDir - BMAD installation directory
+   * @param {Array} existingFilesManifest - Previous files from files-manifest.csv
+   * @returns {Object} Object with customFiles and modifiedFiles arrays
+   */
+  async detectCustomFiles(bmadDir, existingFilesManifest) {
+    const customFiles = [];
+    const modifiedFiles = [];
+
+    // Check if the manifest has hashes - if not, we can't detect modifications
+    let manifestHasHashes = false;
+    if (existingFilesManifest && existingFilesManifest.length > 0) {
+      manifestHasHashes = existingFilesManifest.some((f) => f.hash);
+    }
+
+    // Build map of previously installed files from files-manifest.csv with their hashes
+    const installedFilesMap = new Map();
+    for (const fileEntry of existingFilesManifest) {
+      if (fileEntry.path) {
+        // Files in manifest are stored as relative paths starting with 'bmad/'
+        // Convert to absolute path
+        const relativePath = fileEntry.path.startsWith('bmad/') ? fileEntry.path.slice(5) : fileEntry.path;
+        const absolutePath = path.join(bmadDir, relativePath);
+        installedFilesMap.set(path.normalize(absolutePath), {
+          hash: fileEntry.hash,
+          relativePath: relativePath,
+        });
+      }
+    }
+
+    // Recursively scan bmadDir for all files
+    const scanDirectory = async (dir) => {
+      try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+
+          if (entry.isDirectory()) {
+            // Skip certain directories
+            if (entry.name === 'node_modules' || entry.name === '.git') {
+              continue;
+            }
+            await scanDirectory(fullPath);
+          } else if (entry.isFile()) {
+            const normalizedPath = path.normalize(fullPath);
+            const fileInfo = installedFilesMap.get(normalizedPath);
+
+            // Skip certain system files that are auto-generated
+            const relativePath = path.relative(bmadDir, fullPath);
+            const fileName = path.basename(fullPath);
+
+            // Skip _cfg directory - system files
+            if (relativePath.startsWith('_cfg/') || relativePath.startsWith('_cfg\\')) {
+              continue;
+            }
+
+            // Skip config.yaml files - these are regenerated on each install/update
+            // Users should use _cfg/agents/ override files instead
+            if (fileName === 'config.yaml') {
+              continue;
+            }
+
+            if (!fileInfo) {
+              // File not in manifest = custom file
+              customFiles.push(fullPath);
+            } else if (manifestHasHashes && fileInfo.hash) {
+              // File in manifest with hash - check if it was modified
+              const currentHash = await this.manifest.calculateFileHash(fullPath);
+              if (currentHash && currentHash !== fileInfo.hash) {
+                // Hash changed = file was modified
+                modifiedFiles.push({
+                  path: fullPath,
+                  relativePath: fileInfo.relativePath,
+                });
+              }
+            }
+            // If manifest doesn't have hashes, we can't detect modifications
+            // so we just skip files that are in the manifest
+          }
+        }
+      } catch {
+        // Ignore errors scanning directories
+      }
+    };
+
+    await scanDirectory(bmadDir);
+    return { customFiles, modifiedFiles };
   }
 
   /**
@@ -981,7 +2173,13 @@ Note: You may also want to remove other BMAD-related v4 files/folders left over
 
       configContent += processedTemplate;
 
+      // Ensure POSIX-compliant final newline
+      if (!configContent.endsWith('\n')) {
+        configContent += '\n';
+      }
+
       await fs.writeFile(configPath, configContent, 'utf8');
+      this.installedFiles.push(configPath); // Track agent config files
       createdCount++;
     }
 
@@ -997,7 +2195,7 @@ Note: You may also want to remove other BMAD-related v4 files/folders left over
    * @param {Array} agentDetails - Array of agent details
    */
   async generateAgentManifest(bmadDir, agentDetails) {
-    const manifestPath = path.join(bmadDir, '_cfg', 'agent-party.xml');
+    const manifestPath = path.join(bmadDir, '_cfg', 'agent-manifest.csv');
     await AgentPartyGenerator.writeAgentParty(manifestPath, agentDetails, { forWeb: false });
   }
 
@@ -1061,7 +2259,7 @@ Note: You may also want to remove other BMAD-related v4 files/folders left over
       const targetDocPath = path.join(docsDir, `${ide}-instructions.md`);
 
       if (await fs.pathExists(sourceDocPath)) {
-        await fs.copy(sourceDocPath, targetDocPath, { overwrite: true });
+        await this.copyFileWithPlaceholderReplacement(sourceDocPath, targetDocPath, this.bmadFolderName || 'bmad');
       }
     }
   }