bmad-method 6.0.0-alpha.7 → 6.0.0-alpha.9

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

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

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

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

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

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

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

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

package/tools/cli/installers/lib/ide/trae.js

@@ -1,6 +1,7 @@
 const path = require('node:path');
 const { BaseIdeSetup } = require('./_base-ide');
 const chalk = require('chalk');
+const { AgentCommandGenerator } = require('./shared/agent-command-generator');
 
 /**
  * Trae IDE setup handler
@@ -30,20 +31,22 @@ class TraeSetup extends BaseIdeSetup {
     // Clean up any existing BMAD files before reinstalling
     await this.cleanup(projectDir);
 
-    // Get agents, tasks, tools, and workflows (standalone only)
-    const agents = await this.getAgents(bmadDir);
+    // Generate agent launchers
+    const agentGen = new AgentCommandGenerator(this.bmadFolderName);
+    const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, options.selectedModules || []);
+
+    // Get tasks, tools, and workflows (standalone only)
     const tasks = await this.getTasks(bmadDir, true);
     const tools = await this.getTools(bmadDir, true);
     const workflows = await this.getWorkflows(bmadDir, true);
 
     // Process agents as rules with bmad- prefix
     let agentCount = 0;
-    for (const agent of agents) {
-      const content = await this.readFile(agent.path);
-      const processedContent = this.createAgentRule(agent, content, bmadDir, projectDir);
+    for (const artifact of agentArtifacts) {
+      const processedContent = await this.createAgentRule(artifact, bmadDir, projectDir);
 
       // Use bmad- prefix: bmad-agent-{module}-{name}.md
-      const targetPath = path.join(rulesDir, `bmad-agent-${agent.module}-${agent.name}.md`);
+      const targetPath = path.join(rulesDir, `bmad-agent-${artifact.module}-${artifact.name}.md`);
       await this.writeFile(targetPath, processedContent);
       agentCount++;
     }
@@ -108,44 +111,29 @@ class TraeSetup extends BaseIdeSetup {
   /**
    * Create rule content for an agent
    */
-  createAgentRule(agent, content, bmadDir, projectDir) {
-    // Extract metadata from agent content
-    const titleMatch = content.match(/title="([^"]+)"/);
-    const title = titleMatch ? titleMatch[1] : this.formatTitle(agent.name);
-
-    const iconMatch = content.match(/icon="([^"]+)"/);
-    const icon = iconMatch ? iconMatch[1] : '🤖';
+  async createAgentRule(artifact, bmadDir, projectDir) {
+    // Strip frontmatter from launcher
+    const frontmatterRegex = /^---\s*\n[\s\S]*?\n---\s*\n/;
+    const contentWithoutFrontmatter = artifact.content.replace(frontmatterRegex, '').trim();
 
-    // Extract YAML content if available
-    const yamlMatch = content.match(/```ya?ml\r?\n([\s\S]*?)```/);
-    const yamlContent = yamlMatch ? yamlMatch[1] : content;
+    // Extract metadata from launcher content
+    const titleMatch = artifact.content.match(/description:\s*"([^"]+)"/);
+    const title = titleMatch ? titleMatch[1] : this.formatTitle(artifact.name);
 
     // Calculate relative path for reference
-    const relativePath = path.relative(projectDir, agent.path).replaceAll('\\', '/');
+    const relativePath = path.relative(projectDir, artifact.sourcePath).replaceAll('\\', '/');
 
     let ruleContent = `# ${title} Agent Rule
 
-This rule is triggered when the user types \`@${agent.name}\` and activates the ${title} agent persona.
+This rule is triggered when the user types \`@${artifact.name}\` and activates the ${title} agent persona.
 
 ## Agent Activation
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
-
-\`\`\`yaml
-${yamlContent}
-\`\`\`
+${contentWithoutFrontmatter}
 
 ## File Reference
 
-The complete agent definition is available in [${relativePath}](${relativePath}).
-
-## Usage
-
-When the user types \`@${agent.name}\`, activate this ${title} persona and follow all instructions defined in the YAML configuration above.
-
-## Module
-
-Part of the BMAD ${agent.module.toUpperCase()} module.
+The full agent definition is located at: \`${relativePath}\`
 `;
 
     return ruleContent;

package/tools/cli/installers/lib/ide/windsurf.js

@@ -1,6 +1,7 @@
 const path = require('node:path');
 const { BaseIdeSetup } = require('./_base-ide');
 const chalk = require('chalk');
