Merge branch 'main' into agent-fix

- npm latest tag now correctly points to 5.1.0
- package.json updated to 5.1.1 (what patch should have made)
- installer version synced

.github/workflows/manual-release.yaml

@@ -0,0 +1,173 @@
+name: Manual Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_bump:
+        description: Version bump type
+        required: true
+        default: patch
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          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:check
+          npm run lint
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version
+        run: npm run version:${{ github.event.inputs.version_bump }}
+
+      - name: Get new version and previous tag
+        id: version
+        run: |
+          echo "new_version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
+          echo "previous_tag=$(git describe --tags --abbrev=0)" >> $GITHUB_OUTPUT
+
+      - name: Update installer package.json
+        run: |
+          sed -i 's/"version": ".*"/"version": "${{ steps.version.outputs.new_version }}"/' tools/installer/package.json
+
+      - name: Build project
+        run: npm run build
+
+      - name: Commit version bump
+        run: |
+          git add .
+          git commit -m "release: bump to v${{ steps.version.outputs.new_version }}"
+
+      - name: Generate release notes
+        id: release_notes
+        run: |
+          # Get commits since last tag
+          COMMITS=$(git log ${{ steps.version.outputs.previous_tag }}..HEAD --pretty=format:"- %s" --reverse)
+
+          # Categorize commits
+          FEATURES=$(echo "$COMMITS" | grep -E "^- (feat|Feature)" || true)
+          FIXES=$(echo "$COMMITS" | grep -E "^- (fix|Fix)" || true)  
+          CHORES=$(echo "$COMMITS" | grep -E "^- (chore|Chore)" || true)
+          OTHERS=$(echo "$COMMITS" | grep -v -E "^- (feat|Feature|fix|Fix|chore|Chore|release:|Release:)" || true)
+
+          # Build release notes
+          cat > release_notes.md << 'EOF'
+          ## 🚀 What's New in v${{ steps.version.outputs.new_version }}
+
+          EOF
+
+          if [ ! -z "$FEATURES" ]; then
+            echo "### ✨ New Features" >> release_notes.md
+            echo "$FEATURES" >> release_notes.md
+            echo "" >> release_notes.md
+          fi
+
+          if [ ! -z "$FIXES" ]; then
+            echo "### 🐛 Bug Fixes" >> release_notes.md
+            echo "$FIXES" >> release_notes.md
+            echo "" >> release_notes.md
+          fi
+
+          if [ ! -z "$OTHERS" ]; then
+            echo "### 📦 Other Changes" >> release_notes.md
+            echo "$OTHERS" >> release_notes.md
+            echo "" >> release_notes.md
+          fi
+
+          if [ ! -z "$CHORES" ]; then
+            echo "### 🔧 Maintenance" >> release_notes.md
+            echo "$CHORES" >> release_notes.md
+            echo "" >> release_notes.md
+          fi
+
+          cat >> release_notes.md << 'EOF'
+
+          ## 📦 Installation
+
+          ```bash
+          npx bmad-method install
+          ```
+
+          **Full Changelog**: https://github.com/bmadcode/BMAD-METHOD/compare/${{ steps.version.outputs.previous_tag }}...v${{ steps.version.outputs.new_version }}
+          EOF
+
+          # Output for GitHub Actions
+          echo "RELEASE_NOTES<<EOF" >> $GITHUB_OUTPUT
+          cat release_notes.md >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create and push tag
+        run: |
+          # Check if tag already exists
+          if git rev-parse "v${{ steps.version.outputs.new_version }}" >/dev/null 2>&1; then
+            echo "Tag v${{ steps.version.outputs.new_version }} already exists, skipping tag creation"
+          else
+            git tag -a "v${{ steps.version.outputs.new_version }}" -m "Release v${{ steps.version.outputs.new_version }}"
+            git push origin "v${{ steps.version.outputs.new_version }}"
+          fi
+
+      - name: Push changes to main
+        run: |
+          if git push origin HEAD:main 2>/dev/null; then
+            echo "✅ Successfully pushed to main branch"
+          else
+            echo "⚠️ Could not push to main (protected branch). This is expected."
+            echo "📝 Version bump and tag were created successfully."
+          fi
+
+      - name: Publish to NPM
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish
+
+      - name: Create GitHub Release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: v${{ steps.version.outputs.new_version }}
+          release_name: "BMad Method v${{ steps.version.outputs.new_version }}"
+          body: ${{ steps.release_notes.outputs.RELEASE_NOTES }}
+          draft: false
+          prerelease: false
+
+      - name: Summary
+        run: |
+          echo "🎉 Successfully released v${{ steps.version.outputs.new_version }}!"
+          echo "📦 Published to NPM with @latest tag"
+          echo "🏷️ Git tag: v${{ steps.version.outputs.new_version }}"
+          echo "✅ Users running 'npx bmad-method install' will now get version ${{ steps.version.outputs.new_version }}"
+          echo ""
+          echo "📝 Release notes preview:"
+          cat release_notes.md

.github/workflows/promote-to-stable.yaml

