fix: update package-lock.json for semver dependency

Promote beta features to stable release with dual publishing support

.github/workflows/discord.yaml

@@ -1,6 +1,6 @@
 name: Discord Notification
 
-on: [push, pull_request, workflow_dispatch, release, create, delete, issue_comment, fork, watch, pull_request_review, pull_request_review_comment, repository_dispatch]
+on: [pull_request, release, create, delete, issue_comment, pull_request_review, pull_request_review_comment]
 
 jobs:
   notify:

.github/workflows/release.yaml

@@ -3,6 +3,7 @@ name: Release
   push:
     branches:
       - main
+      - stable
   workflow_dispatch:
     inputs:
       version_type:
@@ -32,7 +33,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '20'
           cache: npm
           registry-url: https://registry.npmjs.org
       - name: Install dependencies

.releaserc.json

@@ -1,18 +1,21 @@
 {
-  "branches": ["main"],
+  "branches": [
+    {
+      "name": "main",
+      "prerelease": "beta",
+      "channel": "beta"
+    },
+    {
+      "name": "stable",
+      "channel": "latest"
+    }
+  ],
   "plugins": [
     "@semantic-release/commit-analyzer",
     "@semantic-release/release-notes-generator",
     "@semantic-release/changelog",
     "@semantic-release/npm",
     "./tools/semantic-release-sync-installer.js",
-    [
-      "@semantic-release/git",
-      {
-        "assets": ["package.json", "package-lock.json", "tools/installer/package.json", "CHANGELOG.md"],
-        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
-      }
-    ],
     "@semantic-release/github"
   ]
 }

CHANGELOG.md

