fix: auto semantic versioning fix

docs/versioning-and-releases.md

@@ -1,38 +1,85 @@
 # How to Release a New Version
 
-## Simple steps for releasing a new version of BMAD-METHOD
+## 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
-# 1. Commit all changes
-git add .
-git commit -m "feat: add versioning and release automation"
-
-# 2. Bump version
-npm run version:minor  # 4.0.0 → 4.1.0
-
-# 3. Push to GitHub (when ready)
-git push && git push --tags
+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
 
-## Available Commands
+### 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)
-```
 
-## What the Version Bump Does
-
-1. Updates `package.json` version
-2. Creates git commit: `chore: bump version to vX.Y.Z`
-3. Creates git tag: `vX.Y.Z`
-4. Shows reminder to push
-
-## To Publish to NPM (Optional)
-
-```bash
+# Then manually publish:
 npm publish
+git push && git push --tags
 ```
 
-Then users can run: `npx bmad-method` to get the new version.
+### 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.