@@ -1,148 +0,0 @@
-name: Promote to Stable
-
-"on":
-  workflow_dispatch:
-    inputs:
-      version_bump:
-        description: "Version bump type"
-        required: true
-        default: "minor"
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-
-jobs:
-  promote:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-          registry-url: "https://registry.npmjs.org"
-
-      - name: Configure Git
-        run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Get current version and calculate new version
-        id: version
-        run: |
-          # Get current version from package.json
-          CURRENT_VERSION=$(node -p "require('./package.json').version")
-          echo "current_version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
-
-          # Remove beta suffix if present
-          BASE_VERSION=$(echo $CURRENT_VERSION | sed 's/-beta\.[0-9]\+//')
-          echo "base_version=$BASE_VERSION" >> $GITHUB_OUTPUT
-
-          # Calculate new version based on bump type
-          IFS='.' read -ra VERSION_PARTS <<< "$BASE_VERSION"
-          MAJOR=${VERSION_PARTS[0]}
-          MINOR=${VERSION_PARTS[1]}
-          PATCH=${VERSION_PARTS[2]}
-
-          case "${{ github.event.inputs.version_bump }}" in
-            "major")
-              NEW_VERSION="$((MAJOR + 1)).0.0"
-              ;;
-            "minor")
-              NEW_VERSION="$MAJOR.$((MINOR + 1)).0"
-              ;;
-            "patch")
-              NEW_VERSION="$MAJOR.$MINOR.$((PATCH + 1))"
-              ;;
-            *)
-              NEW_VERSION="$BASE_VERSION"
-              ;;
-          esac
-
-          # Check if calculated version already exists (either as NPM package or git tag)
-          while npm view bmad-method@$NEW_VERSION version >/dev/null 2>&1 || git ls-remote --tags origin | grep -q "refs/tags/v$NEW_VERSION"; do
-            echo "Version $NEW_VERSION already exists, incrementing..."
-            IFS='.' read -ra NEW_VERSION_PARTS <<< "$NEW_VERSION"
-            NEW_MAJOR=${NEW_VERSION_PARTS[0]}
-            NEW_MINOR=${NEW_VERSION_PARTS[1]}
-            NEW_PATCH=${NEW_VERSION_PARTS[2]}
-            
-            case "${{ github.event.inputs.version_bump }}" in
-              "major")
-                NEW_VERSION="$((NEW_MAJOR + 1)).0.0"
-                ;;
-              "minor")
-                NEW_VERSION="$NEW_MAJOR.$((NEW_MINOR + 1)).0"
-                ;;
-              "patch")
-                NEW_VERSION="$NEW_MAJOR.$NEW_MINOR.$((NEW_PATCH + 1))"
-                ;;
-            esac
-          done
-
-          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
-          echo "Promoting from $CURRENT_VERSION to $NEW_VERSION"
-
-      - name: Update package.json versions
-        run: |
-          # Update main package.json
-          npm version ${{ steps.version.outputs.new_version }} --no-git-tag-version
-
-          # Update installer package.json
-          sed -i 's/"version": ".*"/"version": "${{ steps.version.outputs.new_version }}"/' tools/installer/package.json
-
-      - name: Update package-lock.json
-        run: npm install --package-lock-only
-
-      - name: Commit stable release
-        run: |
-          git add .
-          git commit -m "release: promote to stable ${{ steps.version.outputs.new_version }}"
-
-      - name: Create and push stable tag
-        run: |
-          # Create new tag (version check already ensures it doesn't exist)
-          git tag -a "v${{ steps.version.outputs.new_version }}" -m "Stable release v${{ steps.version.outputs.new_version }}"
-
-          # Push the new tag
-          git push origin "v${{ steps.version.outputs.new_version }}"
-
-      - name: Push changes to main
-        run: |
-          git push origin HEAD:main
-
-      - name: Publish to NPM with stable tag
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: |
-          # Publish with the stable (latest) tag
-          npm publish --tag latest
-
-          # Also tag the previous beta version as stable if it exists
-          if npm view bmad-method@${{ steps.version.outputs.current_version }} version >/dev/null 2>&1; then
-            npm dist-tag add bmad-method@${{ steps.version.outputs.new_version }} stable || true
-          fi
-
-      - name: Summary
-        run: |
-          echo "🎉 Successfully promoted to stable!"
-          echo "📦 Version: ${{ steps.version.outputs.new_version }}"
-          echo "🏷️ Git tag: v${{ steps.version.outputs.new_version }}"
-          echo "✅ Published to NPM with 'latest' tag"
-          echo "✅ Users running 'npx bmad-method install' will now get version ${{ steps.version.outputs.new_version }}"
-          echo "🚀 The stable release will be automatically published to NPM via semantic-release"
-          echo "✅ Users running 'npx bmad-method install' will now get version ${{ steps.version.outputs.new_version }}"

.github/workflows/release.yaml

@@ -1,73 +0,0 @@
-name: Release
-"on":
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-    inputs:
-      version_type:
-        description: Version bump type
-        required: true
-        default: patch
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-permissions:
-  contents: write
-  issues: write
-  pull-requests: write
-  packages: write
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    if: ${{ github.event_name != 'push' || !contains(github.event.head_commit.message, '[skip ci]') }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-          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 }}
-      - name: Semantic Release
-        if: github.event_name == 'push'
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npm run release
-      - name: Clean changelog formatting
-        if: github.event_name == 'push'
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          # Remove any Claude Code attribution from changelog
-          sed -i '/🤖 Generated with \[Claude Code\]/,+2d' CHANGELOG.md || true
-          # Format and commit if changes exist
-          npm run format
-          if ! git diff --quiet CHANGELOG.md; then
-            git add CHANGELOG.md
-            git commit -m "chore: clean changelog formatting [skip ci]"
-            git push
-          fi

.releaserc.json

@@ -1,22 +0,0 @@
-{
-  "branches": [
-    {
-      "name": "main",
-      "prerelease": "beta",
-      "channel": "beta"
-    }
-  ],
-  "plugins": [
-    "@semantic-release/commit-analyzer",
-    "@semantic-release/release-notes-generator",
-    [
-      "@semantic-release/changelog",
-      {
-        "changelogFile": "CHANGELOG.md"
-      }
-    ],
-    "@semantic-release/npm",
-    "./tools/semantic-release-sync-installer.js",
-    "@semantic-release/github"
-  ]
-}

README.md

