CHANGELOG.md

@@ -1,13 +1,6 @@
 # Changelog
 
-## [6.0.0-Beta.2]
-
-- Fix installer so commands match what is installed, centralize most ide into a central file instead of separate files for each ide.
-- Specific IDEs may still need udpates, but all is config driven now and should be easier to maintain
-- Kiro still needs updates, but its been in this state since contributed, will investigate soon
-- Any version older than Beta.0 will recommend removal and reinstall to project. From later alphas though its sufficient to quick update if still desired, but best is just start fresh with Beta.
-
-## [6.0.0-Beta.1]
+## [6.0.0-Beta.0]
 
 **Release: January 2026 - Alpha to Beta Transition**
 

README.md

@@ -32,10 +32,10 @@ Follow the installer prompts, then open your AI IDE (Claude Code, Cursor, Windsu
 
 > **Not sure what to do?** Run `/bmad-help` — it tells you exactly what's next and what's optional. You can also ask it questions like:
 
- - `/bmad-help How should I build a web app for my TShirt Business that can scale to millions?`
+ - `/bmad-help How should I build a web app for for my TShirt Business that can scale to millions?`
  - `/bmad-help I just finished the architecture, I am not sure what to do next`
 
-And the amazing thing is BMad Help evolves depending on what modules you install also!
+And the amazing this is BMad Help evolves depending on what modules you install also!
  - `/bmad-help Im interested in really exploring creative ways to demo BMad at work, what do you recommend to help plan a great slide deck and compelling narrative?`, and if you have the Creative Intelligence Suite installed, it will offer you different or complimentary advice than if you just have BMad Method Module installed!
 
 The workflows below show the fastest path to working code. You can also load agents directly for a more structured process, extensive planning, or to learn about agile development practices — the agents guide you with menus, explanations, and elicitation at each step.
@@ -59,7 +59,7 @@ Products, platforms, complex features — structured planning then build:
 5. `/sprint-planning` — initialize sprint tracking
 6. **Repeat per story:** `/create-story` → `/dev-story` → `/code-review`
 
-Every step tells you what's next. Optional phases (brainstorming, research, UX design) are available when you need them — ask `/bmad-help` anytime. For a detailed walkthrough, see the [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/).
+Every step tells you what's next. Optional phases (brainstorming, research, UX design) are available when you need them — ask `/bmad-help` anytime. For a detailed walkthrough, see the [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/getting-started-bmadv6/).
 
 ## Modules
 
@@ -78,8 +78,8 @@ BMad Method extends with official modules for specialized domains. Modules are a
 
 **[Full Documentation](http://docs.bmad-method.org)** — Tutorials, how-to guides, concepts, and reference
 
-- [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/)
-- [Upgrading from Previous Versions](http://docs.bmad-method.org/how-to/upgrade-to-v6/)
+- [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/getting-started-bmadv6/)
+- [Upgrading from Previous Versions](http://docs.bmad-method.org/how-to/installation/upgrade-to-v6/)
 
 ### For v4 Users
 
@@ -96,7 +96,7 @@ BMad Method extends with official modules for specialized domains. Modules are a
 
 BMad is free for everyone — and always will be. If you'd like to support development:
 
-- ⭐ Please click the star project icon near the top right of this page
+- ⭐ Please click the star project icon at near the top right of this page
 - ☕ [Buy Me a Coffee](https://buymeacoffee.com/bmad) — Fuel the development
 - 🏢 Corporate sponsorship — DM on Discord
 - 🎤 Speaking & Media — Available for conferences, podcasts, interviews (BM on Discord)

docs/how-to/customize-bmad.md

@@ -151,7 +151,7 @@ prompts:
 
 ## Workflow Customization
 
-Information about customizing existing BMad Method workflows and skills are coming soon.
+Information about customizing existing BMad MEthod workflows and skills are coming soon.
 
 ## Module Customization
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "6.0.0-Beta.2",
+  "version": "6.0.0-Beta.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "6.0.0-Beta.2",
+      "version": "6.0.0-Beta.1",
       "license": "MIT",
       "dependencies": {
         "@clack/prompts": "^0.11.0",

package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.0.0-Beta.2",
+  "version": "6.0.0-Beta.1",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md

@@ -2,7 +2,7 @@
 name: 'step-01-understand'
 description: 'Analyze the requirement delta between current state and what user wants to build'
 
-workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec'
+workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec'
 nextStepFile: './step-02-investigate.md'
 skipToStepFile: './step-03-generate.md'
 templateFile: '{workflow_path}/tech-spec-template.md'

src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md

@@ -2,7 +2,7 @@
 name: 'step-02-investigate'
 description: 'Map technical constraints and anchor points within the codebase'
 
-workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec'
+workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec'
 nextStepFile: './step-03-generate.md'
 wipFile: '{implementation_artifacts}/tech-spec-wip.md'
 ---

src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md

@@ -2,7 +2,7 @@
 name: 'step-03-generate'
 description: 'Build the implementation plan based on the technical mapping of constraints'
 
-workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec'
+workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec'
 nextStepFile: './step-04-review.md'
 wipFile: '{implementation_artifacts}/tech-spec-wip.md'
 ---

src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md

@@ -139,7 +139,7 @@ b) **HALT and wait for user selection.**
 #### Menu Handling Logic:
 
 - IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
-- IF B: Read the entire workflow file at `{quick_dev_workflow}` and follow the instructions with the final spec file (warn: fresh context is better)
+- IF B: Load and execute `{quick_dev_workflow}` with the final spec file (warn: fresh context is better)
 - IF D: Exit workflow - display final confirmation and path to spec
 - IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
 - IF R: Execute Adversarial Review (see below)

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

@@ -999,9 +999,6 @@ class Installer {
 
       // Configure IDEs and copy documentation
       if (!config.skipIde && config.ides && config.ides.length > 0) {
-        // Ensure IDE manager is initialized (handlers may not be loaded in quick update flow)
-        await this.ideManager.ensureInitialized();
-
         // Filter out any undefined/null values from the IDE list
         const validIdes = config.ides.filter((ide) => ide && typeof ide === 'string');
 

tools/cli/installers/lib/ide/shared/task-tool-command-generator.js

@@ -76,7 +76,7 @@ description: '${description.replaceAll("'", "''")}'
 
 # ${item.displayName || item.name}
 
-Read the entire ${type} file at: ${itemPath}
+LOAD and execute the ${type} at: ${itemPath}
 
 Follow all instructions in the ${type} file exactly as written.
 `;

tools/cli/installers/lib/ide/templates/combined/antigravity.md

@@ -1,8 +1,6 @@
----
 name: '{{name}}'
 description: '{{description}}'
----
 
-Read the entire workflow file at: {project-root}/_bmad/{{workflow_path}}
+LOAD and execute the workflow at: {project-root}/_bmad/{{workflow_path}}
 
 Follow all instructions in the workflow file exactly as written.

tools/cli/installers/lib/ide/templates/combined/rovodev.md

@@ -4,6 +4,6 @@
 
 ---
 
-Read the entire workflow file at: {project-root}/_bmad/{{workflow_path}}
+LOAD and execute the workflow at: {project-root}/_bmad/{{workflow_path}}
 
 Follow all instructions in the workflow file exactly as written.

tools/cli/installers/lib/ide/templates/combined/trae.md

@@ -4,6 +4,6 @@
 
 ## Instructions
 
-Read the entire workflow file at: {project-root}/_bmad/{{workflow_path}}
+LOAD and execute the workflow at: {project-root}/_bmad/{{workflow_path}}
 
 Follow all instructions in the workflow file exactly as written.

tools/cli/installers/lib/ide/templates/combined/windsurf-workflow.md

@@ -5,6 +5,6 @@ auto_execution_mode: "iterate"
 
 # {{name}}
 
-Read the entire workflow file at {project-root}/_bmad/{{workflow_path}}
+LOAD and execute the workflow at: {project-root}/_bmad/{{workflow_path}}
 
 Follow all instructions in the workflow file exactly as written.

tools/cli/lib/ui.js

@@ -81,7 +81,7 @@ class UI {
       hasLegacyCfg = bmadResult.hasLegacyCfg;
     }
 
-    // Handle legacy .bmad or _cfg folder - these are very old (v4 or alpha)
+    // Handle legacy .bmad or _cfg folder - these are very old (more than 2 versions behind)
     // Show version warning instead of offering conversion
     if (hasLegacyBmadFolder || hasLegacyCfg) {
       console.log('');
@@ -92,8 +92,9 @@ class UI {
           'Found a ".bmad"/"bmad" folder, or a legacy "_cfg" folder under the bmad folder - this is from a old BMAD version that is out of date for automatic upgrade, manual intervention required.',
         ),
       );
-      console.log(chalk.yellow('You have a legacy version installed (v4 or alpha).'));
+      console.log(chalk.yellow('This version is more than 2 alpha versions behind current.'));
       console.log('');
+      console.log(chalk.dim('For stability, we only support updates from the previous 2 alpha versions.'));
       console.log(chalk.dim('Legacy installations may have compatibility issues.'));
       console.log('');
       console.log(chalk.dim('For the best experience, we strongly recommend:'));
@@ -187,8 +188,8 @@ class UI {
       const currentVersion = require(packageJsonPath).version;
       const installedVersion = existingInstall.version || 'unknown';
 
-      // Check if version is pre beta
-      const shouldProceed = await this.showLegacyVersionWarning(installedVersion, currentVersion, path.basename(bmadDir));
+      // Check if version is too old and warn user
+      const shouldProceed = await this.showOldAlphaVersionWarning(installedVersion, currentVersion, path.basename(bmadDir));
 
       // If user chose to cancel, exit the installer
       if (!shouldProceed) {
@@ -1456,40 +1457,96 @@ class UI {
   }
 
   /**
-   * Check if installed version is a legacy version that needs fresh install
-   * @param {string} installedVersion - The installed version
-   * @returns {boolean} True if legacy (v4 or any alpha)
+   * Parse alpha version string (e.g., "6.0.0-Alpha.20")
+   * @param {string} version - Version string
+   * @returns {Object|null} Object with alphaNumber and fullVersion, or null if invalid
    */
-  isLegacyVersion(installedVersion) {
-    if (!installedVersion || installedVersion === 'unknown') {
-      return true; // Treat unknown as legacy for safety
+  parseAlphaVersion(version) {
+    if (!version || version === 'unknown') {
+      return null;
     }
-    // Check if version string contains -alpha or -Alpha (any v6 alpha)
-    return /-alpha\./i.test(installedVersion);
+
+    // Remove 'v' prefix if present
+    const cleanVersion = version.toString().replace(/^v/i, '');
+
+    // Match alpha version pattern: X.Y.Z-Alpha.N (case-insensitive)
+    const match = cleanVersion.match(/[\d.]+-Alpha\.(\d+)/i);
+
+    if (!match) {
+      return null;
+    }
+
+    return {
+      alphaNumber: parseInt(match[1], 10),
+      fullVersion: cleanVersion,
+    };
   }
 
   /**
-   * Show warning for legacy version (v4 or alpha) and ask if user wants to proceed
+   * Check if installed version is more than 2 alpha versions behind current
+   * @param {string} installedVersion - The installed version
+   * @param {string} currentVersion - The current version
+   * @returns {Object} Object with { isOldVersion, versionDiff, shouldWarn, installed, current }
+   */
+  checkAlphaVersionAge(installedVersion, currentVersion) {
+    const installed = this.parseAlphaVersion(installedVersion);
+    const current = this.parseAlphaVersion(currentVersion);
+
+    // If we can't parse either version, don't warn
+    if (!installed || !current) {
+      return { isOldVersion: false, versionDiff: 0, shouldWarn: false };
+    }
+
+    // Calculate alpha version difference
+    const versionDiff = current.alphaNumber - installed.alphaNumber;
+
+    // Consider it old if more than 2 versions behind
+    const isOldVersion = versionDiff > 2;
+
+    return {
+      isOldVersion,
+      versionDiff,
+      shouldWarn: isOldVersion,
+      installed: installed.fullVersion,
+      current: current.fullVersion,
+      installedAlpha: installed.alphaNumber,
+      currentAlpha: current.alphaNumber,
+    };
+  }
+
+  /**
+   * Show warning for old alpha version and ask if user wants to proceed
    * @param {string} installedVersion - The installed version
    * @param {string} currentVersion - The current version
    * @param {string} bmadFolderName - Name of the BMAD folder
    * @returns {Promise<boolean>} True if user wants to proceed, false if they cancel
    */
-  async showLegacyVersionWarning(installedVersion, currentVersion, bmadFolderName) {
-    if (!this.isLegacyVersion(installedVersion)) {
-      return true; // Not legacy, proceed
+  async showOldAlphaVersionWarning(installedVersion, currentVersion, bmadFolderName) {
+    const versionInfo = this.checkAlphaVersionAge(installedVersion, currentVersion);
+
+    // Also warn if version is unknown or can't be parsed (legacy/unsupported)
+    const isUnknownVersion = installedVersion === 'unknown' || !versionInfo.installed;
+
+    if (!versionInfo.shouldWarn && !isUnknownVersion) {
+      return true; // Not old, proceed
     }
 
     console.log('');
     console.log(chalk.yellow.bold('⚠️  VERSION WARNING'));
     console.log(chalk.yellow('─'.repeat(80)));
 
-    if (installedVersion === 'unknown') {
+    if (isUnknownVersion) {
       console.log(chalk.yellow('Unable to detect your installed BMAD version.'));
       console.log(chalk.yellow('This appears to be a legacy or unsupported installation.'));
+      console.log('');
+      console.log(chalk.dim('For stability, we only support updates from the previous 2 alpha versions.'));
+      console.log(chalk.dim('Legacy installations may have compatibility issues.'));
     } else {
-      console.log(chalk.yellow(`You are updating from ${installedVersion} to ${currentVersion}.`));
-      console.log(chalk.yellow('You have a legacy version installed (v4 or alpha).'));
+      console.log(chalk.yellow(`You are updating from ${versionInfo.installed} to ${versionInfo.current}.`));
+      console.log(chalk.yellow(`This is ${versionInfo.versionDiff} alpha versions behind.`));
+      console.log('');
+      console.log(chalk.dim(`For stability, we only support updates from the previous 2 alpha versions`));
+      console.log(chalk.dim(`(Alpha.${versionInfo.currentAlpha - 2} through Alpha.${versionInfo.currentAlpha - 1}).`));
     }
 
     console.log('');