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

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

@@ -7,100 +7,97 @@ field_type: "brownfield"
 description: "Complete product and system design for complex brownfield work"
 
 phases:
-  - prerequisite: true
+  - phase: 0
     name: "Documentation"
     conditional: "if_undocumented"
-    note: "NOT a phase - prerequisite for brownfield without docs"
+    note: "Prerequisite for brownfield without docs"
     workflows:
       - id: "document-project"
         required: true
+        workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml"
         agent: "analyst"
-        command: "document-project"
+        command: "/bmad:bmm:workflows:document-project"
         output: "Comprehensive project documentation"
         purpose: "Understand existing codebase before planning"
-
-  - phase: 0
-    name: "Discovery (Optional)"
+  - phase: 1
+    name: "Analysis (Optional)"
     optional: true
     note: "User-selected during workflow-init"
     workflows:
       - id: "brainstorm-project"
+        exec: "{project-root}/_bmad/core/workflows/brainstorming/workflow.md"
         optional: true
         agent: "analyst"
-        command: "brainstorm-project"
+        command: "/bmad:bmm:workflows:brainstorming"
         included_by: "user_choice"
         note: "Uses core brainstorming workflow with project context template"
-
       - id: "research"
+        exec: "{project-root}/_bmad/bmm/workflows/1-analysis/research/workflow.md"
         optional: true
         agent: "analyst"
-        command: "research"
+        command: "/bmad:bmm:workflows:research"
         included_by: "user_choice"
-
+        note: "Can have multiple research workflows"
       - id: "product-brief"
+        exec: "{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md"
         optional: true
         agent: "analyst"
-        command: "product-brief"
+        command: "/bmad:bmm:workflows:create-product-brief"
         included_by: "user_choice"
-        note: "Optional for brownfield, less common than greenfield"
-
-  - phase: 1
+        note: "Recommended for greenfield Method projects"
+  - phase: 2
     name: "Planning"
     required: true
     workflows:
       - id: "prd"
+        exec: "{project-root}/_bmad/bmm/workflows/2-plan-workflows/prd/workflow.md"
         required: true
         agent: "pm"
-        command: "prd"
-        output: "PRD focused on new features/changes"
-        note: "Must consider existing system constraints"
-
+        command: "/bmad:bmm:workflows:create-prd"
+        output: "Product Requirements Document with FRs and NFRs"
       - id: "create-ux-design"
         conditional: "if_has_ui"
+        exec: "{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md"
         agent: "ux-designer"
-        command: "create-ux-design"
-
-  - phase: 2
+        command: "/bmad:bmm:workflows:create-ux-design"
+        note: "Determined after PRD - user/agent decides if needed"
+  - phase: 3
     name: "Solutioning"
     required: true
     workflows:
       - id: "create-architecture"
-        recommended: true
+        required: true
+        exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md"
         agent: "architect"
-        command: "create-architecture"
-        output: "Integration architecture - solution design for THIS project"
-        note: "HIGHLY RECOMMENDED: Distills massive brownfield context into focused solution design. Prevents agent confusion."
-
+        command: "/bmad:bmm:workflows:create-architecture"
+        output: "System architecture document"
+        note: "Complete system design for greenfield projects"
       - id: "create-epics-and-stories"
         required: true
+        exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md"
         agent: "pm"
-        command: "create-epics-and-stories"
+        command: "/bmad:bmm:workflows:create-epics-and-stories"
         note: "Required: Break down PRD into implementable epics and stories with full context (PRD + UX + Architecture)"
-
       - id: "test-design"
-        recommended: true
+        optional: true
+        workflow: "{project-root}/_bmad/bmm/workflows/testarch/test-design/workflow.yaml"
         agent: "tea"
-        command: "test-design"
+        command: "/bmad:bmm:workflows:test-design"
         output: "System-level testability review"
         note: "Testability assessment before gate check - auto-detects system-level mode"
-
-      - id: "validate-architecture"
-        optional: true
-        agent: "architect"
-        command: "validate-architecture"
-
       - id: "implementation-readiness"
         required: true
+        exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md"
         agent: "architect"
-        command: "implementation-readiness"
+        command: "/bmad:bmm:workflows:implementation-readiness"
         note: "Validates PRD + Architecture + Epics + UX (optional)"
