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

package/tools/cli/installers/lib/ide/claude-code.js

@@ -81,6 +81,20 @@ class ClaudeCodeSetup extends BaseIdeSetup {
     return config;
   }
 
+  /**
+   * Cleanup old BMAD installation before reinstalling
+   * @param {string} projectDir - Project directory
+   */
+  async cleanup(projectDir) {
+    const fs = require('fs-extra');
+    const bmadCommandsDir = path.join(projectDir, this.configDir, this.commandsDir, 'bmad');
+
+    if (await fs.pathExists(bmadCommandsDir)) {
+      await fs.remove(bmadCommandsDir);
+      console.log(chalk.dim(`  Removed old BMAD commands from ${this.name}`));
+    }
+  }
+
   /**
    * Setup Claude Code IDE configuration
    * @param {string} projectDir - Project directory
@@ -93,6 +107,9 @@ class ClaudeCodeSetup extends BaseIdeSetup {
 
     console.log(chalk.cyan(`Setting up ${this.name}...`));
 
+    // Clean up old BMAD installation first
+    await this.cleanup(projectDir);
+
     // Create .claude/commands directory structure
     const claudeDir = path.join(projectDir, this.configDir);
     const commandsDir = path.join(claudeDir, this.commandsDir);
@@ -145,7 +162,20 @@ class ClaudeCodeSetup extends BaseIdeSetup {
 
     // Generate workflow commands from manifest (if it exists)
     const workflowGen = new WorkflowCommandGenerator();
-    const workflowResult = await workflowGen.generateWorkflowCommands(projectDir, bmadDir);
+    const { artifacts: workflowArtifacts } = await workflowGen.collectWorkflowArtifacts(bmadDir);
+
+    // Write only workflow-command artifacts, skip workflow-launcher READMEs
+    let workflowCommandCount = 0;
+    for (const artifact of workflowArtifacts) {
+      if (artifact.type === 'workflow-command') {
+        const moduleWorkflowsDir = path.join(bmadCommandsDir, artifact.module, 'workflows');
+        await this.ensureDir(moduleWorkflowsDir);
+        const commandPath = path.join(moduleWorkflowsDir, path.basename(artifact.relativePath));
+        await this.writeFile(commandPath, artifact.content);
+        workflowCommandCount++;
+      }
+      // Skip workflow-launcher READMEs as they would be treated as slash commands
+    }
 
     // Generate task and tool commands from manifests (if they exist)
     const taskToolGen = new TaskToolCommandGenerator();
@@ -153,8 +183,8 @@ class ClaudeCodeSetup extends BaseIdeSetup {
 
     console.log(chalk.green(`✓ ${this.name} configured:`));
     console.log(chalk.dim(`  - ${agentCount} agents installed`));
-    if (workflowResult.generated > 0) {
-      console.log(chalk.dim(`  - ${workflowResult.generated} workflow commands generated`));
+    if (workflowCommandCount > 0) {
+      console.log(chalk.dim(`  - ${workflowCommandCount} workflow commands generated`));
     }
     if (taskToolResult.generated > 0) {
       console.log(

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

@@ -12,6 +12,20 @@ class CursorSetup extends BaseIdeSetup {
     this.rulesDir = 'rules';
   }
 
+  /**
+   * Cleanup old BMAD installation before reinstalling
+   * @param {string} projectDir - Project directory
+   */
+  async cleanup(projectDir) {
+    const fs = require('fs-extra');
+    const bmadRulesDir = path.join(projectDir, this.configDir, this.rulesDir, 'bmad');
+
+    if (await fs.pathExists(bmadRulesDir)) {
+      await fs.remove(bmadRulesDir);
+      console.log(chalk.dim(`  Removed old BMAD rules from ${this.name}`));
+    }
+  }
+
   /**
    * Setup Cursor IDE configuration
    * @param {string} projectDir - Project directory
@@ -21,6 +35,9 @@ class CursorSetup extends BaseIdeSetup {
   async setup(projectDir, bmadDir, options = {}) {
     console.log(chalk.cyan(`Setting up ${this.name}...`));
 
+    // Clean up old BMAD installation first
+    await this.cleanup(projectDir);
+
     // Create .cursor/rules directory structure
     const cursorDir = path.join(projectDir, this.configDir);
     const rulesDir = path.join(cursorDir, this.rulesDir);

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

@@ -112,6 +112,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 +271,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) => {
@@ -429,6 +439,130 @@ 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
+        // Example: {project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml
+        const sourceMatch = sourceWorkflowPath.match(/\{project-root\}\/bmad\/([^/]+)\/workflows\/(.+)/);
+        if (!sourceMatch) {
+          console.warn(chalk.yellow(`      Could not parse workflow path: ${sourceWorkflowPath}`));
+          continue;
+        }
+
+        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\/(.+)/);
+        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));
+        await fs.copy(actualSourceWorkflowPath, actualDestWorkflowPath, { overwrite: true });
+
+        // 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/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"`;
+
+    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`));
+    }
+  }
+
   /**
    * Run module-specific installer if it exists
    * @param {string} moduleName - Name of the module

package/tools/cli/lib/config.js

@@ -33,7 +33,9 @@ class Config {
     });
 
     await fs.ensureDir(path.dirname(configPath));
-    await fs.writeFile(configPath, yamlContent, 'utf8');
+    // Ensure POSIX-compliant final newline
+    const content = yamlContent.endsWith('\n') ? yamlContent : yamlContent + '\n';
+    await fs.writeFile(configPath, content, 'utf8');
   }
 
   /**

package/tools/cli/lib/ui.js

@@ -82,15 +82,15 @@ class UI {
       // If actionType === 'update' or 'reinstall', continue with normal flow below
     }
 
-    // Collect IDE tool selection EARLY (before module configuration)
-    // This allows users to make all decisions upfront before file copying begins
-    const toolSelection = await this.promptToolSelection(confirmedDirectory, []);
-
     const { installedModuleIds } = await this.getExistingInstallation(confirmedDirectory);
     const coreConfig = await this.collectCoreConfig(confirmedDirectory);
     const moduleChoices = await this.getModuleChoices(installedModuleIds);
     const selectedModules = await this.selectModules(moduleChoices);
 
+    // Collect IDE tool selection AFTER configuration prompts (fixes Windows/PowerShell hang)
+    // 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
@@ -100,7 +100,7 @@ class UI {
       directory: confirmedDirectory,
       installCore: true, // Always install core
       modules: selectedModules,
-      // IDE selection collected early, will be configured later
+      // IDE selection collected after config, will be configured later
       ides: toolSelection.ides,
       skipIde: toolSelection.skipIde,
       coreConfig: coreConfig, // Pass collected core config to installer

package/tools/cli/lib/yaml-format.js

@@ -64,7 +64,8 @@ async function formatYamlContent(content, filename) {
       noRefs: true,
       sortKeys: false, // Preserve key order
     });
-    return formatted;
+    // Ensure POSIX-compliant final newline
+    return formatted.endsWith('\n') ? formatted : formatted + '\n';
   } catch (error) {
     console.error(chalk.red(`❌ YAML syntax error in ${filename}:`), error.message);
     console.error(chalk.yellow(`💡 Try manually fixing the YAML structure first`));

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

@@ -311,7 +311,15 @@ class YamlXmlBuilder {
         const attrs = [`cmd="${trigger}"`];
 
         // Add handler attributes
-        if (item.workflow) attrs.push(`workflow="${item.workflow}"`);
+        // If workflow-install exists, use its value for workflow attribute (vendoring)
+        // workflow-install is build-time metadata - tells installer where to copy workflows
+        // The final XML should only have workflow pointing to the install location
+        if (item['workflow-install']) {
+          attrs.push(`workflow="${item['workflow-install']}"`);
+        } else if (item.workflow) {
+          attrs.push(`workflow="${item.workflow}"`);
+        }
+
         if (item['validate-workflow']) attrs.push(`validate-workflow="${item['validate-workflow']}"`);
         if (item.exec) attrs.push(`exec="${item.exec}"`);
         if (item.tmpl) attrs.push(`tmpl="${item.tmpl}"`);

package/tools/schema/agent.js

@@ -170,12 +170,15 @@ function buildMenuItemSchema() {
       trigger: createNonEmptyString('agent.menu[].trigger'),
       description: createNonEmptyString('agent.menu[].description'),
       workflow: createNonEmptyString('agent.menu[].workflow').optional(),
+      'workflow-install': createNonEmptyString('agent.menu[].workflow-install').optional(),
       'validate-workflow': createNonEmptyString('agent.menu[].validate-workflow').optional(),
       exec: createNonEmptyString('agent.menu[].exec').optional(),
       action: createNonEmptyString('agent.menu[].action').optional(),
       tmpl: createNonEmptyString('agent.menu[].tmpl').optional(),
       data: createNonEmptyString('agent.menu[].data').optional(),
       'run-workflow': createNonEmptyString('agent.menu[].run-workflow').optional(),
+      checklist: createNonEmptyString('agent.menu[].checklist').optional(),
+      document: createNonEmptyString('agent.menu[].document').optional(),
     })
     .strict()
     .superRefine((value, ctx) => {

package/v6-open-items.md

@@ -2,22 +2,16 @@
 
 Before calling this beta
 
-- ensure sharing and indexed folders can be used in all flows
-- Brief and PRD update to be much more interactive similar to architecture and ux flows
-- level 0 and 1 further streamlined
-- leaner phase 4
+- finalize web bundler
+- some subagents working again
+- knowledge base for bmad
 
 ## Needed Beta → v0 release
 
 Aside from stability and bug fixes found during the alpha period - the main focus will be on the following:
 
-- NPX installer
-- github pipelines, branch protection, vulnerability scanners
-- subagent injections reenabled
 - knowledge base for BMM
 - Module repository and submission process defined
-- Final polished documentation and user guide for each module
-- Final polished documentation for overall project architecture
 - MCP Injections based on installation selection
 - sub agent for opencode and claude code optimization
 - TDD Workflow Integration