@@ -75,6 +75,8 @@ This makes it easy to benefit from the latest improvements, bug fixes, and new a
 
 ```bash
 npx bmad-method install
+# OR explicitly use stable tag:
+npx bmad-method@stable install
 # OR if you already have BMad installed:
 git pull
 npm run install:bmad

bmad-core/agents/analyst.md

@@ -17,7 +17,8 @@ REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (
 activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
-  - STEP 3: Greet user with your name/role and mention `*help` command
+  - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
   - DO NOT: Load any other agent files during activation
   - ONLY load dependency files when user selects them for execution via command or request of a task
   - The agent.customization field ALWAYS takes precedence over any conflicting instructions
@@ -26,7 +27,7 @@ activation-instructions:
   - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
 agent:
   name: Mary
   id: analyst

bmad-core/agents/architect.md

@@ -17,7 +17,8 @@ REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (
 activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
-  - STEP 3: Greet user with your name/role and mention `*help` command
+  - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
   - DO NOT: Load any other agent files during activation
   - ONLY load dependency files when user selects them for execution via command or request of a task
   - The agent.customization field ALWAYS takes precedence over any conflicting instructions
@@ -26,8 +27,7 @@ activation-instructions:
   - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - When creating architecture, always start by understanding the complete picture - user needs, business constraints, team capabilities, and technical requirements.
+  - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
 agent:
   name: Winston
   id: architect

bmad-core/agents/bmad-master.md

@@ -17,7 +17,8 @@ REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (
 activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
-  - STEP 3: Greet user with your name/role and mention `*help` command
+  - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
   - DO NOT: Load any other agent files during activation
   - ONLY load dependency files when user selects them for execution via command or request of a task
   - The agent.customization field ALWAYS takes precedence over any conflicting instructions
@@ -26,10 +27,10 @@ activation-instructions:
   - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - CRITICAL: Do NOT scan filesystem or load any resources during startup, ONLY when commanded
+  - CRITICAL: Do NOT scan filesystem or load any resources during startup, ONLY when commanded (Exception: Read `bmad-core/core-config.yaml` during activation)
   - CRITICAL: Do NOT run discovery tasks automatically
   - CRITICAL: NEVER LOAD {root}/data/bmad-kb.md UNLESS USER TYPES *kb
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
 agent:
   name: BMad Master
   id: bmad-master

bmad-core/agents/bmad-orchestrator.md

@@ -17,7 +17,8 @@ REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (
 activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
-  - STEP 3: Greet user with your name/role and mention `*help` command
+  - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
   - DO NOT: Load any other agent files during activation
   - ONLY load dependency files when user selects them for execution via command or request of a task
   - The agent.customization field ALWAYS takes precedence over any conflicting instructions
@@ -28,8 +29,8 @@ activation-instructions:
   - Assess user goal against available agents and workflows in this bundle
   - If clear match to an agent's expertise, suggest transformation with *agent command
   - If project-oriented, suggest *workflow-guidance to explore options
-  - Load resources only when needed - never pre-load
+  - Load resources only when needed - never pre-load (Exception: Read `bmad-core/core-config.yaml` during activation)
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
 agent:
   name: BMad Orchestrator
   id: bmad-orchestrator

bmad-core/agents/dev.md

@@ -17,7 +17,8 @@ REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (
 activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
-  - STEP 3: Greet user with your name/role and mention `*help` command
+  - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
   - DO NOT: Load any other agent files during activation
   - ONLY load dependency files when user selects them for execution via command or request of a task
   - The agent.customization field ALWAYS takes precedence over any conflicting instructions
@@ -29,7 +30,7 @@ activation-instructions:
   - CRITICAL: Read the following full files as these are your explicit rules for development standards for this project - {root}/core-config.yaml devLoadAlwaysFiles list
   - CRITICAL: Do NOT load any other files during startup aside from the assigned story and devLoadAlwaysFiles items, unless user requested you do or the following contradicts
   - CRITICAL: Do NOT begin development until a story is not in draft mode and you are told to proceed
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
 agent:
   name: James
   id: dev
@@ -65,11 +66,13 @@ commands:
       - blocking: 'HALT for: Unapproved deps needed, confirm with user | Ambiguous after story check | 3 failures attempting to implement or fix something repeatedly | Missing config | Failing regression'
       - ready-for-review: 'Code matches requirements + All validations pass + Follows standards + File List complete'
       - completion: "All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON'T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→set story status: 'Ready for Review'→HALT"
+- review-qa: run task `apply-qa-fixes.md'
 
 dependencies:
   tasks:
     - execute-checklist.md
     - validate-next-story.md
