chore: bump version to v4.2.0

## [1.0.1](https://github.com/bmadcode/BMAD-METHOD/compare/v1.0.0...v1.0.1) (2025-06-15)

### Bug Fixes

* resolve NPM token configuration ([620b09a](620b09a556))

.github/workflows/release.yml

@@ -14,6 +14,11 @@ name: Release
           - patch
           - minor
           - major
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+  packages: write
 jobs:
   release:
     runs-on: ubuntu-latest
@@ -29,12 +34,19 @@ jobs:
         with:
           node-version: '18'
           cache: npm
+          registry-url: https://registry.npmjs.org
       - name: Install dependencies
         run: npm ci
       - name: Run tests and validation
         run: |
           npm run validate
           npm run format
+      - name: Debug permissions
+        run: |
+          echo "Testing git permissions..."
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          echo "Git config set successfully"
       - name: Manual version bump
         if: github.event_name == 'workflow_dispatch'
         run: npm run version:${{ github.event.inputs.version_type }}
@@ -43,4 +55,5 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: npm run release

.releaserc.json

@@ -5,10 +5,13 @@
     "@semantic-release/release-notes-generator",
     "@semantic-release/changelog",
     "@semantic-release/npm",
-    ["@semantic-release/git", {
+    [
-      "assets": ["package.json", "CHANGELOG.md"],
+      "@semantic-release/git",
+      {
+        "assets": ["package.json", "package-lock.json", "CHANGELOG.md"],
         "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
-    }],
+      }
+    ],
     "@semantic-release/github"
   ]
 }

CHANGELOG.md

