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

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

@@ -15,6 +15,67 @@ class CodexSetup extends BaseIdeSetup {
     super('codex', 'Codex', true); // preferred IDE
   }
 
+  /**
+   * Collect configuration choices before installation
+   * @param {Object} options - Configuration options
+   * @returns {Object} Collected configuration
+   */
+  async collectConfiguration(options = {}) {
+    const inquirer = require('inquirer');
+
+    let confirmed = false;
+    let installLocation = 'global';
+
+    while (!confirmed) {
+      const { location } = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'location',
+          message: 'Where would you like to install Codex CLI prompts?',
+          choices: [
+            {
+              name: 'Global - Simple for single project ' + '(~/.codex/prompts, but references THIS project only)',
+              value: 'global',
+            },
+            {
+              name: `Project-specific - Recommended for real work (requires CODEX_HOME=<project-dir>${path.sep}.codex)`,
+              value: 'project',
+            },
+          ],
+          default: 'global',
+        },
+      ]);
+
+      installLocation = location;
+
+      // Display detailed instructions for the chosen option
+      console.log('');
+      if (installLocation === 'project') {
+        console.log(this.getProjectSpecificInstructions());
+      } else {
+        console.log(this.getGlobalInstructions());
+      }
+
+      // Confirm the choice
+      const { proceed } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'proceed',
+          message: 'Proceed with this installation option?',
+          default: true,
+        },
+      ]);
+
+      confirmed = proceed;
+
+      if (!confirmed) {
+        console.log(chalk.yellow("\n  Let's choose a different installation option.\n"));
+      }
+    }
+
+    return { installLocation };
+  }
+
   /**
    * Setup Codex configuration
    * @param {string} projectDir - Project directory
@@ -27,9 +88,12 @@ class CodexSetup extends BaseIdeSetup {
     // Always use CLI mode
     const mode = 'cli';
 
+    // Get installation location from pre-collected config or default to global
+    const installLocation = options.preCollectedConfig?.installLocation || 'global';
+
     const { artifacts, counts } = await this.collectClaudeArtifacts(projectDir, bmadDir, options);
 
-    const destDir = this.getCodexPromptDir();
+    const destDir = this.getCodexPromptDir(projectDir, installLocation);
     await fs.ensureDir(destDir);
     await this.clearOldBmadFiles(destDir);
     const written = await this.flattenAndWriteArtifacts(artifacts, destDir);
@@ -45,22 +109,6 @@ class CodexSetup extends BaseIdeSetup {
     console.log(chalk.dim(`  - ${written} Codex prompt files written`));
     console.log(chalk.dim(`  - Destination: ${destDir}`));
 
-    // Prominent notice about home directory installation
-    console.log('');
-    console.log(chalk.bold.cyan('═'.repeat(70)));
-    console.log(chalk.bold.yellow('  IMPORTANT: Codex Configuration'));
-    console.log(chalk.bold.cyan('═'.repeat(70)));
-    console.log('');
-    console.log(chalk.white('  Prompts have been installed to your HOME DIRECTORY, not this project.'));
-    console.log(chalk.white('  No .codex file was created in the project root.'));
-    console.log('');
-    console.log(chalk.green('  ✓ You can now use slash commands (/) in Codex CLI'));
-    console.log(chalk.dim('    Example: /bmad-bmm-agents-pm'));
-    console.log(chalk.dim('    Type / to see all available commands'));
-    console.log('');
-    console.log(chalk.bold.cyan('═'.repeat(70)));
-    console.log('');
-
     return {
       success: true,
       mode,
@@ -68,21 +116,36 @@ class CodexSetup extends BaseIdeSetup {
       counts,
       destination: destDir,
       written,
+      installLocation,
     };
   }
 
   /**
    * Detect Codex installation by checking for BMAD prompt exports
    */