+    - apply-qa-fixes.md
   checklists:
     - story-dod-checklist.md
 ```

bmad-core/agents/pm.md

@@ -17,7 +17,8 @@ REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (
 activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
-  - STEP 3: Greet user with your name/role and mention `*help` command
+  - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
   - DO NOT: Load any other agent files during activation
   - ONLY load dependency files when user selects them for execution via command or request of a task
   - The agent.customization field ALWAYS takes precedence over any conflicting instructions
@@ -26,7 +27,7 @@ activation-instructions:
   - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
 agent:
   name: John
   id: pm

bmad-core/agents/po.md

@@ -17,7 +17,8 @@ REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (
 activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
-  - STEP 3: Greet user with your name/role and mention `*help` command
+  - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
   - DO NOT: Load any other agent files during activation
   - ONLY load dependency files when user selects them for execution via command or request of a task
   - The agent.customization field ALWAYS takes precedence over any conflicting instructions
@@ -26,7 +27,7 @@ activation-instructions:
   - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
 agent:
   name: Sarah
   id: po

bmad-core/agents/qa.md

@@ -17,7 +17,8 @@ REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (
 activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
-  - STEP 3: Greet user with your name/role and mention `*help` command
+  - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
   - DO NOT: Load any other agent files during activation
   - ONLY load dependency files when user selects them for execution via command or request of a task
   - The agent.customization field ALWAYS takes precedence over any conflicting instructions
@@ -26,7 +27,7 @@ activation-instructions:
   - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
 agent:
   name: Quinn
   id: qa
@@ -64,9 +65,9 @@ commands:
   - review {story}: |
       Adaptive, risk-aware comprehensive review. 
       Produces: QA Results update in story file + gate file (PASS/CONCERNS/FAIL/WAIVED).
-      Gate file location: docs/qa/gates/{epic}.{story}-{slug}.yml
+      Gate file location: qa.qaLocation/gates/{epic}.{story}-{slug}.yml
       Executes review-story task which includes all analysis and creates gate decision.
-  - gate {story}: Execute qa-gate task to write/update quality gate decision in docs/qa/gates/
+  - gate {story}: Execute qa-gate task to write/update quality gate decision in directory from qa.qaLocation/gates/
   - trace {story}: Execute trace-requirements task to map requirements to tests using Given-When-Then
   - risk-profile {story}: Execute risk-profile task to generate risk assessment matrix
   - test-design {story}: Execute test-design task to create comprehensive test scenarios

bmad-core/agents/sm.md

@@ -17,7 +17,8 @@ REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (
 activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
-  - STEP 3: Greet user with your name/role and mention `*help` command
+  - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
   - DO NOT: Load any other agent files during activation
   - ONLY load dependency files when user selects them for execution via command or request of a task
   - The agent.customization field ALWAYS takes precedence over any conflicting instructions
@@ -26,7 +27,7 @@ activation-instructions:
   - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
 agent:
   name: Bob
   id: sm

bmad-core/agents/ux-expert.md

@@ -17,7 +17,8 @@ REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (
 activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
-  - STEP 3: Greet user with your name/role and mention `*help` command
+  - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
   - DO NOT: Load any other agent files during activation
   - ONLY load dependency files when user selects them for execution via command or request of a task
   - The agent.customization field ALWAYS takes precedence over any conflicting instructions
@@ -26,7 +27,7 @@ activation-instructions:
   - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+  - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
 agent:
   name: Sally
   id: ux-expert

bmad-core/core-config.yaml

@@ -1,4 +1,6 @@
 markdownExploder: true
+qa:
+  qaLocation: docs/qa
 prd:
   prdFile: docs/prd.md
   prdVersion: v4

bmad-core/tasks/apply-qa-fixes.md

@@ -0,0 +1,148 @@
+# apply-qa-fixes
+
+Implement fixes based on QA results (gate and assessments) for a specific story. This task is for the Dev agent to systematically consume QA outputs and apply code/test changes while only updating allowed sections in the story file.
+
+## Purpose
+
+- Read QA outputs for a story (gate YAML + assessment markdowns)
+- Create a prioritized, deterministic fix plan
+- Apply code and test changes to close gaps and address issues
+- Update only the allowed story sections for the Dev agent
+
+## Inputs
+
+```yaml
+required:
+  - story_id: '{epic}.{story}' # e.g., "2.2"
+  - qa_root: from `bmad-core/core-config.yaml` key `qa.qaLocation` (e.g., `docs/project/qa`)
+  - story_root: from `bmad-core/core-config.yaml` key `devStoryLocation` (e.g., `docs/project/stories`)
+
+optional:
+  - story_title: '{title}' # derive from story H1 if missing
+  - story_slug: '{slug}' # derive from title (lowercase, hyphenated) if missing
+```
+
+## QA Sources to Read
+
+- Gate (YAML): `{qa_root}/gates/{epic}.{story}-*.yml`
+  - If multiple, use the most recent by modified time
+- Assessments (Markdown):
+  - Test Design: `{qa_root}/assessments/{epic}.{story}-test-design-*.md`
+  - Traceability: `{qa_root}/assessments/{epic}.{story}-trace-*.md`
+  - Risk Profile: `{qa_root}/assessments/{epic}.{story}-risk-*.md`
+  - NFR Assessment: `{qa_root}/assessments/{epic}.{story}-nfr-*.md`
+
+## Prerequisites
+
+- Repository builds and tests run locally (Deno 2)
+- Lint and test commands available:
+  - `deno lint`
+  - `deno test -A`
+
+## Process (Do not skip steps)
+
+### 0) Load Core Config & Locate Story
+
+- Read `bmad-core/core-config.yaml` and resolve `qa_root` and `story_root`
+- Locate story file in `{story_root}/{epic}.{story}.*.md`
+  - HALT if missing and ask for correct story id/path
+
+### 1) Collect QA Findings
+
+- Parse the latest gate YAML:
+  - `gate` (PASS|CONCERNS|FAIL|WAIVED)
+  - `top_issues[]` with `id`, `severity`, `finding`, `suggested_action`
+  - `nfr_validation.*.status` and notes
+  - `trace` coverage summary/gaps
+  - `test_design.coverage_gaps[]`
+  - `risk_summary.recommendations.must_fix[]` (if present)
+- Read any present assessment markdowns and extract explicit gaps/recommendations
+
+### 2) Build Deterministic Fix Plan (Priority Order)
+
+Apply in order, highest priority first:
+
+1. High severity items in `top_issues` (security/perf/reliability/maintainability)
+2. NFR statuses: all FAIL must be fixed → then CONCERNS
+3. Test Design `coverage_gaps` (prioritize P0 scenarios if specified)
+4. Trace uncovered requirements (AC-level)
+5. Risk `must_fix` recommendations
+6. Medium severity issues, then low
+
+Guidance:
+
+- Prefer tests closing coverage gaps before/with code changes
+- Keep changes minimal and targeted; follow project architecture and TS/Deno rules
+
+### 3) Apply Changes
+
+- Implement code fixes per plan
+- Add missing tests to close coverage gaps (unit first; integration where required by AC)
+- Keep imports centralized via `deps.ts` (see `docs/project/typescript-rules.md`)
+- Follow DI boundaries in `src/core/di.ts` and existing patterns
+
+### 4) Validate
+
+- Run `deno lint` and fix issues
+- Run `deno test -A` until all tests pass
+- Iterate until clean
+
+### 5) Update Story (Allowed Sections ONLY)
+
+CRITICAL: Dev agent is ONLY authorized to update these sections of the story file. Do not modify any other sections (e.g., QA Results, Story, Acceptance Criteria, Dev Notes, Testing):
+
+- Tasks / Subtasks Checkboxes (mark any fix subtask you added as done)
+- Dev Agent Record →
+  - Agent Model Used (if changed)
+  - Debug Log References (commands/results, e.g., lint/tests)
+  - Completion Notes List (what changed, why, how)
+  - File List (all added/modified/deleted files)
+- Change Log (new dated entry describing applied fixes)
+- Status (see Rule below)
+
+Status Rule:
+
+- If gate was PASS and all identified gaps are closed → set `Status: Ready for Done`
+- Otherwise → set `Status: Ready for Review` and notify QA to re-run the review
+
+### 6) Do NOT Edit Gate Files
+
+- Dev does not modify gate YAML. If fixes address issues, request QA to re-run `review-story` to update the gate
+
+## Blocking Conditions
+
+- Missing `bmad-core/core-config.yaml`
+- Story file not found for `story_id`
+- No QA artifacts found (neither gate nor assessments)
+  - HALT and request QA to generate at least a gate file (or proceed only with clear developer-provided fix list)
+
+## Completion Checklist
+
+- deno lint: 0 problems
+- deno test -A: all tests pass
+- All high severity `top_issues` addressed
+- NFR FAIL → resolved; CONCERNS minimized or documented
+- Coverage gaps closed or explicitly documented with rationale
+- Story updated (allowed sections only) including File List and Change Log
+- Status set according to Status Rule
+
+## Example: Story 2.2
+
+Given gate `docs/project/qa/gates/2.2-*.yml` shows
+
+- `coverage_gaps`: Back action behavior untested (AC2)
+- `coverage_gaps`: Centralized dependencies enforcement untested (AC4)
+
+Fix plan:
+
+- Add a test ensuring the Toolkit Menu "Back" action returns to Main Menu
+- Add a static test verifying imports for service/view go through `deps.ts`
+- Re-run lint/tests and update Dev Agent Record + File List accordingly
+
+## Key Principles
+
+- Deterministic, risk-first prioritization
+- Minimal, maintainable changes
+- Tests validate behavior and close gaps
+- Strict adherence to allowed story update areas
+- Gate ownership remains with QA; Dev signals readiness via Status

bmad-core/tasks/nfr-assess.md

@@ -7,11 +7,11 @@ Quick NFR validation focused on the core four: security, performance, reliabilit
 ```yaml
 required:
   - story_id: '{epic}.{story}' # e.g., "1.3"