@@ -0,0 +1,22 @@
+## [1.0.1](https://github.com/bmadcode/BMAD-METHOD/compare/v1.0.0...v1.0.1) (2025-06-15)
+
+
+### Bug Fixes
+
+* resolve NPM token configuration ([620b09a](https://github.com/bmadcode/BMAD-METHOD/commit/620b09a556ce8d61ad1a4d8ee7c523d263abd69c))
+
+# 1.0.0 (2025-06-15)
+
+### Bug Fixes
+
+- Add bin field to root package.json for npx execution ([01cb46e](https://github.com/bmadcode/BMAD-METHOD/commit/01cb46e43da9713c24e68e57221ebe312c53b6ee)), closes [bmadcode/BMAD-METHOD#v4](https://github.com/bmadcode/BMAD-METHOD/issues/v4)
+- Add glob dependency for installer ([8d788b6](https://github.com/bmadcode/BMAD-METHOD/commit/8d788b6f490a94386658dff2f96165dca88c0a9a))
+- Add installer dependencies to root package.json ([0a838e9](https://github.com/bmadcode/BMAD-METHOD/commit/0a838e9d579a5efc632707d237194648394fbd61))
+- auto semantic versioning fix ([166ed04](https://github.com/bmadcode/BMAD-METHOD/commit/166ed047671cccab2874fd327efb1ac293ae7276))
+- auto semantic versioning fix again ([11260e4](https://github.com/bmadcode/BMAD-METHOD/commit/11260e43950b6bf78d68c759dc3ac278bc13f8a8))
+- Remove problematic install script from package.json ([cb1836b](https://github.com/bmadcode/BMAD-METHOD/commit/cb1836bd6ddbb2369e2ed97a1d2f5d6630a7152b))
+- resolve NPM token configuration ([b447a8b](https://github.com/bmadcode/BMAD-METHOD/commit/b447a8bd57625d02692d7e2771241bacd120c631))
+
+### Features
+
+- add versioning and release automation ([0ea5e50](https://github.com/bmadcode/BMAD-METHOD/commit/0ea5e50aa7ace5946d0100c180dd4c0da3e2fd8c))

README.md

@@ -1,9 +1,9 @@
 # BMAD-METHOD
 
-[![Version](https://img.shields.io/badge/version-4.0.0-blue.svg)](docs/versions.md)
+[![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org)
-[![Discord](https://img.shields.io/discord/1234567890?color=7289da&label=Discord&logo=discord&logoColor=white)](https://discord.gg/g6ypHytrCB)
+[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/YOUR_ACTUAL_DISCORD_INVITE)
 
 **AI-Powered Agile Development Framework** - Transform your software development with specialized AI agents that work as your complete Agile team.
 
@@ -30,7 +30,7 @@ npx bmad-method install
 # - Fresh installation or upgrade from v3
 # - Full installation or single agent
 # - Destination folder and IDE configuration
-```
+```text
 
 This installs all agents and configures them for your IDE. If you have an existing v3 installation, it will offer to upgrade it automatically.
 
@@ -135,7 +135,7 @@ After installation with `--ide` flag:
 
 # In Windsurf
 @dev Implement story 1.3
-```
+```text
 
 ### With Web UI (ChatGPT/Claude/Gemini)
 
@@ -161,7 +161,7 @@ If you have an existing BMAD-METHOD V3 project, simply run the installer in your
 ```bash
 npx bmad-method install
 # The installer will automatically detect your V3 installation and offer to upgrade
-```
+```text
 
 The upgrade process will:
 

docs/versioning-and-releases.md

@@ -0,0 +1,85 @@
+# How to Release a New Version
+
+## Automated Releases (Recommended)
+
+The easiest way to release new versions is through **automatic semantic releases**. Just commit with the right message format and push - everything else happens automatically!
+
+### Commit Message Format
+
+Use these prefixes to control what type of release happens:
+
+```bash
+fix: resolve CLI argument parsing bug      # → patch release (4.1.0 → 4.1.1)
+feat: add new agent orchestration mode     # → minor release (4.1.0 → 4.2.0)
+feat!: redesign CLI interface              # → major release (4.1.0 → 5.0.0)
+```text
+
+### What Happens Automatically
+
+When you push commits with `fix:` or `feat:`, GitHub Actions will:
+
+1. ✅ Analyze your commit messages
+2. ✅ Bump version in `package.json`
+3. ✅ Generate changelog
+4. ✅ Create git tag
+5. ✅ **Publish to NPM automatically**
+6. ✅ Create GitHub release with notes
+
+### Your Simple Workflow
+
+```bash
+# Make your changes
+git add .
+git commit -m "feat: add team collaboration mode"
+git push
+
+# That's it! Release happens automatically 🎉
+# Users can now run: npx bmad-method (and get the new version)
+```
+
+### Commits That DON'T Trigger Releases
+
+These commit types won't create releases (use them for maintenance):
+
+```bash
+chore: update dependencies     # No release
+docs: fix typo in readme      # No release
+style: format code            # No release
+test: add unit tests          # No release
+```text
+
+### Test Your Setup
+
+```bash
+npm run release:test    # Safe to run locally - tests the config
+```
+
+---
+
+## Manual Release Methods (Exceptions Only)
+
+**⚠️ Only use these methods if you need to bypass the automatic system**
+
+### Quick Manual Version Bump
+
+```bash
+npm run version:patch   # 4.1.0 → 4.1.1 (bug fixes)
+npm run version:minor   # 4.1.0 → 4.2.0 (new features)
+npm run version:major   # 4.1.0 → 5.0.0 (breaking changes)
+
+# Then manually publish:
+npm publish
+git push && git push --tags
+```
+
+### Manual GitHub Actions Trigger
+
+You can also trigger releases manually through GitHub Actions workflow dispatch if needed.
+
+---
+
+## Summary
+
+**For 99% of releases**: Just use `fix:` or `feat:` commit messages and push. Everything else is automatic!
+
+**Manual methods**: Only needed for special cases or if you want to bypass the automated system.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "main": "tools/cli.js",
   "bin": {
@@ -19,6 +19,7 @@
     "version:minor": "node tools/version-bump.js minor",
     "version:major": "node tools/version-bump.js major",
     "release": "semantic-release",
+    "release:test": "semantic-release --dry-run --no-ci || echo 'Config test complete - authentication errors are expected locally'",
     "prepare": "husky"
   },
   "dependencies": {
@@ -44,18 +45,18 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/your-org/bmad-method.git"
+    "url": "https://github.com/bmadcode/BMAD-METHOD.git"
   },
   "engines": {
     "node": ">=14.0.0"
   },
   "devDependencies": {
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
     "husky": "^9.1.7",
     "lint-staged": "^16.1.1",
     "prettier": "^3.5.3",
-    "semantic-release": "^24.2.5",
+    "semantic-release": "^22.0.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
     "yaml-lint": "^1.7.0"
   },
   "lint-staged": {