@@ -1,9 +1,21 @@
-# [4.36.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.35.3...v4.36.0) (2025-08-09)
+## [4.36.2](https://github.com/bmadcode/BMAD-METHOD/compare/v4.36.1...v4.36.2) (2025-08-10)
 
 
+### Bug Fixes
+
+* align installer dependencies with root package versions for ESM compatibility ([#420](https://github.com/bmadcode/BMAD-METHOD/issues/420)) ([3f6b674](https://github.com/bmadcode/BMAD-METHOD/commit/3f6b67443d61ae6add98656374bed27da4704644))
+
+## [4.36.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.36.0...v4.36.1) (2025-08-09)
+
+### Bug Fixes
+
+- update Node.js version to 20 in release workflow and reduce Discord spam ([3f7e19a](https://github.com/bmadcode/BMAD-METHOD/commit/3f7e19a098155341a2b89796addc47b0623cb87a))
+
+# [4.36.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.35.3...v4.36.0) (2025-08-09)
+
 ### Features
 
-* modularize flattener tool into separate components with improved project root detection ([#417](https://github.com/bmadcode/BMAD-METHOD/issues/417)) ([0fdbca7](https://github.com/bmadcode/BMAD-METHOD/commit/0fdbca73fc60e306109f682f018e105e2b4623a2))
+- modularize flattener tool into separate components with improved project root detection ([#417](https://github.com/bmadcode/BMAD-METHOD/issues/417)) ([0fdbca7](https://github.com/bmadcode/BMAD-METHOD/commit/0fdbca73fc60e306109f682f018e105e2b4623a2))
 
 ## [4.35.3](https://github.com/bmadcode/BMAD-METHOD/compare/v4.35.2...v4.35.3) (2025-08-06)
 

docs/GUIDING-PRINCIPLES.md

@@ -65,7 +65,7 @@ See [Expansion Packs Guide](../docs/expansion-packs.md) for detailed examples an
 
 ### Template Rules
 
-Templates follow the [BMad Document Template](common/utils/bmad-doc-template.md) specification using YAML format:
+Templates follow the [BMad Document Template](../common/utils/bmad-doc-template.md) specification using YAML format:
 
 1. **Structure**: Templates are defined in YAML with clear metadata, workflow configuration, and section hierarchy
 2. **Separation of Concerns**: Instructions for LLMs are in `instruction` fields, separate from content

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "4.36.0",
+  "version": "4.37.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "4.36.0",
+      "version": "4.37.0",
       "license": "MIT",
       "dependencies": {
         "@kayvan/markdown-tree-parser": "^1.5.0",
@@ -18,7 +18,8 @@
         "ignore": "^7.0.5",
         "inquirer": "^8.2.6",
         "js-yaml": "^4.1.0",
-        "ora": "^5.4.1"
+        "ora": "^5.4.1",
+        "semver": "^7.6.3"
       },
       "bin": {
         "bmad": "tools/bmad-npx-wrapper.js",
@@ -108,6 +109,16 @@
         "url": "https://opencollective.com/babel"
       }
     },
+    "node_modules/@babel/core/node_modules/semver": {
+      "version": "6.3.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
+      "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      }
+    },
     "node_modules/@babel/generator": {
       "version": "7.28.0",
       "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.28.0.tgz",
@@ -142,6 +153,16 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/@babel/helper-compilation-targets/node_modules/semver": {
+      "version": "6.3.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
+      "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      }
+    },
     "node_modules/@babel/helper-globals": {
       "version": "7.28.0",
       "resolved": "https://registry.npmjs.org/@babel/helper-globals/-/helper-globals-7.28.0.tgz",
@@ -1959,19 +1980,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/@semantic-release/npm/node_modules/semver": {
-      "version": "7.7.2",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.2.tgz",
-      "integrity": "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/@semantic-release/npm/node_modules/signal-exit": {
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
@@ -3341,19 +3349,6 @@
         "node": ">=16"
       }
     },
-    "node_modules/conventional-changelog-writer/node_modules/semver": {
-      "version": "7.7.2",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.2.tgz",
-      "integrity": "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/conventional-commits-filter": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/conventional-commits-filter/-/conventional-commits-filter-4.0.0.tgz",
@@ -4907,19 +4902,6 @@
         "node": ">=10"
       }
     },
-    "node_modules/istanbul-lib-instrument/node_modules/semver": {
-      "version": "7.7.2",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.2.tgz",
-      "integrity": "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/istanbul-lib-report": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/istanbul-lib-report/-/istanbul-lib-report-3.0.1.tgz",
@@ -5621,19 +5603,6 @@
         "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
       }
     },
-    "node_modules/jest-snapshot/node_modules/semver": {
-      "version": "7.7.2",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.2.tgz",
-      "integrity": "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/jest-util": {
       "version": "30.0.5",
       "resolved": "https://registry.npmjs.org/jest-util/-/jest-util-30.0.5.tgz",
@@ -6403,19 +6372,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/make-dir/node_modules/semver": {
-      "version": "7.7.2",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.2.tgz",
-      "integrity": "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/makeerror": {
       "version": "1.0.12",
       "resolved": "https://registry.npmjs.org/makeerror/-/makeerror-1.0.12.tgz",
@@ -7308,19 +7264,6 @@
         "node": "^16.14.0 || >=18.0.0"
       }
     },
-    "node_modules/normalize-package-data/node_modules/semver": {
-      "version": "7.7.2",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.2.tgz",
-      "integrity": "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/normalize-path": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz",
@@ -11177,19 +11120,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/semantic-release/node_modules/semver": {
-      "version": "7.7.2",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.2.tgz",
-      "integrity": "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/semantic-release/node_modules/signal-exit": {
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
@@ -11217,13 +11147,15 @@
       }
     },
     "node_modules/semver": {
-      "version": "6.3.1",
+      "version": "7.7.2",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.2.tgz",
-      "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
+      "integrity": "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==",
-      "dev": true,
       "license": "ISC",
       "bin": {
         "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
       }
     },
     "node_modules/semver-diff": {
@@ -11242,19 +11174,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/semver-diff/node_modules/semver": {
-      "version": "7.7.2",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.2.tgz",
-      "integrity": "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==",
-      "dev": true,
-      "license": "ISC",
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/semver-regex": {
       "version": "4.0.5",
       "resolved": "https://registry.npmjs.org/semver-regex/-/semver-regex-4.0.5.tgz",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.36.0",
+  "version": "4.37.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "main": "tools/cli.js",
   "bin": {
@@ -43,7 +43,8 @@
     "ignore": "^7.0.5",
     "inquirer": "^8.2.6",
     "js-yaml": "^4.1.0",
-    "ora": "^5.4.1"
+    "ora": "^5.4.1",
+    "semver": "^7.6.3"
   },
   "keywords": [
     "agile",

tools/installer/bin/bmad.js

@@ -6,13 +6,17 @@ const fs = require('fs').promises;
 const yaml = require('js-yaml');
 const chalk = require('chalk');
 const inquirer = require('inquirer');
+const semver = require('semver');
+const https = require('https');
 
 // Handle both execution contexts (from root via npx or from installer directory)
 let version;
 let installer;
+let packageName;
 try {
   // Try installer context first (when run from tools/installer/)
   version = require('../package.json').version;
+  packageName = require('../package.json').name;
   installer = require('../lib/installer');
 } catch (e) {
   // Fall back to root context (when run via npx from GitHub)
@@ -86,6 +90,60 @@ program
     }
   });
 
+// Command to check if updates are available
+program
+  .command('update-check')
+  .description('Check for BMad Update')
+  .action(async () => {
+    console.log('Checking for updates...');
+    
+    // Make HTTP request to npm registry for latest version info
+    const req = https.get(`https://registry.npmjs.org/${packageName}/latest`, res => {
+      // Check for HTTP errors (non-200 status codes)
+      if (res.statusCode !== 200) {
+        console.error(chalk.red(`Update check failed: Received status code ${res.statusCode}`));
+        return;
+      }
+      
+      // Accumulate response data chunks
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      
+      // Process complete response
+      res.on('end', () => {
+        try {
+          // Parse npm registry response and extract version
+          const latest = JSON.parse(data).version;
+          
+          // Compare versions using semver
+          if (semver.gt(latest, version)) {
+            console.log(chalk.bold.blue(`⚠️  ${packageName} update available: ${version} → ${latest}`));
+            console.log(chalk.bold.blue('\nInstall latest by running:'));
+            console.log(chalk.bold.magenta(`  npm install ${packageName}@latest`));
+            console.log(chalk.dim('  or'));
+            console.log(chalk.bold.magenta(`  npx ${packageName}@latest`));
+          } else {
+            console.log(chalk.bold.blue(`✨ ${packageName} is up to date`));
+          }
+        } catch (error) {
+          // Handle JSON parsing errors
+          console.error(chalk.red('Failed to parse npm registry data:'), error.message);
+        }
+      });
+    });
+    
+    // Handle network/connection errors
+    req.on('error', error => {
+      console.error(chalk.red('Update check failed:'), error.message);
+    });
+    
+    // Set 30 second timeout to prevent hanging
+    req.setTimeout(30000, () => {
+      req.destroy();
+      console.error(chalk.red('Update check timed out'));
+    });
+  });
+
 program
   .command('list:expansions')
   .description('List available expansion packs')

tools/installer/config/install.config.yaml

@@ -11,7 +11,7 @@ installation-options:
 ide-configurations:
   cursor:
     name: Cursor
-    rule-dir: .cursor/rules/
+    rule-dir: .cursor/rules/bmad/
     format: multi-file
     command-suffix: .mdc
     instructions: |

tools/installer/lib/ide-setup.js

@@ -68,7 +68,7 @@ class IdeSetup extends BaseIdeSetup {
   }
 
   async setupCursor(installDir, selectedAgent) {
-    const cursorRulesDir = path.join(installDir, ".cursor", "rules");
+    const cursorRulesDir = path.join(installDir, ".cursor", "rules", "bmad");
     const agents = selectedAgent ? [selectedAgent] : await this.getAllAgentIds(installDir);
 
     await fileManager.ensureDirectory(cursorRulesDir);

tools/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.36.0",
+  "version": "4.37.0",
   "description": "BMad Method installer - AI-powered Agile development framework",
   "main": "lib/installer.js",
   "bin": {
@@ -22,12 +22,13 @@
   "author": "BMad Team",
   "license": "MIT",
   "dependencies": {
-    "chalk": "^5.4.1",
+    "chalk": "^4.1.2",
     "commander": "^14.0.0",
     "fs-extra": "^11.3.0",
-    "inquirer": "^12.6.3",
+    "inquirer": "^8.2.6",
     "js-yaml": "^4.1.0",
-    "ora": "^8.2.0"
+    "ora": "^5.4.1",
+    "semver": "^7.6.3"
   },
   "engines": {
     "node": ">=20.0.0"

tools/upgraders/v3-to-v4-upgrader.js

@@ -557,7 +557,7 @@ class V3ToV4Upgrader {
 
     try {
       const ideMessages = {
-        cursor: "Rules created in .cursor/rules/",
+        cursor: "Rules created in .cursor/rules/bmad/",
         "claude-code": "Commands created in .claude/commands/BMad/",
         windsurf: "Rules created in .windsurf/rules/",
         trae: "Rules created in.trae/rules/",