-  - story_path: 'docs/stories/{epic}.{story}.*.md'
+  - story_path: `bmad-core/core-config.yaml` for the `devStoryLocation`
 
 optional:
-  - architecture_refs: 'docs/architecture/*.md'
+  - architecture_refs: `bmad-core/core-config.yaml` for the `architecture.architectureFile`
-  - technical_preferences: 'docs/technical-preferences.md'
+  - technical_preferences: `bmad-core/core-config.yaml` for the `technicalPreferences`
   - acceptance_criteria: From story file
 ```
 
@@ -20,7 +20,7 @@ optional:
 Assess non-functional requirements for a story and generate:
 
 1. YAML block for the gate file's `nfr_validation` section
-2. Brief markdown assessment saved to `docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md`
+2. Brief markdown assessment saved to `qa.qaLocation/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md`
 
 ## Process
 
@@ -123,7 +123,7 @@ If `technical-preferences.md` defines custom weights, use those instead.
 
 ## Output 2: Brief Assessment Report
 
-**ALWAYS save to:** `docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md`
+**ALWAYS save to:** `qa.qaLocation/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md`
 
 ```markdown
 # NFR Assessment: {epic}.{story}
@@ -162,7 +162,7 @@ Reviewer: Quinn
 **End with this line for the review task to quote:**
 
 ```
-NFR assessment: docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
+NFR assessment: qa.qaLocation/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
 ```
 
 ## Output 4: Gate Integration Line
@@ -170,7 +170,7 @@ NFR assessment: docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
 **Always print at the end:**
 
 ```
-Gate NFR block ready → paste into docs/qa/gates/{epic}.{story}-{slug}.yml under nfr_validation
+Gate NFR block ready → paste into qa.qaLocation/gates/{epic}.{story}-{slug}.yml under nfr_validation
 ```
 
 ## Assessment Criteria

bmad-core/tasks/qa-gate.md

@@ -14,7 +14,7 @@ Generate a standalone quality gate file that provides a clear pass/fail decision
 
 ## Gate File Location
 
-**ALWAYS** create file at: `docs/qa/gates/{epic}.{story}-{slug}.yml`
+**ALWAYS** check the `bmad-core/core-config.yaml` for the `qa.qaLocation/gates`
 
 Slug rules:
 
@@ -124,11 +124,13 @@ waiver:
 
 ## Output Requirements
 
-1. **ALWAYS** create gate file at: `docs/qa/gates/{epic}.{story}-{slug}.yml`
+1. **ALWAYS** create gate file at: `qa.qaLocation/gates` from `bmad-core/core-config.yaml`
 2. **ALWAYS** append this exact format to story's QA Results section:
+
+   ```text
+   Gate: {STATUS} → qa.qaLocation/gates/{epic}.{story}-{slug}.yml
    ```