+const { AgentCommandGenerator } = require('./shared/agent-command-generator');
 
 /**
  * Windsurf IDE setup handler
@@ -31,8 +32,14 @@ class WindsurfSetup extends BaseIdeSetup {
     // Clean up any existing BMAD workflows before reinstalling
     await this.cleanup(projectDir);
 
-    // Get agents, tasks, tools, and workflows (standalone only)
-    const agents = await this.getAgents(bmadDir);
+    // Generate agent launchers
+    const agentGen = new AgentCommandGenerator(this.bmadFolderName);
+    const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, options.selectedModules || []);
+
+    // Convert artifacts to agent format for module organization
+    const agents = agentArtifacts.map((a) => ({ module: a.module, name: a.name }));
+
+    // Get tasks, tools, and workflows (standalone only)
     const tasks = await this.getTasks(bmadDir, true);
     const tools = await this.getTools(bmadDir, true);
     const workflows = await this.getWorkflows(bmadDir, true);
@@ -49,14 +56,13 @@ class WindsurfSetup extends BaseIdeSetup {
       await this.ensureDir(path.join(bmadWorkflowsDir, module, 'workflows'));
     }
 
-    // Process agents as workflows with organized structure
+    // Process agent launchers as workflows with organized structure
     let agentCount = 0;
-    for (const agent of agents) {
-      const content = await this.readFile(agent.path);
-      const processedContent = this.createWorkflowContent(agent, content);
+    for (const artifact of agentArtifacts) {
+      const processedContent = this.createWorkflowContent({ module: artifact.module, name: artifact.name }, artifact.content);
 
       // Organized path: bmad/module/agents/agent-name.md
-      const targetPath = path.join(bmadWorkflowsDir, agent.module, 'agents', `${agent.name}.md`);
+      const targetPath = path.join(bmadWorkflowsDir, artifact.module, 'agents', `${artifact.name}.md`);
       await this.writeFile(targetPath, processedContent);
       agentCount++;
     }
@@ -127,13 +133,17 @@ class WindsurfSetup extends BaseIdeSetup {
    * Create workflow content for an agent
    */
   createWorkflowContent(agent, content) {
+    // Strip existing frontmatter from launcher
+    const frontmatterRegex = /^---\s*\n[\s\S]*?\n---\s*\n/;
+    const contentWithoutFrontmatter = content.replace(frontmatterRegex, '');
+
     // Create simple Windsurf frontmatter matching original format
     let workflowContent = `---
 description: ${agent.name}
 auto_execution_mode: 3
 ---
 
-${content}`;
+${contentWithoutFrontmatter}`;
 
     return workflowContent;
   }

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

@@ -26,6 +26,70 @@ class ModuleManager {
     // Path to source modules directory
     this.modulesSourcePath = getSourcePath('modules');
     this.xmlHandler = new XmlHandler();
+    this.bmadFolderName = 'bmad'; // Default, can be overridden
+  }
+
+  /**
+   * Set the bmad folder name for placeholder replacement
+   * @param {string} bmadFolderName - The bmad folder name
+   */
+  setBmadFolderName(bmadFolderName) {
+    this.bmadFolderName = bmadFolderName;
+  }
+
+  /**
+   * Copy a file and replace {bmad_folder} placeholder with actual folder name
+   * @param {string} sourcePath - Source file path
+   * @param {string} targetPath - Target file path
+   */
+  async copyFileWithPlaceholderReplacement(sourcePath, targetPath) {
+    // List of text file extensions that should have placeholder replacement
+    const textExtensions = ['.md', '.yaml', '.yml', '.txt', '.json', '.js', '.ts', '.html', '.css', '.sh', '.bat', '.csv'];
+    const ext = path.extname(sourcePath).toLowerCase();
+
+    // Check if this is a text file that might contain placeholders
+    if (textExtensions.includes(ext)) {
+      try {
+        // Read the file content
+        let content = await fs.readFile(sourcePath, 'utf8');
+
+        // Replace {bmad_folder} placeholder with actual folder name
+        if (content.includes('{bmad_folder}')) {
+          content = content.replaceAll('{bmad_folder}', this.bmadFolderName);
+        }
+
+        // Write to target with replaced content
+        await fs.ensureDir(path.dirname(targetPath));
+        await fs.writeFile(targetPath, content, 'utf8');
+      } catch {
+        // If reading as text fails (might be binary despite extension), fall back to regular copy
+        await fs.copy(sourcePath, targetPath, { overwrite: true });
+      }
+    } else {
+      // Binary file or other file type - just copy directly
+      await fs.copy(sourcePath, targetPath, { overwrite: true });
+    }
+  }
+
+  /**
+   * Copy a directory recursively with placeholder replacement
+   * @param {string} sourceDir - Source directory path
+   * @param {string} targetDir - Target directory path
+   */
+  async copyDirectoryWithPlaceholderReplacement(sourceDir, targetDir) {
+    await fs.ensureDir(targetDir);
+    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const sourcePath = path.join(sourceDir, entry.name);
+      const targetPath = path.join(targetDir, entry.name);
+
+      if (entry.isDirectory()) {
+        await this.copyDirectoryWithPlaceholderReplacement(sourcePath, targetPath);
+      } else {
+        await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath);
+      }
+    }
   }
 
   /**
@@ -311,9 +375,8 @@ class ModuleManager {
         await fs.ensureDir(path.dirname(targetFile));
         await this.copyWorkflowYamlStripped(sourceFile, targetFile);
       } else {
-        // Copy the file normally
-        await fs.ensureDir(path.dirname(targetFile));
-        await fs.copy(sourceFile, targetFile, { overwrite: true });
+        // Copy the file with placeholder replacement
+        await this.copyFileWithPlaceholderReplacement(sourceFile, targetFile);
       }
 
       // Track the file if callback provided
@@ -333,12 +396,16 @@ class ModuleManager {
     // Read the source YAML file
     let yamlContent = await fs.readFile(sourceFile, 'utf8');
 
+    // IMPORTANT: Replace {bmad_folder} BEFORE parsing YAML
+    // Otherwise parsing will fail on the placeholder
+    yamlContent = yamlContent.replaceAll('{bmad_folder}', this.bmadFolderName);
+
     try {
       // First check if web_bundle exists by parsing
       const workflowConfig = yaml.load(yamlContent);
 
       if (workflowConfig.web_bundle === undefined) {
-        // No web_bundle section, just copy as-is
+        // No web_bundle section, just write (placeholders already replaced above)
         await fs.writeFile(targetFile, yamlContent, 'utf8');
         return;
       }
@@ -400,6 +467,7 @@ class ModuleManager {
       // Clean up any double blank lines that might result
       const strippedYaml = newLines.join('\n').replaceAll(/\n\n\n+/g, '\n\n');
 
+      // Placeholders already replaced at the beginning of this function
       await fs.writeFile(targetFile, strippedYaml, 'utf8');
     } catch {
       // If anything fails, just copy the file as-is
@@ -488,8 +556,10 @@ class ModuleManager {
         const installWorkflowPath = item['workflow-install']; // Where to copy TO
 
         // Parse SOURCE workflow path
-        // Example: {project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml
-        const sourceMatch = sourceWorkflowPath.match(/\{project-root\}\/bmad\/([^/]+)\/workflows\/(.+)/);
+        // Handle both {bmad_folder} placeholder and hardcoded 'bmad'
+        // Example: {project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story/workflow.yaml
+        // Or: {project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml
+        const sourceMatch = sourceWorkflowPath.match(/\{project-root\}\/(?:\{bmad_folder\}|bmad)\/([^/]+)\/workflows\/(.+)/);
         if (!sourceMatch) {
           console.warn(chalk.yellow(`      Could not parse workflow path: ${sourceWorkflowPath}`));
           continue;
@@ -498,8 +568,9 @@ class ModuleManager {
         const [, sourceModule, sourceWorkflowSubPath] = sourceMatch;
 
         // Parse INSTALL workflow path
-        // Example: {project-root}/bmad/bmgd/workflows/4-production/create-story/workflow.yaml
-        const installMatch = installWorkflowPath.match(/\{project-root\}\/bmad\/([^/]+)\/workflows\/(.+)/);
+        // Handle both {bmad_folder} placeholder and hardcoded 'bmad'
+        // Example: {project-root}/{bmad_folder}/bmgd/workflows/4-production/create-story/workflow.yaml
+        const installMatch = installWorkflowPath.match(/\{project-root\}\/(?:\{bmad_folder\}|bmad)\/([^/]+)\/workflows\/(.+)/);
         if (!installMatch) {
           console.warn(chalk.yellow(`      Could not parse workflow-install path: ${installWorkflowPath}`));
           continue;
@@ -527,7 +598,8 @@ class ModuleManager {
         );
 
         await fs.ensureDir(path.dirname(actualDestWorkflowPath));
-        await fs.copy(actualSourceWorkflowPath, actualDestWorkflowPath, { overwrite: true });
+        // Copy the workflow directory recursively with placeholder replacement
+        await this.copyDirectoryWithPlaceholderReplacement(actualSourceWorkflowPath, actualDestWorkflowPath);
 
         // Update the workflow.yaml config_source reference
         const workflowYamlPath = path.join(actualDestWorkflowPath, 'workflow.yaml');
@@ -550,16 +622,17 @@ class ModuleManager {
   async updateWorkflowConfigSource(workflowYamlPath, newModuleName) {
     let yamlContent = await fs.readFile(workflowYamlPath, 'utf8');
 
-    // Replace config_source: "{project-root}/bmad/OLD_MODULE/config.yaml"
-    // with config_source: "{project-root}/bmad/NEW_MODULE/config.yaml"
-    const configSourcePattern = /config_source:\s*["']?\{project-root\}\/bmad\/[^/]+\/config\.yaml["']?/g;
-    const newConfigSource = `config_source: "{project-root}/bmad/${newModuleName}/config.yaml"`;
+    // Replace config_source: "{project-root}/{bmad_folder}/OLD_MODULE/config.yaml"
+    // with config_source: "{project-root}/{bmad_folder}/NEW_MODULE/config.yaml"
+    // Note: At this point {bmad_folder} has already been replaced with actual folder name
+    const configSourcePattern = /config_source:\s*["']?\{project-root\}\/[^/]+\/[^/]+\/config\.yaml["']?/g;
+    const newConfigSource = `config_source: "{project-root}/${this.bmadFolderName}/${newModuleName}/config.yaml"`;
 
     const updatedYaml = yamlContent.replaceAll(configSourcePattern, newConfigSource);
 
     if (updatedYaml !== yamlContent) {
       await fs.writeFile(workflowYamlPath, updatedYaml, 'utf8');
-      console.log(chalk.dim(`      Updated config_source to: bmad/${newModuleName}/config.yaml`));
+      console.log(chalk.dim(`      Updated config_source to: ${this.bmadFolderName}/${newModuleName}/config.yaml`));
     }
   }
 
@@ -664,9 +737,8 @@ class ModuleManager {
         }
       }
 
-      // Copy file
-      await fs.ensureDir(path.dirname(targetFile));
-      await fs.copy(sourceFile, targetFile, { overwrite: true });
+      // Copy file with placeholder replacement
+      await this.copyFileWithPlaceholderReplacement(sourceFile, targetFile);
     }
   }
 

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

@@ -2,13 +2,31 @@ const chalk = require('chalk');
 const boxen = require('boxen');
 const wrapAnsi = require('wrap-ansi');
 const figlet = require('figlet');
+const path = require('node:path');
 
 const CLIUtils = {
+  /**
+   * Get version from package.json
+   */
+  getVersion() {
+    try {
+      const packageJson = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+      return packageJson.version || 'Unknown';
+    } catch {
+      return 'Unknown';
+    }
+  },
+
   /**
    * Display BMAD logo
+   * @param {boolean} clearScreen - Whether to clear the screen first (default: true for initial display only)
    */
-  displayLogo() {
-    console.clear();
+  displayLogo(clearScreen = true) {
+    if (clearScreen) {
+      console.clear();
+    }
+
+    const version = this.getVersion();
 
     // ASCII art logo
     const logo = `
@@ -20,7 +38,7 @@ const CLIUtils = {
     ╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝╚═════╝`;
 
     console.log(chalk.cyan(logo));
-    console.log(chalk.dim('    Build More, Architect Dreams\n'));
+    console.log(chalk.dim(`    Build More, Architect Dreams`) + chalk.cyan.bold(` v${version}`) + '\n');
   },
 
   /**
@@ -64,18 +82,35 @@ const CLIUtils = {
   },
 
   /**
-   * Display prompt section
-   * @param {string|Array} prompts - Prompts to display
+   * Display module configuration header
+   * @param {string} moduleName - Module name (fallback if no custom header)
+   * @param {string} header - Custom header from install-config.yaml
+   * @param {string} subheader - Custom subheader from install-config.yaml
    */
-  displayPromptSection(prompts) {
-    const promptArray = Array.isArray(prompts) ? prompts : [prompts];
-
-    const formattedPrompts = promptArray.map((p) => wrapAnsi(p, 76, { hard: true, wordWrap: true }));
+  displayModuleConfigHeader(moduleName, header = null, subheader = null) {
+    // Simple blue banner with custom header/subheader if provided
+    console.log('\n' + chalk.cyan('─'.repeat(80)));
+    console.log(chalk.cyan(header || `Configuring ${moduleName.toUpperCase()} Module`));
+    if (subheader) {
+      console.log(chalk.dim(`${subheader}`));
+    }
+    console.log(chalk.cyan('─'.repeat(80)) + '\n');
+  },
 
-    this.displayBox(formattedPrompts, {
-      borderColor: 'yellow',
-      borderStyle: 'double',
-    });
+  /**
+   * Display module with no custom configuration
+   * @param {string} moduleName - Module name (fallback if no custom header)
+   * @param {string} header - Custom header from install-config.yaml
+   * @param {string} subheader - Custom subheader from install-config.yaml
+   */
+  displayModuleNoConfig(moduleName, header = null, subheader = null) {
+    // Show full banner with header/subheader, just like modules with config
+    console.log('\n' + chalk.cyan('─'.repeat(80)));
+    console.log(chalk.cyan(header || `${moduleName.toUpperCase()} Module - No Custom Configuration`));
+    if (subheader) {
+      console.log(chalk.dim(`${subheader}`));
+    }
+    console.log(chalk.cyan('─'.repeat(80)) + '\n');
   },
 
   /**
@@ -164,44 +199,11 @@ const CLIUtils = {
   /**
    * Display module completion message
    * @param {string} moduleName - Name of the completed module
-   * @param {boolean} clearScreen - Whether to clear the screen first
+   * @param {boolean} clearScreen - Whether to clear the screen first (deprecated, always false now)
    */
-  displayModuleComplete(moduleName, clearScreen = true) {
-    if (clearScreen) {
-      console.clear();
-      this.displayLogo();
-    }
-
-    let message;
-
-    // Special messages for specific modules
-    if (moduleName.toLowerCase() === 'bmm') {
-      message = `Thank you for configuring the BMAD™ Method Module (BMM)!
-
-Your responses have been saved and will be used to configure your installation.`;
-    } else if (moduleName.toLowerCase() === 'cis') {
-      message = `Thank you for choosing the BMAD™ Creative Innovation Suite, an early beta
-release with much more planned!
-
-With this BMAD™ Creative Innovation Suite Configuration, remember that all
-paths are relative to project root, with no leading slash.`;
-    } else if (moduleName.toLowerCase() === 'core') {
-      message = `Thank you for choosing the BMAD™ Method, your gateway to dreaming, planning
-and building with real world proven techniques.
-
-All paths are relative to project root, with no leading slash.`;
-    } else {
-      message = `Thank you for configuring the BMAD™ ${moduleName.toUpperCase()} module!
-
-Your responses have been saved and will be used to configure your installation.`;
-    }
-
-    this.displayBox(message, {
-      borderColor: 'yellow',
-      borderStyle: 'double',
-      padding: 1,
-      margin: 1,
-    });
+  displayModuleComplete(moduleName, clearScreen = false) {
+    // No longer clear screen or show boxes - just a simple completion message
+    // This is deprecated but kept for backwards compatibility
   },
 };
 

package/tools/cli/lib/ui.js

@@ -17,14 +17,26 @@ class UI {
    */
   async promptInstall() {
     CLIUtils.displayLogo();
-    CLIUtils.displaySection('BMAD™ Setup', 'Build More, Architect Dreams');
+    const version = CLIUtils.getVersion();
+    CLIUtils.displaySection('BMAD™ Setup', `Build More, Architect Dreams v${version}`);
 
     const confirmedDirectory = await this.getConfirmedDirectory();
 
+    // Preflight: Check for legacy BMAD v4 footprints immediately after getting directory
+    const { Detector } = require('../installers/lib/core/detector');
+    const { Installer } = require('../installers/lib/core/installer');
+    const detector = new Detector();
+    const installer = new Installer();
+    const legacyV4 = await detector.detectLegacyV4(confirmedDirectory);
+    if (legacyV4.hasLegacyV4) {
+      await installer.handleLegacyV4Migration(confirmedDirectory, legacyV4);
+    }
+
     // Check if there's an existing BMAD installation
     const fs = require('fs-extra');
     const path = require('node:path');
-    const bmadDir = path.join(confirmedDirectory, 'bmad');
+    // Use findBmadDir to detect any custom folder names (V6+)
+    const bmadDir = await installer.findBmadDir(confirmedDirectory);
     const hasExistingInstall = await fs.pathExists(bmadDir);
 
     // Track action type (only set if there's an existing installation)
@@ -91,9 +103,7 @@ class UI {
     // This allows text-based prompts to complete before the checkbox prompt
     const toolSelection = await this.promptToolSelection(confirmedDirectory, selectedModules);
 
-    console.clear();
-    CLIUtils.displayLogo();
-    CLIUtils.displayModuleComplete('core', false); // false = don't clear the screen again
+    // No more screen clearing - keep output flowing
 
     return {
       actionType: actionType || 'update', // Preserve reinstall or update action
@@ -114,10 +124,12 @@ class UI {
    * @returns {Object} Tool configuration
    */
   async promptToolSelection(projectDir, selectedModules) {
-    // Check for existing configured IDEs
+    // Check for existing configured IDEs - use findBmadDir to detect custom folder names
     const { Detector } = require('../installers/lib/core/detector');
+    const { Installer } = require('../installers/lib/core/installer');
     const detector = new Detector();
-    const bmadDir = path.join(projectDir || process.cwd(), 'bmad');
+    const installer = new Installer();
+    const bmadDir = await installer.findBmadDir(projectDir || process.cwd());
     const existingInstall = await detector.detect(bmadDir);
     const configuredIdes = existingInstall.ides || [];
 
@@ -322,8 +334,10 @@ class UI {
    */
   async getExistingInstallation(directory) {
     const { Detector } = require('../installers/lib/core/detector');
+    const { Installer } = require('../installers/lib/core/installer');
     const detector = new Detector();
-    const bmadDir = path.join(directory, 'bmad');
+    const installer = new Installer();
+    const bmadDir = await installer.findBmadDir(directory);
     const existingInstall = await detector.detect(bmadDir);
     const installedModuleIds = new Set(existingInstall.modules.map((mod) => mod.id));
 
@@ -421,17 +435,20 @@ class UI {
       if (stats.isDirectory()) {
         const files = await fs.readdir(directory);
         if (files.length > 0) {
+          // Check for any bmad installation (any folder with _cfg/manifest.yaml)
+          const { Installer } = require('../installers/lib/core/installer');
+          const installer = new Installer();
+          const bmadDir = await installer.findBmadDir(directory);
+          const hasBmadInstall = (await fs.pathExists(bmadDir)) && (await fs.pathExists(path.join(bmadDir, '_cfg', 'manifest.yaml')));
+
           console.log(
             chalk.gray(`Directory exists and contains ${files.length} item(s)`) +
-              (files.includes('bmad') ? chalk.yellow(' including existing bmad installation') : ''),
+              (hasBmadInstall ? chalk.yellow(` including existing BMAD installation (${path.basename(bmadDir)})`) : ''),
           );
         } else {
           console.log(chalk.gray('Directory exists and is empty'));
         }
       }
-    } else {
-      const existingParent = await this.findExistingParent(directory);
-      console.log(chalk.gray(`Will create in: ${existingParent}`));
     }
   }
 

package/tools/cli/lib/yaml-xml-builder.js

@@ -270,13 +270,31 @@ class YamlXmlBuilder {
 
   /**
    * Build prompts XML section
+   * Handles both array format and object/dictionary format
    */
   buildPromptsXml(prompts) {
-    if (!prompts || prompts.length === 0) return '';
+    if (!prompts) return '';
+
+    // Handle object/dictionary format: { promptId: 'content', ... }
+    // Convert to array format for processing
+    let promptsArray = prompts;
+    if (!Array.isArray(prompts)) {
+      // Check if it's an object with no length property (dictionary format)
+      if (typeof prompts === 'object' && prompts.length === undefined) {
+        promptsArray = Object.entries(prompts).map(([id, content]) => ({
+          id: id,
+          content: content,
+        }));
+      } else {
+        return ''; // Not a valid prompts format
+      }
+    }
+
+    if (promptsArray.length === 0) return '';
 
     let xml = '  <prompts>\n';
 
-    for (const prompt of prompts) {
+    for (const prompt of promptsArray) {
       xml += `    <prompt id="${prompt.id || ''}">\n`;
       xml += `      <![CDATA[\n`;
       xml += `      ${prompt.content || ''}\n`;