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

package/src/modules/bmm/workflows/testarch/ci/gitlab-ci-template.yaml

@@ -15,6 +15,8 @@ variables:
   npm_config_cache: "$CI_PROJECT_DIR/.npm"
   # Playwright browser cache
   PLAYWRIGHT_BROWSERS_PATH: "$CI_PROJECT_DIR/.cache/ms-playwright"
+  # Default Node version when .nvmrc is missing
+  DEFAULT_NODE_VERSION: "24"
 
 # Caching configuration
 cache:
@@ -29,19 +31,32 @@ cache:
 # Lint stage - Code quality checks
 lint:
   stage: lint
-  image: node:20
-  script:
+  image: node:$DEFAULT_NODE_VERSION
+  before_script:
+    - |
+      NODE_VERSION=$(cat .nvmrc 2>/dev/null || echo "$DEFAULT_NODE_VERSION")
+      echo "Using Node $NODE_VERSION"
+      npm install -g n
+      n "$NODE_VERSION"
+      node -v
     - npm ci
+  script:
     - npm run lint
   timeout: 5 minutes
 
 # Test stage - Parallel execution with sharding
 .test-template: &test-template
   stage: test
-  image: node:20
+  image: node:$DEFAULT_NODE_VERSION
   needs:
     - lint
   before_script:
+    - |
+      NODE_VERSION=$(cat .nvmrc 2>/dev/null || echo "$DEFAULT_NODE_VERSION")
+      echo "Using Node $NODE_VERSION"
+      npm install -g n
+      n "$NODE_VERSION"
+      node -v
     - npm ci
     - npx playwright install --with-deps chromium
   artifacts:
@@ -75,7 +90,7 @@ test:shard-4:
 # Burn-in stage - Flaky test detection
 burn-in:
   stage: burn-in
-  image: node:20
+  image: node:$DEFAULT_NODE_VERSION
   needs:
     - test:shard-1
     - test:shard-2
@@ -86,6 +101,12 @@ burn-in:
     - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
     - if: '$CI_PIPELINE_SOURCE == "schedule"'
   before_script:
+    - |
+      NODE_VERSION=$(cat .nvmrc 2>/dev/null || echo "$DEFAULT_NODE_VERSION")
+      echo "Using Node $NODE_VERSION"
+      npm install -g n
+      n "$NODE_VERSION"
+      node -v
     - npm ci
     - npx playwright install --with-deps chromium
   script:

package/src/modules/bmm/workflows/testarch/ci/instructions.md

@@ -61,8 +61,8 @@ Scaffolds a production-ready CI/CD quality pipeline with test execution, burn-in
      - Ask user if unable to auto-detect
 
 5. **Read Environment Configuration**
-   - Check for `.nvmrc` to determine Node version
-   - Default to Node 20 LTS if not found
+   - Use `.nvmrc` for Node version if present
+   - If missing, default to a current LTS (Node 24) or newer instead of a fixed old version
    - Read `package.json` to identify dependencies (affects caching strategy)
 
 **Halt Condition:** If preflight checks fail, stop immediately and report which requirement failed.

package/src/modules/bmm/workflows/testarch/test-review/instructions.md