-   Gate: {STATUS} → docs/qa/gates/{epic}.{story}-{slug}.yml
+
-   ```
 3. Keep status_reason to 1-2 sentences maximum
 4. Use severity values exactly: `low`, `medium`, or `high`
 
@@ -147,7 +149,7 @@ After creating gate file, append to story's QA Results section:
 
 ### Gate Status
 
-Gate: CONCERNS → docs/qa/gates/1.3-user-auth-login.yml
+Gate: CONCERNS → qa.qaLocation/gates/{epic}.{story}-{slug}.yml
 ```
 
 ## Key Principles

bmad-core/tasks/review-story.md

@@ -167,9 +167,9 @@ After review and any refactoring, append your results to the story file in the Q
 
 ### Gate Status
 
-Gate: {STATUS} → docs/qa/gates/{epic}.{story}-{slug}.yml
+Gate: {STATUS} → qa.qaLocation/gates/{epic}.{story}-{slug}.yml
-Risk profile: docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
+Risk profile: qa.qaLocation/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
-NFR assessment: docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
+NFR assessment: qa.qaLocation/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
 
 # Note: Paths should reference core-config.yaml for custom configurations
 
@@ -183,9 +183,9 @@ NFR assessment: docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
 
 **Template and Directory:**
 
-- Render from `templates/qa-gate-tmpl.yaml`
+- Render from `../templates/qa-gate-tmpl.yaml`
-- Create `docs/qa/gates/` directory if missing (or configure in core-config.yaml)
+- Create directory defined in `qa.qaLocation/gates` (see `bmad-core/core-config.yaml`) if missing
-- Save to: `docs/qa/gates/{epic}.{story}-{slug}.yml`
+- Save to: `qa.qaLocation/gates/{epic}.{story}-{slug}.yml`
 
 Gate file structure:
 
@@ -308,7 +308,7 @@ Stop the review and request clarification if:
 After review:
 
 1. Update the QA Results section in the story file
-2. Create the gate file in `docs/qa/gates/`
+2. Create the gate file in directory from `qa.qaLocation/gates`
 3. Recommend status: "Ready for Done" or "Changes Required" (owner decides)
 4. If files were modified, list them in QA Results and ask Dev to update File List
 5. Always provide constructive feedback and actionable recommendations

bmad-core/tasks/risk-profile.md

@@ -105,7 +105,7 @@ Evaluate each risk using probability × impact:
 - `Medium (2)`: Moderate consequences (degraded performance, minor data issues)
 - `Low (1)`: Minor consequences (cosmetic issues, slight inconvenience)
 
-**Risk Score = Probability × Impact**
+### Risk Score = Probability × Impact
 
 - 9: Critical Risk (Red)
 - 6: High Risk (Orange)
@@ -182,7 +182,7 @@ risk_summary:
 
 ### Output 2: Markdown Report
 
-**Save to:** `docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md`
+**Save to:** `qa.qaLocation/assessments/{epic}.{story}-risk-{YYYYMMDD}.md`
 
 ```markdown
 # Risk Profile: Story {epic}.{story}
@@ -290,7 +290,7 @@ Review and update risk profile when:
 
 Calculate overall story risk score:
 
-```
+```text
 Base Score = 100
 For each risk:
   - Critical (9): Deduct 20 points
@@ -339,8 +339,8 @@ Based on risk profile, recommend:
 
 **Print this line for review task to quote:**
 
-```
+```text
-Risk profile: docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
+Risk profile: qa.qaLocation/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
 ```
 
 ## Key Principles

bmad-core/tasks/test-design.md

@@ -84,7 +84,7 @@ Ensure:
 
 ### Output 1: Test Design Document
 
-**Save to:** `docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md`
+**Save to:** `qa.qaLocation/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md`
 
 ```markdown
 # Test Design: Story {epic}.{story}
@@ -150,7 +150,7 @@ test_design:
 Print for use by trace-requirements task:
 
 ```text
-Test design matrix: docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
+Test design matrix: qa.qaLocation/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
 P0 tests identified: {count}
 ```
 

bmad-core/tasks/trace-requirements.md

@@ -95,16 +95,16 @@ trace:
     full: Y
     partial: Z
     none: W
-  planning_ref: 'docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md'
+  planning_ref: 'qa.qaLocation/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md'
   uncovered:
     - ac: 'AC3'
       reason: 'No test found for password reset timing'
-  notes: 'See docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md'
+  notes: 'See qa.qaLocation/assessments/{epic}.{story}-trace-{YYYYMMDD}.md'
 ```
 
 ### Output 2: Traceability Report
 
-**Save to:** `docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md`
+**Save to:** `qa.qaLocation/assessments/{epic}.{story}-trace-{YYYYMMDD}.md`
 
 Create a traceability report with:
 
@@ -250,7 +250,7 @@ This traceability feeds into quality gates:
 **Print this line for review task to quote:**
 
 ```text
-Trace matrix: docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
+Trace matrix: qa.qaLocation/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
 ```
 
 - Full coverage → PASS contribution

bmad-core/templates/qa-gate-tmpl.yaml

@@ -4,7 +4,7 @@ template:
   version: 1.0
   output:
     format: yaml
-    filename: docs/qa/gates/{{epic_num}}.{{story_num}}-{{story_slug}}.yml
+    filename: qa.qaLocation/gates/{{epic_num}}.{{story_num}}-{{story_slug}}.yml
     title: "Quality Gate: {{epic_num}}.{{story_num}}"
 
 # Required fields (keep these first)

docs/versioning-and-releases.md

@@ -1,77 +1,147 @@
-# How to Release a New Version
+# Versioning and Releases
 
-## Automated Releases (Recommended)
+BMad Method uses a simplified release system with manual control and automatic release notes generation.
 
-The easiest way to release new versions is through **automatic semantic releases**. Just commit with the right message format and push and everything else happens automatically.
+## 🚀 Release Workflow
 
-### Commit Message Format
+### Command Line Release (Recommended)
 
