bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.21

package/tools/cli/installers/lib/ide/shared/workflow-command-generator.js

@@ -0,0 +1,241 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const csv = require('csv-parse/sync');
+const chalk = require('chalk');
+
+/**
+ * Generates command files for each workflow in the manifest
+ */
+class WorkflowCommandGenerator {
+  constructor(bmadFolderName = 'bmad') {
+    this.templatePath = path.join(__dirname, '../templates/workflow-command-template.md');
+    this.bmadFolderName = bmadFolderName;
+  }
+
+  /**
+   * Generate workflow commands from the manifest CSV
+   * @param {string} projectDir - Project directory
+   * @param {string} bmadDir - BMAD installation directory
+   */
+  async generateWorkflowCommands(projectDir, bmadDir) {
+    const workflows = await this.loadWorkflowManifest(bmadDir);
+
+    if (!workflows) {
+      console.log(chalk.yellow('Workflow manifest not found. Skipping command generation.'));
+      return { generated: 0 };
+    }
+
+    // ALL workflows now generate commands - no standalone filtering
+    const allWorkflows = workflows;
+
+    // Base commands directory
+    const baseCommandsDir = path.join(projectDir, '.claude', 'commands', 'bmad');
+
+    let generatedCount = 0;
+
+    // Generate a command file for each workflow, organized by module
+    for (const workflow of allWorkflows) {
+      const moduleWorkflowsDir = path.join(baseCommandsDir, workflow.module, 'workflows');
+      await fs.ensureDir(moduleWorkflowsDir);
+
+      const commandContent = await this.generateCommandContent(workflow, bmadDir);
+      const commandPath = path.join(moduleWorkflowsDir, `${workflow.name}.md`);
+
+      await fs.writeFile(commandPath, commandContent);
+      generatedCount++;
+    }
+
+    // Also create a workflow launcher README in each module
+    const groupedWorkflows = this.groupWorkflowsByModule(allWorkflows);
+    await this.createModuleWorkflowLaunchers(baseCommandsDir, groupedWorkflows);
+
+    return { generated: generatedCount };
+  }
+
+  async collectWorkflowArtifacts(bmadDir) {
+    const workflows = await this.loadWorkflowManifest(bmadDir);
+
+    if (!workflows) {
+      return { artifacts: [], counts: { commands: 0, launchers: 0 } };
+    }
+
+    // ALL workflows now generate commands - no standalone filtering
+    const allWorkflows = workflows;
+
+    const artifacts = [];
+
+    for (const workflow of allWorkflows) {
+      const commandContent = await this.generateCommandContent(workflow, bmadDir);
+      artifacts.push({
+        type: 'workflow-command',
+        module: workflow.module,
+        relativePath: path.join(workflow.module, 'workflows', `${workflow.name}.md`),
+        content: commandContent,
+        sourcePath: workflow.path,
+      });
+    }
+
+    const groupedWorkflows = this.groupWorkflowsByModule(allWorkflows);
+    for (const [module, launcherContent] of Object.entries(this.buildModuleWorkflowLaunchers(groupedWorkflows))) {
+      artifacts.push({
+        type: 'workflow-launcher',
+        module,
+        relativePath: path.join(module, 'workflows', 'README.md'),
+        content: launcherContent,
+        sourcePath: null,
+      });
+    }
+
+    return {
+      artifacts,
+      counts: {
+        commands: allWorkflows.length,
+        launchers: Object.keys(groupedWorkflows).length,
+      },
+    };
+  }
+
+  /**
+   * Generate command content for a workflow
+   */
+  async generateCommandContent(workflow, bmadDir) {
+    // Determine template based on workflow file type
+    const isMarkdownWorkflow = workflow.path.endsWith('workflow.md');
+    const templateName = isMarkdownWorkflow ? 'workflow-commander.md' : 'workflow-command-template.md';
+    const templatePath = path.join(path.dirname(this.templatePath), templateName);
+
+    // Load the appropriate template
+    const template = await fs.readFile(templatePath, 'utf8');
+
+    // Convert source path to installed path
+    // From: /Users/.../src/modules/bmm/workflows/.../workflow.yaml
+    // To: {project-root}/_bmad/bmm/workflows/.../workflow.yaml
+    let workflowPath = workflow.path;
+
+    // Extract the relative path from source
+    if (workflowPath.includes('/src/modules/')) {
+      const match = workflowPath.match(/\/src\/modules\/(.+)/);
+      if (match) {
+        workflowPath = `${this.bmadFolderName}/${match[1]}`;
+      }
+    } else if (workflowPath.includes('/src/core/')) {
+      const match = workflowPath.match(/\/src\/core\/(.+)/);
+      if (match) {
+        workflowPath = `${this.bmadFolderName}/core/${match[1]}`;
+      }
+    }
+
+    // Replace template variables
+    return template
+      .replaceAll('{{name}}', workflow.name)
+      .replaceAll('{{module}}', workflow.module)
+      .replaceAll('{{description}}', workflow.description)
+      .replaceAll('{{workflow_path}}', workflowPath)
+      .replaceAll('_bmad', this.bmadFolderName)
+      .replaceAll('_bmad', '_bmad');
+  }
+
+  /**
+   * Create workflow launcher files for each module
+   */
+  async createModuleWorkflowLaunchers(baseCommandsDir, workflowsByModule) {
+    for (const [module, moduleWorkflows] of Object.entries(workflowsByModule)) {
+      const content = this.buildLauncherContent(module, moduleWorkflows);
+      const moduleWorkflowsDir = path.join(baseCommandsDir, module, 'workflows');
+      await fs.ensureDir(moduleWorkflowsDir);
+      const launcherPath = path.join(moduleWorkflowsDir, 'README.md');
+      await fs.writeFile(launcherPath, content);
+    }
+  }
+
+  groupWorkflowsByModule(workflows) {
+    const workflowsByModule = {};
+
+    for (const workflow of workflows) {
+      if (!workflowsByModule[workflow.module]) {
+        workflowsByModule[workflow.module] = [];
+      }
+
+      workflowsByModule[workflow.module].push({
+        ...workflow,
+        displayPath: this.transformWorkflowPath(workflow.path),
+      });
+    }
+
+    return workflowsByModule;
+  }
+
+  buildModuleWorkflowLaunchers(groupedWorkflows) {
+    const launchers = {};
+
+    for (const [module, moduleWorkflows] of Object.entries(groupedWorkflows)) {
+      launchers[module] = this.buildLauncherContent(module, moduleWorkflows);
+    }
+
+    return launchers;
+  }
+
+  buildLauncherContent(module, moduleWorkflows) {
+    let content = `# ${module.toUpperCase()} Workflows
+
+## Available Workflows in ${module}
+
+`;
+
+    for (const workflow of moduleWorkflows) {
+      content += `**${workflow.name}**\n`;
+      content += `- Path: \`${workflow.displayPath}\`\n`;
+      content += `- ${workflow.description}\n\n`;
+    }
+
+    content += `
+## Execution
+
+When running any workflow:
+1. LOAD {project-root}/${this.bmadFolderName}/core/tasks/workflow.xml
+2. Pass the workflow path as 'workflow-config' parameter
+3. Follow workflow.xml instructions EXACTLY
+4. Save outputs after EACH section
+
+## Modes
+- Normal: Full interaction
+- #yolo: Skip optional steps
+`;
+
+    return content;
+  }
+
+  transformWorkflowPath(workflowPath) {
+    let transformed = workflowPath;
+
+    if (workflowPath.includes('/src/modules/')) {
+      const match = workflowPath.match(/\/src\/modules\/(.+)/);
+      if (match) {
+        transformed = `{project-root}/${this.bmadFolderName}/${match[1]}`;
+      }
+    } else if (workflowPath.includes('/src/core/')) {
+      const match = workflowPath.match(/\/src\/core\/(.+)/);
+      if (match) {
+        transformed = `{project-root}/${this.bmadFolderName}/core/${match[1]}`;
+      }
+    }
+
+    return transformed;
+  }
+
+  async loadWorkflowManifest(bmadDir) {
+    const manifestPath = path.join(bmadDir, '_config', 'workflow-manifest.csv');
+
+    if (!(await fs.pathExists(manifestPath))) {
+      return null;
+    }
+
+    const csvContent = await fs.readFile(manifestPath, 'utf8');
+    return csv.parse(csvContent, {
+      columns: true,
+      skip_empty_lines: true,
+    });
+  }
+}
+
+module.exports = { WorkflowCommandGenerator };

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/{{module}}/agents/{{path}}
+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}/{{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}/{{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}/{{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}/{{module}}/config.yaml.
+2.  [ ] IMMEDIATE ACTION: Read and load the task definition at @{_bmad}/{{module}}/tasks/{{filename}}.
+
+Follow all instructions and complete the task as defined.
+
+TASK DEFINITION: @{_bmad}/{{module}}/tasks/{{filename}}
+"""

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

@@ -0,0 +1,13 @@
+---
+description: '{{description}}'
+---
+
+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 @_bmad/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 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/templates/workflow-commander.md

@@ -0,0 +1,5 @@
+---
+description: '{{description}}'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{{workflow_path}}, READ its entire contents and follow its directions exactly!

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

@@ -1,6 +1,8 @@
 const path = require('node:path');
+const fs = require('fs-extra');
 const { BaseIdeSetup } = require('./_base-ide');
 const chalk = require('chalk');
+const { AgentCommandGenerator } = require('./shared/agent-command-generator');
 
 /**
  * Trae IDE setup handler
@@ -30,20 +32,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 +112,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;
@@ -273,6 +262,52 @@ Part of the BMAD ${workflow.module.toUpperCase()} module.
       }
     }
   }
+
+  /**
+   * Install a custom agent launcher for Trae
+   * @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} Installation result
+   */
+  async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
+    const traeDir = path.join(projectDir, this.configDir);
+    const rulesDir = path.join(traeDir, this.rulesDir);
+
+    // Create .trae/rules directory if it doesn't exist
+    await fs.ensureDir(rulesDir);
+
+    // Create custom agent launcher
+    const launcherContent = `# ${agentName} Custom Agent
+
+**⚠️ IMPORTANT**: Run @${agentPath} first to load the complete agent!
+
+This is a launcher for the custom BMAD agent "${agentName}".
+
+## Usage
+1. First run: \`${agentPath}\` to load the complete agent
+2. Then use this rule to activate ${agentName}
+
+The agent will follow the persona and instructions from the main agent file.
+
+---
+
+*Generated by BMAD Method*`;
+
+    const fileName = `bmad-agent-custom-${agentName.toLowerCase()}.md`;
+    const launcherPath = path.join(rulesDir, fileName);
+
+    // Write the launcher file
+    await fs.writeFile(launcherPath, launcherContent, 'utf8');
+
+    return {
+      ide: 'trae',
+      path: path.relative(projectDir, launcherPath),
+      command: agentName,
+      type: 'custom-agent-launcher',
+    };
+  }
 }
 
 module.exports = { TraeSetup };

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;
   }
@@ -196,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 };

package/tools/cli/installers/lib/message-loader.js

@@ -0,0 +1,85 @@
+const fs = require('fs-extra');
+const path = require('node:path');
+const yaml = require('yaml');
+const chalk = require('chalk');
+
+/**
+ * Load and display installer messages from messages.yaml
+ */
+class MessageLoader {
+  constructor() {}
+
+  /**
+   * Load messages from the YAML file
+   * @returns {Object|null} Messages object or null if not found
+   */
+  load() {
+    if (this.messages) {
+      return this.messages;
+    }
+
+    const messagesPath = path.join(__dirname, '..', 'install-messages.yaml');
+
+    try {
+      const content = fs.readFileSync(messagesPath, 'utf8');
+      this.messages = yaml.parse(content);
+      return this.messages;
+    } catch {
+      // File doesn't exist or is invalid - return null
+      return null;
+    }
+  }
+
+  /**
+   * Get the start message for display
+   * @returns {string|null} Start message or null
+   */
+  getStartMessage() {
+    const messages = this.load();
+    return messages?.startMessage || null;
+  }
+
+  /**
+   * Get the end message for display
+   * @returns {string|null} End message or null
+   */
+  getEndMessage() {
+    const messages = this.load();
+    return messages?.endMessage || null;
+  }
+
+  /**
+   * Display the start message (after logo, before prompts)
+   */
+  displayStartMessage() {
+    const message = this.getStartMessage();
+    if (message) {
+      console.log(chalk.cyan(message));
+      console.log();
+    }
+  }
+
+  /**
+   * Display the end message (after installation completes)
+   */
+  displayEndMessage() {
+    const message = this.getEndMessage();
+    if (message) {
+      console.log();
+      console.log(chalk.cyan(message));
+    }
+  }
+
+  /**
+   * Check if messages exist for the current version
+   * @param {string} currentVersion - Current package version
+   * @returns {boolean} True if messages match current version
+   */
+  isCurrent(currentVersion) {
+    const messages = this.load();
+    return messages && messages.version === currentVersion;
+  }
+  messages = null;
+}
+
+module.exports = { MessageLoader };