bmad-method 6.0.0-alpha.13 → 6.0.0-alpha.15

package/tools/cli/installers/lib/custom/handler.js

@@ -0,0 +1,396 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const chalk = require('chalk');
+const yaml = require('js-yaml');
+const { FileOps } = require('../../../lib/file-ops');
+const { XmlHandler } = require('../../../lib/xml-handler');
+
+/**
+ * Handler for custom content (custom.yaml)
+ * Installs custom agents and workflows without requiring a full module structure
+ */
+class CustomHandler {
+  constructor() {
+    this.fileOps = new FileOps();
+    this.xmlHandler = new XmlHandler();
+  }
+
+  /**
+   * Find all custom.yaml files in the project
+   * @param {string} projectRoot - Project root directory
+   * @returns {Array} List of custom content paths
+   */
+  async findCustomContent(projectRoot) {
+    const customPaths = [];
+
+    // Helper function to recursively scan directories
+    async function scanDirectory(dir, excludePaths = []) {
+      try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+
+          // Skip hidden directories and common exclusions
+          if (
+            entry.name.startsWith('.') ||
+            entry.name === 'node_modules' ||
+            entry.name === 'dist' ||
+            entry.name === 'build' ||
+            entry.name === '.git' ||
+            entry.name === 'bmad'
+          ) {
+            continue;
+          }
+
+          // Skip excluded paths
+          if (excludePaths.some((exclude) => fullPath.startsWith(exclude))) {
+            continue;
+          }
+
+          if (entry.isDirectory()) {
+            // Recursively scan subdirectories
+            await scanDirectory(fullPath, excludePaths);
+          } else if (entry.name === 'custom.yaml') {
+            // Found a custom.yaml file
+            customPaths.push(fullPath);
+          } else if (
+            entry.name === 'module.yaml' && // Check if this is a custom module (either in _module-installer or in root directory)
+            // Skip if it's in src/modules (those are standard modules)
+            !fullPath.includes(path.join('src', 'modules'))
+          ) {
+            customPaths.push(fullPath);
+          }
+        }
+      } catch {
+        // Ignore errors (e.g., permission denied)
+      }
+    }
+
+    // Scan the entire project, but exclude source directories
+    await scanDirectory(projectRoot, [path.join(projectRoot, 'src'), path.join(projectRoot, 'tools'), path.join(projectRoot, 'test')]);
+
+    return customPaths;
+  }
+
+  /**
+   * Get custom content info from a custom.yaml or module.yaml file
+   * @param {string} configPath - Path to config file
+   * @param {string} projectRoot - Project root directory for calculating relative paths
+   * @returns {Object|null} Custom content info
+   */
+  async getCustomInfo(configPath, projectRoot = null) {
+    try {
+      const configContent = await fs.readFile(configPath, 'utf8');
+
+      // Try to parse YAML with error handling
+      let config;
+      try {
+        config = yaml.load(configContent);
+      } catch (parseError) {
+        console.warn(chalk.yellow(`Warning: YAML parse error in ${configPath}:`, parseError.message));
+        return null;
+      }
+
+      // Check if this is an module.yaml (module) or custom.yaml (custom content)
+      const isInstallConfig = configPath.endsWith('module.yaml');
+      const configDir = path.dirname(configPath);
+
+      // Use provided projectRoot or fall back to process.cwd()
+      const basePath = projectRoot || process.cwd();
+      const relativePath = path.relative(basePath, configDir);
+
+      return {
+        id: config.code || 'unknown-code',
+        name: config.name,
+        description: config.description || '',
+        path: configDir,
+        relativePath: relativePath,
+        defaultSelected: config.default_selected === true,
+        config: config,
+        isInstallConfig: isInstallConfig, // Track which type this is
+      };
+    } catch (error) {
+      console.warn(chalk.yellow(`Warning: Failed to read ${configPath}:`, error.message));
+      return null;
+    }
+  }
+
+  /**
+   * Install custom content
+   * @param {string} customPath - Path to custom content directory
+   * @param {string} bmadDir - Target bmad directory
+   * @param {Object} config - Configuration from custom.yaml
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @returns {Object} Installation result
+   */
+  async install(customPath, bmadDir, config, fileTrackingCallback = null) {
+    const results = {
+      agentsInstalled: 0,
+      workflowsInstalled: 0,
+      filesCopied: 0,
+      preserved: 0,
+      errors: [],
+    };
+
+    try {
+      // Create custom directories in bmad
+      const bmadCustomDir = path.join(bmadDir, 'custom');
+      const bmadAgentsDir = path.join(bmadCustomDir, 'agents');
+      const bmadWorkflowsDir = path.join(bmadCustomDir, 'workflows');
+
+      await fs.ensureDir(bmadCustomDir);
+      await fs.ensureDir(bmadAgentsDir);
+      await fs.ensureDir(bmadWorkflowsDir);
+
+      // Process agents - compile and copy agents
+      const agentsDir = path.join(customPath, 'agents');
+      if (await fs.pathExists(agentsDir)) {
+        await this.compileAndCopyAgents(agentsDir, bmadAgentsDir, bmadDir, config, fileTrackingCallback, results);
+
+        // Count agent files
+        const agentFiles = await this.findFilesRecursively(agentsDir, ['.agent.yaml', '.md']);
+        results.agentsInstalled = agentFiles.length;
+      }
+
+      // Process workflows - copy entire workflows directory structure
+      const workflowsDir = path.join(customPath, 'workflows');
+      if (await fs.pathExists(workflowsDir)) {
+        await this.copyDirectory(workflowsDir, bmadWorkflowsDir, results, fileTrackingCallback, config);
+
+        // Count workflow files
+        const workflowFiles = await this.findFilesRecursively(workflowsDir, ['.md']);
+        results.workflowsInstalled = workflowFiles.length;
+      }
+
+      // Process any additional files at root
+      const entries = await fs.readdir(customPath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name !== 'custom.yaml' && !entry.name.startsWith('.') && !entry.name.endsWith('.md')) {
+          // Skip .md files at root as they're likely docs
+          const sourcePath = path.join(customPath, entry.name);
+          const targetPath = path.join(bmadCustomDir, entry.name);
+
+          try {
+            // Check if file already exists
+            if (await fs.pathExists(targetPath)) {
+              // File already exists, preserve it
+              results.preserved = (results.preserved || 0) + 1;
+            } else {
+              await fs.copy(sourcePath, targetPath);
+              results.filesCopied++;
+
+              if (fileTrackingCallback) {
+                fileTrackingCallback(targetPath);
+              }
+            }
+          } catch (error) {
+            results.errors.push(`Failed to copy file ${entry.name}: ${error.message}`);
+          }
+        }
+      }
+    } catch (error) {
+      results.errors.push(`Installation failed: ${error.message}`);
+    }
+
+    return results;
+  }
+
+  /**
+   * Find all files with specific extensions recursively
+   * @param {string} dir - Directory to search
+   * @param {Array} extensions - File extensions to match
+   * @returns {Array} List of matching files
+   */
+  async findFilesRecursively(dir, extensions) {
+    const files = [];
+
+    async function search(currentDir) {
+      const entries = await fs.readdir(currentDir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(currentDir, entry.name);
+
+        if (entry.isDirectory()) {
+          await search(fullPath);
+        } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+          files.push(fullPath);
+        }
+      }
+    }
+
+    await search(dir);
+    return files;
+  }
+
+  /**
+   * Recursively copy a directory
+   * @param {string} sourceDir - Source directory
+   * @param {string} targetDir - Target directory
+   * @param {Object} results - Results object to update
+   * @param {Function} fileTrackingCallback - Optional callback
+   * @param {Object} config - Configuration for placeholder replacement
+   */
+  async copyDirectory(sourceDir, targetDir, results, fileTrackingCallback, config) {
+    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.copyDirectory(sourcePath, targetPath, results, fileTrackingCallback, config);
+      } else {
+        try {
+          // Check if file already exists
+          if (await fs.pathExists(targetPath)) {
+            // File already exists, preserve it
+            results.preserved = (results.preserved || 0) + 1;
+          } else {
+            // Copy with placeholder replacement for text files
+            const textExtensions = ['.md', '.yaml', '.yml', '.txt', '.json'];
+            if (textExtensions.some((ext) => entry.name.endsWith(ext))) {
+              // Read source content
+              let content = await fs.readFile(sourcePath, 'utf8');
+
+              // Replace placeholders
+              content = content.replaceAll('{bmad_folder}', config.bmad_folder || 'bmad');
+              content = content.replaceAll('{user_name}', config.user_name || 'User');
+              content = content.replaceAll('{communication_language}', config.communication_language || 'English');
+              content = content.replaceAll('{output_folder}', config.output_folder || 'docs');
+
+              // Write to target
+              await fs.ensureDir(path.dirname(targetPath));
+              await fs.writeFile(targetPath, content, 'utf8');
+            } else {
+              // Copy binary files as-is
+              await fs.copy(sourcePath, targetPath);
+            }
+
+            results.filesCopied++;
+            if (fileTrackingCallback) {
+              fileTrackingCallback(targetPath);
+            }
+          }
+
+          if (entry.name.endsWith('.md')) {
+            results.workflowsInstalled++;
+          }
+        } catch (error) {
+          results.errors.push(`Failed to copy ${entry.name}: ${error.message}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Compile .agent.yaml files to .md format and handle sidecars
+   * @param {string} sourceAgentsPath - Source agents directory
+   * @param {string} targetAgentsPath - Target agents directory
+   * @param {string} bmadDir - BMAD installation directory
+   * @param {Object} config - Configuration for placeholder replacement
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @param {Object} results - Results object to update
+   */
+  async compileAndCopyAgents(sourceAgentsPath, targetAgentsPath, bmadDir, config, fileTrackingCallback, results) {
+    // Get all .agent.yaml files recursively
+    const agentFiles = await this.findFilesRecursively(sourceAgentsPath, ['.agent.yaml']);
+
+    for (const agentFile of agentFiles) {
+      const relativePath = path.relative(sourceAgentsPath, agentFile);
+      const targetDir = path.join(targetAgentsPath, path.dirname(relativePath));
+
+      await fs.ensureDir(targetDir);
+
+      const agentName = path.basename(agentFile, '.agent.yaml');
+      const targetMdPath = path.join(targetDir, `${agentName}.md`);
+      // Use the actual bmadDir if available (for when installing to temp dir)
+      const actualBmadDir = config._bmadDir || bmadDir;
+      const customizePath = path.join(actualBmadDir, '_cfg', 'agents', `custom-${agentName}.customize.yaml`);
+
+      // Read and compile the YAML
+      try {
+        const yamlContent = await fs.readFile(agentFile, 'utf8');
+        const { compileAgent } = require('../../../lib/agent/compiler');
+
+        // Create customize template if it doesn't exist
+        if (!(await fs.pathExists(customizePath))) {
+          const { getSourcePath } = require('../../../lib/project-root');
+          const genericTemplatePath = getSourcePath('utility', 'templates', 'agent.customize.template.yaml');
+          if (await fs.pathExists(genericTemplatePath)) {
+            // Copy with placeholder replacement
+            let templateContent = await fs.readFile(genericTemplatePath, 'utf8');
+            templateContent = templateContent.replaceAll('{bmad_folder}', config.bmad_folder || 'bmad');
+            await fs.writeFile(customizePath, templateContent, 'utf8');
+            console.log(chalk.dim(`  Created customize: custom-${agentName}.customize.yaml`));
+          }
+        }
+
+        // Compile the agent
+        const { xml } = compileAgent(yamlContent, {}, agentName, relativePath, { config });
+
+        // Replace placeholders in the compiled content
+        let processedXml = xml;
+        processedXml = processedXml.replaceAll('{bmad_folder}', config.bmad_folder || 'bmad');
+        processedXml = processedXml.replaceAll('{user_name}', config.user_name || 'User');
+        processedXml = processedXml.replaceAll('{communication_language}', config.communication_language || 'English');
+        processedXml = processedXml.replaceAll('{output_folder}', config.output_folder || 'docs');
+
+        // Write the compiled MD file
+        await fs.writeFile(targetMdPath, processedXml, 'utf8');
+
+        // Check if agent has sidecar
+        let hasSidecar = false;
+        try {
+          const yamlLib = require('yaml');
+          const agentYaml = yamlLib.parse(yamlContent);
+          hasSidecar = agentYaml?.agent?.metadata?.hasSidecar === true;
+        } catch {
+          // Continue without sidecar processing
+        }
+
+        // Copy sidecar files if agent has hasSidecar flag
+        if (hasSidecar && config.agent_sidecar_folder) {
+          const { copyAgentSidecarFiles } = require('../../../lib/agent/installer');
+
+          // Resolve agent sidecar folder path
+          const projectDir = path.dirname(bmadDir);
+          const resolvedSidecarFolder = config.agent_sidecar_folder
+            .replaceAll('{project-root}', projectDir)
+            .replaceAll('{bmad_folder}', path.basename(bmadDir));
+
+          // Create sidecar directory for this agent
+          const agentSidecarDir = path.join(resolvedSidecarFolder, agentName);
+          await fs.ensureDir(agentSidecarDir);
+
+          // Copy sidecar files
+          const sidecarResult = copyAgentSidecarFiles(path.dirname(agentFile), agentSidecarDir, agentFile);
+
+          if (sidecarResult.copied.length > 0) {
+            console.log(chalk.dim(`    Copied ${sidecarResult.copied.length} sidecar file(s) to: ${agentSidecarDir}`));
+          }
+          if (sidecarResult.preserved.length > 0) {
+            console.log(chalk.dim(`    Preserved ${sidecarResult.preserved.length} existing sidecar file(s)`));
+          }
+        }
+
+        // Track the file
+        if (fileTrackingCallback) {
+          fileTrackingCallback(targetMdPath);
+        }
+
+        console.log(
+          chalk.dim(
+            `    Compiled agent: ${agentName} -> ${path.relative(targetAgentsPath, targetMdPath)}${hasSidecar ? ' (with sidecar)' : ''}`,
+          ),
+        );
+      } catch (error) {
+        console.warn(chalk.yellow(`    Failed to compile agent ${agentName}:`, error.message));
+        results.errors.push(`Failed to compile agent ${agentName}: ${error.message}`);
+      }
+    }
+  }
+}
+
+module.exports = { CustomHandler };

package/tools/cli/installers/lib/ide/_base-ide.js

@@ -536,6 +536,11 @@ class BaseIdeSetup {
     if (typeof content === 'string' && content.includes('{bmad_folder}')) {
       content = content.replaceAll('{bmad_folder}', this.bmadFolderName);
     }
+
+    // Replace escape sequence {*bmad_folder*} with literal {bmad_folder}
+    if (typeof content === 'string' && content.includes('{*bmad_folder*}')) {
+      content = content.replaceAll('{*bmad_folder*}', '{bmad_folder}');
+    }
     await this.ensureDir(path.dirname(filePath));
     await fs.writeFile(filePath, content, 'utf8');
   }
@@ -563,6 +568,11 @@ class BaseIdeSetup {
           content = content.replaceAll('{bmad_folder}', this.bmadFolderName);
         }
 
+        // Replace escape sequence {*bmad_folder*} with literal {bmad_folder}
+        if (content.includes('{*bmad_folder*}')) {
+          content = content.replaceAll('{*bmad_folder*}', '{bmad_folder}');
+        }
+
         // Write to dest with replaced content
         await fs.writeFile(dest, content, 'utf8');
       } catch {

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

@@ -3,6 +3,7 @@ const fs = require('fs-extra');
 const { BaseIdeSetup } = require('./_base-ide');
 const chalk = require('chalk');
 const { AgentCommandGenerator } = require('./shared/agent-command-generator');
+const { WorkflowCommandGenerator } = require('./shared/workflow-command-generator');
 
 /**
  * Auggie CLI setup handler
@@ -33,10 +34,23 @@ class AuggieSetup extends BaseIdeSetup {
     const agentGen = new AgentCommandGenerator(this.bmadFolderName);
     const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, options.selectedModules || []);
 
-    // Get tasks, tools, and workflows (standalone only)
+    // Get tasks, tools, and workflows (ALL workflows now generate commands)
     const tasks = await this.getTasks(bmadDir, true);
     const tools = await this.getTools(bmadDir, true);
-    const workflows = await this.getWorkflows(bmadDir, true);
+
+    // Get ALL workflows using the new workflow command generator
+    const workflowGenerator = new WorkflowCommandGenerator(this.bmadFolderName);
+    const { artifacts: workflowArtifacts, counts: workflowCounts } = await workflowGenerator.collectWorkflowArtifacts(bmadDir);
+
+    // Convert workflow artifacts to expected format
+    const workflows = workflowArtifacts
+      .filter((artifact) => artifact.type === 'workflow-command')
+      .map((artifact) => ({
+        module: artifact.module,
+        name: path.basename(artifact.relativePath, '.md'),
+        path: artifact.sourcePath,
+        content: artifact.content,
+      }));
 
     const bmadCommandsDir = path.join(location, 'bmad');
     const agentsDir = path.join(bmadCommandsDir, 'agents');
@@ -73,13 +87,11 @@ class AuggieSetup extends BaseIdeSetup {
       await this.writeFile(targetPath, commandContent);
     }
 
-    // Install workflows
+    // Install workflows (already generated commands)
     for (const workflow of workflows) {
-      const content = await this.readFile(workflow.path);
-      const commandContent = this.createWorkflowCommand(workflow, content);
-
+      // Use the pre-generated workflow command content
       const targetPath = path.join(workflowsDir, `${workflow.module}-${workflow.name}.md`);
-      await this.writeFile(targetPath, commandContent);
+      await this.writeFile(targetPath, workflow.content);
     }
 
     const totalInstalled = agentArtifacts.length + tasks.length + tools.length + workflows.length;

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

@@ -3,6 +3,7 @@ const fs = require('fs-extra');
 const { BaseIdeSetup } = require('./_base-ide');
 const chalk = require('chalk');
 const { AgentCommandGenerator } = require('./shared/agent-command-generator');
+const { WorkflowCommandGenerator } = require('./shared/workflow-command-generator');
 
 /**
  * Crush IDE setup handler
@@ -34,10 +35,23 @@ class CrushSetup extends BaseIdeSetup {
     const agentGen = new AgentCommandGenerator(this.bmadFolderName);
     const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, options.selectedModules || []);
 
-    // Get tasks, tools, and workflows (standalone only)
+    // Get tasks, tools, and workflows (ALL workflows now generate commands)
     const tasks = await this.getTasks(bmadDir, true);
     const tools = await this.getTools(bmadDir, true);
-    const workflows = await this.getWorkflows(bmadDir, true);
+
+    // Get ALL workflows using the new workflow command generator
+    const workflowGenerator = new WorkflowCommandGenerator(this.bmadFolderName);
+    const { artifacts: workflowArtifacts, counts: workflowCounts } = await workflowGenerator.collectWorkflowArtifacts(bmadDir);
+
+    // Convert workflow artifacts to expected format for organizeByModule
+    const workflows = workflowArtifacts
+      .filter((artifact) => artifact.type === 'workflow-command')
+      .map((artifact) => ({
+        module: artifact.module,
+        name: path.basename(artifact.relativePath, '.md'),
+        path: artifact.sourcePath,
+        content: artifact.content,
+      }));
 
     // Organize by module
     const agentCount = await this.organizeByModule(commandsDir, agentArtifacts, tasks, tools, workflows, projectDir);
@@ -113,13 +127,12 @@ class CrushSetup extends BaseIdeSetup {
         toolCount++;
       }
 
-      // Copy module-specific workflows
+      // Copy module-specific workflow commands (already generated)
       const moduleWorkflows = workflows.filter((w) => w.module === module);
       for (const workflow of moduleWorkflows) {
-        const content = await this.readFile(workflow.path);
-        const commandContent = this.createWorkflowCommand(workflow, content);
+        // Use the pre-generated workflow command content
         const targetPath = path.join(moduleWorkflowsDir, `${workflow.name}.md`);
-        await this.writeFile(targetPath, commandContent);
+        await this.writeFile(targetPath, workflow.content);
         workflowCount++;
       }
     }

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

@@ -2,6 +2,7 @@ const path = require('node:path');
 const { BaseIdeSetup } = require('./_base-ide');
 const chalk = require('chalk');
 const { AgentCommandGenerator } = require('./shared/agent-command-generator');
+const { WorkflowCommandGenerator } = require('./shared/workflow-command-generator');
 
 /**
  * Cursor IDE setup handler
@@ -53,10 +54,22 @@ class CursorSetup extends BaseIdeSetup {
     // Convert artifacts to agent format for index creation
     const agents = agentArtifacts.map((a) => ({ module: a.module, name: a.name }));
 
-    // Get tasks, tools, and workflows (standalone only)
+    // Get tasks, tools, and workflows (ALL workflows now generate commands)
     const tasks = await this.getTasks(bmadDir, true);
     const tools = await this.getTools(bmadDir, true);
-    const workflows = await this.getWorkflows(bmadDir, true);
+
+    // Get ALL workflows using the new workflow command generator
+    const workflowGenerator = new WorkflowCommandGenerator(this.bmadFolderName);
+    const { artifacts: workflowArtifacts, counts: workflowCounts } = await workflowGenerator.collectWorkflowArtifacts(bmadDir);
+
+    // Convert artifacts to workflow objects for directory creation
+    const workflows = workflowArtifacts
+      .filter((artifact) => artifact.type === 'workflow-command')
+      .map((artifact) => ({
+        module: artifact.module,
+        name: path.basename(artifact.relativePath, '.md'),
+        path: artifact.sourcePath,
+      }));
 
     // Create directories for each module
     const modules = new Set();
@@ -113,18 +126,21 @@ class CursorSetup extends BaseIdeSetup {
       toolCount++;
     }
 
-    // Process and copy workflows
+    // Process and copy workflow commands (generated, not raw workflows)
     let workflowCount = 0;
-    for (const workflow of workflows) {
-      const content = await this.readAndProcess(workflow.path, {
-        module: workflow.module,
-        name: workflow.name,
-      });
-
-      const targetPath = path.join(bmadRulesDir, workflow.module, 'workflows', `${workflow.name}.mdc`);
-
-      await this.writeFile(targetPath, content);
-      workflowCount++;
+    for (const artifact of workflowArtifacts) {
+      if (artifact.type === 'workflow-command') {
+        // Add MDC metadata header to workflow command
+        const content = this.wrapLauncherWithMDC(artifact.content, {
+          module: artifact.module,
+          name: path.basename(artifact.relativePath, '.md'),
+        });
+
+        const targetPath = path.join(bmadRulesDir, artifact.module, 'workflows', `${path.basename(artifact.relativePath, '.md')}.mdc`);
+
+        await this.writeFile(targetPath, content);
+        workflowCount++;
+      }
     }
 
     // Create BMAD index file (but NOT .cursorrules - user manages that)