-
-  - phase: 3
+  - phase: 4
     name: "Implementation"
     required: true
     workflows:
       - id: "sprint-planning"
         required: true
+        workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml"
         agent: "sm"
-        command: "sprint-planning"
-        note: "Creates sprint plan with stories"
+        command: "/bmad:bmm:workflows:sprint-planning"
+        note: "Creates sprint plan - subsequent work tracked there"

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

@@ -7,90 +7,94 @@ field_type: "greenfield"
 description: "Complete product and system design methodology for greenfield projects"
 
 phases:
-  - phase: 0
-    name: "Discovery (Optional)"
+  - phase: 1
+    name: "Analysis (Optional)"
     optional: true
     note: "User-selected during workflow-init"
     workflows:
       - id: "brainstorm-project"
+        exec: "{project-root}/_bmad/core/workflows/brainstorming/workflow.md"
         optional: true
         agent: "analyst"
-        command: "brainstorm-project"
+        command: "/bmad:bmm:workflows:brainstorming"
         included_by: "user_choice"
         note: "Uses core brainstorming workflow with project context template"
 
       - id: "research"
+        exec: "{project-root}/_bmad/bmm/workflows/1-analysis/research/workflow.md"
         optional: true
         agent: "analyst"
-        command: "research"
+        command: "/bmad:bmm:workflows:research"
         included_by: "user_choice"
         note: "Can have multiple research workflows"
 
       - id: "product-brief"
+        exec: "{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md"
         optional: true
         agent: "analyst"
-        command: "product-brief"
+        command: "/bmad:bmm:workflows:create-product-brief"
         included_by: "user_choice"
         note: "Recommended for greenfield Method projects"
 
-  - phase: 1
+  - phase: 2
     name: "Planning"
     required: true
     workflows:
       - id: "prd"
+        exec: "{project-root}/_bmad/bmm/workflows/2-plan-workflows/prd/workflow.md"
         required: true
         agent: "pm"
-        command: "prd"
+        command: "/bmad:bmm:workflows:create-prd"
         output: "Product Requirements Document with FRs and NFRs"
 
       - id: "create-ux-design"
         conditional: "if_has_ui"
+        exec: "{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md"
         agent: "ux-designer"
-        command: "create-ux-design"
+        command: "/bmad:bmm:workflows:create-ux-design"
         note: "Determined after PRD - user/agent decides if needed"
 
-  - phase: 2
+  - phase: 3
     name: "Solutioning"
     required: true
     workflows:
       - id: "create-architecture"
         required: true
+        exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md"
         agent: "architect"
-        command: "create-architecture"
+        command: "/bmad:bmm:workflows:create-architecture"
         output: "System architecture document"
         note: "Complete system design for greenfield projects"
 
       - id: "create-epics-and-stories"
         required: true
+        exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md"
         agent: "pm"
-        command: "create-epics-and-stories"
+        command: "/bmad:bmm:workflows:create-epics-and-stories"
         note: "Required: Break down PRD into implementable epics and stories with full context (PRD + UX + Architecture)"
 
       - id: "test-design"
-        recommended: true
+        optional: true
+        workflow: "{project-root}/_bmad/bmm/workflows/testarch/test-design/workflow.yaml"
         agent: "tea"
-        command: "test-design"
+        command: "/bmad:bmm:workflows:test-design"
         output: "System-level testability review"
         note: "Testability assessment before gate check - auto-detects system-level mode"
 
-      - id: "validate-architecture"
-        optional: true
-        agent: "architect"
-        command: "validate-architecture"
-        note: "Quality check for architecture completeness"
-
       - id: "implementation-readiness"
         required: true
+        exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md"
         agent: "architect"
-        command: "implementation-readiness"
+        command: "/bmad:bmm:workflows:implementation-readiness"
         note: "Validates PRD + Architecture + Epics + UX (optional)"
 
-  - phase: 3
+  - phase: 4
     name: "Implementation"
     required: true
     workflows:
       - id: "sprint-planning"
         required: true
+        workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml"
         agent: "sm"