-Use these prefixes to control what type of release happens:
+The fastest way to create a release with beautiful release notes:
 
 ```bash
-fix: resolve CLI argument parsing bug      # → patch release (4.1.0 → 4.1.1)
+# Preview what will be in the release
-feat: add new agent orchestration mode     # → minor release (4.1.0 → 4.2.0)
+npm run preview:release
-feat!: redesign CLI interface              # → major release (4.1.0 → 5.0.0)
+
+# Create a release
+npm run release:patch    # 5.1.0 → 5.1.1 (bug fixes)
+npm run release:minor    # 5.1.0 → 5.2.0 (new features)
+npm run release:major    # 5.1.0 → 6.0.0 (breaking changes)
+
+# Watch the release process
+npm run release:watch
 ```
 
-### What Happens Automatically
+### One-Liner Release
-
-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
+npm run preview:release && npm run release:minor && npm run release:watch
-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
+## 📝 What Happens Automatically
 
-These commit types won't create releases (use them for maintenance):
+When you trigger a release, the GitHub Actions workflow automatically:
+
+1. ✅ **Validates** - Runs tests, linting, and formatting checks
+2. ✅ **Bumps Version** - Updates `package.json` and installer version
+3. ✅ **Generates Release Notes** - Categorizes commits since last release:
+   - ✨ **New Features** (`feat:`, `Feature:`)
+   - 🐛 **Bug Fixes** (`fix:`, `Fix:`)
+   - 🔧 **Maintenance** (`chore:`, `Chore:`)
+   - 📦 **Other Changes** (everything else)
+4. ✅ **Creates Git Tag** - Tags the release version
+5. ✅ **Publishes to NPM** - With `@latest` tag for user installations
+6. ✅ **Creates GitHub Release** - With formatted release notes
+
+## 📋 Sample Release Notes
+
+The workflow automatically generates professional release notes like this:
+
+````markdown
+## 🚀 What's New in v5.2.0
+
+### ✨ New Features
+
+- feat: add team collaboration mode
+- feat: enhance CLI with interactive prompts
+
+### 🐛 Bug Fixes
+
+- fix: resolve installation path issues
+- fix: handle edge cases in agent loading
+
+### 🔧 Maintenance
+
+- chore: update dependencies
+- chore: improve error messages
+
+## 📦 Installation
 
 ```bash
-chore: update dependencies     # No release
+npx bmad-method install
-docs: fix typo in readme      # No release
-style: format code            # No release
-test: add unit tests          # No release
 ```
+````
 
-### Test Your Setup
+**Full Changelog**: https://github.com/bmadcode/BMAD-METHOD/compare/v5.1.0...v5.2.0
+
+````
+
+## 🎯 User Installation
+
+After any release, users can immediately get the new version with:
 
 ```bash
-npm run release:test    # Safe to run locally - tests the config
+npx bmad-method install    # Always gets latest release
 ```
 
----
+## 📊 Preview Before Release
 
-## Manual Release Methods (Exceptions Only)
+Always preview what will be included in your release:
-
-⚠️ 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 preview:release
-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
+This shows:
 
-You can also trigger releases manually through GitHub Actions workflow dispatch if needed.
+- Commits since last release
+- Categorized changes
+- Estimated next version
+- Release notes preview
+
+## 🔧 Manual Release (GitHub UI)
+
+You can also trigger releases through GitHub Actions:
+
+1. Go to **GitHub Actions** → **Manual Release**
+2. Click **"Run workflow"**
+3. Choose version bump type (patch/minor/major)
+4. Everything else happens automatically
+
+## 📈 Version Strategy
+
+- **Patch** (5.1.0 → 5.1.1): Bug fixes, minor improvements
+- **Minor** (5.1.0 → 5.2.0): New features, enhancements
+- **Major** (5.1.0 → 6.0.0): Breaking changes, major redesigns
+
+## 🛠️ Development Workflow
+
+1. **Develop Freely** - Merge PRs to main without triggering releases
+2. **Test Unreleased Changes** - Clone repo to test latest main branch
+3. **Release When Ready** - Use command line or GitHub Actions to cut releases
+4. **Users Get Updates** - Via simple `npx bmad-method install` command
+
+This gives you complete control over when releases happen while automating all the tedious parts like version bumping, release notes, and publishing.
+
+## 🔍 Troubleshooting
+
+### Check Release Status
+
+```bash
+gh run list --workflow="Manual Release"
+npm view bmad-method dist-tags
+git tag -l | sort -V | tail -5
+```
+
+### View Latest Release
+
+```bash
+gh release view --web
+npm view bmad-method versions --json
+```
+
+### If Release Fails
+
+- Check GitHub Actions logs: `gh run view <run-id> --log-failed`
+- Verify NPM tokens are configured
+- Ensure branch protection allows workflow pushes
+````

package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "5.0.0",
+  "version": "5.1.3",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -35,8 +35,11 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "list:agents": "node tools/cli.js list:agents",
     "prepare": "husky",
-    "release": "semantic-release",
+    "preview:release": "node tools/preview-release-notes.js",
-    "release:test": "semantic-release --dry-run --no-ci || echo 'Config test complete - authentication errors are expected locally'",
+    "release:major": "gh workflow run \"Manual Release\" -f version_bump=major",
+    "release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
+    "release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
+    "release:watch": "gh run watch",
     "validate": "node tools/cli.js validate",
     "version:all": "node tools/bump-all-versions.js",
     "version:all:major": "node tools/bump-all-versions.js major",
@@ -80,8 +83,6 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.33.0",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
     "eslint": "^9.33.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-n": "^17.21.3",
@@ -92,11 +93,13 @@
     "lint-staged": "^16.1.1",
     "prettier": "^3.5.3",
     "prettier-plugin-packagejson": "^2.5.19",