@@ -524,7 +524,7 @@ await expect(page.locator('[data-testid="user-menu"]')).toBeVisible({ timeout: 1
 ### 1. Use Data Factory for Test User (Lines 23, 32, 41)
 
 **Severity**: P1 (High)
-**Issue**: Hardcoded email 'test@example.com' - maintainability risk
+**Issue**: Hardcoded email `test@example.com` - maintainability risk
 **Fix**: Create factory function for test users
 **Knowledge**: See data-factories.md
 

package/src/modules/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml

@@ -56,11 +56,6 @@ phases:
         output: "Enterprise PRD with compliance requirements"
         note: "Must address existing system constraints and migration strategy"
 
-      - id: "validate-prd"
-        recommended: true
-        agent: "pm"
-        command: "validate-prd"
-
       - id: "create-ux-design"
         recommended: true
         agent: "ux-designer"
@@ -114,7 +109,7 @@ phases:
         required: true
         agent: "architect"
         command: "implementation-readiness"
-        note: "Critical gate - validates all planning + Epics before touching production system"
+        note: "Validates PRD + Architecture + Epics + UX (optional)"
 
   - phase: 3
     name: "Implementation"

package/src/modules/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml

@@ -44,11 +44,6 @@ phases:
         output: "Comprehensive Product Requirements Document"
         note: "Enterprise-level requirements with compliance considerations"
 
-      - id: "validate-prd"
-        recommended: true
-        agent: "pm"
-        command: "validate-prd"
-
       - id: "create-ux-design"
         recommended: true
         agent: "ux-designer"
@@ -102,7 +97,7 @@ phases:
         required: true
         agent: "architect"
         command: "implementation-readiness"
-        note: "Validates all planning artifacts + Epics + testability align before implementation"
+        note: "Validates PRD + Architecture + Epics + UX (optional)"
 
   - phase: 3
     name: "Implementation"

package/src/modules/bmm/workflows/workflow-status/paths/method-brownfield.yaml

@@ -55,11 +55,6 @@ phases:
         output: "PRD focused on new features/changes"
         note: "Must consider existing system constraints"
 
-      - id: "validate-prd"
-        optional: true
-        agent: "pm"
-        command: "validate-prd"
-
       - id: "create-ux-design"
         conditional: "if_has_ui"
         agent: "ux-designer"
@@ -98,7 +93,7 @@ phases:
         required: true
         agent: "architect"
         command: "implementation-readiness"
-        note: "Validates PRD + UX + Architecture + Epics cohesion before implementation"
+        note: "Validates PRD + Architecture + Epics + UX (optional)"
 
   - phase: 3
     name: "Implementation"

package/src/modules/bmm/workflows/workflow-status/paths/method-greenfield.yaml

@@ -43,12 +43,6 @@ phases:
         command: "prd"
         output: "Product Requirements Document with FRs and NFRs"
 
-      - id: "validate-prd"
-        optional: true
-        agent: "pm"
-        command: "validate-prd"
-        note: "Quality check for PRD completeness"
-
       - id: "create-ux-design"
         conditional: "if_has_ui"
         agent: "ux-designer"
@@ -89,7 +83,7 @@ phases:
         required: true
         agent: "architect"
         command: "implementation-readiness"
-        note: "Validates PRD + UX + Architecture + Epics + Testability cohesion before implementation"
+        note: "Validates PRD + Architecture + Epics + UX (optional)"
 
   - phase: 3
     name: "Implementation"

package/tools/cli/README.md

@@ -604,6 +604,6 @@ node tools/cli/regenerate-manifests.js
 
 ## Support
 
-- **Issues**: https://github.com/bmad-code-org/BMAD-METHOD/issues
-- **Discord**: https://discord.gg/gk8jAdXWmj (#general-dev, #bugs-issues)
-- **YouTube**: https://www.youtube.com/@BMadCode
+- **Issues**: <https://github.com/bmad-code-org/BMAD-METHOD/issues>
+- **Discord**: <https://discord.gg/gk8jAdXWmj> (#general-dev, #bugs-issues)
+- **YouTube**: <https://www.youtube.com/@BMadCode>

package/tools/cli/commands/build.js

@@ -28,9 +28,8 @@ module.exports = {
   command: 'build [agent]',
   description: 'Build agent XML files from YAML sources',
   options: [
-    ['-a, --all', 'Rebuild all agents'],
+    ['-a, --all', 'Build all agents'],
     ['-d, --directory <path>', 'Project directory', '.'],
-    ['--force', 'Force rebuild even if up to date'],
   ],
   action: async (agentName, options) => {
     try {
@@ -54,13 +53,15 @@ module.exports = {
 
       if (options.all) {
         // Build all agents
-        await buildAllAgents(projectDir, options.force);
+        await buildAllAgents(projectDir);
       } else if (agentName) {
         // Build specific agent
-        await buildAgent(projectDir, agentName, options.force);
+        await buildAgent(projectDir, agentName);
       } else {
-        // No agent specified, check what needs rebuilding
-        await checkBuildStatus(projectDir);
+        // No agent specified, list available agents
+        console.log(chalk.yellow('No agent specified. Use --all to build all agents or specify an agent name.'));
+        console.log(chalk.dim('\nAvailable agents:'));
+        await listAvailableAgents(projectDir);
       }
 
       process.exit(0);
@@ -77,7 +78,7 @@ module.exports = {
 /**
  * Build a specific agent
  */
-async function buildAgent(projectDir, agentName, force = false) {
+async function buildAgent(projectDir, agentName) {
   // First check standalone agents in bmad/agents/{agentname}/
   const standaloneAgentDir = path.join(projectDir, 'bmad', 'agents', agentName);
   let standaloneYamlPath = path.join(standaloneAgentDir, `${agentName}.agent.yaml`);
@@ -95,15 +96,6 @@ async function buildAgent(projectDir, agentName, force = false) {
     const yamlFileName = path.basename(standaloneYamlPath, '.agent.yaml');
     const outputPath = path.join(standaloneAgentDir, `${yamlFileName}.md`);
 
-    // Check if rebuild needed
-    if (!force && (await fs.pathExists(outputPath))) {
-      const needsRebuild = await checkIfNeedsRebuild(standaloneYamlPath, outputPath, projectDir, agentName);
-      if (!needsRebuild) {
-        console.log(chalk.dim(`  ${agentName}: already up to date`));
-        return;
-      }
-    }
-
     // Build the standalone agent
     console.log(chalk.cyan(`  Building standalone agent ${agentName}...`));
 
@@ -130,15 +122,6 @@ async function buildAgent(projectDir, agentName, force = false) {
     if (await fs.pathExists(agentYamlPath)) {
       found = true;
 
-      // Check if rebuild needed
-      if (!force && (await fs.pathExists(outputPath))) {
-        const needsRebuild = await checkIfNeedsRebuild(agentYamlPath, outputPath, projectDir, agentName);
-        if (!needsRebuild) {
-          console.log(chalk.dim(`  ${agentName}: already up to date`));
-          return;
-        }
-      }
-
       // Build the agent
       console.log(chalk.cyan(`  Building ${agentName}...`));
 
@@ -162,9 +145,8 @@ async function buildAgent(projectDir, agentName, force = false) {
 /**
  * Build all agents
  */
-async function buildAllAgents(projectDir, force = false) {
+async function buildAllAgents(projectDir) {
   let builtCount = 0;
-  let skippedCount = 0;
 
   // First, build standalone agents in bmad/agents/
   const standaloneAgentsDir = path.join(projectDir, 'bmad', 'agents');
@@ -193,16 +175,6 @@ async function buildAllAgents(projectDir, force = false) {
       const agentName = path.basename(agentFile, '.agent.yaml');
       const outputPath = path.join(agentDir, `${agentName}.md`);
 
-      // Check if rebuild needed
-      if (!force && (await fs.pathExists(outputPath))) {
-        const needsRebuild = await checkIfNeedsRebuild(agentYamlPath, outputPath, projectDir, agentName);
-        if (!needsRebuild) {
-          console.log(chalk.dim(`  ${agentName}: up to date`));
-          skippedCount++;
-          continue;
-        }
-      }
-
       console.log(chalk.cyan(`  Building standalone agent ${agentName}...`));
 
       const customizePath = path.join(projectDir, 'bmad', '_cfg', 'agents', `${agentName}.customize.yaml`);
@@ -239,16 +211,6 @@ async function buildAllAgents(projectDir, force = false) {
         const agentYamlPath = path.join(agentsDir, file);
         const outputPath = path.join(agentsDir, `${agentName}.md`);
 
-        // Check if rebuild needed
-        if (!force && (await fs.pathExists(outputPath))) {
-          const needsRebuild = await checkIfNeedsRebuild(agentYamlPath, outputPath, projectDir, agentName);
-          if (!needsRebuild) {
-            console.log(chalk.dim(`  ${agentName}: up to date`));
-            skippedCount++;
-            continue;
-          }
-        }
-
         console.log(chalk.cyan(`  Building ${agentName}...`));
 
         const customizePath = path.join(projectDir, '.claude', '_cfg', 'agents', `${agentName}.customize.yaml`);
@@ -263,143 +225,6 @@ async function buildAllAgents(projectDir, force = false) {
   }
 
   console.log(chalk.green(`\n✓ Built ${builtCount} agent(s)`));
-  if (skippedCount > 0) {
-    console.log(chalk.dim(`  Skipped ${skippedCount} (already up to date)`));
-  }
-}
-
-/**
- * Check what needs rebuilding
- */
-async function checkBuildStatus(projectDir) {
-  const needsRebuild = [];
-  const upToDate = [];
-
-  // Check standalone agents in bmad/agents/
-  const standaloneAgentsDir = path.join(projectDir, 'bmad', 'agents');
-  if (await fs.pathExists(standaloneAgentsDir)) {
-    const agentDirs = await fs.readdir(standaloneAgentsDir);
-
-    for (const agentDirName of agentDirs) {
-      const agentDir = path.join(standaloneAgentsDir, agentDirName);
-
-      // Skip if not a directory
-      const stat = await fs.stat(agentDir);
-      if (!stat.isDirectory()) {
-        continue;
-      }
-
-      // Find any .agent.yaml file in the directory
-      const files = await fs.readdir(agentDir);
-      const agentFile = files.find((f) => f.endsWith('.agent.yaml'));
-
-      if (!agentFile) {
-        continue;
-      }
-
-      const agentYamlPath = path.join(agentDir, agentFile);
-      const agentName = path.basename(agentFile, '.agent.yaml');
-      const outputPath = path.join(agentDir, `${agentName}.md`);
-
-      if (!(await fs.pathExists(outputPath))) {
-        needsRebuild.push(`${agentName} (standalone)`);
-      } else if (await checkIfNeedsRebuild(agentYamlPath, outputPath, projectDir, agentName)) {
-        needsRebuild.push(`${agentName} (standalone)`);
-      } else {
-        upToDate.push(`${agentName} (standalone)`);
-      }
-    }
-  }
-
-  // Check module agents in .claude/commands/bmad/
-  const bmadCommandsDir = path.join(projectDir, '.claude', 'commands', 'bmad');
-  if (await fs.pathExists(bmadCommandsDir)) {
-    const modules = await fs.readdir(bmadCommandsDir);
-
-    for (const module of modules) {
-      const agentsDir = path.join(bmadCommandsDir, module, 'agents');
-
-      if (!(await fs.pathExists(agentsDir))) {
-        continue;
-      }
-
-      const files = await fs.readdir(agentsDir);
-
-      for (const file of files) {
-        if (!file.endsWith('.agent.yaml')) {
-          continue;
-        }
-
-        const agentName = file.replace('.agent.yaml', '');
-        const agentYamlPath = path.join(agentsDir, file);
-        const outputPath = path.join(agentsDir, `${agentName}.md`);
-
-        if (!(await fs.pathExists(outputPath))) {
-          needsRebuild.push(`${agentName} (${module})`);
-        } else if (await checkIfNeedsRebuild(agentYamlPath, outputPath, projectDir, agentName)) {
-          needsRebuild.push(`${agentName} (${module})`);
-        } else {
-          upToDate.push(`${agentName} (${module})`);
-        }
-      }
-    }
-  }
-
-  if (needsRebuild.length === 0) {
-    console.log(chalk.green('✓ All agents are up to date'));
-  } else {
-    console.log(chalk.yellow(`${needsRebuild.length} agent(s) need rebuilding:`));
-    for (const agent of needsRebuild) {
-      console.log(chalk.dim(`  - ${agent}`));
-    }
-    console.log(chalk.dim('\nRun "bmad build --all" to rebuild all agents'));
-  }
-
-  if (upToDate.length > 0) {
-    console.log(chalk.dim(`\n${upToDate.length} agent(s) up to date`));
-  }
-}
-
-/**
- * Check if an agent needs rebuilding by comparing hashes
- */
-async function checkIfNeedsRebuild(yamlPath, outputPath, projectDir, agentName) {
-  // Read the output file to check its metadata
-  const outputContent = await fs.readFile(outputPath, 'utf8');
-
-  // Extract hash from BUILD-META comment
-  const metaMatch = outputContent.match(/source:.*\(hash: ([a-f0-9]+)\)/);
-  if (!metaMatch) {
-    // No metadata, needs rebuild
-    return true;
-  }
-
-  const storedHash = metaMatch[1];
-
-  // Calculate current hash
-  const currentHash = await builder.calculateFileHash(yamlPath);
-
-  if (storedHash !== currentHash) {
-    return true;
-  }
-
-  // Check customize file if it exists
-  const customizePath = path.join(projectDir, '.claude', '_cfg', 'agents', `${agentName}.customize.yaml`);
-  if (await fs.pathExists(customizePath)) {
-    const customizeMetaMatch = outputContent.match(/customize:.*\(hash: ([a-f0-9]+)\)/);
-    if (!customizeMetaMatch) {
-      return true;
-    }
-
-    const storedCustomizeHash = customizeMetaMatch[1];
-    const currentCustomizeHash = await builder.calculateFileHash(customizePath);
-
-    if (storedCustomizeHash !== currentCustomizeHash) {
-      return true;
-    }
-  }
-
-  return false;
 }
 
 /**

package/tools/cli/commands/install.js

@@ -9,7 +9,7 @@ const ui = new UI();
 module.exports = {
   command: 'install',
   description: 'Install BMAD Core agents and tools',
-  options: [['--skip-cleanup', 'Skip automatic cleanup of legacy files']],
+  options: [],
   action: async (options) => {
     try {
       const config = await ui.promptInstall();
@@ -44,11 +44,6 @@ module.exports = {
         config._requestedReinstall = true;
       }
 
-      // Add skip cleanup flag if option provided
-      if (options && options.skipCleanup) {
-        config.skipCleanup = true;
-      }
-
       // Regular install/update flow
       const result = await installer.install(config);
 

package/tools/cli/installers/lib/core/config-collector.js

@@ -182,15 +182,43 @@ class ConfigCollector {
     }
 
     // Load module's install config schema
-    const installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'install-config.yaml');
-    const legacyConfigPath = path.join(getModulePath(moduleName), 'config.yaml');
+    // First, try the standard src/modules location
+    let installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'install-config.yaml');
+
+    // If not found in src/modules, we need to find it by searching the project
+    if (!(await fs.pathExists(installerConfigPath))) {
+      // Use the module manager to find the module source
+      const { ModuleManager } = require('../modules/manager');
+      const moduleManager = new ModuleManager();
+      const moduleSourcePath = await moduleManager.findModuleSource(moduleName);
+
+      if (moduleSourcePath) {
+        installerConfigPath = path.join(moduleSourcePath, '_module-installer', 'install-config.yaml');
+      }
+    }
 
     let configPath = null;
+    let isCustomModule = false;
+
     if (await fs.pathExists(installerConfigPath)) {
       configPath = installerConfigPath;
-    } else if (await fs.pathExists(legacyConfigPath)) {
-      configPath = legacyConfigPath;
     } else {
+      // Check if this is a custom module with custom.yaml
+      const { ModuleManager } = require('../modules/manager');
+      const moduleManager = new ModuleManager();
+      const moduleSourcePath = await moduleManager.findModuleSource(moduleName);
+
+      if (moduleSourcePath) {
+        const rootCustomConfigPath = path.join(moduleSourcePath, 'custom.yaml');
+        const moduleInstallerCustomPath = path.join(moduleSourcePath, '_module-installer', 'custom.yaml');
+
+        if ((await fs.pathExists(rootCustomConfigPath)) || (await fs.pathExists(moduleInstallerCustomPath))) {
+          isCustomModule = true;
+          // For custom modules, we don't have an install-config schema, so just use existing values
+          // The custom.yaml values will be loaded and merged during installation
+        }
+      }
+
       // No config schema for this module - use existing values
       if (this.existingConfig && this.existingConfig[moduleName]) {
         if (!this.collectedConfig[moduleName]) {
@@ -226,9 +254,31 @@ class ConfigCollector {
         }
         this.collectedConfig[moduleName] = { ...this.existingConfig[moduleName] };
 
+        // Special handling for user_name: ensure it has a value
+        if (
+          moduleName === 'core' &&
+          (!this.collectedConfig[moduleName].user_name || this.collectedConfig[moduleName].user_name === '[USER_NAME]')
+        ) {
+          this.collectedConfig[moduleName].user_name = this.getDefaultUsername();
+        }
+
         // Also populate allAnswers for cross-referencing
         for (const [key, value] of Object.entries(this.existingConfig[moduleName])) {
-          this.allAnswers[`${moduleName}_${key}`] = value;
+          // Ensure user_name is properly set in allAnswers too
+          let finalValue = value;
+          if (moduleName === 'core' && key === 'user_name' && (!value || value === '[USER_NAME]')) {
+            finalValue = this.getDefaultUsername();
+          }
+          this.allAnswers[`${moduleName}_${key}`] = finalValue;
+        }
+      } else if (moduleName === 'core') {
+        // No existing core config - ensure we at least have user_name
+        if (!this.collectedConfig[moduleName]) {
+          this.collectedConfig[moduleName] = {};
+        }
+        if (!this.collectedConfig[moduleName].user_name) {
+          this.collectedConfig[moduleName].user_name = this.getDefaultUsername();
+          this.allAnswers[`${moduleName}_user_name`] = this.getDefaultUsername();
         }
       }
       // Show "no config" message for modules with no new questions
@@ -396,15 +446,25 @@ class ConfigCollector {
     if (!this.allAnswers) {
       this.allAnswers = {};
     }
-    // Load module's config.yaml (check new location first, then fallback)
-    const installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'install-config.yaml');
-    const legacyConfigPath = path.join(getModulePath(moduleName), 'config.yaml');
+    // Load module's config
+    // First, try the standard src/modules location
+    let installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'install-config.yaml');
+
+    // If not found in src/modules, we need to find it by searching the project
+    if (!(await fs.pathExists(installerConfigPath))) {
+      // Use the module manager to find the module source
+      const { ModuleManager } = require('../modules/manager');
+      const moduleManager = new ModuleManager();
+      const moduleSourcePath = await moduleManager.findModuleSource(moduleName);
+
+      if (moduleSourcePath) {
+        installerConfigPath = path.join(moduleSourcePath, '_module-installer', 'install-config.yaml');
+      }
+    }
 
     let configPath = null;
     if (await fs.pathExists(installerConfigPath)) {
       configPath = installerConfigPath;
-    } else if (await fs.pathExists(legacyConfigPath)) {
-      configPath = legacyConfigPath;
     } else {
       // No config for this module
       return;