-        command: "sprint-planning"
+        command: "/bmad:bmm:workflows:sprint-planning"
         note: "Creates sprint plan - subsequent work tracked there"

package/tools/cli/bmad-cli.js

@@ -2,6 +2,24 @@ const { program } = require('commander');
 const path = require('node:path');
 const fs = require('node:fs');
 
+// Fix for stdin issues when running through npm on Windows
+// Ensures keyboard interaction works properly with inquirer prompts
+if (process.stdin.isTTY) {
+  try {
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+
+    // On Windows, explicitly reference the stdin stream to ensure it's properly initialized
+    if (process.platform === 'win32') {
+      process.stdin.on('error', () => {
+        // Ignore stdin errors - they can occur when the terminal is closing
+      });
+    }
+  } catch {
+    // Silently ignore - some environments may not support these operations
+  }
+}
+
 // Load package.json from root for version info
 const packageJson = require('../../package.json');
 

package/tools/cli/commands/install.js

@@ -1,5 +1,6 @@
 const chalk = require('chalk');
 const path = require('node:path');
+const inquirer = require('inquirer').default || require('inquirer');
 const { Installer } = require('../installers/lib/core/installer');
 const { UI } = require('../lib/ui');
 
@@ -65,18 +66,13 @@ module.exports = {
           console.log(chalk.dim('  • ElevenLabs AI (150+ premium voices)'));
           console.log(chalk.dim('  • Piper TTS (50+ free voices)\n'));
 
-          const readline = require('node:readline');
-          const rl = readline.createInterface({
-            input: process.stdin,
-            output: process.stdout,
-          });
-
-          await new Promise((resolve) => {
-            rl.question(chalk.green('Press Enter to start AgentVibes installer...'), () => {
-              rl.close();
-              resolve();
-            });
-          });
+          await inquirer.prompt([
+            {
+              type: 'input',
+              name: 'continue',
+              message: chalk.green('Press Enter to start AgentVibes installer...'),
+            },
+          ]);
 
           console.log('');
 

package/tools/cli/installers/install-messages.yaml

@@ -6,11 +6,13 @@
 startMessage: |
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  🎉🎉 Happy Holidays and New Year 🍾🍾
+  If you are looking for Version 4 of BMad Method, please note that you can
+  still install it by using the command `npx bmad-method@latest install`, until v6 reaches beta.
 
-  IMPORTANT Changes with Version Alpha.20 - PLEASE READ THIS if upgrading from earlier Alpha Versions:
+  IMPORTANT Changes with Version Alpha.22 - PLEASE READ THIS if upgrading from earlier Alpha Versions:
 
-  1. The BMad Core default output folder has changed from docs to `_bmad-output`. `docs` is meant for long-term artifacts, which you can always decide to move content to.
+  1. The BMad Core default output folder has changed from `docs` to `_bmad-output`. `docs`
+  is meant for long-term artifacts, which you can always decide to move content to.
 
   2. If utilizing the BMad Method Module (BMM) please be aware of the following important recent changes:
 
@@ -21,8 +23,8 @@ startMessage: |
   IT IS STRONGLY SUGGESTED to align with these folder conventions instead of dumping all to docs/ - if you are upgrading from a prior
   version where all output was going to docs or docs/sprint-artifacts, it is suggested to reset configs to these new values.
 
-  If you have anything in progress, you can move what was in sprint-artifacts to _bmad-output/implementation-artifacts, and if you had brainstorming
-  content, a PRD, UX or Architecture, you can move the content to _bmad-output/planning-artifacts.
+  If you have anything in progress, you can move what was in sprint-artifacts to _bmad-output/implementation-artifacts,
+  and if you had brainstorming content, a PRD, UX or Architecture, you can move the content to _bmad-output/planning-artifacts.
 
   Read the latest updates before continuing:
   https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md
@@ -35,8 +37,11 @@ endMessage: |
 
   ✨ BMAD IS READY TO USE!
 
-  ONE FINAL NOTE WITH VERSION Alpha.20: Phase 4 (Implementation) is still in the process of being migrated to the improved workflow progressive disclosure system.
-  Along with this, the full conversion to the new path locations for content being searched may possibly be incomplete. If you run a workflow that relies on finding input documents automatically, and you notice they are not being found / looking in the wrong location, either:
+  ONE FINAL NOTE WITH VERSION Alpha.22: Phase 4 (Implementation) is still in the process of
+  being migrated to the improved workflow progressive disclosure system.
+  Along with this, the full conversion to the new path locations for content being searched
+  may possibly be incomplete. If you run a workflow that relies on finding input documents
+  automatically, and you notice they are not being found / looking in the wrong location, either:
   1. Manually specify the correct input location when prompted
   2. Open an issue on GitHub so we can address the problem quickly if you think its a bug.
   3. Ensure your content is in the new locations for best results:
@@ -47,6 +52,7 @@ endMessage: |
   Thank you for helping test the early release version of the new BMad Core and BMad Method!
   Stable Beta coming soon - please read the full README.md and linked documentation to get started.
 
-  And again, here is the Change Log with all the details of recent updates: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md
+  And again, here is the Change Log with all the details of recent updates:
+  https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md
 
   ════════════════════════════════════════════════════════════════════════════════

package/tools/cli/installers/lib/core/detector.js

@@ -203,127 +203,17 @@ class Detector {
   }
 
   /**
-   * Detect legacy BMAD v4 footprints (case-sensitive path checks)
-   * V4 used _bmad-method as default folder name
-   * V6+ uses configurable folder names and ALWAYS has _config/manifest.yaml with installation.version
+   * Detect legacy BMAD v4 .bmad-method folder
    * @param {string} projectDir - Project directory to check
    * @returns {{ hasLegacyV4: boolean, offenders: string[] }}
    */
   async detectLegacyV4(projectDir) {
-    // Helper: check existence of a nested path with case-sensitive segment matching
-    const existsCaseSensitive = async (baseDir, segments) => {
-      let dir = baseDir;
-      for (let i = 0; i < segments.length; i++) {
-        const seg = segments[i];
-        let entries;
-        try {
-          entries = await fs.readdir(dir, { withFileTypes: true });
-        } catch {
-          return false;
-        }
-        const hit = entries.find((e) => e.name === seg);
-        if (!hit) return false;
-        // Parents must be directories; the last segment may be a file or directory
-        if (i < segments.length - 1 && !hit.isDirectory()) return false;
-        dir = path.join(dir, hit.name);
-      }
-      return true;
-    };
-
-    // Helper: check if a directory is a V6+ installation
-    const isV6Installation = async (dirPath) => {
-      const manifestPath = path.join(dirPath, '_config', 'manifest.yaml');
-      if (!(await fs.pathExists(manifestPath))) {
-        return false;
-      }
-      try {
-        const yaml = require('yaml');
-        const manifestContent = await fs.readFile(manifestPath, 'utf8');
-        const manifest = yaml.parse(manifestContent);
-        // V6+ manifest has installation.version
-        return manifest && manifest.installation && manifest.installation.version;
-      } catch {
-        return false;
-      }
-    };
-
     const offenders = [];
 
-    // Strategy:
-    // 1. First scan for ANY V6+ installation (_config/manifest.yaml)
-    // 2. If V6+ found → don't flag anything (user is already on V6+)
-    // 3. If NO V6+ found → flag folders with "bmad" in name as potential V4 legacy
-
-    let hasV6Installation = false;
-    const potentialV4Folders = [];
-
-    try {
-      const entries = await fs.readdir(projectDir, { withFileTypes: true });
-
-      for (const entry of entries) {
-        if (entry.isDirectory()) {
-          const name = entry.name;
-          const fullPath = path.join(projectDir, entry.name);
-
-          // Check if directory is empty (skip empty leftover folders)
-          const dirContents = await fs.readdir(fullPath);
-          if (dirContents.length === 0) {
-            continue; // Skip empty folders
-          }
-
-          // Check if it's a V6+ installation by looking for _config/manifest.yaml
-          // This works for ANY folder name (not just bmad-prefixed)
-          const isV6 = await isV6Installation(fullPath);
-
-          if (isV6) {
-            // Found a V6+ installation - user is already on V6+
-            hasV6Installation = true;
-            // Don't break - continue scanning to be thorough
-          } else {
-            // Not V6+, check if this is the exact V4 folder name "bmad-method"
-            if (name === 'bmad-method') {
-              // This is the V4 default folder - flag it as legacy
-              potentialV4Folders.push(fullPath);
-            }
-          }
-        }
-      }
-    } catch {
-      // Ignore errors reading directory
-    }
-
-    // Only flag V4 folders if NO V6+ installation was found
-    if (!hasV6Installation && potentialV4Folders.length > 0) {
-      offenders.push(...potentialV4Folders);
-    }
-
-    // Check inside various IDE command folders for legacy bmad folders
-    // V4 used folders like 'bmad-method' or custom names in IDE commands
-    // V6+ uses 'bmad' in IDE commands (hardcoded in IDE handlers)
-    // Legacy V4 IDE command folders won't have a corresponding V6+ installation
-    const ideConfigFolders = ['.opencode', '.claude', '.crush', '.continue', '.cursor', '.windsurf', '.cline', '.roo-cline'];
-
-    for (const ideFolder of ideConfigFolders) {
-      const commandsDirName = ideFolder === '.opencode' ? 'command' : 'commands';
-      const commandsPath = path.join(projectDir, ideFolder, commandsDirName);
-      if (await fs.pathExists(commandsPath)) {
-        try {
-          const commandEntries = await fs.readdir(commandsPath, { withFileTypes: true });
-          for (const entry of commandEntries) {
-            if (entry.isDirectory()) {
-              const name = entry.name;
-              // V4 used 'bmad-method' or similar in IDE commands folders
-              // V6+ uses 'bmad' (hardcoded)
-              // So anything that's NOT 'bmad' but starts with bmad/Bmad is likely V4
-              if ((name.startsWith('bmad') || name.startsWith('Bmad') || name === 'BMad') && name !== 'bmad') {
-                offenders.push(path.join(commandsPath, entry.name));
-              }
-            }
-          }
-        } catch {
-          // Ignore errors reading commands directory
-        }
-      }
+    // Check for .bmad-method folder
+    const bmadMethodPath = path.join(projectDir, '.bmad-method');
+    if (await fs.pathExists(bmadMethodPath)) {
+      offenders.push(bmadMethodPath);
     }
 
     return { hasLegacyV4: offenders.length > 0, offenders };

package/tools/cli/installers/lib/core/installer.js

@@ -2152,90 +2152,59 @@ class Installer {
   }
 
   /**
-   * Handle legacy BMAD v4 migration with automatic backup
-   * @param {string} projectDir - Project directory
-   * @param {Object} legacyV4 - Legacy V4 detection result with offenders array
+   * Handle legacy BMAD v4 detection with simple warning
+   * @param {string} _projectDir - Project directory (unused in simplified version)
+   * @param {Object} _legacyV4 - Legacy V4 detection result (unused in simplified version)
    */
-  async handleLegacyV4Migration(projectDir, legacyV4) {
-    console.log(chalk.yellow.bold('\n⚠️  Legacy BMAD v4 detected'));
-    console.log(chalk.dim('The installer found legacy artefacts in your project.\n'));
-
-    // Separate _bmad* folders (auto-backup) from other offending paths (manual cleanup)
-    const bmadFolders = legacyV4.offenders.filter((p) => {
-      const name = path.basename(p);
-      return name.startsWith('_bmad'); // Only dot-prefixed folders get auto-backed up
-    });
-    const otherOffenders = legacyV4.offenders.filter((p) => {
-      const name = path.basename(p);
-      return !name.startsWith('_bmad'); // Everything else is manual cleanup
-    });
-
+  async handleLegacyV4Migration(_projectDir, _legacyV4) {
     const inquirer = require('inquirer').default || require('inquirer');
 
-    // Show warning for other offending paths FIRST
-    if (otherOffenders.length > 0) {
-      console.log(chalk.yellow('⚠️  Recommended cleanup:'));
-      console.log(chalk.dim('It is recommended to remove the following items before proceeding:\n'));
-      for (const p of otherOffenders) console.log(chalk.dim(` - ${p}`));
-
-      console.log(chalk.cyan('\nCleanup commands you can copy/paste:'));
-      console.log(chalk.dim('macOS/Linux:'));
-      for (const p of otherOffenders) console.log(chalk.dim(`  rm -rf '${p}'`));
-      console.log(chalk.dim('Windows:'));
-      for (const p of otherOffenders) console.log(chalk.dim(`  rmdir /S /Q "${p}"`));
-
-      const { cleanedUp } = await inquirer.prompt([
-        {
-          type: 'confirm',
-          name: 'cleanedUp',
-          message: 'Have you completed the recommended cleanup? (You can proceed without it, but it is recommended)',
-          default: false,
-        },
-      ]);
-
-      if (cleanedUp) {
-        console.log(chalk.green('✓ Cleanup acknowledged\n'));
-      } else {
-        console.log(chalk.yellow('⚠️  Proceeding without recommended cleanup\n'));
-      }
-    }
-
-    // Handle _bmad* folders with automatic backup
-    if (bmadFolders.length > 0) {
-      console.log(chalk.cyan('The following legacy folders will be moved to v4-backup:'));
-      for (const p of bmadFolders) console.log(chalk.dim(` - ${p}`));
-
-      const { proceed } = await inquirer.prompt([
-        {
-          type: 'confirm',
-          name: 'proceed',
-          message: 'Proceed with backing up legacy v4 folders?',
-          default: true,
-        },
-      ]);
+    console.log('');
+    console.log(chalk.yellow.bold('⚠️  Legacy BMAD v4 detected'));
+    console.log(chalk.yellow('─'.repeat(80)));
+    console.log(chalk.yellow('Found .bmad-method folder from BMAD v4 installation.'));
+    console.log('');
 
-      if (proceed) {
-        const backupDir = path.join(projectDir, 'v4-backup');
-        await fs.ensureDir(backupDir);
+    console.log(chalk.dim('Before continuing with installation, we recommend:'));
+    console.log(chalk.dim('  1. Remove the .bmad-method folder, OR'));
+    console.log(chalk.dim('  2. Back it up by renaming it to another name (e.g., bmad-method-backup)'));
+    console.log('');
 
-        for (const folder of bmadFolders) {
-          const folderName = path.basename(folder);
-          const backupPath = path.join(backupDir, folderName);
+    console.log(chalk.dim('If your v4 installation set up rules or commands, you should remove those as well.'));
+    console.log('');
 
-          // If backup already exists, add timestamp
-          let finalBackupPath = backupPath;
-          if (await fs.pathExists(backupPath)) {
-            const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-').split('T')[0];
-            finalBackupPath = path.join(backupDir, `${folderName}-${timestamp}`);
-          }
+    const { proceed } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'proceed',
+        message: 'What would you like to do?',
+        choices: [
+          {
+            name: 'Exit and clean up manually (recommended)',
+            value: 'exit',
+            short: 'Exit installation',
+          },
+          {
+            name: 'Continue with installation anyway',
+            value: 'continue',
+            short: 'Continue',
+          },
+        ],
+        default: 'exit',
+      },
+    ]);
 
-          await fs.move(folder, finalBackupPath, { overwrite: false });
-          console.log(chalk.green(`✓ Moved ${folderName} to ${path.relative(projectDir, finalBackupPath)}`));
-        }
-      } else {
-        throw new Error('Installation cancelled by user');
-      }
+    if (proceed === 'exit') {
+      console.log('');
+      console.log(chalk.cyan('Please remove the .bmad-method folder and any v4 rules/commands,'));
+      console.log(chalk.cyan('then run the installer again.'));
+      console.log('');
+      process.exit(0);
     }
+
+    console.log('');
+    console.log(chalk.yellow('⚠️  Proceeding with installation despite legacy v4 folder'));
+    console.log('');
   }
 
   /**

package/tools/cli/lib/agent/compiler.js

@@ -142,11 +142,7 @@ function buildMenuXml(menuItems) {
       }
       // Handle legacy format menu items
       else if (item.trigger) {
-        // For legacy items, keep using cmd with *<trigger> format
         let trigger = item.trigger || '';
-        if (!trigger.startsWith('*')) {
-          trigger = '*' + trigger;
-        }
 
         const attrs = [`cmd="${trigger}"`];
 

package/tools/docs/index.md

@@ -0,0 +1,2 @@
+# Tool and Repo Maintainability Documentation
+