-    "semantic-release": "^22.0.0",
     "yaml-eslint-parser": "^1.2.3",
     "yaml-lint": "^1.7.0"
   },
   "engines": {
     "node": ">=20.10.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

tools/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "5.0.0",
+  "version": "5.1.3",
   "description": "BMad Method installer - AI-powered Agile development framework",
   "keywords": [
     "bmad",

tools/preview-release-notes.js

@@ -0,0 +1,66 @@
+const { execSync } = require('node:child_process');
+const fs = require('node:fs');
+
+// Get the latest stable tag (exclude beta tags)
+const allTags = execSync('git tag -l | sort -V', { encoding: 'utf8' }).split('\n').filter(Boolean);
+const stableTags = allTags.filter((tag) => !tag.includes('beta'));
+const latestTag = stableTags.at(-1) || 'v5.0.0';
+
+// Get commits since last tag
+const commits = execSync(`git log ${latestTag}..HEAD --pretty=format:"- %s" --reverse`, {
+  encoding: 'utf8',
+})
+  .split('\n')
+  .filter(Boolean);
+
+// Categorize commits
+const features = commits.filter((commit) => /^- (feat|Feature)/.test(commit));
+const fixes = commits.filter((commit) => /^- (fix|Fix)/.test(commit));
+const chores = commits.filter((commit) => /^- (chore|Chore)/.test(commit));
+const others = commits.filter(
+  (commit) => !/^- (feat|Feature|fix|Fix|chore|Chore|release:|Release:)/.test(commit),
+);
+
+// Get next version (you can modify this logic)
+const currentVersion = require('../package.json').version;
+const versionParts = currentVersion.split('.').map(Number);
+const nextVersion = `${versionParts[0]}.${versionParts[1] + 1}.0`; // Default to minor bump
+
+console.log(`## 🚀 What's New in v${nextVersion}\n`);
+
+if (features.length > 0) {
+  console.log('### ✨ New Features');
+  for (const feature of features) console.log(feature);
+  console.log('');
+}
+
+if (fixes.length > 0) {
+  console.log('### 🐛 Bug Fixes');
+  for (const fix of fixes) console.log(fix);
+  console.log('');
+}
+
+if (others.length > 0) {
+  console.log('### 📦 Other Changes');
+  for (const other of others) console.log(other);
+  console.log('');
+}
+
+if (chores.length > 0) {
+  console.log('### 🔧 Maintenance');
+  for (const chore of chores) console.log(chore);
+  console.log('');
+}
+
+console.log('\n## 📦 Installation\n');
+console.log('```bash');
+console.log('npx bmad-method install');
+console.log('```');
+
+console.log(
+  `\n**Full Changelog**: https://github.com/bmadcode/BMAD-METHOD/compare/${latestTag}...v${nextVersion}`,
+);
+
+console.log(`\n---\n📊 **Summary**: ${commits.length} commits since ${latestTag}`);
+console.log(`🏷️ **Previous tag**: ${latestTag}`);
+console.log(`🚀 **Next version**: v${nextVersion} (estimated)`);

tools/semantic-release-sync-installer.js

@@ -1,30 +0,0 @@
-/**
- * Semantic-release plugin to sync installer package.json version
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-// This function runs during the "prepare" step of semantic-release
-function prepare(_, { nextRelease, logger }) {
-  // Define the path to the installer package.json file
-  const file = path.join(process.cwd(), 'tools/installer/package.json');
-
-  // If the file does not exist, skip syncing and log a message
-  if (!fs.existsSync(file)) return logger.log('Installer package.json not found, skipping');
-
-  // Read and parse the package.json file
-  const package_ = JSON.parse(fs.readFileSync(file, 'utf8'));
-
-  // Update the version field with the next release version
-  package_.version = nextRelease.version;
-
-  // Write the updated JSON back to the file
-  fs.writeFileSync(file, JSON.stringify(package_, null, 2) + '\n');
-
-  // Log success message
-  logger.log(`Synced installer package.json to version ${nextRelease.version}`);
-}
-
-// Export the prepare function so semantic-release can use it
-module.exports = { prepare };

tools/version-bump.js

@@ -31,18 +31,35 @@ async function bumpVersion(type = 'patch') {
     process.exit(1);
   }
 
-  console.log(chalk.yellow('⚠️  Manual version bumping is disabled.'));
+  const currentVersion = getCurrentVersion();
-  console.log(chalk.blue('🤖 This project uses semantic-release for automated versioning.'));
+  const versionParts = currentVersion.split('.').map(Number);
-  console.log('');
+  let newVersion;
-  console.log(chalk.bold('To create a new release, use conventional commits:'));
-  console.log(chalk.cyan('  feat: new feature (minor version bump)'));
-  console.log(chalk.cyan('  fix: bug fix (patch version bump)'));
-  console.log(chalk.cyan('  feat!: breaking change (major version bump)'));
-  console.log('');
-  console.log(chalk.dim('Example: git commit -m "feat: add new installer features"'));
-  console.log(chalk.dim('Then push to main branch to trigger automatic release.'));
 
-  return null;
+  switch (type) {
+    case 'major': {
+      newVersion = `${versionParts[0] + 1}.0.0`;
+      break;
+    }
+    case 'minor': {
+      newVersion = `${versionParts[0]}.${versionParts[1] + 1}.0`;
+      break;
+    }
+    case 'patch': {
+      newVersion = `${versionParts[0]}.${versionParts[1]}.${versionParts[2] + 1}`;
+      break;
+    }
+  }
+
+  console.log(chalk.blue(`Bumping version: ${currentVersion} → ${newVersion}`));
+
+  // Update package.json
+  const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+  packageJson.version = newVersion;
+  fs.writeFileSync('package.json', JSON.stringify(packageJson, null, 2) + '\n');
+
+  console.log(chalk.green(`✓ Updated package.json to ${newVersion}`));
+
+  return newVersion;
 }
 
 async function main() {