bmad-method 6.0.0-alpha.1 → 6.0.0-alpha.11

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;
   }
@@ -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/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);
+      }
+    }
   }
 
   /**
@@ -112,6 +176,10 @@ class ModuleManager {
       await fs.remove(targetPath);
     }
 
+    // Vendor cross-module workflows BEFORE copying
+    // This reads source agent.yaml files and copies referenced workflows
+    await this.vendorCrossModuleWorkflows(sourcePath, targetPath, moduleName);
+
     // Copy module files with filtering
     await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
 
@@ -267,6 +335,12 @@ class ModuleManager {
         continue;
       }
 
+      // Skip user documentation if install_user_docs is false
+      if (moduleConfig.install_user_docs === false && (file.startsWith('docs/') || file.startsWith('docs\\'))) {
+        console.log(chalk.dim(`  Skipping user documentation: ${file}`));
+        continue;
+      }
+
       // Skip game development content if include_game_planning is false
       if (moduleConfig.include_game_planning === false) {
         const shouldSkipGameDev = gameDevFiles.some((gamePath) => {
@@ -301,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
@@ -323,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;
       }
@@ -390,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
@@ -429,6 +507,135 @@ class ModuleManager {
     }
   }
 
+  /**
+   * Vendor cross-module workflows referenced in agent files
+   * Scans SOURCE agent.yaml files for workflow-install and copies workflows to destination
+   * @param {string} sourcePath - Source module path
+   * @param {string} targetPath - Target module path (destination)
+   * @param {string} moduleName - Module name being installed
+   */
+  async vendorCrossModuleWorkflows(sourcePath, targetPath, moduleName) {
+    const sourceAgentsPath = path.join(sourcePath, 'agents');
+
+    // Check if source agents directory exists
+    if (!(await fs.pathExists(sourceAgentsPath))) {
+      return; // No agents to process
+    }
+
+    // Get all agent YAML files from source
+    const agentFiles = await fs.readdir(sourceAgentsPath);
+    const yamlFiles = agentFiles.filter((f) => f.endsWith('.agent.yaml') || f.endsWith('.yaml'));
+
+    if (yamlFiles.length === 0) {
+      return; // No YAML agent files
+    }
+
+    let workflowsVendored = false;
+
+    for (const agentFile of yamlFiles) {
+      const agentPath = path.join(sourceAgentsPath, agentFile);
+      const agentYaml = yaml.load(await fs.readFile(agentPath, 'utf8'));
+
+      // Check if agent has menu items with workflow-install
+      const menuItems = agentYaml?.agent?.menu || [];
+      const workflowInstallItems = menuItems.filter((item) => item['workflow-install']);
+
+      if (workflowInstallItems.length === 0) {
+        continue; // No workflow-install in this agent
+      }
+
+      if (!workflowsVendored) {
+        console.log(chalk.cyan(`\n  Vendoring cross-module workflows for ${moduleName}...`));
+        workflowsVendored = true;
+      }
+
+      console.log(chalk.dim(`    Processing: ${agentFile}`));
+
+      for (const item of workflowInstallItems) {
+        const sourceWorkflowPath = item.workflow; // Where to copy FROM
+        const installWorkflowPath = item['workflow-install']; // Where to copy TO
+
+        // Parse SOURCE workflow path
+        // 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;
+        }
+
+        const [, sourceModule, sourceWorkflowSubPath] = sourceMatch;
+
+        // Parse INSTALL workflow path
+        // 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;
+        }
+
+        const installWorkflowSubPath = installMatch[2];
+
+        // Determine actual filesystem paths
+        const sourceModulePath = path.join(this.modulesSourcePath, sourceModule);
+        const actualSourceWorkflowPath = path.join(sourceModulePath, 'workflows', sourceWorkflowSubPath.replace(/\/workflow\.yaml$/, ''));
+
+        const actualDestWorkflowPath = path.join(targetPath, 'workflows', installWorkflowSubPath.replace(/\/workflow\.yaml$/, ''));
+
+        // Check if source workflow exists
+        if (!(await fs.pathExists(actualSourceWorkflowPath))) {
+          console.warn(chalk.yellow(`      Source workflow not found: ${actualSourceWorkflowPath}`));
+          continue;
+        }
+
+        // Copy the entire workflow folder
+        console.log(
+          chalk.dim(
+            `      Vendoring: ${sourceModule}/workflows/${sourceWorkflowSubPath.replace(/\/workflow\.yaml$/, '')} → ${moduleName}/workflows/${installWorkflowSubPath.replace(/\/workflow\.yaml$/, '')}`,
+          ),
+        );
+
+        await fs.ensureDir(path.dirname(actualDestWorkflowPath));
+        // 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');
+        if (await fs.pathExists(workflowYamlPath)) {
+          await this.updateWorkflowConfigSource(workflowYamlPath, moduleName);
+        }
+      }
+    }
+
+    if (workflowsVendored) {
+      console.log(chalk.green(`  ✓ Workflow vendoring complete\n`));
+    }
+  }
+
+  /**
+   * Update workflow.yaml config_source to point to new module
+   * @param {string} workflowYamlPath - Path to workflow.yaml file
+   * @param {string} newModuleName - New module name to reference
+   */
+  async updateWorkflowConfigSource(workflowYamlPath, newModuleName) {
+    let yamlContent = await fs.readFile(workflowYamlPath, 'utf8');
+
+    // 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: ${this.bmadFolderName}/${newModuleName}/config.yaml`));
+    }
+  }
+
   /**
    * Run module-specific installer if it exists
    * @param {string} moduleName - Name of the module
@@ -530,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);
     }
   }