-  async detect(_projectDir) {
-    const destDir = this.getCodexPromptDir();
+  async detect(projectDir) {
+    // Check both global and project-specific locations
+    const globalDir = this.getCodexPromptDir(null, 'global');
+    const projectDir_local = projectDir || process.cwd();
+    const projectSpecificDir = this.getCodexPromptDir(projectDir_local, 'project');
 
-    if (!(await fs.pathExists(destDir))) {
-      return false;
+    // Check global location
+    if (await fs.pathExists(globalDir)) {
+      const entries = await fs.readdir(globalDir);
+      if (entries.some((entry) => entry.startsWith('bmad-'))) {
+        return true;
+      }
     }
 
-    const entries = await fs.readdir(destDir);
-    return entries.some((entry) => entry.startsWith('bmad-'));
+    // Check project-specific location
+    if (await fs.pathExists(projectSpecificDir)) {
+      const entries = await fs.readdir(projectSpecificDir);
+      if (entries.some((entry) => entry.startsWith('bmad-'))) {
+        return true;
+      }
+    }
+
+    return false;
   }
 
   /**
@@ -142,15 +205,13 @@ class CodexSetup extends BaseIdeSetup {
     };
   }
 
-  getCodexPromptDir() {
+  getCodexPromptDir(projectDir = null, location = 'global') {
+    if (location === 'project' && projectDir) {
+      return path.join(projectDir, '.codex', 'prompts');
+    }
     return path.join(os.homedir(), '.codex', 'prompts');
   }
 
-  flattenFilename(relativePath) {
-    const sanitized = relativePath.replaceAll(/[\\/]/g, '-');
-    return `bmad-${sanitized}`;
-  }
-
   async flattenAndWriteArtifacts(artifacts, destDir) {
     let written = 0;
 
@@ -192,11 +253,135 @@ class CodexSetup extends BaseIdeSetup {
   }
 
   /**
-   * Cleanup Codex configuration (no-op until export destination is finalized)
+   * Get instructions for global installation
+   * @returns {string} Instructions text
+   */
+  getGlobalInstructions(destDir) {
+    const lines = [
+      '',
+      chalk.bold.cyan('═'.repeat(70)),
+      chalk.bold.yellow('  IMPORTANT: Codex Configuration'),
+      chalk.bold.cyan('═'.repeat(70)),
+      '',
+      chalk.white('  /prompts installed globally to your HOME DIRECTORY.'),
+      '',
+      chalk.yellow('  ⚠️  These prompts reference a specific .bmad path'),
+      chalk.dim("  To use with other projects, you'd need to copy the .bmad dir"),
+      '',
+      chalk.green('  ✓ You can now use /commands in Codex CLI'),
+      chalk.dim('    Example: /bmad-bmm-agents-pm'),
+      chalk.dim('    Type / to see all available commands'),
+      '',
+      chalk.bold.cyan('═'.repeat(70)),
+      '',
+    ];
+    return lines.join('\n');
+  }
+
+  /**
+   * Get instructions for project-specific installation
+   * @param {string} projectDir - Optional project directory
+   * @param {string} destDir - Optional destination directory
+   * @returns {string} Instructions text
+   */
+  getProjectSpecificInstructions(projectDir = null, destDir = null) {
+    const isWindows = os.platform() === 'win32';
+
+    const commonLines = [
+      '',
+      chalk.bold.cyan('═'.repeat(70)),
+      chalk.bold.yellow('  Project-Specific Codex Configuration'),
+      chalk.bold.cyan('═'.repeat(70)),
+      '',
+      chalk.white('  Prompts will be installed to: ') + chalk.cyan(destDir || '<project>/.codex/prompts'),
+      '',
+      chalk.bold.yellow('  ⚠️  REQUIRED: You must set CODEX_HOME to use these prompts'),
+      '',
+    ];
+
+    const windowsLines = [
+      chalk.bold('  Create a codex.cmd file in your project root:'),
+      '',
+      chalk.green('    @echo off'),
+      chalk.green('    set CODEX_HOME=%~dp0.codex'),
+      chalk.green('    codex %*'),
+      '',
+      chalk.dim(String.raw`  Then run: .\codex instead of codex`),
+      chalk.dim('  (The %~dp0 gets the directory of the .cmd file)'),
+    ];
+
+    const unixLines = [
+      chalk.bold('  Add this alias to your ~/.bashrc or ~/.zshrc:'),
+      '',
+      chalk.green('    alias codex=\'CODEX_HOME="$PWD/.codex" codex\''),
+      '',
+      chalk.dim('  After adding, run: source ~/.bashrc  (or source ~/.zshrc)'),
+      chalk.dim('  (The $PWD uses your current working directory)'),
+    ];
+    const closingLines = [
+      '',
+      chalk.dim('  This tells Codex CLI to use prompts from this project instead of ~/.codex'),
+      '',
+      chalk.bold.cyan('═'.repeat(70)),
+      '',
+    ];
+
+    const lines = [...commonLines, ...(isWindows ? windowsLines : unixLines), ...closingLines];
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Cleanup Codex configuration
    */
-  async cleanup() {
+  async cleanup(projectDir = null) {
+    // Clean both global and project-specific locations
+    const globalDir = this.getCodexPromptDir(null, 'global');
+    await this.clearOldBmadFiles(globalDir);
+
+    if (projectDir) {
+      const projectSpecificDir = this.getCodexPromptDir(projectDir, 'project');
+      await this.clearOldBmadFiles(projectSpecificDir);
+    }
+  }
+
+  /**
+   * Install a custom agent launcher for Codex
+   * @param {string} projectDir - Project directory (not used, Codex installs to home)
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object|null} Info about created command
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
     const destDir = this.getCodexPromptDir();
-    await this.clearOldBmadFiles(destDir);
+    await fs.ensureDir(destDir);
+
+    const launcherContent = `---
+name: '${agentName}'
+description: '${agentName} agent'
+---
+
+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 @${agentPath}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+
+    const fileName = `bmad-custom-agents-${agentName}.md`;
+    const launcherPath = path.join(destDir, fileName);
+    await fs.writeFile(launcherPath, launcherContent, 'utf8');
+
+    return {
+      path: launcherPath,
+      command: `/${fileName.replace('.md', '')}`,
+    };
   }
 }
 

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

@@ -347,6 +347,54 @@ alwaysApply: false
     // Return MDC header + launcher content (without its original frontmatter)
     return mdcHeader + contentWithoutFrontmatter;
   }
+
+  /**
+   * Install a custom agent launcher for Cursor
+   * @param {string} projectDir - Project directory
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object|null} Info about created command
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
+    const customAgentsDir = path.join(projectDir, this.configDir, this.rulesDir, 'bmad', 'custom', 'agents');
+
+    if (!(await this.exists(path.join(projectDir, this.configDir)))) {
+      return null; // IDE not configured for this project
+    }
+
+    await this.ensureDir(customAgentsDir);
+
+    const launcherContent = `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 @${agentPath}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+
+    // Cursor uses MDC format with metadata header
+    const mdcContent = `---
+description: "${agentName} agent"
+globs:
+alwaysApply: false
+---
+
+${launcherContent}
+`;
+
+    const launcherPath = path.join(customAgentsDir, `${agentName}.mdc`);
+    await this.writeFile(launcherPath, mdcContent);
+
+    return {
+      path: launcherPath,
+      command: `@${agentName}`,
+    };
+  }
 }
 
 module.exports = { CursorSetup };

package/tools/cli/installers/lib/ide/github-copilot.js

@@ -297,6 +297,80 @@ ${cleanContent}
       }
     }
   }
+
+  /**
+   * Install a custom agent launcher for GitHub Copilot
+   * @param {string} projectDir - Project directory
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object|null} Info about created command
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
+    const chatmodesDir = path.join(projectDir, this.configDir, this.chatmodesDir);
+
+    if (!(await this.exists(path.join(projectDir, this.configDir)))) {
+      return null; // IDE not configured for this project
+    }
+
+    await this.ensureDir(chatmodesDir);
+
+    const launcherContent = `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 @${agentPath}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+
+    // GitHub Copilot needs specific tools in frontmatter
+    const copilotTools = [
+      'changes',
+      'codebase',
+      'createDirectory',
+      'createFile',
+      'editFiles',
+      'fetch',
+      'fileSearch',
+      'githubRepo',
+      'listDirectory',
+      'problems',
+      'readFile',
+      'runInTerminal',
+      'runTask',
+      'runTests',
+      'runVscodeCommand',
+      'search',
+      'searchResults',
+      'terminalLastCommand',
+      'terminalSelection',
+      'testFailure',
+      'textSearch',
+      'usages',
+    ];
+
+    const chatmodeContent = `---
+description: "Activates the ${metadata.title || agentName} agent persona."
+tools: ${JSON.stringify(copilotTools)}
+---
+
+# ${metadata.title || agentName} Agent
+
+${launcherContent}
+`;
+
+    const chatmodePath = path.join(chatmodesDir, `bmad-agent-custom-${agentName}.chatmode.md`);
+    await this.writeFile(chatmodePath, chatmodeContent);
+
+    return {
+      path: chatmodePath,
+      command: `bmad-agent-custom-${agentName}`,
+    };
+  }
 }
 
 module.exports = { GitHubCopilotSetup };

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

@@ -204,6 +204,41 @@ class IdeManager {
 
     return detected;
   }
+
+  /**
+   * Install custom agent launchers for specified IDEs
+   * @param {Array} ides - List of IDE names to install for
+   * @param {string} projectDir - Project directory
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object} Results for each IDE
+   */
+  async installCustomAgentLaunchers(ides, projectDir, agentName, agentPath, metadata) {
+    const results = {};
+
+    for (const ideName of ides) {
+      const handler = this.handlers.get(ideName.toLowerCase());
+
+      if (!handler) {
+        console.warn(chalk.yellow(`⚠️  IDE '${ideName}' is not yet supported for custom agent installation`));
+        continue;
+      }
+
+      try {
+        if (typeof handler.installCustomAgentLauncher === 'function') {
+          const result = await handler.installCustomAgentLauncher(projectDir, agentName, agentPath, metadata);
+          if (result) {
+            results[ideName] = result;
+          }
+        }
+      } catch (error) {
+        console.warn(chalk.yellow(`⚠️  Failed to install ${ideName} launcher: ${error.message}`));
+      }
+    }
+
+    return results;
+  }
 }
 
 module.exports = { IdeManager };

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

@@ -207,6 +207,51 @@ class OpenCodeSetup extends BaseIdeSetup {
       console.log(chalk.dim(`  Cleaned up ${removed} existing BMAD files`));
     }
   }
+
+  /**
+   * Install a custom agent launcher for OpenCode
+   * @param {string} projectDir - Project directory
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object|null} Info about created command
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
+    const agentsDir = path.join(projectDir, this.configDir, this.agentsDir);
+
+    if (!(await this.exists(path.join(projectDir, this.configDir)))) {
+      return null; // IDE not configured for this project
+    }
+
+    await this.ensureDir(agentsDir);
+
+    const launcherContent = `---
+name: '${agentName}'
+description: '${metadata.title || agentName} agent'
+mode: 'primary'
+---
+
+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 @${agentPath}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+
+    // OpenCode uses flat naming: bmad-agent-custom-{name}.md
+    const launcherPath = path.join(agentsDir, `bmad-agent-custom-${agentName}.md`);
+    await this.writeFile(launcherPath, launcherContent);
+
+    return {
+      path: launcherPath,
+      command: `bmad-agent-custom-${agentName}`,
+    };
+  }
 }
 
 module.exports = { OpenCodeSetup };

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

@@ -206,6 +206,53 @@ ${content}`;
       console.log(chalk.dim(`  Cleaned up existing BMAD workflows`));
     }
   }
+
+  /**
+   * Install a custom agent launcher for Windsurf
+   * @param {string} projectDir - Project directory
+   * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
+   * @param {string} agentPath - Path to compiled agent (relative to project root)
+   * @param {Object} metadata - Agent metadata
+   * @returns {Object|null} Info about created command
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
+    const fs = require('fs-extra');
+    const customAgentsDir = path.join(projectDir, this.configDir, this.workflowsDir, 'bmad', 'custom', 'agents');
+
+    if (!(await this.exists(path.join(projectDir, this.configDir)))) {
+      return null; // IDE not configured for this project
+    }
+
+    await this.ensureDir(customAgentsDir);
+
+    const launcherContent = `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 @${agentPath}
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+
+    // Windsurf uses workflow format with frontmatter
+    const workflowContent = `---
+description: ${metadata.title || agentName}
+auto_execution_mode: 3
+---
+
+${launcherContent}`;
+
+    const launcherPath = path.join(customAgentsDir, `${agentName}.md`);
+    await fs.writeFile(launcherPath, workflowContent);
+
+    return {
+      path: launcherPath,
+      command: `bmad/custom/agents/${agentName}`,
+    };
+  }
 }
 
 module.exports = { WindsurfSetup };