Update src/modules/bmm/_module-installer/install-config.yaml

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Update README.md
2026-01-30 04:32:02 +00:00 · 2025-11-20 15:26:58 -06:00 · 2025-11-20 15:26:50 -06:00 · 2025-11-20 14:04:19 -06:00 · 2025-11-20 14:04:03 -06:00 · 2025-11-20 14:04:03 -06:00
744 changed files with 102592 additions and 25604 deletions
--- a/.github/ISSUE_TEMPLATE/config.yaml
+++ b/.github/ISSUE_TEMPLATE/config.yaml
@@ -1 +1,5 @@
 blank_issues_enabled: false
+contact_links:
+  - name: Discord Community Support
+    url: https://discord.gg/gk8jAdXWmj
+    about: Please join our Discord server for general questions and community discussion before opening an issue.
--- a/.github/ISSUE_TEMPLATE/idea_submission.md
+++ b/.github/ISSUE_TEMPLATE/idea_submission.md
@@ -1,6 +1,6 @@
 ---
-name: V5 Idea Submission
-about: Suggest an idea for v5
+name: V6 Idea Submission
+about: Suggest an idea for v6
 title: ''
 labels: ''
 assignees: ''
@@ -92,7 +92,7 @@ Fix issues and add features.

 _Why this is poor: Too vague, no specific problem identified, no measurable success criteria, unclear scope_

-</details>****
+</details>

 ---

--- a/.github/workflows/bundle-latest.yaml
+++ b/.github/workflows/bundle-latest.yaml
@@ -0,0 +1,329 @@
+name: Publish Latest Bundles
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+
+jobs:
+  bundle-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout BMAD-METHOD
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate bundles
+        run: npm run bundle
+
+      - name: Create bundle distribution structure
+        run: |
+          mkdir -p dist/bundles
+
+          # Copy web bundles (XML files from npm run bundle output)
+          cp -r web-bundles/* dist/bundles/ 2>/dev/null || true
+
+          # Verify bundles were copied (fail if completely empty)
+          if [ ! "$(ls -A dist/bundles)" ]; then
+            echo "❌ ERROR: No bundles found in dist/bundles/"
+            echo "This likely means 'npm run bundle' failed or bundles weren't generated"
+            exit 1
+          fi
+
+          # Count bundles per module
+          for module in bmm bmb cis bmgd; do
+            if [ -d "dist/bundles/$module/agents" ]; then
+              COUNT=$(find dist/bundles/$module/agents -name '*.xml' 2>/dev/null | wc -l)
+              echo "✅ $module: $COUNT agent bundles"
+            fi
+          done
+
+          # Generate index.html for each agents directory (fixes directory browsing)
+          for module in bmm bmb cis bmgd; do
+            if [ -d "dist/bundles/$module/agents" ]; then
+              cat > "dist/bundles/$module/agents/index.html" << 'DIREOF'
+          <!DOCTYPE html>
+          <html>
+          <head>
+            <title>MODULE_NAME Agents</title>
+            <style>
+              body { font-family: system-ui; max-width: 800px; margin: 50px auto; padding: 20px; }
+              li { margin: 10px 0; }
+              a { color: #0066cc; text-decoration: none; }
+              a:hover { text-decoration: underline; }
+            </style>
+          </head>
+          <body>
+            <h1>MODULE_NAME Agents</h1>
+            <ul>
+          AGENT_LINKS
+            </ul>
+            <p><a href="../../">← Back to all modules</a></p>
+          </body>
+          </html>
+          DIREOF
+
+              # Replace MODULE_NAME
+              sed -i "s/MODULE_NAME/${module^^}/g" "dist/bundles/$module/agents/index.html"
+
+              # Generate agent links
+              LINKS=""
+              for file in dist/bundles/$module/agents/*.xml; do
+                if [ -f "$file" ]; then
+                  name=$(basename "$file" .xml)
+                  LINKS="$LINKS      <li><a href=\"./$name.xml\">$name</a></li>\n"
+                fi
+              done
+              sed -i "s|AGENT_LINKS|$LINKS|" "dist/bundles/$module/agents/index.html"
+            fi
+          done
+
+          # Create zip archives per module
+          mkdir -p dist/bundles/downloads
+          for module in bmm bmb cis bmgd; do
+            if [ -d "dist/bundles/$module" ]; then
+              (cd dist/bundles && zip -r downloads/$module-agents.zip $module/)
+              echo "✅ Created $module-agents.zip"
+            fi
+          done
+
+          # Generate index.html dynamically based on actual bundles
+          TIMESTAMP=$(date -u +"%Y-%m-%d %H:%M UTC")
+          COMMIT_SHA=$(git rev-parse --short HEAD)
+
+          # Function to generate agent links for a module
+          generate_agent_links() {
+            local module=$1
+            local agent_dir="dist/bundles/$module/agents"
+
+            if [ ! -d "$agent_dir" ]; then
+              echo ""
+              return
+            fi
+
+            local links=""
+            local count=0
+
+            # Find all XML files and generate links
+            for xml_file in "$agent_dir"/*.xml; do
+              if [ -f "$xml_file" ]; then
+                local agent_name=$(basename "$xml_file" .xml)
+                # Convert filename to display name (pm -> PM, tech-writer -> Tech Writer)
+                local display_name=$(echo "$agent_name" | sed 's/-/ /g' | awk '{for(i=1;i<=NF;i++) {if(length($i)==2) $i=toupper($i); else $i=toupper(substr($i,1,1)) tolower(substr($i,2));}}1')
+
+                if [ $count -gt 0 ]; then
+                  links="$links | "
+                fi
+                links="$links<a href=\"./$module/agents/$agent_name.xml\">$display_name</a>"
+                count=$((count + 1))
+              fi
+            done
+
+            echo "$links"
+          }
+
+          # Generate agent links for each module
+          BMM_LINKS=$(generate_agent_links "bmm")
+          CIS_LINKS=$(generate_agent_links "cis")
+          BMGD_LINKS=$(generate_agent_links "bmgd")
+
+          # Count agents for bulk downloads
+          BMM_COUNT=$(find dist/bundles/bmm/agents -name '*.xml' 2>/dev/null | wc -l | tr -d ' ')
+          CIS_COUNT=$(find dist/bundles/cis/agents -name '*.xml' 2>/dev/null | wc -l | tr -d ' ')
+          BMGD_COUNT=$(find dist/bundles/bmgd/agents -name '*.xml' 2>/dev/null | wc -l | tr -d ' ')
+
+          # Create index.html
+          cat > dist/bundles/index.html << EOF
+          <!DOCTYPE html>
+          <html>
+          <head>
+            <title>BMAD Bundles - Latest</title>
+            <meta charset="utf-8">
+            <style>
+              body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; max-width: 800px; margin: 50px auto; padding: 20px; }
+              h1 { color: #333; }
+              .platform { margin: 30px 0; padding: 20px; background: #f5f5f5; border-radius: 8px; }
+              .module { margin: 15px 0; }
+              a { color: #0066cc; text-decoration: none; }
+              a:hover { text-decoration: underline; }
+              code { background: #e0e0e0; padding: 2px 6px; border-radius: 3px; }
+              .warning { background: #fff3cd; padding: 15px; border-left: 4px solid #ffc107; margin: 20px 0; }
+            </style>
+          </head>
+          <body>
+            <h1>BMAD Web Bundles - Latest (Main Branch)</h1>
+
+            <div class="warning">
+              <strong>⚠️ Latest Build (Unstable)</strong><br>
+              These bundles are built from the latest main branch commit. For stable releases, visit
+              <a href="https://github.com/bmad-code-org/BMAD-METHOD/releases/latest">GitHub Releases</a>.
+            </div>
+
+            <p><strong>Last Updated:</strong> <code>$TIMESTAMP</code></p>
+            <p><strong>Commit:</strong> <code>$COMMIT_SHA</code></p>
+
+            <h2>Available Modules</h2>
+
+          EOF
+
+          # Add BMM section if agents exist
+          if [ -n "$BMM_LINKS" ]; then
+            cat >> dist/bundles/index.html << EOF
+            <div class="platform">
+              <h3>BMM (BMad Method)</h3>
+              <div class="module">
+                $BMM_LINKS<br>
+                📁 <a href="./bmm/agents/">Browse All</a> | 📦 <a href="./downloads/bmm-agents.zip">Download Zip</a>
+              </div>
+            </div>
+
+          EOF
+          fi
+
+          # Add CIS section if agents exist
+          if [ -n "$CIS_LINKS" ]; then
+            cat >> dist/bundles/index.html << EOF
+            <div class="platform">
+              <h3>CIS (Creative Intelligence Suite)</h3>
+              <div class="module">
+                $CIS_LINKS<br>
+                📁 <a href="./cis/agents/">Browse Agents</a> | 📦 <a href="./downloads/cis-agents.zip">Download Zip</a>
+              </div>
+            </div>
+
+          EOF
+          fi
+
+          # Add BMGD section if agents exist
+          if [ -n "$BMGD_LINKS" ]; then
+            cat >> dist/bundles/index.html << EOF
+            <div class="platform">
+              <h3>BMGD (Game Development)</h3>
+              <div class="module">
+                $BMGD_LINKS<br>
+                📁 <a href="./bmgd/agents/">Browse Agents</a> | 📦 <a href="./downloads/bmgd-agents.zip">Download Zip</a>
+              </div>
+            </div>
+
+          EOF
+          fi
+
+          # Add bulk downloads section
+          cat >> dist/bundles/index.html << EOF
+            <h2>Bulk Downloads</h2>
+            <p>Download all agents for a module as a zip archive:</p>
+            <ul>
+          EOF
+
+          [ "$BMM_COUNT" -gt 0 ] && echo "              <li><a href=\"./downloads/bmm-agents.zip\">📦 BMM Agents (all $BMM_COUNT)</a></li>" >> dist/bundles/index.html
+          [ "$CIS_COUNT" -gt 0 ] && echo "              <li><a href=\"./downloads/cis-agents.zip\">📦 CIS Agents (all $CIS_COUNT)</a></li>" >> dist/bundles/index.html
+          [ "$BMGD_COUNT" -gt 0 ] && echo "              <li><a href=\"./downloads/bmgd-agents.zip\">📦 BMGD Agents (all $BMGD_COUNT)</a></li>" >> dist/bundles/index.html
+
+          # Close HTML
+          cat >> dist/bundles/index.html << 'EOF'
+            </ul>
+
+            <h2>Usage</h2>
+            <p>Copy the raw XML URL and paste into your AI platform's custom instructions or project knowledge.</p>
+            <p>Example: <code>https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/bmm/agents/pm.xml</code></p>
+
+            <h2>Installation (Recommended)</h2>
+            <p>For full IDE integration with slash commands, use the installer:</p>
+            <pre>npx bmad-method@alpha install</pre>
+
+            <footer style="margin-top: 50px; padding-top: 20px; border-top: 1px solid #ccc; color: #666;">
+              <p>Built from <a href="https://github.com/bmad-code-org/BMAD-METHOD">BMAD-METHOD</a> repository.</p>
+            </footer>
+          </body>
+          </html>
+          EOF
+
+      - name: Checkout bmad-bundles repo
+        uses: actions/checkout@v4
+        with:
+          repository: bmad-code-org/bmad-bundles
+          path: bmad-bundles
+          token: ${{ secrets.BUNDLES_PAT }}
+
+      - name: Update bundles
+        run: |
+          # Clear old bundles
+          rm -rf bmad-bundles/*
+
+          # Copy new bundles
+          cp -r dist/bundles/* bmad-bundles/
+
+          # Create .nojekyll for GitHub Pages
+          touch bmad-bundles/.nojekyll
+
+          # Create README
+          cat > bmad-bundles/README.md << 'EOF'
+          # BMAD Web Bundles (Latest)
+
+          **⚠️ Unstable Build**: These bundles are auto-generated from the latest `main` branch.
+
+          For stable releases, visit [GitHub Releases](https://github.com/bmad-code-org/BMAD-METHOD/releases/latest).
+
+          ## Usage
+
+          Copy raw markdown URLs for use in AI platforms:
+
+          - Claude Code: `https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/claude-code/sub-agents/{agent}.md`
+          - ChatGPT: `https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/chatgpt/sub-agents/{agent}.md`
+          - Gemini: `https://raw.githubusercontent.com/bmad-code-org/bmad-bundles/main/gemini/sub-agents/{agent}.md`
+
+          ## Browse
+
+          Visit [https://bmad-code-org.github.io/bmad-bundles/](https://bmad-code-org.github.io/bmad-bundles/) to browse bundles.
+
+          ## Installation (Recommended)
+
+          For full IDE integration:
+          ```bash
+          npx bmad-method@alpha install
+          ```
+
+          ---
+
+          Auto-updated by [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) on every main branch merge.
+          EOF
+
+      - name: Commit and push to bmad-bundles
+        run: |
+          cd bmad-bundles
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          git add .
+
+          if git diff --staged --quiet; then
+            echo "No changes to bundles, skipping commit"
+          else
+            COMMIT_SHA=$(cd .. && git rev-parse --short HEAD)
+            git commit -m "Update bundles from BMAD-METHOD@${COMMIT_SHA}"
+            git push
+            echo "✅ Bundles published to GitHub Pages"
+          fi
+
+      - name: Summary
+        run: |
+          echo "## 🎉 Bundles Published!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Latest bundles** available at:" >> $GITHUB_STEP_SUMMARY
+          echo "- 🌐 Browse: https://bmad-code-org.github.io/bmad-bundles/" >> $GITHUB_STEP_SUMMARY
+          echo "- 📦 Raw files: https://github.com/bmad-code-org/bmad-bundles" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Commit**: ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY
--- a/.github/workflows/format-check.yaml
+++ b/.github/workflows/format-check.yaml
@@ -1,43 +0,0 @@
-name: format-check
-
-"on":
-  pull_request:
-    branches: ["**"]
-  workflow_dispatch:
-
-jobs:
-  prettier:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version-file: ".nvmrc"
-          cache: "npm"
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Prettier format check
-        run: npm run format:check
-
-  eslint:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version-file: ".nvmrc"
-          cache: "npm"
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: ESLint
-        run: npm run lint
--- a/.github/workflows/manual-release.yaml
+++ b/.github/workflows/manual-release.yaml
@@ -61,8 +61,34 @@ jobs:
        run: |
          sed -i 's/"version": ".*"/"version": "${{ steps.version.outputs.new_version }}"/' tools/installer/package.json

-      - name: Build project
-        run: npm run build
+      - name: Generate web bundles
+        run: npm run bundle
+
+      - name: Package bundles for release
+        run: |
+          mkdir -p dist/release-bundles
+
+          # Copy web bundles
+          cp -r web-bundles dist/release-bundles/bmad-bundles-v${{ steps.version.outputs.new_version }}
+
+          # Verify bundles exist
+          if [ ! "$(ls -A dist/release-bundles/bmad-bundles-v${{ steps.version.outputs.new_version }})" ]; then
+            echo "❌ ERROR: No bundles found"
+            echo "This likely means 'npm run bundle' failed"
+            exit 1
+          fi
+
+          # Count and display bundles per module
+          for module in bmm bmb cis bmgd; do
+            if [ -d "dist/release-bundles/bmad-bundles-v${{ steps.version.outputs.new_version }}/$module/agents" ]; then
+              COUNT=$(find dist/release-bundles/bmad-bundles-v${{ steps.version.outputs.new_version }}/$module/agents -name '*.xml' 2>/dev/null | wc -l)
+              echo "✅ $module: $COUNT agents"
+            fi
+          done
+
+          # Create archive
+          tar -czf dist/release-bundles/bmad-bundles-v${{ steps.version.outputs.new_version }}.tar.gz \
+            -C dist/release-bundles/bmad-bundles-v${{ steps.version.outputs.new_version }} .

      - name: Commit version bump
        run: |
@@ -149,25 +175,46 @@ jobs:
      - name: Publish to NPM
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npm publish
+        run: |
+          VERSION="${{ steps.version.outputs.new_version }}"
+          if [[ "$VERSION" == *"alpha"* ]] || [[ "$VERSION" == *"beta"* ]]; then
+            echo "Publishing prerelease version with --tag alpha"
+            npm publish --tag alpha
+          else
+            echo "Publishing stable version with --tag latest"
+            npm publish --tag latest
+          fi

-      - name: Create GitHub Release
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Create GitHub Release with Bundles
+        uses: softprops/action-gh-release@v2
        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 }}
+          name: "BMad Method v${{ steps.version.outputs.new_version }}"
+          body: |
+            ${{ steps.release_notes.outputs.RELEASE_NOTES }}
+
+            ## 📦 Web Bundles
+
+            Download XML bundles for use in AI platforms (Claude Projects, ChatGPT, Gemini):
+
+            - `bmad-bundles-v${{ steps.version.outputs.new_version }}.tar.gz` - All modules (BMM, BMB, CIS, BMGD)
+
+            **Browse online** (bleeding edge): https://bmad-code-org.github.io/bmad-bundles/
          draft: false
-          prerelease: false
+          prerelease: ${{ contains(steps.version.outputs.new_version, 'alpha') || contains(steps.version.outputs.new_version, 'beta') }}
+          files: |
+            dist/release-bundles/*.tar.gz

      - 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
+          echo "## 🎉 Successfully released v${{ steps.version.outputs.new_version }}!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 📦 Distribution" >> $GITHUB_STEP_SUMMARY
+          echo "- **NPM**: Published with @latest tag" >> $GITHUB_STEP_SUMMARY
+          echo "- **GitHub Release**: https://github.com/bmad-code-org/BMAD-METHOD/releases/tag/v${{ steps.version.outputs.new_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Web Bundles**: Attached to GitHub Release (4 archives)" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### ✅ Installation" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "npx bmad-method@${{ steps.version.outputs.new_version }} install" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
--- a/.github/workflows/quality.yaml
+++ b/.github/workflows/quality.yaml
@@ -0,0 +1,78 @@
+name: Quality & Validation
+
+# Runs comprehensive quality checks on all PRs:
+# - Prettier (formatting)
+# - ESLint (linting)
+# - Schema validation (YAML structure)
+# - Agent schema tests (fixture-based validation)
+# - Installation component tests (compilation)
+# - Bundle validation (web bundle integrity)
+
+"on":
+  pull_request:
+    branches: ["**"]
+  workflow_dispatch:
+
+jobs:
+  prettier:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Prettier format check
+        run: npm run format:check
+
+  eslint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: ESLint
+        run: npm run lint
+
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate YAML schemas
+        run: npm run validate:schemas
+
+      - name: Run agent schema validation tests
+        run: npm run test:schemas
+
+      - name: Test agent compilation components
+        run: npm run test:install
+
+      - name: Validate web bundles
+        run: npm run validate:bundles
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,10 @@ deno.lock
 pnpm-workspace.yaml
 package-lock.json

+
+test-output/*
+coverage/
+
 # Logs
 logs/
 *.log
@@ -22,7 +26,6 @@ build/*.txt
 Thumbs.db

 # Development tools and configs
-.prettierignore
 .prettierrc

 # IDE and editor configs
@@ -33,12 +36,12 @@ Thumbs.db
 # AI assistant files
 CLAUDE.md
 .ai/*
-.claude
 cursor
 .gemini
 .mcp.json
 CLAUDE.local.md
 .serena/
+.claude/settings.local.json

 # Project-specific
 .bmad-core
@@ -51,9 +54,17 @@ flattened-codebase.xml
 #UAT template testing output files
 tools/template-test-generator/test-scenarios/

-# Bundler temporary files
+# Bundler temporary files and generated bundles
 .bundler-temp/

-# Test Install Output
+# Generated web bundles (built by CI, not committed)
+src/modules/bmm/sub-modules/
+src/modules/bmb/sub-modules/
+src/modules/cis/sub-modules/
+src/modules/bmgd/sub-modules/

 z*/
+
+.bmad
+.claude
+.codex
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1,3 +1,7 @@
 #!/usr/bin/env sh

+# Auto-fix changed files and stage them
 npx --no-install lint-staged
+
+# Validate everything
+npm test
--- a/.prettierignore
+++ b/.prettierignore
@@ -0,0 +1,6 @@
+# Test fixtures with intentionally broken/malformed files
+test/fixtures/**
+
+# BMAD runtime folders (user-specific, not in repo)
+.bmad/
+.bmad*/
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -21,6 +21,7 @@
    "Decisioning",
    "eksctl",
    "elicitations",
+    "Excalidraw",
    "filecomplete",
    "fintech",
    "fluxcd",
@@ -56,7 +57,8 @@
    "tileset",
    "tmpl",
    "Trae",
-    "VNET"
+    "VNET",
+    "webskip"
  ],
  "json.schemas": [
    {
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,21 +1,354 @@
 # Changelog

+## [Unreleased]
+
+### Added
+
+- **Playwright Utils Integration**: Test Architect now supports `@seontechnologies/playwright-utils` integration
+  - Installation prompt with `use_playwright_utils` configuration flag (mirrors tea_use_mcp_enhancements pattern)
+  - 11 comprehensive knowledge fragments covering ALL utilities: overview, api-request, network-recorder, auth-session, intercept-network-call, recurse, log, file-utils, burn-in, network-error-monitor, fixtures-composition
+  - Adaptive workflow recommendations in 6 workflows: automate (CRITICAL), framework, test-review, ci, atdd, test-design (light mention)
+  - 32 total knowledge fragments (21 core patterns + 11 playwright-utils)
+  - Context-aware fragment loading preserves existing behavior when flag is false
+  - Production-ready utilities from SEON Technologies now integrated with TEA's proven testing patterns
+
+## [6.0.0-alpha.12]
+
+**Release: November 19, 2025**
+
+### 🐛 Bug Fixes
+
+- Added missing `yaml` dependency to fix `MODULE_NOT_FOUND` error when running `npx bmad-method install`
+
+## [6.0.0-alpha.11]
+
+**Release: November 18, 2025**
+
+This alpha release introduces a complete agent installation system with the new `bmad agent-install` command, vastly improves the BMB agent builder capabilities with comprehensive documentation and reference agents, and refines diagram distribution to better align with BMad Method's core principle: **BMad agents mirror real agile teams**.
+
+### 🎨 Diagram Capabilities Refined and Distributed
+
+**Excalidraw Integration Evolution:**
+
+Building on the excellent Excalidraw integration introduced with the Frame Expert agent, we've refined how diagram capabilities are distributed across the BMad Method ecosystem to better reflect real agile team dynamics.
+
+**The Refinement:**
+
+- The valuable Excalidraw diagramming capabilities have been distributed to the agents who naturally create these artifacts in real teams
+- **Architect**: System architecture diagrams, data flow visualizations
+- **Product Manager**: Process flowcharts and workflow diagrams
+- **UX Designer**: Wireframe creation capabilities
+- **Tech Writer**: All diagram types for documentation needs
+- **New CIS Agent**: presentation-master for specialized visual communication
+
+**Shared Infrastructure Enhancement:**
+
+- Excalidraw templates, component libraries, and validation patterns elevated to core resources
+- Available to both BMM agents AND CIS presentation specialists
+- Preserves all the excellent Excalidraw functionality while aligning with natural team roles
+
+### 🚀 New Agent Installation System
+
+**Agent Installation Infrastructure (NEW in alpha.11):**
+
+- `bmad agent-install` CLI command with interactive persona customization
+- **YAML → XML compilation engine** with smart handler injection
+- Supports Simple (single file), Expert (with sidecars), and Module agents
+- Handlebars-style template variable processing
+- Automatic manifest tracking and IDE integration
+- Source preservation in `_cfg/custom/agents/` for reinstallation
+
+**New Reference Agents Added:**
+
+- **commit-poet**: Poetic git commit message generator (Simple agent example)
+- **journal-keeper**: Daily journaling agent with templates (Expert agent example)
+- **security-engineer & trend-analyst**: Module agent examples with ecosystem integration
+
+**Critical Persona Field Guidance Added:**
+
+New documentation explaining how LLMs interpret persona fields for better agent quality:
+
+- **role** → "What knowledge, skills, and capabilities do I possess?"
+- **identity** → "What background, experience, and context shape my responses?"
+- **communication_style** → "What verbal patterns, word choice, and phrasing do I use?"
+- **principles** → "What beliefs and operating philosophy drive my choices?"
+
+Key insight: `communication_style` should ONLY describe HOW the agent talks, not WHAT they do
+
+**BMM Agent Voice Enhancement:**
+
+All 9 existing BMM agents enhanced with distinct, memorable communication voices:
+
+- **Mary (analyst)**: "Treats analysis like a treasure hunt - excited by every clue"
+- **John (PM)**: "Asks 'WHY?' relentlessly like a detective on a case"
+- **Winston (architect)**: "Champions boring technology that actually works"
+- **Amelia (dev)**: "Ultra-succinct. Speaks in file paths and AC IDs"
+- **Sally (UX)**: "Paints pictures with words, telling user stories that make you FEEL"
+
+### 🔧 Edit-Agent Workflow Comprehensive Enhancement
+
+**Expert Agent Sidecar Support (NEW):**
+
+- Automatically detects and handles Expert agents with multiple files
+- Loads and manages templates, data files, knowledge bases
+- Smart sidecar analysis: maps references, finds orphans, validates paths
+- 5 complete sidecar editing patterns with warm, educational feedback
+
+**7-Step Communication Style Refinement Pattern:**
+
+1. Diagnose current style with red flag word detection
+2. Extract non-style content to working copy
+3. Discover TRUE communication style through interview questions
+4. Craft pure style using presets and reference agents
+5. Show before/after transformation with full context
+6. Validate against standards (zero red flags)
+7. Confirm with user through dramatic reading
+
+**Unified Validation Checklist:**
+
+- Single source of truth: `agent-validation-checklist.md` (160 lines)
+- Shared between create-agent and edit-agent workflows
+- Comprehensive persona field separation validation
+- Expert agent sidecar validation (9 specific checks)
+- Common issues and fixes with real examples
+
+### 📚 BMB Agent Builder Enhancement
+
+**Vastly Improved Agent Creation & Editing Capabilities:**
+
+- Create-agent and edit-agent workflows now have accurate, comprehensive documentation
+- All context references updated and validated for consistency
+- Workflows can now properly guide users through complex agent design decisions
+
+**New Agent Documentation Suite:**
+
+- `understanding-agent-types.md` - Architecture vs capability distinction
+- `simple-agent-architecture.md` - Self-contained agents guide
+- `expert-agent-architecture.md` - Agents with sidecar files
+- `module-agent-architecture.md` - Workflow-integrated agents
+- `agent-compilation.md` - YAML → XML transformation process
+- `agent-menu-patterns.md` - Menu design patterns
+- `communication-presets.csv` - 60 pure communication styles for reference
+
+**New Reference Agents for Learning:**
+
+- Complete working examples of Simple, Expert, and Module agents
+- Can be installed directly via the new `bmad agent-install` command
+- Serve as both learning resources and ready-to-use agents
+
+### 🎯 Epic Creation Moved to Phase 3 (After Architecture)
+
+**Workflow Sequence Corrected:**
+
+```
+Phase 2: PRD → UX Design
+Phase 3: Architecture → Epics & Stories ← NOW HERE (technically informed)
+```
+
+**Why This Fundamental Change:**
+
+- Epics need architectural context: API contracts, data models, technical decisions
+- Stories can reference actual architectural patterns and constraints
+- Reduces rewrites when architecture reveals complexity
+- Better complexity-based estimation (not time-based)
+
+### 🖥️ New IDE Support
+
+**Google Antigravity IDE Installer:**
+
+- Flattened file naming for proper slash commands (bmad-module-agents-name.md)
+- Namespace isolation prevents module conflicts
+- Subagent installation support (project or user level)
+- Module-specific injection configuration
+
+**Codex CLI Enhancement:**
+
+- Now supports both global and project-specific installation
+- CODEX_HOME configuration for multi-project workflows
+- OS-specific setup instructions (Unix/Mac/Windows)
+
+### 🏗️ Reference Agents & Standards
+
+**New Reference Agents Provide Clear Examples:**
+
+- **commit-poet.agent.yaml**: Simple agent with pure communication style
+- **journal-keeper.agent.yaml**: Expert agent with sidecar file structure
+- **security-engineer.agent.yaml**: Module agent for ecosystem integration
+- **trend-analyst.agent.yaml**: Module agent with cross-workflow capabilities
+
+**Agent Type Clarification:**
+
+- Clear documentation that agent types (Simple/Expert/Module) describe architecture, not capability
+- Module = designed for ecosystem integration, not limited in function
+
+### 🐛 Technical Improvements
+
+**Linting Compliance:**
+
+- Fixed all ESLint warnings across agent tooling
+- `'utf-8'` → `'utf8'` (unicorn/text-encoding-identifier-case)
+- `hasOwnProperty` → `Object.hasOwn` (unicorn/prefer-object-has-own)
+- `JSON.parse(JSON.stringify(...))` → `structuredClone(...)`
+
+**Agent Compilation Engine:**
+
+- Auto-injects frontmatter, activation, handlers, help/exit menu items
+- Smart handler inclusion (only includes handlers actually used)
+- Proper XML escaping and formatting
+- Persona name customization support
+
+### 📊 Impact Summary
+
+**New in alpha.11:**
+
+- **Agent installation system** with `bmad agent-install` CLI command
+- **4 new reference agents** (commit-poet, journal-keeper, security-engineer, trend-analyst)
+- **Complete agent documentation suite** with 7 new focused guides
+- **Expert agent sidecar support** in edit-agent workflow
+- **2 new IDE installers** (Google Antigravity, enhanced Codex)
+- **Unified validation checklist** (160 lines) for consistent quality standards
+- **60 pure communication style presets** for agent persona design
+
+**Enhanced from alpha.10:**
+
+- **BMB agent builder workflows** with accurate context and comprehensive guidance
+- **All 9 BMM agents** enhanced with distinct, memorable communication voices
+- **Excalidraw capabilities** refined and distributed to role-appropriate agents
+- **Epic creation** moved to Phase 3 (after Architecture) for technical context
+
+### ⚠️ Breaking Changes
+
+**Agent Changes:**
+
+- Frame Expert agent retired - diagram capabilities now available through role-appropriate agents:
+  - Architecture diagrams → `/architect`
+  - Process flows → `/pm`
+  - Wireframes → `/ux-designer`
+  - Documentation visuals → `/tech-writer`
+
+**Workflow Changes:**
+
+- Epic creation moved from Phase 2 to Phase 3 (after Architecture)
+- Excalidraw workflows redistributed to appropriate agents
+
+**Installation Changes:**
+
+- New `bmad agent-install` command replaces manual agent installation
+- Agent YAML files must be compiled to XML for use
+
+### 🔄 Migration Notes
+
+**For Existing Projects:**
+
+1. **Frame Expert Users:**
+   - Transition to role-appropriate agents for diagrams
+   - All Excalidraw functionality preserved and enhanced
+   - Shared templates now in core resources for wider access
+
+2. **Agent Installation:**
+   - Use `bmad agent-install` for all agent installations
+   - Existing manual installations still work but won't have customization
+
+3. **Epic Creation Timing:**
+   - Epics now created in Phase 3 after Architecture
+   - Update any automation expecting epics in Phase 2
+
+4. **Communication Styles:**
+   - Review agent communication_style fields
+   - Remove any role/identity/principle content
+   - Use communication-presets.csv for pure styles
+
+5. **Expert Agents:**
+   - Edit-agent workflow now fully supports sidecar files
+   - Organize templates and data files in agent folder
+
+## [6.0.0-alpha.10]
+
+**Release: November 16, 2025**
+
+- **🎯 Epics Generated AFTER Architecture**: Major milestone - epics/stories now created after architecture for technically-informed user stories with better acceptance criteria
+- **🎨 Frame Expert Agent**: New Excalidraw specialist with 4 diagram workflows (flowchart, diagram, dataflow, wireframe) for visual documentation
+- **⏰ Time Estimate Prohibition**: Critical warnings added across 33 workflows - acknowledges AI has fundamentally changed development speed
+- **🎯 Platform-Specific Commands**: New `ide-only`/`web-only` fields filter menu items based on environment (IDE vs web bundle)
+- **🔧 Agent Customization**: Enhanced memory/prompts merging via `*.customize.yaml` files for persistent agent personalization
+
+## [6.0.0-alpha.9]
+
+**Release: November 12, 2025**
+
+- **🚀 Intelligent File Discovery Protocol**: New `discover_inputs` with FULL_LOAD, SELECTIVE_LOAD, and INDEX_GUIDED strategies for automatic context loading
+- **📚 3-Track System**: Simplified from 5 levels to 3 intuitive tracks: quick-flow, bmad-method, and enterprise-bmad-method
+- **🌐 Web Bundles Guide**: Comprehensive documentation for Gemini Gems and Custom GPTs with 60-80% cost savings strategies
+- **🏗️ Unified Output Structure**: Eliminated `.ephemeral/` folders - all artifacts now in single configurable output folder
+- **🎮 BMGD Phase 4**: Added 10 game development workflows following BMM patterns with game-specific adaptations
+
+## [6.0.0-alpha.8]
+
+**Release: November 9, 2025**
+
+- **🎯 Configurable Installation**: Custom directories with `.bmad` hidden folder default for cleaner project structure
+- **🚀 Optimized Agent Loading**: CLI loads from installed files eliminating duplication and maintenance burden
+- **🌐 Party Mode Everywhere**: All web bundles include multi-agent collaboration with customizable party configurations
+- **🔧 Phase 4 Artifact Separation**: Stories, code reviews, sprint plans now configurable outside docs folder
+- **📦 Expanded Web Bundles**: All BMM, BMGD, and CIS agents bundled with advanced elicitation integration
+
+## [6.0.0-alpha.7]
+
+**Release: November 7, 2025**
+
+- **🌐 Workflow Vendoring**: Web bundler performs automatic workflow vendoring for cross-module dependencies
+- **🎮 BMGD Module Extraction**: Game development split into standalone module with 4-phase industry-standard structure
+- **🔧 Enhanced Dependency Resolution**: Better handling of `web_bundle: false` workflows with positive resolution messages
+- **📚 Advanced Elicitation Fix**: Added missing CSV files to workflow bundles fixing runtime failures
+- **🐛 Claude Code Fix**: Resolved README slash command installation regression
+
+## [6.0.0-alpha.6]
+
+**Release: November 4, 2025**
+
+- **🐛 Critical Installer Fixes**: Fixed manifestPath error and option display issues blocking installation
+- **📖 Conditional Docs Installation**: Optional documentation installation to reduce footprint in production
+- **🎨 Improved Installer UX**: Better formatting with descriptive labels and clearer feedback
+- **🧹 Issue Tracker Cleanup**: Closed 54 legacy v4 issues for focused v6 development
+- **📝 Contributing Updates**: Removed references to non-existent branches in documentation
+
+## [6.0.0-alpha.5]
+
+**Release: November 4, 2025**
+
+- **🎯 3-Track Scale System**: Revolutionary simplification from 5 confusing levels to 3 intuitive preference-driven tracks
+- **✨ Elicitation Modernization**: Replaced legacy XML tags with explicit `invoke-task` pattern at strategic decision points
+- **📚 PM/UX Evolution Section**: Added November 2025 industry research on AI Agent PMs and Full-Stack Product Leads
+- **🏗️ Brownfield Reality Check**: Rewrote Phase 0 with 4 real-world scenarios for messy existing codebases
+- **📖 Documentation Accuracy**: All agent capabilities now match YAML source of truth with zero hallucination risk
+
+## [6.0.0-alpha.4]
+
+**Release: November 2, 2025**
+
+- **📚 Documentation Hub**: Created 18 comprehensive guides (7000+ lines) with professional technical writing standards
+- **🤖 Paige Agent**: New technical documentation specialist available across all BMM phases
+- **🚀 Quick Spec Flow**: Intelligent Level 0-1 planning with auto-stack detection and brownfield analysis
+- **📦 Universal Shard-Doc**: Split large markdown documents into organized sections with dual-strategy loading
+- **🔧 Intent-Driven Planning**: PRD and Product Brief transformed from template-filling to natural conversation
+
+## [6.0.0-alpha.3]
+
+**Release: October 2025**
+
+- **Codex Installer**: Custom prompts in `.codex/prompts/` directory structure
+- **Bug Fixes**: Various installer and workflow improvements
+- **Documentation**: Initial documentation structure established
+
 ## [6.0.0-alpha.0]

 **Release: September 28, 2025**

-Initial alpha release of a major rewrite and overhaul improvement of past versions.
-
-### Major New Features
-
- **Lean Core**: The core of BMad is very simple - common tasks that apply to any future module or agents, along with common agents that will be added to any modules - bmad-web-orchestrator and bmad-master.
- **BMad Method**: The new BMad Method (AKA bmm) is a complete overhaul of the v4 method, now a fully scale adaptive rewrite. The workflow now scales from small enhancements to massive undertakings across multiple services or architectures, supporting a new vast array of project type, including a full subclass of game development specifics.
- **BoMB**: The BMad Builder (AKA BoMB) now is able to fully automate creation and conversion of expansion packs from v5 to modules in v5 along with the net new ideation and brainstorming through implementation and testing of net new Modules, Workflows (were tasks and templates), Module Agents, and Standalone Personal Agents
- **CIS**: The Creative Intelligence Suite (AKA CIS)
-
-## [v5.0.0] - SKIPPED
-
-**Note**: Version 5.0.0 was skipped due to NPX registry issues that corrupted the version. Development continues with v6.0.0-alpha.0.
+- **Lean Core**: Simple common tasks and agents (bmad-web-orchestrator, bmad-master)
+- **BMad Method (BMM)**: Complete scale-adaptive rewrite supporting projects from small enhancements to massive undertakings
+- **BoMB**: BMad Builder for creating and converting modules, workflows, and agents
+- **CIS**: Creative Intelligence Suite for ideation and creative workflows
+- **Game Development**: Full subclass of game-specific development patterns**Note**: Version 5.0.0 was skipped due to NPX registry issues that corrupted the version. Development continues with v6.0.0-alpha.0.

 ## [v4.43.0](https://github.com/bmad-code-org/BMAD-METHOD/releases/tag/v4.43.0)

--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -86,25 +86,13 @@ Please propose small, granular changes! For large or significant changes, discus

 ### Which Branch?

-**Submit to `next` branch** (most contributions):
-
- ✨ New features or agents
- 🎨 Enhancements to existing features
- 📚 Documentation updates
- ♻️ Code refactoring
- ⚡ Performance improvements
- 🧪 New tests
- 🎁 New bmad modules
-
-**Submit to `main` branch** (critical only):
+**Submit PR's to `main` branch** (critical only):

 - 🚨 Critical bug fixes that break basic functionality
 - 🔒 Security patches
 - 📚 Fixing dangerously incorrect documentation
 - 🐛 Bugs preventing installation or basic usage

-**When in doubt, submit to `next`**. We'd rather test changes thoroughly before they hit stable.
-
 ### PR Size Guidelines

 - **Ideal PR size**: 200-400 lines of code changes
@@ -256,6 +244,7 @@ Each commit should represent one logical change:
 - Web/planning agents can be larger with more complex tasks
 - Everything is natural language (markdown) - no code in core framework
 - Use bmad modules for domain-specific features
+- Validate YAML schemas with `npm run validate:schemas` before committing

 ## Code of Conduct

--- a/README.md
+++ b/README.md
@@ -1,216 +1,214 @@
-# BMad CORE v6 Alpha
+# BMad Method & BMad Core

-[![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method)
+[![Stable Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=stable)](https://www.npmjs.com/package/bmad-method)
+[![Alpha Version](https://img.shields.io/npm/v/bmad-method/alpha?color=orange&label=alpha)](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%3D20.0.0-brightgreen)](https://nodejs.org)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)

-**The Universal Human-AI Collaboration Platform**
+## AI-Driven Agile Development That Scales From Bug Fixes to Enterprise

-IMPORTANT NOTE: ALPHA is potentially an unstable release that could drastically change in many ways. While we hope that is not the case, know that it could - your using and testing it during this time though is much appreciated. Please help us out by filing issues or reaching out in Discord to discuss.
+**Build More, Architect Dreams** (BMAD) with **19 specialized AI agents** and **50+ guided workflows** that adapt to your project's complexity—from quick bug fixes to enterprise platforms.

-IMPORTANT NOTE 2: ALPHA is not complete - there are still many small and big features, polish, doc improvements, and more agents and workflows coming ahead of the beta release!
+> **🚀 v6 is a MASSIVE upgrade from v4!** Complete architectural overhaul, scale-adaptive intelligence, visual workflows, and the powerful BMad Core framework. v4 users: this changes everything. [See what's new →](#whats-new-in-v6)

-IMPORTANT NOTE 3: ALPHA Web Bundles and Agents are not fully working yet - so you will need to use a good quality IDE to test many of the features, especially with the BMad Method module. BUT - the new agent builder and stand alone agent feature can work great with weaker models - this will still evolve over the coming weeks.
+> **📌 v6 Alpha Status:** Near-beta quality with vastly improved stability. Documentation is being finalized. New videos coming soon to [BMadCode YouTube](https://www.youtube.com/@BMadCode).

-BMad-CORE (Collaboration Optimized Reflection Engine) is a framework that brings out the best in you through AI agents designed to enhance human thinking rather than replace it. Unlike traditional AI tools that do the work for you, BMad-CORE's specialized agents guide you through the facilitation of optimized collaborative reflective workflows to unlock your full potential across any domain. It is this magic that powers the BMad Method, which is just one of the many modules that exist or are coming soon.
+## 🎯 Why BMad Method?

-**[Subscribe to BMadCode on YouTube](https://www.youtube.com/@BMadCode?sub_confirmation=1)** and **[Join our amazing, active Discord Community](https://discord.gg/gk8jAdXWmj)**
+Unlike generic AI coding assistants, BMad Method provides **structured, battle-tested workflows** powered by specialized agents who understand agile development. Each agent has deep domain expertise—from product management to architecture to testing—working together seamlessly.

-⭐ **If you find this project helpful or useful, please give it a star in the upper right-hand corner!** It helps others discover BMad-CORE and you will be notified of updates!
+**✨ Key Benefits:**

-## What Makes BMad-Core Different
+- **Scale-Adaptive Intelligence** - Automatically adjusts planning depth from bug fixes to enterprise systems
+- **Complete Development Lifecycle** - Analysis → Planning → Architecture → Implementation
+- **Specialized Expertise** - 19 agents with specific roles (PM, Architect, Developer, UX Designer, etc.)
+- **Proven Methodologies** - Built on agile best practices with AI amplification
+- **IDE Integration** - Works with Claude Code, Cursor, Windsurf, VS Code

-**Traditional AI**: Does the thinking for you, providing average, bland answers and solutions
-**BMad-CORE**: Brings out the best thinking in you and the AI through guided collaboration, elicitation, and facilitation
+## 🏗️ The Power of BMad Core

-### Core Philosophy: Human Amplification, Not Replacement
+**BMad Method** is actually a sophisticated module built on top of **BMad Core** (**C**ollaboration **O**ptimized **R**eflection **E**ngine). This revolutionary architecture means:

-BMad-Core's AI agents act as expert coaches, mentors, and collaborators who:
+- **BMad Core** provides the universal framework for human-AI collaboration
+- **BMad Method** leverages Core to deliver agile development workflows
+- **BMad Builder** lets YOU create custom modules as powerful as BMad Method itself

- Ask the right questions to stimulate your thinking
- Provide structured frameworks for complex problems
- Guide you through reflective processes to discover insights
- Help you develop mastery in your chosen domains
- Amplify your natural abilities rather than substituting for them
+With **BMad Builder**, you can architect both simple agents and vastly complex domain-specific modules (legal, medical, finance, education, creative) that will soon be sharable in an **official community marketplace**. Imagine building and sharing your own specialized AI team!

-## The Collaboration Optimized Reflection Engine
+## 📊 See It In Action

-At the heart of BMad-Core lies the **C.O.R.E.** system:
+<p align="center">
+  <img src="./src/modules/bmm/docs/images/workflow-method-greenfield.svg" alt="BMad Method Workflow" width="100%">
+</p>

- **Collaboration**: Human-AI partnership where both contribute unique strengths
- **Optimized**: The collaborative process has been refined for maximum effectiveness
- **Reflection**: Guided thinking that helps you discover better solutions and insights
- **Engine**: The powerful framework that orchestrates specialized agents and workflows
+<p align="center">
+  <em>Complete BMad Method workflow showing all phases, agents, and decision points</em>
+</p>

-## Universal Domain Coverage Through Modules
+## 🚀 Get Started in 3 Steps

-BMad-CORE works in ANY domain through specialized modules (previously called expansion packs)!
+### 1. Install BMad Method

-### Available Modules with Alpha Release
+```bash
+# Install v6 Alpha (recommended)
+npx bmad-method@alpha install

- **BMad Core (core)**: Included and used to power every current and future module; includes a master orchestrator for the local environment and one for the web bundles used with ChatGPT or Gemini Gems, for example.
- **BMad Method (bmm)**: Agile AI-driven software development - the classic that started it all and is still the best - but with v6, massively improved thanks to a rebuild from the ground up built on the new powerful BMad-CORE engine. The BMad Method has also been expanded to use a new "Scale Adaptive Workflow Engine"™.
- **BMad BoMB (bmb)**: The BMad Builder is your Custom Agent, Workflow, and Module authoring tool - it's now easier than ever to customize existing modules or create whatever you can imagine as a standalone module.
- **Creative Intelligence Suite (cis)**: Unlock innovation, problem-solving, and creative thinking! Brainstorming that was part of the BMad Method in the past is now part of this standalone module along with other workflows. The power of BMad modules still allows modules to borrow from each other - so the CIS, while standalone, also powers the brainstorming abilities for certain agents within the BMad Method!
+# Or stable v4 for production
+npx bmad-method install
+```

-## Alpha Installation and Testing
+### 2. Initialize Your Project

-**Prerequisites**: [Node.js](https://nodejs.org) v20+ required
+Load any agent in your IDE and run:

-Clone this repo ALPHA BRANCH to a folder. From the root of the folder, run `npm run install:bmad` and follow the installer questions.
+```
+*workflow-init
+```

-The Core Module will always be installed. The default initial module selection will be BMM for all the core BMad Method functionality and flow from brainstorming through software development.
+This analyzes your project and recommends the right workflow track.

-Note on installation: All installs now go to a single folder called `bmad` instead of multiple folders. When you install a module, you may still see folders other than the one you selected in the destination/bmad folder. This is intentional and not a bug - it will copy over to those other folders only the minimum that is needed because it is shared across the modules. For example, for now during Alpha to test this feature - BMM relies on the brainstorming feature of the CIS and some items from CORE - so this is why even if you only select BMM, you will still see bmad/core and bmad/cis along with bmad/bmm.
+### 3. Choose Your Track

-## What's New in V6-ALPHA
+BMad Method adapts to your needs with three intelligent tracks:

-Stability, customizability, installation Q&A, massive prompt improvements.
+| Track              | Use For                   | Planning                | Time to Start |
+| ------------------ | ------------------------- | ----------------------- | ------------- |
+| **⚡ Quick Flow**  | Bug fixes, small features | Tech spec only          | < 5 minutes   |
+| **📋 BMad Method** | Products, platforms       | PRD + Architecture + UX | < 15 minutes  |
+| **🏢 Enterprise**  | Compliance, scale         | Full governance suite   | < 30 minutes  |

-Everything has been rewritten from the ground up with best practices and advances learned over previous versions, standardizing on prompt format techniques. There is a lot more core usage of XML or XML-type tags within markdown, with many conventions and standards that drastically increase adherence of the agents.
+> **Not sure?** Run `*workflow-init` and let BMad analyze your project goal.

-Customizability is a key theme of this new version. All agents are now customizable by modifying a file under the installation bmad/\_cfg/agents. Every agent installed will generate an agent file that you can customize. The nice thing about this is when agents change or update in future versions, your customizations in these sidecar files will never be lost! You can change the name, their personas, how they talk, what they call you, and most exciting - what language they communicate in!
+## 🔄 How It Works: 4-Phase Methodology

-The BMad installer is 100% new from the ground up. First, along the way you will add your name (what the agents will call you and what you will author documents as), what language you want the agents to talk to you in, and every module you select will have its own set of questions to customize the experience. Also, when you install, a consolidated agent party is created so now when you use party-mode in the IDE, it is super efficient for the agent running the party to simulate all installed agents. Post alpha release, this will manifest itself in many interesting ways in time for beta - but for now, have fun with party mode and epic sprint retrospectives!
+BMad Method guides you through a proven development lifecycle:

-Speaking of installation - everything will now install to a single core bmad folder. No more separate root folders for every module! Instead, all will be contained within bmad/.
+1. **📊 Analysis** (Optional) - Brainstorm, research, and explore solutions
+2. **📝 Planning** - Create PRDs, tech specs, or game design documents
+3. **🏗️ Solutioning** - Design architecture, UX, and technical approach
+4. **⚡ Implementation** - Story-driven development with continuous validation

-All IDE selections now support the option to add in special install functionality per module. As an example with the alpha release, if you select the BMad Method and Claude Code, you will have an option to install pre-created Claude sub-agents. Not only do they get installed, but certain workflows will have injected into their instructions key indicators to the agent when to activate the sub-agents, removing some non-determinism. The sub-agent experience is still undergoing some work, so install them if you choose, and remove them if they become a pain.
+Each phase has specialized workflows and agents working together to deliver exceptional results.

-Also, when you read about the BoMB below, it will link to more information about various features in this new evolution of the BMad Code - one of the exciting ones is the new agent types - there are 3 now! The most exciting, with more info coming soon, are the new standalone tiny agents that you can easily generate and deploy free from any module - specialized for your own exact needs.
+## 🤖 Meet Your Team

-### BMad Method
+**12 Specialized Agents** working in concert:

-The BMad Method is significantly transforming and yet more powerful than ever. **Scale Adaptive** is a new term that means when you start the workflow to create a PRD or a GDD (or a simple tech-spec in the case of simple tasks), you will first answer some questions about the scope of the project, new vs. existing codebase and its state, and other questions. This will trigger a leveling of the effort from 0-4, and based on this scale adaptation, it will guide the workflow in different directions.
+| Development | Architecture   | Product       | Leadership     |
+| ----------- | -------------- | ------------- | -------------- |
+| Developer   | Architect      | PM            | Scrum Master   |
+| UX Designer | Test Architect | Analyst       | BMad Master    |
+| Tech Writer | Game Architect | Game Designer | Game Developer |

-Right now, this is still a bit alpha feeling and disjointed, but before beta it will be tied together through all four workflow phases with a potential single orchestration if you choose - or you can still jump right in, especially for simple tasks that just need a simple tech-spec and then right off to development.
+**Test Architect** integrates with `@seontechnologies/playwright-utils` for production-ready fixture-based utilities.

-To test and experience this now, here is the new main flow for BMM v6 alpha:
+Each agent brings deep expertise and can be customized to match your team's style.

-(Docs will be all linked in soon with new user guide and workflow diagrams coming this week)
+## 📦 What's Included

-NOTE: Game Development expansion packs are all being rolled into the official BNad Method module - along with any more game engine platforms being added. Additionally game development planning for the GDD is not only scale adpative, but also adapts to the type of game you are making - so you can plan all that is needed for your dream game!
+### Core Modules

-#### **PHASE 1 - Analysis**
+- **BMad Method (BMM)** - Complete agile development framework
+  - 12 specialized agents
+  - 34 workflows across 4 phases
+  - Scale-adaptive planning
+  - [→ Documentation Hub](./src/modules/bmm/docs/README.md)

-**Analyst:**
+- **BMad Builder (BMB)** - Create custom agents and workflows
+  - Build anything from simple agents to complex modules
+  - Create domain-specific solutions (legal, medical, finance, education)
+  - Share your creations in the upcoming community marketplace
+  - [→ Builder Guide](./src/modules/bmb/README.md)

- `brainstorm-project`
- `research` (market research, deep research, deep research prompt generation)
- `product-brief`
+- **Creative Intelligence Suite (CIS)** - Innovation & problem-solving
+  - Brainstorming, design thinking, storytelling
+  - 5 creative facilitation workflows
+  - [→ Creative Workflows](./src/modules/cis/README.md)

-**Game Designer (Optional):**
+### Key Features

- `brainstorm-game`
- `game-brief`
- `research`
+- **🎨 Customizable Agents** - Modify personalities, expertise, and communication styles
+- **🌐 Multi-Language Support** - Separate settings for communication and code output
+- **📄 Document Sharding** - 90% token savings for large projects
+- **🔄 Update-Safe** - Your customizations persist through updates
+- **🚀 Web Bundles** - Use in ChatGPT, Claude Projects, or Gemini Gems
+
+## 📚 Documentation
+
+### Quick Links
+
+- **[Quick Start Guide](./src/modules/bmm/docs/quick-start.md)** - 15-minute introduction
+- **[Complete BMM Documentation](./src/modules/bmm/docs/README.md)** - All guides and references
+- **[Agent Customization](./docs/agent-customization-guide.md)** - Personalize your agents
+- **[All Documentation](./docs/index.md)** - Complete documentation index
+
+### For v4 Users
+
+- **[v4 Documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)**
+- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)**
+
+## 💬 Community & Support
+
+- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help, share projects
+- **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs, request features
+- **[YouTube Channel](https://www.youtube.com/@BMadCode)** - Video tutorials and demos
+- **[Web Bundles](https://bmad-code-org.github.io/bmad-bundles/)** - Pre-built agent bundles
+
+## 🛠️ Development
+
+For contributors working on the BMad codebase:
+
+```bash
+# Run all quality checks
+npm test
+
+# Development commands
+npm run lint:fix      # Fix code style
+npm run format:fix    # Auto-format code
+npm run bundle        # Build web bundles
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.
+
+## What's New in v6
+
+**v6 represents a complete architectural revolution from v4:**
+
+### 🚀 Major Upgrades
+
+- **BMad Core Framework** - Modular architecture enabling custom domain solutions
+- **Scale-Adaptive Intelligence** - Automatic adjustment from bug fixes to enterprise
+- **Visual Workflows** - Beautiful SVG diagrams showing complete methodology
+- **BMad Builder Module** - Create and share your own AI agent teams
+- **50+ Workflows** - Up from 20 in v4, covering every development scenario
+- **19 Specialized Agents** - Enhanced with customizable personalities and expertise
+- **Update-Safe Customization** - Your configs persist through all updates
+- **Web Bundles** - Use agents in ChatGPT, Claude, and Gemini
+- **Multi-Language Support** - Separate settings for communication and code
+- **Document Sharding** - 90% token savings for large projects
+
+### 🔄 For v4 Users
+
+- **[Comprehensive Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Step-by-step migration
+- **[v4 Documentation Archive](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)** - Legacy reference
+- Backwards compatibility where possible
+- Smooth migration path with installer detection
+
+## 📄 License
+
+MIT License - See [LICENSE](LICENSE) for details.
+
+**Trademarks:** BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.

 ---

-#### **PHASE 2 - Planning**
+<p align="center">
+  <a href="https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors">
+    <img src="https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD" alt="Contributors">
+  </a>
+</p>

-**PM:**
-
- `plan-project`
-
-**Game Designer:**
-
- `plan-game` (calls the same plan-project workflow, but input docs or your answers should drive it towards GDD)
-
---
-
-#### **PHASE 3 - Solutioning**
-
-**Architect or Game Architect:**
-
-Just like the scale-adjusted planning, architecture is the same. No more document sharding though!! Now in the IDE you create an architecture that adapts to the type of project you are working on - based on the inputs from your PRD, it will adapt the sections it includes to your project type. No longer is the architecture biased just towards full stack or back-end APIs. There are many more options now, from embedded hardware to mobile to many other options - with many more coming with beta.
-
- `solution-architecture`
-
-> **Note:** Testing, DevOps, or security concerns beyond the basics are generally not included in the architecture. If it is more complicated, especially for complex massive undertakings, you will be suggested to pull in specific agents to help with those areas. _(Not released with alpha.0, coming soon)_
-
-Once the full architecture is complete, you can still use the PO to run the checklist to validate the epics and stories are still correct - although the architect should also be keeping them updated as needed (needs some tuning during alpha). Once done, then it's time to create the tech spec for your first epic.
-
- `tech-spec`
-
-The tech spec pulls all technical information from all planning thus far, along with any further research needed from the web to produce an **Epic Tech Spec** - each epic will have one. This is going to make the SM even more capable of finding the info it needs for each story when we get to phase 4!!
-
---
-
-#### **PHASE 4 - Implementation**
-
-And now here we are at phase 4 - where we, just like in BMad Method of yore, use the SM and the Dev Agent. No more QA agent here though; the dev now has a dev task and also a senior dev agent review task.
-
-**Scrum Master (SM) Tasks:**
-
-Before the dev starts, the SM will:
-
-1. `create-story`
-2. `story-context` _(NEW!)_
-
-**Story-context** is a game-changing new feature beyond what we had with create-story in the past. Create-story still pulls in all the info it needs from the tech-spec and elsewhere as needed (including previously completed stories), but the generation of the new story-context takes it up a whole new level.
-
-This real-time prep means no more generic devLoadAlways list of story files. During the alpha phase, we will be tuning what goes into this context, but this is going to supercharge and specialize your dev to the story at hand!
-
---
-
-> **🎉 There are many other exciting changes throughout for you to discover during the alpha BMad Method module!**
-
-## CIS
-
-The CIS has 5 agents to try out, each with their own workflow! This is a new module that will drastically change over time.
-
- [CIS Readme](./src/modules/cis/readme.md)
-
-### BoMB: BMad Builder
-
-#### Agent Docs
-
- [Agent Architecture](src/modules/bmb/workflows/create-agent/agent-architecture)
- [Agent command patterns](src/modules/bmb/workflows/create-agent/agent-command-patterns.md)
- [Agent Types](src/modules/bmb/workflows/create-agent/agent-types.md)
- [Communication Styles](src/modules/bmb/workflows/create-agent/communication-styles.md)
-
-#### Modules
-
-Modules are what we used to call Expansion Packs. A new repository to contribute modules is coming very soon with the beta release where you can start contributing modules - we just want to make sure the final format and conventions are stable. A module will generally be made up of agents and workflows. Tasks are still also possible, but generally should be avoided in favor of more flexible workflows. Workflows can have sub-workflows and soon will support a standardized multi-workflow orchestration pattern that the BMad master will be able to guide users through.
-
- [Module Structure](src/modules/bmb/workflows/create-module/module-structure.md)
-
-#### Workflows
-
-What used to be tasks and create-doc templates are now all workflows! Simpler, yet more powerful and support many ways of achieving many different outcomes! A lot more documentation will be coming. This document is used by the agent builder to generate workflows or convert to workflows, but there is a lot more than what we have documented here in this alpha doc.
-
- [Workflow Creation Guide](src/modules/bmb/workflows/create-workflow/workflow-creation-guide)
-
-### Installer Changes
-
- [IDE Injections](docs/installers-bundlers/ide-injections)
- [Installers Modules Platforms References](docs/installers-bundlers/installers-modules-platforms-reference)
- [Web Bundler Usage](docs/installers-bundlers/web-bundler-usage)
- [Claude Code Sub Module BMM Installer](src/modules/bmm/sub-modules/claude-code/readme.md)
-
-## Support & Community
-
- 💬 [Discord Community](https://discord.gg/gk8jAdXWmj) - Get help, share ideas, collaborate
- 🐛 [Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues) - Bug reports and feature requests
- 💬 [Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions) - Community conversations
-
-## Contributing
-
-We welcome contributions and new module development!
-
-📋 **[Read CONTRIBUTING.md](CONTRIBUTING.md)** - Complete contribution guide
-
-## License
-
-MIT License - see [LICENSE](LICENSE) for details.
-
-## Trademark Notice
-
-BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. All rights reserved.
-
-[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors)
-
-<sub>Built with ❤️ for the human-AI collaboration community</sub>
+<p align="center">
+  <sub>Built with ❤️ for the human-AI collaboration community</sub>
+</p>
--- a/docs/BUNDLE_DISTRIBUTION_SETUP.md
+++ b/docs/BUNDLE_DISTRIBUTION_SETUP.md
@@ -0,0 +1,95 @@
+# Bundle Distribution Setup (For Maintainers)
+
+**Audience:** BMAD maintainers setting up bundle auto-publishing
+
+---
+
+## One-Time Setup
+
+Run these commands once to enable auto-publishing:
+
+```bash
+# 1. Create bmad-bundles repo
+gh repo create bmad-code-org/bmad-bundles --public --description "BMAD Web Bundles"
+
+# 2. Ensure `main` exists (GitHub Pages API requires a source branch)
+git clone git@github.com:bmad-code-org/bmad-bundles.git
+cd bmad-bundles
+printf '# bmad-bundles\n\nStatic bundles published from BMAD-METHOD.\n' > README.md
+git add README.md
+git commit -m "Initial commit"
+git push origin main
+cd -
+
+# 3. Enable GitHub Pages (API replacement for removed --enable-pages flag)
+gh api repos/bmad-code-org/bmad-bundles/pages --method POST -f source[branch]=main -f source[path]=/
+# (Optional) confirm status
+gh api repos/bmad-code-org/bmad-bundles/pages --jq '{status,source}'
+
+# 4. Create GitHub PAT and add as secret
+# Go to: https://github.com/settings/tokens/new
+# Scopes: repo (full control)
+# Name: bmad-bundles-ci
+# Then add as secret:
+gh secret set BUNDLES_PAT --repo bmad-code-org/BMAD-METHOD
+# (paste PAT when prompted)
+```
+
+If the Pages POST returns `409`, the site already exists. If it returns `422` about `main` missing, redo step 2 to push the initial commit.
+
+**Done.** Bundles auto-publish on every main merge.
+
+---
+
+## How It Works
+
+**On main merge:**
+
+- `.github/workflows/bundle-latest.yaml` runs
+- Publishes to: `https://bmad-code-org.github.io/bmad-bundles/`
+
+**On release:**
+
+- `npm run release:patch` runs `.github/workflows/manual-release.yaml`
+- Attaches bundles to: `https://github.com/bmad-code-org/BMAD-METHOD/releases/latest`
+
+---
+
+## Testing
+
+```bash
+# Test latest channel
+git push origin main
+# Wait 2 min, then: curl https://bmad-code-org.github.io/bmad-bundles/
+
+# Test stable channel
+npm run release:patch
+# Check: gh release view
+```
+
+---
+
+## Troubleshooting
+
+**"Permission denied" or auth errors**
+
+```bash
+# Verify PAT secret exists
+gh secret list --repo bmad-code-org/BMAD-METHOD | grep BUNDLES_PAT
+
+# If missing, recreate PAT and add secret:
+gh secret set BUNDLES_PAT --repo bmad-code-org/BMAD-METHOD
+```
+
+**GitHub Pages not updating / need to re-check config**
+
+```bash
+gh api repos/bmad-code-org/bmad-bundles/pages --jq '{status,source,html_url}'
+```
+
+---
+
+## Distribution URLs
+
+**Stable:** `https://github.com/bmad-code-org/BMAD-METHOD/releases/latest`
+**Latest:** `https://bmad-code-org.github.io/bmad-bundles/`
--- a/docs/agent-customization-guide.md
+++ b/docs/agent-customization-guide.md
@@ -0,0 +1,208 @@
+# Agent Customization Guide
+
+Customize BMad agents without modifying core files. All customizations persist through updates.
+
+## Quick Start
+
+**1. Locate Customization Files**
+
+After installation, find agent customization files in:
+
+```
+{bmad_folder}/_cfg/agents/
+├── core-bmad-master.customize.yaml
+├── bmm-dev.customize.yaml
+├── bmm-pm.customize.yaml
+└── ... (one file per installed agent)
+```
+
+**2. Edit Any Agent**
+
+Open the `.customize.yaml` file for the agent you want to modify. All sections are optional - customize only what you need.
+
+**3. Rebuild the Agent**
+
+After editing, IT IS CRITICAL to rebuild the agent to apply changes:
+
+```bash
+npx bmad-method@alpha install # and then select option to compile all agents
+# OR for individual agent only
+npx bmad-method@alpha build <agent-name>
+
+# Examples:
+npx bmad-method@alpha build bmm-dev
+npx bmad-method@alpha build core-bmad-master
+npx bmad-method@alpha build bmm-pm
+```
+
+## What You Can Customize
+
+### Agent Name
+
+Change how the agent introduces itself:
+
+```yaml
+agent:
+  metadata:
+    name: 'Spongebob' # Default: "Amelia"
+```
+
+### Persona
+
+Replace the agent's personality, role, and communication style:
+
+```yaml
+persona:
+  role: 'Senior Full-Stack Engineer'
+  identity: 'Lives in a pineapple (under the sea)'
+  communication_style: 'Spongebob'
+  principles:
+    - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep'
+    - 'Favor composition over inheritance'
+```
+
+**Note:** The persona section replaces the entire default persona (not merged).
+
+### Memories
+
+Add persistent context the agent will always remember:
+
+```yaml
+memories:
+  - 'Works at Krusty Krab'
+  - 'Favorite Celebrity: David Hasslehoff'
+  - 'Learned in Epic 1 that its not cool to just pretend that tests have passed'
+```
+
+### Custom Menu Items
+
+Add your own workflows to the agent's menu:
+
+```yaml
+menu:
+  - trigger: my-workflow
+    workflow: '{project-root}/custom/my-workflow.yaml'
+    description: My custom workflow
+  - trigger: deploy
+    action: '#deploy-prompt'
+    description: Deploy to production
+```
+
+**Don't include:** `*` prefix or `help`/`exit` items - these are auto-injected.
+
+### Critical Actions
+
+Add instructions that execute before the agent starts:
+
+```yaml
+critical_actions:
+  - 'Always check git status before making changes'
+  - 'Use conventional commit messages'
+```
+
+### Custom Prompts
+
+Define reusable prompts for `action="#id"` menu handlers:
+
+```yaml
+prompts:
+  - id: deploy-prompt
+    content: |
+      Deploy the current branch to production:
+      1. Run all tests
+      2. Build the project
+      3. Execute deployment script
+```
+
+## Real-World Examples
+
+**Example 1: Customize Developer Agent for TDD**
+
+```yaml
+# {bmad_folder}/_cfg/agents/bmm-dev.customize.yaml
+agent:
+  metadata:
+    name: 'TDD Developer'
+
+memories:
+  - 'Always write tests before implementation'
+  - 'Project uses Jest and React Testing Library'
+
+critical_actions:
+  - 'Review test coverage before committing'
+```
+
+**Example 2: Add Custom Deployment Workflow**
+
+```yaml
+# {bmad_folder}/_cfg/agents/bmm-dev.customize.yaml
+menu:
+  - trigger: deploy-staging
+    workflow: '{project-root}/.bmad-custom/deploy-staging.yaml'
+    description: Deploy to staging environment
+  - trigger: deploy-prod
+    workflow: '{project-root}/.bmad-custom/deploy-prod.yaml'
+    description: Deploy to production (with approval)
+```
+
+**Example 3: Multilingual Product Manager**
+
+```yaml
+# {bmad_folder}/_cfg/agents/bmm-pm.customize.yaml
+persona:
+  role: 'Bilingual Product Manager'
+  identity: 'Expert in US and LATAM markets'
+  communication_style: 'Clear, strategic, with cultural awareness'
+  principles:
+    - 'Consider localization from day one'
+    - 'Balance business goals with user needs'
+
+memories:
+  - 'User speaks English and Spanish'
+  - 'Target markets: US and Latin America'
+```
+
+## Tips
+
+- **Start Small:** Customize one section at a time and rebuild to test
+- **Backup:** Copy customization files before major changes
+- **Update-Safe:** Your customizations in `_cfg/` survive all BMad updates
+- **Per-Project:** Customization files are per-project, not global
+- **Version Control:** Consider committing `_cfg/` to share customizations with your team
+
+## Module vs. Global Config
+
+**Module-Level (Recommended):**
+
+- Customize agents per-project in `{bmad_folder}/_cfg/agents/`
+- Different projects can have different agent behaviors
+
+**Global Config (Coming Soon):**
+
+- Set defaults that apply across all projects
+- Override with project-specific customizations
+
+## Troubleshooting
+
+**Changes not appearing?**
+
+- Make sure you ran `npx bmad-method build <agent-name>` after editing
+- Check YAML syntax is valid (indentation matters!)
+- Verify the agent name matches the file name pattern
+
+**Agent not loading?**
+
+- Check for YAML syntax errors
+- Ensure required fields aren't left empty if you uncommented them
+- Try reverting to the template and rebuilding
+
+**Need to reset?**
+
+- Delete the `.customize.yaml` file
+- Run `npx bmad-method build <agent-name>` to regenerate defaults
+
+## Next Steps
+
+- **[BMM Agents Guide](../src/modules/bmm/docs/agents-guide.md)** - Learn about all 12 BMad Method agents
+- **[BMB Create Agent Workflow](../src/modules/bmb/workflows/create-agent/README.md)** - Build completely custom agents
+- **[BMM Complete Documentation](../src/modules/bmm/docs/README.md)** - Full BMad Method reference
--- a/docs/codebase-flattener.md
+++ b/docs/codebase-flattener.md
@@ -1,19 +0,0 @@
-# Codebase Flattener Tool
-
-BMad-Core includes a powerful codebase flattener for preparing existing projects to the web for AI Analysis
-
-```bash
-# Basic usage - creates flattened-codebase.xml
-npx bmad-method flatten
-
-# Custom input/output
-npx bmad-method flatten --input /path/to/source --output project.xml
-```
-
-Features:
-
- AI-optimized XML output format
- Smart filtering with .gitignore respect
- Binary file detection and exclusion
- Real-time progress tracking
- Comprehensive completion statistics
--- a/docs/custom-agent-installation.md
+++ b/docs/custom-agent-installation.md
@@ -0,0 +1,169 @@
+# Custom Agent Installation
+
+Install and personalize BMAD agents in your project.
+
+## Quick Start
+
+```bash
+# From your project directory with BMAD installed
+npx bmad agent-install
+```
+
+Or if you have bmad-cli installed globally:
+
+```bash
+bmad agent-install
+```
+
+## What It Does
+
+1. **Discovers** available agent templates from your custom agents folder
+2. **Prompts** you to personalize the agent (name, behavior, preferences)
+3. **Compiles** the agent with your choices baked in
+4. **Installs** to your project's `.bmad/custom/agents/` directory
+5. **Creates** IDE commands for all your configured IDEs (Claude Code, Codex, Cursor, etc.)
+6. **Saves** your configuration for automatic reinstallation during BMAD updates
+
+## Options
+
+```bash
+bmad agent-install [options]
+
+Options:
+  -p, --path <path>     Direct path to specific agent YAML file or folder
+  -d, --defaults        Use default values without prompting
+  -t, --target <path>   Target installation directory
+```
+
+## Example Session
+
+```
+🔧 BMAD Agent Installer
+
+Found BMAD at: /project/.bmad
+Searching for agents in: /project/.bmad/custom/agents
+
+Available Agents:
+
+  1. 📄 commit-poet (simple)
+  2. 📚 journal-keeper (expert)
+
+Select agent to install (number): 1
+
+Selected: commit-poet
+
+📛 Agent Persona Name
+
+   Agent type: commit-poet
+   Default persona: Inkwell Von Comitizen
+
+   Custom name (or Enter for default): Fred
+
+   Persona: Fred
+   File: fred-commit-poet.md
+
+📝 Agent Configuration
+
+   What's your preferred default commit message style?
+   * 1. Conventional (feat/fix/chore)
+     2. Narrative storytelling
+     3. Poetic haiku
+     4. Detailed explanation
+   Choice (default: 1): 1
+
+   How enthusiastic should the agent be?
+     1. Moderate - Professional with personality
+   * 2. High - Genuinely excited
+     3. EXTREME - Full theatrical drama
+   Choice (default: 2): 3
+
+   Include emojis in commit messages? [Y/n]: y
+
+✨ Agent installed successfully!
+   Name: fred-commit-poet
+   Location: /project/.bmad/custom/agents/fred-commit-poet
+   Compiled: fred-commit-poet.md
+
+   ✓ Source saved for reinstallation
+   ✓ Added to agent-manifest.csv
+   ✓ Created IDE commands:
+      claude-code: /bmad:custom:agents:fred-commit-poet
+      codex: /bmad-custom-agents-fred-commit-poet
+      github-copilot: bmad-agent-custom-fred-commit-poet
+```
+
+## Reinstallation
+
+Custom agents are automatically reinstalled when you run `bmad init --quick`. Your personalization choices are preserved in `.bmad/_cfg/custom/agents/`.
+
+## Installing Reference Agents
+
+The BMAD source includes example agents you can install. **You must copy them to your project first.**
+
+### Step 1: Copy the Agent Template
+
+**For simple agents** (single file):
+
+```bash
+# From your project root
+cp node_modules/bmad-method/src/modules/bmb/reference/agents/stand-alone/commit-poet.agent.yaml \
+   .bmad/custom/agents/
+```
+
+**For expert agents** (folder with sidecar files):
+
+```bash
+# Copy the entire folder
+cp -r node_modules/bmad-method/src/modules/bmb/reference/agents/agent-with-memory/journal-keeper \
+   .bmad/custom/agents/
+```
+
+### Step 2: Install and Personalize
+
+```bash
+npx bmad agent-install
+# or: bmad agent-install
+```
+
+The installer will:
+
+1. Find the copied template in `.bmad/custom/agents/`
+2. Prompt for personalization (name, behavior, preferences)
+3. Compile and install with your choices baked in
+4. Create IDE commands for immediate use
+
+### Available Reference Agents
+
+**Simple (standalone file):**
+
+- `commit-poet.agent.yaml` - Commit message artisan with style preferences
+
+**Expert (folder with sidecar):**
+
+- `journal-keeper/` - Personal journal companion with memory and pattern recognition
+
+Find these in the BMAD source:
+
+```
+src/modules/bmb/reference/agents/
+├── stand-alone/
+│   └── commit-poet.agent.yaml
+└── agent-with-memory/
+    └── journal-keeper/
+        ├── journal-keeper.agent.yaml
+        └── journal-keeper-sidecar/
+```
+
+## Creating Your Own
+
+Place your `.agent.yaml` files in `.bmad/custom/agents/`. Use the reference agents as templates.
+
+Key sections in an agent YAML:
+
+- `metadata`: name, title, icon, type
+- `persona`: role, identity, communication_style, principles
+- `prompts`: reusable prompt templates
+- `menu`: numbered menu items
+- `install_config`: personalization questions (optional, at end of file)
+
+See the reference agents for complete examples with install_config templates and XML-style semantic tags.
--- a/docs/document-sharding-guide.md
+++ b/docs/document-sharding-guide.md
@@ -0,0 +1,449 @@
+# Document Sharding Guide
+
+Comprehensive guide to BMad Method's document sharding system for managing large planning and architecture documents.
+
+## Table of Contents
+
+- [What is Document Sharding?](#what-is-document-sharding)
+- [When to Use Sharding](#when-to-use-sharding)
+- [How Sharding Works](#how-sharding-works)
+- [Using the Shard-Doc Tool](#using-the-shard-doc-tool)
+- [Workflow Support](#workflow-support)
+- [Best Practices](#best-practices)
+- [Examples](#examples)
+
+## What is Document Sharding?
+
+Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`). This enables:
+
+- **Selective Loading** - Workflows load only the sections they need
+- **Reduced Token Usage** - Massive efficiency gains for large projects
+- **Better Organization** - Logical section-based file structure
+- **Maintained Context** - Index file preserves document structure
+
+### Architecture
+
+```
+Before Sharding:
+docs/
+└── PRD.md (large 50k token file)
+
+After Sharding:
+docs/
+└── prd/
+    ├── index.md                    # Table of contents with descriptions
+    ├── overview.md                 # Section 1
+    ├── user-requirements.md        # Section 2
+    ├── technical-requirements.md   # Section 3
+    └── ...                         # Additional sections
+```
+
+## When to Use Sharding
+
+### Ideal Candidates
+
+**Large Multi-Epic Projects:**
+
+- Very large complex PRDs
+- Architecture documents with multiple system layers
+- Epic files with 4+ epics (especially for Phase 4)
+- UX design specs covering multiple subsystems
+
+**Token Thresholds:**
+
+- **Consider sharding**: Documents > 20k tokens
+- **Strongly recommended**: Documents > 40k tokens
+- **Critical for efficiency**: Documents > 60k tokens
+
+### When NOT to Shard
+
+**Small Projects:**
+
+- Single epic projects
+- Level 0-1 projects (tech-spec only)
+- Documents under 10k tokens
+- Quick prototypes
+
+**Frequently Updated Docs:**
+
+- Active work-in-progress documents
+- Documents updated daily
+- Documents where whole-file context is essential
+
+## How Sharding Works
+
+### Sharding Process
+
+1. **Tool Execution**: Run `npx @kayvan/markdown-tree-parser source.md destination/` - this is abstracted with the core shard-doc task which is installed as a slash command or manual task rule depending on your tools.
+2. **Section Extraction**: Tool splits by level 2 headings
+3. **File Creation**: Each section becomes a separate file
+4. **Index Generation**: `index.md` created with structure and descriptions
+
+### Workflow Discovery
+
+BMad workflows use a **dual discovery system**:
+
+1. **Try whole document first** - Look for `document-name.md`
+2. **Check for sharded version** - Look for `document-name/index.md`
+3. **Priority rule** - Whole document takes precedence if both exist
+
+### Loading Strategies
+
+**Full Load (Phase 1-3 workflows):**
+
+```
+If sharded:
+  - Read index.md
+  - Read ALL section files
+  - Treat as single combined document
+```
+
+**Selective Load (Phase 4 workflows):**
+
+```
+If sharded epics and working on Epic 3:
+  - Read epics/index.md
+  - Load ONLY epics/epic-3.md
+  - Skip all other epic files
+  - 90%+ token savings!
+```
+
+## Using the Shard-Doc Tool
+
+### CLI Command
+
+```bash
+# Activate bmad-master or analyst agent, then:
+/shard-doc
+```
+
+### Interactive Process
+
+```
+Agent: Which document would you like to shard?
+User: docs/PRD.md
+
+Agent: Default destination: docs/prd/
+       Accept default? [y/n]
+User: y
+
+Agent: Sharding PRD.md...
+       ✓ Created 12 section files
+       ✓ Generated index.md
+       ✓ Complete!
+```
+
+### What Gets Created
+
+**index.md structure:**
+
+```markdown
+# PRD - Index
+
+## Sections
+
+1. [Overview](./overview.md) - Project vision and objectives
+2. [User Requirements](./user-requirements.md) - Feature specifications
+3. [Epic 1: Authentication](./epic-1-authentication.md) - User auth system
+4. [Epic 2: Dashboard](./epic-2-dashboard.md) - Main dashboard UI
+   ...
+```
+
+**Individual section files:**
+
+- Named from heading text (kebab-case)
+- Contains complete section content
+- Preserves all markdown formatting
+- Can be read independently
+
+## Workflow Support
+
+### Universal Support
+
+**All BMM workflows support both formats:**
+
+- ✅ Whole documents
+- ✅ Sharded documents
+- ✅ Automatic detection
+- ✅ Transparent to user
+
+### Workflow-Specific Patterns
+
+#### Phase 1-3 (Full Load)
+
+Workflows load entire sharded documents:
+
+- `product-brief` - Research, brainstorming docs
+- `prd` - Product brief, research
+- `gdd` - Game brief, research
+- `create-ux-design` - PRD, brief, architecture (if available)
+- `tech-spec` - Brief, research
+- `architecture` - PRD, UX design (if available)
+- `create-epics-and-stories` - PRD, architecture
+- `implementation-readiness` - All planning docs
+
+#### Phase 4 (Selective Load)
+
+Workflows load only needed sections:
+
+**sprint-planning** (Full Load):
+
+- Needs ALL epics to build complete status
+
+**epic-tech-context, create-story, story-context, code-review** (Selective):
+
+```
+Working on Epic 3, Story 2:
+  ✓ Load epics/epic-3.md only
+  ✗ Skip epics/epic-1.md, epic-2.md, epic-4.md, etc.
+
+Result: 90%+ token reduction for 10-epic projects!
+```
+
+### Input File Patterns
+
+Workflows use standardized patterns:
+
+```yaml
+input_file_patterns:
+  prd:
+    whole: '{output_folder}/*prd*.md'
+    sharded: '{output_folder}/*prd*/index.md'
+
+  epics:
+    whole: '{output_folder}/*epic*.md'
+    sharded_index: '{output_folder}/*epic*/index.md'
+    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md'
+```
+
+## Best Practices
+
+### Sharding Strategy
+
+**Do:**
+
+- ✅ Shard after planning phase complete
+- ✅ Keep level 2 headings well-organized
+- ✅ Use descriptive section names
+- ✅ Shard before Phase 4 implementation
+- ✅ Keep original file as backup initially
+
+**Don't:**
+
+- ❌ Shard work-in-progress documents
+- ❌ Shard small documents (<20k tokens)
+- ❌ Mix sharded and whole versions
+- ❌ Manually edit index.md structure
+
+### Naming Conventions
+
+**Good Section Names:**
+
+```markdown
+## Epic 1: User Authentication
+
+## Technical Requirements
+
+## System Architecture
+
+## UX Design Principles
+```
+
+**Poor Section Names:**
+
+```markdown
+## Section 1
+
+## Part A
+
+## Details
+
+## More Info
+```
+
+### File Management
+
+**When to Re-shard:**
+
+- Significant structural changes to document
+- Adding/removing major sections
+- After major refactoring
+
+**Updating Sharded Docs:**
+
+1. Edit individual section files directly
+2. OR edit original, delete sharded folder, re-shard
+3. Don't manually edit index.md
+
+## Examples
+
+### Example 1: Large PRD
+
+**Scenario:** 15-epic project, PRD is 45k tokens
+
+**Before Sharding:**
+
+```
+Every workflow loads entire 45k token PRD
+Architecture workflow: 45k tokens
+UX design workflow: 45k tokens
+```
+
+**After Sharding:**
+
+```bash
+/shard-doc
+Source: docs/PRD.md
+Destination: docs/prd/
+
+Created:
+  prd/index.md
+  prd/overview.md (3k tokens)
+  prd/functional-requirements.md (8k tokens)
+  prd/non-functional-requirements.md (6k tokens)
+  prd/user-personas.md (4k tokens)
+  ...additional FR/NFR sections
+```
+
+**Result:**
+
+```
+Architecture workflow: Can load specific sections needed
+UX design workflow: Can load specific sections needed
+Significant token reduction for large requirement docs!
+```
+
+### Example 2: Sharding Epics File
+
+**Scenario:** 8 epics with detailed stories, 35k tokens total
+
+```bash
+/shard-doc
+Source: docs/bmm-epics.md
+Destination: docs/epics/
+
+Created:
+  epics/index.md
+  epics/epic-1.md
+  epics/epic-2.md
+  ...
+  epics/epic-8.md
+```
+
+**Efficiency Gain:**
+
+```
+Working on Epic 5 stories:
+  Old: Load all 8 epics (35k tokens)
+  New: Load epic-5.md only (4k tokens)
+  Savings: 88% reduction
+```
+
+### Example 3: Architecture Document
+
+**Scenario:** Multi-layer system architecture, 28k tokens
+
+```bash
+/shard-doc
+Source: docs/architecture.md
+Destination: docs/architecture/
+
+Created:
+  architecture/index.md
+  architecture/system-overview.md
+  architecture/frontend-architecture.md
+  architecture/backend-services.md
+  architecture/data-layer.md
+  architecture/infrastructure.md
+  architecture/security-architecture.md
+```
+
+**Benefit:** Code-review workflow can reference specific architectural layers without loading entire architecture doc.
+
+## Custom Workflow Integration
+
+### For Workflow Builders
+
+When creating custom workflows that load large documents:
+
+**1. Add input_file_patterns to workflow.yaml:**
+
+```yaml
+input_file_patterns:
+  your_document:
+    whole: '{output_folder}/*your-doc*.md'
+    sharded: '{output_folder}/*your-doc*/index.md'
+```
+
+**2. Add discovery instructions to instructions.md:**
+
+```markdown
+## Document Discovery
+
+1. Search for whole document: _your-doc_.md
+2. Check for sharded version: _your-doc_/index.md
+3. If sharded: Read index + ALL sections (or specific sections if selective load)
+4. Priority: Whole document first
+```
+
+**3. Choose loading strategy:**
+
+- **Full Load**: Read all sections when sharded
+- **Selective Load**: Read only relevant sections (requires section identification logic)
+
+### Pattern Templates
+
+**Full Load Pattern:**
+
+```xml
+<action>Search for document: {output_folder}/*doc-name*.md</action>
+<action>If not found, check for sharded: {output_folder}/*doc-name*/index.md</action>
+<action if="sharded found">Read index.md to understand structure</action>
+<action if="sharded found">Read ALL section files listed in index</action>
+<action if="sharded found">Combine content as single document</action>
+```
+
+**Selective Load Pattern (with section ID):**
+
+```xml
+<action>Determine section needed (e.g., epic_num = 3)</action>
+<action>Check for sharded version: {output_folder}/*doc-name*/index.md</action>
+<action if="sharded found">Read ONLY the specific section file needed</action>
+<action if="sharded found">Skip all other section files</action>
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Both whole and sharded exist:**
+
+- Workflows will use whole document (priority rule)
+- Delete or archive the one you don't want
+
+**Index.md out of sync:**
+
+- Delete sharded folder
+- Re-run shard-doc on original
+
+**Workflow can't find document:**
+
+- Check file naming matches patterns (`*prd*.md`, `*epic*.md`, etc.)
+- Verify index.md exists in sharded folder
+- Check output_folder path in config
+
+**Sections too granular:**
+
+- Combine sections in original document
+- Use fewer level 2 headings
+- Re-shard
+
+## Related Documentation
+
+- [shard-doc Tool](../src/core/tools/shard-doc.xml) - Tool implementation
+- [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Workflow overview
+- [Workflow Creation Guide](../src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md) - Custom workflow patterns
+
+---
+
+**Document sharding is optional but powerful** - use it when efficiency matters for large projects!
--- a/docs/ide-info/auggie.md
+++ b/docs/ide-info/auggie.md
@@ -6,8 +6,8 @@ BMAD agents can be installed in multiple locations based on your setup.

 ### Common Locations

- User Home: `~/.auggie/commands/`
- Project: `.auggie/commands/`
+- User Home: `~/.augment/commands/`
+- Project: `.augment/commands/`
 - Custom paths you selected

 ### How to Use
--- a/docs/ide-info/claude-code.md
+++ b/docs/ide-info/claude-code.md
@@ -13,13 +13,13 @@ BMAD agents are installed as slash commands in `.claude/commands/bmad/`.
 ### Examples

 ```
-/bmad-dev - Activate development agent
-/bmad-architect - Activate architect agent
-/bmad-task-setup - Execute setup task
+/bmad:bmm:agents:dev - Activate development agent
+/bmad:bmm:agents:architect - Activate architect agent
+/bmad:bmm:workflows:dev-story - Execute dev-story workflow
 ```

 ### Notes

 - Commands are autocompleted when you type `/`
 - Agent remains active for the conversation
- Start new conversation to switch agents
+- Start a new conversation to switch agents
--- a/docs/ide-info/codex.md
+++ b/docs/ide-info/codex.md
@@ -2,31 +2,20 @@

 ## Activating Agents

-BMAD agents are documented in `AGENTS.md` file in project root.
-
-### CLI Mode
-
-1. **Reference Agent**: Type `@{agent-name}` in prompt
-2. **Execute Task**: Type `@task-{task-name}`
-3. **Active Session**: Agent remains active for conversation
-
-### Web Mode
-
-1. **Navigate**: Go to Agents section in web interface
-2. **Select Agent**: Click to activate agent persona
-3. **Session**: Agent active for browser session
+BMAD agents, tasks and workflows are installed as custom prompts in
+`$CODEX_HOME/prompts/bmad-*.md` files. If `CODEX_HOME` is not set, it
+defaults to `$HOME/.codex/`.

 ### Examples

 ```
-@dev - Activate development agent
-@architect - Activate architect agent
-@task-setup - Execute setup task
+/bmad-bmm-agents-dev - Activate development agent
+/bmad-bmm-agents-architect - Activate architect agent
+/bmad-bmm-workflows-dev-story - Execute dev-story workflow
 ```

 ### Notes

- All agents documented in AGENTS.md
- CLI: Reference with @ syntax
- Web: Use interface to select
- One agent active at a time
+Prompts are autocompleted when you type /
+Agent remains active for the conversation
+Start a new conversation to switch agents
--- a/docs/ide-info/crush.md
+++ b/docs/ide-info/crush.md
@@ -7,7 +7,7 @@ BMAD agents are installed as commands in `.crush/commands/bmad/`.
 ### How to Use

 1. **Open Command Palette**: Use Crush command interface
-2. **Navigate**: Browse to `bmad/{module}/agents/`
+2. **Navigate**: Browse to `{bmad_folder}/{module}/agents/`
 3. **Select Agent**: Choose the agent command
 4. **Execute**: Run to activate agent persona

--- a/docs/ide-info/cursor.md
+++ b/docs/ide-info/cursor.md
@@ -6,20 +6,20 @@ BMAD agents are installed in `.cursor/rules/bmad/` as MDC rules.

 ### How to Use

-1. **Reference in Chat**: Use `@bmad/{module}/agents/{agent-name}`
-2. **Include Entire Module**: Use `@bmad/{module}`
-3. **Reference Index**: Use `@bmad/index` for all available agents
+1. **Reference in Chat**: Use `@{bmad_folder}/{module}/agents/{agent-name}`
+2. **Include Entire Module**: Use `@{bmad_folder}/{module}`
+3. **Reference Index**: Use `@{bmad_folder}/index` for all available agents

 ### Examples

 ```
-@bmad/core/agents/dev - Activate dev agent
-@bmad/bmm/agents/architect - Activate architect agent
-@bmad/core - Include all core agents/tasks
+@{bmad_folder}/core/agents/dev - Activate dev agent
+@{bmad_folder}/bmm/agents/architect - Activate architect agent
+@{bmad_folder}/core - Include all core agents/tasks
 ```

 ### Notes

 - Rules are Manual type - only loaded when explicitly referenced
 - No automatic context pollution
- Can combine multiple agents: `@bmad/core/agents/dev @bmad/core/agents/test`
+- Can combine multiple agents: `@{bmad_folder}/core/agents/dev @{bmad_folder}/core/agents/test`
--- a/docs/ide-info/iflow.md
+++ b/docs/ide-info/iflow.md
@@ -7,7 +7,7 @@ BMAD agents are installed as commands in `.iflow/commands/bmad/`.
 ### How to Use

 1. **Access Commands**: Use iFlow command interface
-2. **Navigate**: Browse to `bmad/agents/` or `bmad/tasks/`
+2. **Navigate**: Browse to `{bmad_folder}/agents/` or `{bmad_folder}/tasks/`
 3. **Select**: Choose the agent or task command
 4. **Execute**: Run to activate

@@ -22,8 +22,8 @@ BMAD agents are installed as commands in `.iflow/commands/bmad/`.
 ### Examples

 ```
-/bmad/agents/core-dev - Activate dev agent
-/bmad/tasks/core-setup - Execute setup task
+/{bmad_folder}/agents/core-dev - Activate dev agent
+/{bmad_folder}/tasks/core-setup - Execute setup task
 ```

 ### Notes
--- a/docs/ide-info/opencode.md
+++ b/docs/ide-info/opencode.md
@@ -0,0 +1,24 @@
+# BMAD Method - OpenCode Instructions
+
+## Activating Agents
+
+BMAD agents are installed as OpenCode agents in `.opencode/agent/BMAD/{module_name}` and workflow commands in `.opencode/command/BMAD/{module_name}`.
+
+### How to Use
+
+1. **Switch Agents**: Press **Tab** to cycle through primary agents or select using the `/agents`
+2. **Activate Agent**: Once the Agent is selected say `hello` or any prompt to activate that agent persona
+3. **Execute Commands**: Type `/bmad` to see and execute bmad workflow commands (commands allow for fuzzy matching)
+
+### Examples
+
+```
+/agents - to see a list of agents and switch between them
+/{bmad_folder}/bmm/workflows/workflow-init - Activate the workflow-init command
+```
+
+### Notes
+
+- Press **Tab** to switch between primary agents (Analyst, Architect, Dev, etc.)
+- Commands are autocompleted when you type `/` and allow for fuzzy matching
+- Workflow commands execute in current agent context, make sure you have the right agent activated before running a command
--- a/docs/index.md
+++ b/docs/index.md
@@ -0,0 +1,227 @@
+# BMad Documentation Index
+
+Complete map of all BMad Method v6 documentation with recommended reading paths.
+
+---
+
+## 🎯 Getting Started (Start Here!)
+
+**New users:** Start with one of these based on your situation:
+
+| Your Situation         | Start Here                                                      | Then Read                                                     |
+| ---------------------- | --------------------------------------------------------------- | ------------------------------------------------------------- |
+| **Brand new to BMad**  | [Quick Start Guide](../src/modules/bmm/docs/quick-start.md)     | [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) |
+| **Upgrading from v4**  | [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)                 | [Quick Start Guide](../src/modules/bmm/docs/quick-start.md)   |
+| **Brownfield project** | [Brownfield Guide](../src/modules/bmm/docs/brownfield-guide.md) | [Quick Start Guide](../src/modules/bmm/docs/quick-start.md)   |
+
+---
+
+## 📋 Core Documentation
+
+### Project-Level Docs (Root)
+
+- **[README.md](../README.md)** - Main project overview, feature summary, and module introductions
+- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - How to contribute, pull request guidelines, code style
+- **[CHANGELOG.md](../CHANGELOG.md)** - Version history and breaking changes
+- **[CLAUDE.md](../CLAUDE.md)** - Claude Code specific guidelines for this project
+
+### Installation & Setup
+
+- **[v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)** - Migration path for v4 users
+- **[Document Sharding Guide](./document-sharding-guide.md)** - Split large documents for 90%+ token savings
+- **[Web Bundles](./USING_WEB_BUNDLES.md)** - Use BMAD agents in Claude Projects, ChatGPT, or Gemini without installation
+- **[Bundle Distribution Setup](./BUNDLE_DISTRIBUTION_SETUP.md)** - Maintainer guide for bundle auto-publishing
+
+---
+
+## 🏗️ Module Documentation
+
+### BMad Method (BMM) - Software & Game Development
+
+The flagship module for agile AI-driven development.
+
+- **[BMM Module README](../src/modules/bmm/README.md)** - Module overview, agents, and complete documentation index
+- **[BMM Documentation](../src/modules/bmm/docs/)** - All BMM-specific guides and references:
+  - [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Step-by-step guide to building your first project
+  - [Quick Spec Flow](../src/modules/bmm/docs/quick-spec-flow.md) - Rapid Level 0-1 development
+  - [Scale Adaptive System](../src/modules/bmm/docs/scale-adaptive-system.md) - Understanding the 5-level system
+  - [Brownfield Guide](../src/modules/bmm/docs/brownfield-guide.md) - Working with existing codebases
+- **[BMM Workflows Guide](../src/modules/bmm/workflows/README.md)** - **ESSENTIAL READING**
+- **[Test Architect Guide](../src/modules/bmm/testarch/README.md)** - Testing strategy and quality assurance
+
+### BMad Builder (BMB) - Create Custom Solutions
+
+Build your own agents, workflows, and modules.
+
+- **[BMB Module README](../src/modules/bmb/README.md)** - Module overview and capabilities
+- **[Agent Creation Guide](../src/modules/bmb/workflows/create-agent/README.md)** - Design custom agents
+
+### Creative Intelligence Suite (CIS) - Innovation & Creativity
+
+AI-powered creative thinking and brainstorming.
+
+- **[CIS Module README](../src/modules/cis/README.md)** - Module overview and workflows
+
+---
+
+## 🖥️ IDE-Specific Guides
+
+Instructions for loading agents and running workflows in your development environment.
+
+**Popular IDEs:**
+
+- [Claude Code](./ide-info/claude-code.md)
+- [Cursor](./ide-info/cursor.md)
+- [VS Code](./ide-info/windsurf.md)
+
+**Other Supported IDEs:**
+
+- [Augment](./ide-info/auggie.md)
+- [Cline](./ide-info/cline.md)
+- [Codex](./ide-info/codex.md)
+- [Crush](./ide-info/crush.md)
+- [Gemini](./ide-info/gemini.md)
+- [GitHub Copilot](./ide-info/github-copilot.md)
+- [IFlow](./ide-info/iflow.md)
+- [Kilo](./ide-info/kilo.md)
+- [OpenCode](./ide-info/opencode.md)
+- [Qwen](./ide-info/qwen.md)
+- [Roo](./ide-info/roo.md)
+- [Trae](./ide-info/trae.md)
+
+**Key concept:** Every reference to "load an agent" or "activate an agent" in the main docs links to the [ide-info](./ide-info/) directory for IDE-specific instructions.
+
+---
+
+## 🔧 Advanced Topics
+
+### Installation & Bundling
+
+- [IDE Injections Reference](./installers-bundlers/ide-injections.md) - How agents are installed to IDEs
+- [Installers & Platforms Reference](./installers-bundlers/installers-modules-platforms-reference.md) - CLI tool and platform support
+- [Web Bundler Usage](./installers-bundlers/web-bundler-usage.md) - Creating web-compatible bundles
+
+---
+
+## 📊 Documentation Map
+
+```
+docs/                              # Core/cross-module documentation
+├── index.md (this file)
+├── v4-to-v6-upgrade.md
+├── document-sharding-guide.md
+├── ide-info/                      # IDE setup guides
+│   ├── claude-code.md
+│   ├── cursor.md
+│   ├── windsurf.md
+│   └── [14+ other IDEs]
+└── installers-bundlers/           # Installation reference
+    ├── ide-injections.md
+    ├── installers-modules-platforms-reference.md
+    └── web-bundler-usage.md
+
+src/modules/
+├── bmm/                           # BMad Method module
+│   ├── README.md                  # Module overview & docs index
+│   ├── docs/                      # BMM-specific documentation
+│   │   ├── quick-start.md
+│   │   ├── quick-spec-flow.md
+│   │   ├── scale-adaptive-system.md
+│   │   └── brownfield-guide.md
+│   ├── workflows/README.md        # ESSENTIAL workflow guide
+│   └── testarch/README.md         # Testing strategy
+├── bmb/                           # BMad Builder module
+│   ├── README.md
+│   └── workflows/create-agent/README.md
+└── cis/                           # Creative Intelligence Suite
+    └── README.md
+```
+
+---
+
+## 🎓 Recommended Reading Paths
+
+### Path 1: Brand New to BMad (Software Project)
+
+1. [README.md](../README.md) - Understand the vision
+2. [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Get hands-on
+3. [BMM Module README](../src/modules/bmm/README.md) - Understand agents
+4. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Master the methodology
+5. [Your IDE guide](./ide-info/) - Optimize your workflow
+
+### Path 2: Game Development Project
+
+1. [README.md](../README.md) - Understand the vision
+2. [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Get hands-on
+3. [BMM Module README](../src/modules/bmm/README.md) - Game agents are included
+4. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Game workflows
+5. [Your IDE guide](./ide-info/) - Optimize your workflow
+
+### Path 3: Upgrading from v4
+
+1. [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md) - Understand what changed
+2. [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Reorient yourself
+3. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Learn new v6 workflows
+
+### Path 4: Working with Existing Codebase (Brownfield)
+
+1. [Brownfield Guide](../src/modules/bmm/docs/brownfield-guide.md) - Approach for legacy code
+2. [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Follow the process
+3. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Master the methodology
+
+### Path 5: Building Custom Solutions
+
+1. [BMB Module README](../src/modules/bmb/README.md) - Understand capabilities
+2. [Agent Creation Guide](../src/modules/bmb/workflows/create-agent/README.md) - Create agents
+3. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Understand workflow structure
+
+### Path 6: Contributing to BMad
+
+1. [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines
+2. Relevant module README - Understand the area you're contributing to
+3. [Code Style section in CONTRIBUTING.md](../CONTRIBUTING.md#code-style) - Follow standards
+
+---
+
+## 🔍 Quick Reference
+
+**What is each module for?**
+
+- **BMM** - AI-driven software and game development
+- **BMB** - Create custom agents and workflows
+- **CIS** - Creative thinking and brainstorming
+
+**How do I load an agent?**
+→ See [ide-info](./ide-info/) folder for your IDE
+
+**I'm stuck, what's next?**
+→ Check the [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) or run `workflow-status`
+
+**I want to contribute**
+→ Start with [CONTRIBUTING.md](../CONTRIBUTING.md)
+
+---
+
+## 📚 Important Concepts
+
+### Fresh Chats
+
+Each workflow should run in a fresh chat with the specified agent to avoid context limitations. This is emphasized throughout the docs because it's critical to successful workflows.
+
+### Scale Levels
+
+BMM adapts to project complexity (Levels 0-4). Documentation is scale-adaptive - you only need what's relevant to your project size.
+
+### Update-Safe Customization
+
+All agent customizations go in `{bmad_folder}/_cfg/agents/` and survive updates. See your IDE guide and module README for details.
+
+---
+
+## 🆘 Getting Help
+
+- **Discord**: [Join the BMad Community](https://discord.gg/gk8jAdXWmj)
+  - #general-dev - Technical questions
+  - #bugs-issues - Bug reports
+- **Issues**: [GitHub Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues)
+- **YouTube**: [BMad Code Channel](https://www.youtube.com/@BMadCode)
--- a/docs/installers-bundlers/ide-injections.md
+++ b/docs/installers-bundlers/ide-injections.md
@@ -158,7 +158,7 @@ src/modules/bmm/

 ```yaml
 injections:
-  - file: 'bmad/bmm/agents/pm.md'
+  - file: '{bmad_folder}/bmm/agents/pm.md'
    point: 'pm-agent-instructions'
    requires: 'any' # Injected if ANY subagent is selected
    content: |
@@ -166,7 +166,7 @@ injections:
        <i>Use 'market-researcher' subagent for analysis</i>
      </llm>

-  - file: 'bmad/bmm/templates/prd.md'
+  - file: '{bmad_folder}/bmm/templates/prd.md'
    point: 'prd-goals-context-delegation'
    requires: 'market-researcher' # Only if this specific subagent selected
    content: |
@@ -184,13 +184,3 @@ injections:
  <cmds>...</cmds>
 </agent>
 ```
-
-## Testing Checklist
-
- [ ] Injection points are properly named and unique
- [ ] injections.yaml is valid YAML with correct structure
- [ ] Content formatting is preserved after injection
- [ ] Installation works without the IDE (injection points removed)
- [ ] Installation works with the IDE (content properly injected)
- [ ] Subagents/files are copied to correct locations
- [ ] No IDE-specific content remains when different IDE selected
--- a/docs/installers-bundlers/installers-modules-platforms-reference.md
+++ b/docs/installers-bundlers/installers-modules-platforms-reference.md
@@ -1,4 +1,4 @@
-# BMAD v6 Installation & Module System Reference
+# BMAD Installation & Module System Reference

 ## Table of Contents

@@ -13,63 +13,36 @@

 ## Overview

-BMAD v6 is a modular AI agent framework with intelligent installation, platform-agnostic support, and configuration inheritance.
+BMad Core is a modular AI agent framework with intelligent installation, platform-agnostic support, and configuration inheritance.

 ### Key Features

- **Modular Design**: Core + optional modules (BMM, CIS)
+- **Modular Design**: Core + optional modules (BMB, BMM, CIS)
 - **Smart Installation**: Interactive configuration with dependency resolution
- **Multi-Platform**: Supports 15+ AI coding platforms
- **Clean Architecture**: Centralized `bmad/` directory, no source pollution
-
-## Quick Start
-
-```bash
-# Interactive installation (recommended)
-bmad install
-
-# Install specific modules
-bmad install -m bmm cis
-
-# Full installation
-bmad install -f
-
-# Check status
-bmad status
-```
-
-### Installation Options
-
- `-d <path>`: Target directory (default: current)
- `-m <modules...>`: Specific modules (bmm, cis)
- `-f`: Full installation
- `-c`: Core only
- `-i <ide...>`: Configure specific IDEs
- `--skip-ide`: Skip IDE configuration
- `-v`: Verbose output
+- **Clean Architecture**: Centralized `{bmad_folder}` directory add to project, no source pollution with multiple folders added

 ## Architecture

-### Directory Structure
+### Directory Structure upon installation

 ```
 project-root/
-├── bmad/                    # Centralized installation
-│   ├── _cfg/               # Configuration
-│   │   ├── agents/         # Agent configs
-│   │   └── agent-party.xml # Agent manifest
-│   ├── core/               # Core module
+├── {bmad_folder}/             # Centralized installation
+│   ├── _cfg/                  # Configuration
+│   │   ├── agents/            # Agent configs
+│   │   └── agent-manifest.csv # Agent manifest
+│   ├── core/                  # Core module
 │   │   ├── agents/
 │   │   ├── tasks/
 │   │   └── config.yaml
-│   ├── bmm/                # BMad Method module
+│   ├── bmm/                   # BMad Method module
 │   │   ├── agents/
 │   │   ├── tasks/
-│   │   ├── templates/
+│   │   ├── workflows/
 │   │   └── config.yaml
-│   └── cis/                # Creative Innovation Studio
+│   └── cis/                   # Creative Innovation Studio
 │       └── ...
-└── .claude/                # Platform-specific (example)
+└── .claude/                   # Platform-specific (example)
    └── agents/
 ```

@@ -78,11 +51,10 @@ project-root/
 1. **Detection**: Check existing installation
 2. **Selection**: Choose modules interactively or via CLI
 3. **Configuration**: Collect module-specific settings
-4. **Platform Setup**: Configure AI coding platforms
-5. **Installation**: Process and copy files
-6. **Generation**: Create config files with inheritance
-7. **Post-Install**: Run module installers
-8. **Manifest**: Track installed components
+4. **Installation**: Compile Process and copy files
+5. **Generation**: Create config files with inheritance
+6. **Post-Install**: Run module installers
+7. **Manifest**: Track installed components

 ### Key Exclusions

@@ -121,7 +93,7 @@ Creative Innovation Studio for design workflows
 src/modules/{module}/
 ├── _module-installer/       # Not copied to destination
 │   ├── installer.js        # Post-install logic
-│   └── install-menu-config.yaml
+│   └── install-config.yaml
 ├── agents/
 ├── tasks/
 ├── templates/
@@ -135,7 +107,7 @@ src/modules/{module}/

 ### Collection Process

-Modules define prompts in `install-menu-config.yaml`:
+Modules define prompts in `install-config.yaml`:

 ```yaml
 project_name:
@@ -212,7 +184,7 @@ Cline, Roo, Auggie, GitHub Copilot, Codex, Gemini, Qwen, Trae, Kilo, Crush, iFlo

   ```yaml
   injections:
-     - file: 'bmad/bmm/agents/pm.md'
+     - file: '{bmad_folder}/bmm/agents/pm.md'
       point: 'pm-agent-instructions'
       content: |
         <i>Platform-specific instruction</i>
@@ -246,12 +218,12 @@ Platform-specific content without source modification:
   src/modules/mymod/
   ├── _module-installer/
   │   ├── installer.js
-   │   └── install-menu-config.yaml
+   │   └── install-config.yaml
   ├── agents/
   └── tasks/
   ```

-2. **Configuration** (`install-menu-config.yaml`)
+2. **Configuration** (`install-config.yaml`)

   ```yaml
   code: mymod
@@ -298,14 +270,14 @@ Generated in: `bmad/_cfg/agents/{module}-{agent}.md`

 ### Common Issues

-| Issue                     | Solution                            |
-| ------------------------- | ----------------------------------- |
-| Existing installation     | Use `bmad update` or remove `bmad/` |
-| Module not found          | Check `src/modules/` exists         |
-| Config not applied        | Verify `bmad/{module}/config.yaml`  |
-| Missing config.yaml       | Fixed: All modules now get configs  |
-| Agent unavailable         | Check for `localskip="true"`        |
-| \_module-installer copied | Fixed: Now excluded from copy       |
+| Issue                   | Solution                                     |
+| ----------------------- | -------------------------------------------- |
+| Existing installation   | Use `bmad update` or remove `{bmad_folder}/` |
+| Module not found        | Check `src/modules/` exists                  |
+| Config not applied      | Verify `{bmad_folder}/{module}/config.yaml`  |
+| Missing config.yaml     | Fixed: All modules now get configs           |
+| Agent unavailable       | Check for `localskip="true"`                 |
+| module-installer copied | Fixed: Now excluded from copy                |

 ### Debug Commands

@@ -317,19 +289,19 @@ bmad status -v      # Detailed status
 ### Best Practices

 1. Run from project root
-2. Backup `bmad/_cfg/` before updates
+2. Backup `{bmad_folder}/_cfg/` before updates
 3. Use interactive mode for guidance
 4. Review generated configs post-install

 ## Migration from v4

-| v4                  | v6                  |
-| ------------------- | ------------------- |
-| Scattered files     | Centralized `bmad/` |
-| Monolithic          | Modular             |
-| Manual config       | Interactive setup   |
-| Limited IDE support | 15+ platforms       |
-| Source modification | Clean injection     |
+| v4                  | v6                           |
+| ------------------- | ---------------------------- |
+| Scattered files     | Centralized `{bmad_folder}/` |
+| Monolithic          | Modular                      |
+| Manual config       | Interactive setup            |
+| Limited IDE support | 15+ platforms                |
+| Source modification | Clean injection              |

 ## Technical Notes

@@ -339,6 +311,66 @@ bmad status -v      # Detailed status
 - Agent references (cross-module)
 - Template dependencies
 - Partial module installation (only required files)
+- Workflow vendoring for standalone module operation
+
+## Workflow Vendoring
+
+**Problem**: Modules that reference workflows from other modules create dependencies, forcing users to install multiple modules even when they only need one.
+
+**Solution**: Workflow vendoring allows modules to copy workflows from other modules during installation, making them fully standalone.
+
+### How It Works
+
+Agents can specify both `workflow` (source location) and `workflow-install` (destination location) in their menu items:
+
+```yaml
+menu:
+  - trigger: create-story
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story/workflow.yaml'
+    workflow-install: '{project-root}/{bmad_folder}/bmgd/workflows/4-production/create-story/workflow.yaml'
+    description: 'Create a game feature story'
+```
+
+**During Installation:**
+
+1. **Vendoring Phase**: Before copying module files, the installer:
+   - Scans source agent YAML files for `workflow-install` attributes
+   - Copies entire workflow folders from `workflow` path to `workflow-install` path
+   - Updates vendored `workflow.yaml` files to reference target module's config
+
+2. **Compilation Phase**: When compiling agents:
+   - If `workflow-install` exists, uses its value for the `workflow` attribute
+   - `workflow-install` is build-time metadata only, never appears in final XML
+   - Compiled agent references vendored workflow location
+
+3. **Config Update**: Vendored workflows get their `config_source` updated:
+
+   ```yaml
+   # Source workflow (in bmm):
+   config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
+
+   # Vendored workflow (in bmgd):
+   config_source: "{project-root}/{bmad_folder}/bmgd/config.yaml"
+   ```
+
+**Result**: Modules become completely standalone with their own copies of needed workflows, configured for their specific use case.
+
+### Example Use Case: BMGD Module
+
+The BMad Game Development module vendors implementation workflows from BMM:
+
+- Game Dev Scrum Master agent references BMM workflows
+- During installation, workflows are copied to `bmgd/workflows/4-production/`
+- Vendored workflows use BMGD's config (with game-specific settings)
+- BMGD can be installed without BMM dependency
+
+### Benefits
+
+✅ **Module Independence** - No forced dependencies
+✅ **Clean Namespace** - Workflows live in their module
+✅ **Config Isolation** - Each module uses its own configuration
+✅ **Customization Ready** - Vendored workflows can be modified independently
+✅ **No User Confusion** - Avoid partial module installations

 ### File Processing

@@ -346,6 +378,7 @@ bmad status -v      # Detailed status
 - Excludes `_module-installer/` directories
 - Replaces path placeholders at runtime
 - Injects activation blocks
+- Vendors cross-module workflows (see Workflow Vendoring below)

 ### Web Bundling

--- a/docs/installers-bundlers/web-bundler-usage.md
+++ b/docs/installers-bundlers/web-bundler-usage.md
@@ -1,54 +0,0 @@
-# Web Bundler Usage
-
-ALPHA NOTE: Bundling of individual agents might work, team bundling is being reworked and will come with Beta release soon.
-
-The web bundler creates self-contained XML bundles for BMAD agents, packaging all dependencies for web deployment.
-
-## Quick Start
-
-```bash
-# Bundle all agents from all modules
-npm run bundle
-
-# Clean and rebundle (removes old bundles first)
-npm run rebundle
-```
-
-## Custom Output Directory
-
-```bash
-# Bundle to custom directory
-node tools/cli/bundlers/bundle-web.js all --output ./my-bundles
-
-# Rebundle to custom directory (auto-cleans first)
-node tools/cli/bundlers/bundle-web.js rebundle --output /absolute/path/to/custom/directory
-
-# Bundle specific module to custom directory
-node tools/cli/bundlers/bundle-web.js module bmm --output ./custom-folder
-
-# Bundle specific agent to custom directory
-node tools/cli/bundlers/bundle-web.js agent bmm analyst -o ./custom-folder
-```
-
-## Output
-
-Bundles are generated in `web-bundles/` directory by default when run from the root of the clones project:
-
-```
-web-bundles/
-├── [module-name]/
-│   └── agents/
-│       └── [agent-name].xml
-```
-
-## Skipping Agents
-
-Agents with `bundle="false"` attribute are automatically skipped during bundling.
-
-## Bundle Contents
-
-Each bundle includes:
-
- Agent definition with web activation
- All resolved dependencies
- Manifests for agent/team discovery
--- a/docs/v4-to-v6-upgrade.md
+++ b/docs/v4-to-v6-upgrade.md
@@ -0,0 +1,227 @@
+# BMad v4 to v6 Upgrade Guide
+
+## Overview
+
+BMad v6 represents a complete ground-up rewrite with significant architectural changes. This guide will help you migrate your v4 project to v6.
+
+---
+
+## Automatic V4 Detection
+
+When you run `npm run install:bmad` on a project with v4 installed, the installer automatically detects:
+
+- **Legacy folders**: Any folders starting with `.bmad`, `bmad` (lowercase), or `Bmad`
+- **IDE command artifacts**: Legacy bmad folders in IDE configuration directories (`.claude/commands/`, `.cursor/commands/`, etc.)
+
+### What Happens During Detection
+
+1. **Automatic Backup of v4 Modules**: All `.bmad-*` folders are moved to `v4-backup/` in your project root
+   - If a backup already exists, a timestamp is added to avoid conflicts
+   - Example: `.bmad-core` → `v4-backup/.bmad-core`
+   - Your project files and data are NOT affected
+
+2. **IDE Command Cleanup Recommended**: Legacy v4 IDE commands should be manually removed
+   - Located in IDE config folders: `.claude/commands/`, `.cursor/commands/`, etc.
+   - These old commands would still reference v4 folder structure if left in place
+   - The installer provides copy/paste terminal commands for your platform
+   - You can proceed without cleanup, but removing them prevents confusion with old v4 commands
+
+---
+
+## Module Migration
+
+### Deprecated Modules
+
+| v4 Module                     | v6 Status                                        |
+| ----------------------------- | ------------------------------------------------ |
+| `.bmad-2d-phaser-game-dev`    | Integrated into BMM                              |
+| `.bmad-2d-unity-game-dev`     | Integrated into BMM                              |
+| `.bmad-godot-game-dev`        | Integrated into BMM                              |
+| `.bmad-*-game-dev` (any)      | Integrated into BMM                              |
+| `.bmad-infrastructure-devops` | Deprecated - New core devops agent coming in BMM |
+| `.bmad-creative-writing`      | Not adapted - New module releasing soon          |
+
+**Game Development**: All game development functionality has been consolidated and expanded within the BMM (BMad Method) module. Game-specific workflows now adapt to your game type and engine.
+
+---
+
+## Architecture Changes
+
+### Folder Structure
+
+**v4 "Expansion Packs" Structure:**
+
+```
+your-project/
+├── .bmad-core/           # Was actually the BMad Method
+├── .bmad-game-dev/       # Separate expansion packs
+├── .bmad-creative-writing/
+└── .bmad-infrastructure-devops/
+```
+
+**v6 Unified Structure:**
+
+```
+your-project/
+└── {bmad_folder}/       # Single installation folder, default .bmad
+    ├── core/            # Real core framework (applies to all modules)
+    ├── bmm/             # BMad Method (software/game dev)
+    ├── bmb/             # BMad Builder (create agents/workflows)
+    ├── cis/             # Creative Intelligence Suite
+    └── _cfg/            # Your customizations
+        └── agents/      # Agent customization files
+```
+
+### Key Concept Changes
+
+- **v4 `.bmad-core`**: Was actually the BMad Method
+- **v6 `{bmad_folder}/core/`**: Is the real universal core framework
+- **v6 `{bmad_folder}/bmm/`**: Is the BMad Method module
+- **Module identification**: All modules now have a `config.yaml` file
+
+---
+
+## Project Progress Migration
+
+### If You've Completed Planning Phase (PRD/Architecture) with the BMad Method:
+
+After running the v6 installer:
+
+1. **Run `workflow-init`** workflow to set up the guided workflow system
+2. **Specify your project level** when prompted:
+   - If you followed v4's full workflow (PRD → Architecture → Stories), select **Level 3 or 4**
+   - This tells v6 you've already completed planning and solutioning phases
+3. **Document paths**: Keep your existing paths during installation
+   - Default PRD/Architecture location: `docs/`
+   - Default stories location: `docs/sprint-artifacts/`
+   - **Accept these defaults** if you're already using them in v4
+
+> **Important**: v6 workflows can handle both sharded and unsharded documents. You don't need to restructure your existing PRD or architecture files.
+
+### If You're Mid-Development (Stories Created/Implemented)
+
+1. Complete the v6 installation as above
+2. Run `workflow-init` and specify Level 3 or 4
+3. When ready to continue development, run the **`sprint-planning`** workflow (Phase 4)
+
+---
+
+## Agent Customization Migration
+
+### v4 Agent Customization
+
+In v4, you may have modified agent files directly in `.bmad-*` folders.
+
+### v6 Agent Customization
+
+**All customizations** now go in `{bmad_folder}/_cfg/agents/` using customize files:
+
+**Example: Renaming an agent and changing communication style**
+
+File: `{bmad_folder}/_cfg/agents/bmm-pm.customize.yaml`
+
+```yaml
+# Customize the PM agent
+persona:
+  name: 'Captain Jack' # Override agent name
+  role: 'Swashbuckling Product Owner'
+  communication_style: |
+    - Talk like a pirate
+    - Use nautical metaphors for software concepts
+    - Always upbeat and adventurous
+```
+
+**How it works:**
+
+- Base agent: `{bmad_folder}/bmm/agents/pm.md`
+- Customization: `{bmad_folder}/_cfg/agents/bmm-pm.customize.yaml`
+- Result: Agent uses your custom name and style, but updates don't overwrite your changes
+
+---
+
+## Document Compatibility
+
+### Sharded vs Unsharded Documents
+
+**Good news**: Unlike v4, v6 workflows are **fully flexible** with document structure:
+
+- ✅ Sharded documents (split into multiple files)
+- ✅ Unsharded documents (single file per section)
+- ✅ Custom sections for your project type
+- ✅ Mixed approaches
+
+All workflow files are scanned automatically. No manual configuration needed.
+
+---
+
+## Installation Steps
+
+### 1. Clone Repository
+
+```bash
+git clone https://github.com/bmad-code-org/BMAD-METHOD
+cd BMAD-METHOD
+npm install
+```
+
+### 2. Run Installer on Your v4 Project
+
+```bash
+npx bmad-method install
+```
+
+**Enter the full path to your v4 project** when prompted.
+
+### 3. Follow Interactive Prompts
+
+The installer will:
+
+1. Detect v4 installation and offer to backup `.bmad-*` folders
+2. Prompt for recommended cleanup (you can skip)
+3. Let you select modules (recommend: BMM for software and or game development)
+4. Configure core settings (name, language, etc.)
+5. Configure module-specific options
+6. Configure IDE integrations
+
+### 4. Accept Default Paths
+
+If you're using:
+
+- `docs/` for PRD and architecture
+- `docs/sprint-artifacts/` for story files
+
+**Accept these defaults** during installation.
+
+### 5. Initialize Workflow
+
+After installation:
+
+1. **Load the Analyst agent** - See your IDE-specific instructions in [docs/ide-info](./ide-info/) for how to activate agents:
+   - [Claude Code](./ide-info/claude-code.md)
+   - [Cursor](./ide-info/cursor.md)
+   - [VS Code/Windsurf](./ide-info/) - Check your IDE folder
+
+2. **Wait for the agent's menu** to appear
+
+3. **Tell the agent**: `*workflow-init` - v6 supports excellent natural language fuzzy matching, so you could also say "workflow init" or "please init the workflow"
+
+Since you are migrating an existing project from v4, it's most likely **Level 3 or 4** you will want to suggest when asked - if you've already completed PRD/architecture in v4.
+
+---
+
+## Post-Migration Checklist
+
+- [ ] v4 folders backed up to `v4-backup/`
+- [ ] v6 installed to `{bmad_folder}/` folder
+- [ ] `workflow-init` run with correct project level selected
+- [ ] Agent customizations migrated to `{bmad_folder}/_cfg/agents/` if needed
+- [ ] IDE integration working (test by listing agents)
+- [ ] For active development: `sprint-planning` workflow executed
+
+---
+
+## Getting Help
+
+- **Discord**: [Join the BMad Community](https://discord.gg/gk8jAdXWmj)
+- **Issues**: [GitHub Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues)
+- **Docs**: Check `{bmad_folder}/docs/` in your installation for IDE-specific instructions
--- a/docs/v6-open-items.md
+++ b/docs/v6-open-items.md
@@ -0,0 +1,17 @@
+# v6 Pending Items
+
+Before calling this beta
+
+- finalize web bundler
+- some subagents working again
+- knowledge base for bmad
+
+## Needed Beta → v0 release
+
+Aside from stability and bug fixes found during the alpha period - the main focus will be on the following:
+
+- knowledge base for BMM
+- Module repository and submission process defined
+- MCP Injections based on installation selection
+- sub agent for open-code and claude code optimization
+- TDD Workflow Integration
--- a/docs/web-bundles-gemini-gpt-guide.md
+++ b/docs/web-bundles-gemini-gpt-guide.md
@@ -0,0 +1,473 @@
+# Using BMad Web Bundles in Gemini Gems & Custom GPTs
+
+Web bundles package BMad agents as self-contained XML files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file.
+
+## What Are Web Bundles?
+
+Web bundles are standalone XML files containing:
+
+- Complete agent persona and instructions
+- All workflows and dependencies
+- Interactive menu system
+- Party mode for multi-agent collaboration
+- No external files required
+
+**Perfect for:** Uploading a single file to a Gemini GEM or Custom GPT to use BMad Method from the Web, generally at a huge cost savings, at the expense of some quality and convenience of using locally.
+
+## Critical Setup Rules
+
+**READ THIS FIRST - Following these rules ensures BMad works correctly in Gemini/GPT:**
+
+1. **ONE file per Gem/GPT** - Upload exactly ONE XML file per Gemini Gem or Custom GPT instance. Do NOT combine multiple agent files.
+
+2. **Use the setup instructions** - When creating your Gem/GPT, you MUST add the configuration prompt (shown in Quick Start below) so it knows how to read the XML file.
+
+3. **Enable Canvas/Code Execution** - This is ESSENTIAL for document generation workflows (PRD, Architecture, etc.). Enable this in your Gem/GPT settings.
+
+4. **Gemini Gems are strongly preferred** - They work significantly better than Custom GPTs for BMad workflows.
+
+5. **Team bundles = Gemini 2.5 Pro+ only** - Team bundles (multiple agents) have terrible performance in Custom GPTs due to context limits. Only use them with Gemini 2.5 Pro or higher.
+
+6. **Create separate Gems for each agent** - Make a PM Gem, an Architect Gem, a Developer Gem, etc. Don't try to combine them (except via official team bundles).
+
+## Quick Start
+
+### 1. Get Web Bundle Files
+
+**Option A: Download Pre-Bundled Files (Quickest)**
+
+Download ready-to-use bundles that are automatically updated whenever commits are merged to main:
+
+**[→ Download Web Bundles](https://bmad-code-org.github.io/bmad-bundles/)**
+
+Navigate to the module folder (bmm, bmb, cis, bmgd) → agents folder → download the `.xml` file you need. These bundles are automatically regenerated and deployed with every commit to the main branch, ensuring you always have the latest version.
+
+**Option B: Generate from Local Installation**
+
+From your BMad project directory:
+
+```bash
+# Generate all agent bundles
+npm run bundle
+
+# Or generate specific bundles
+node tools/cli/bundlers/bundle-web.js module bmm
+node tools/cli/bundlers/bundle-web.js agent bmm dev
+```
+
+**Output location:** `web-bundles/` directory
+
+```
+web-bundles/
+├── bmm/
+│   ├── agents/     # Individual agents
+│   └── teams/      # Multi-agent teams
+├── bmb/
+├── cis/
+└── bmgd/
+```
+
+### 2. Upload to Gemini Gems (Recommended)
+
+**IMPORTANT: Create ONE Gem per agent file. Do NOT upload multiple agent files to a single Gem.**
+
+**Create a Gem:**
+
+1. Go to [Google AI Studio](https://aistudio.google.com/)
+2. Click "New Gem" or "Create Gem"
+3. Give your Gem a name (e.g., "BMad PM Agent")
+4. **Enable "Code execution" for best results with document generation**
+5. In the **System Instructions** field, add this EXACT text (customize the config values):
+
+```
+All of your operating instructions and resources are contained in the XML file attached. Read in the initial agent block and instructions to understand it. You will not deviate from the character and rules outlined in the attached!
+
+CONFIG.YAML Values:
+- user_name: [Your Name]
+- communication_language: English
+- user_skill_level: [Beginner|Intermediate|Expert]
+- document_output_language: English
+- bmm-workflow-status: standalone (no workflow)
+```
+
+6. **Upload ONE XML file** (e.g., `pm.xml`) - either attach as a file or paste contents
+7. Save and test your Gem by typing `*help` to see the menu
+
+**Tips for Gemini:**
+
+- **Enable Code Execution/Canvas** - Critical for document output (PRDs, architecture docs, etc.)
+- **Use Gemini 2.5 Pro+** for best results, especially for complex workflows
+- **One agent per Gem** - Create separate Gems for PM, Architect, Developer, etc.
+- Test the agent by triggering menu items with `*workflow-name`
+
+### 3. Upload to Custom GPTs
+
+**IMPORTANT: Create ONE Custom GPT per agent file. Do NOT upload multiple agent files to a single GPT.**
+
+**Create a Custom GPT:**
+
+1. Go to [ChatGPT](https://chat.openai.com/)
+2. Click your profile → "My GPTs" → "Create a GPT"
+3. Configure your GPT:
+   - **Name:** BMad PM Agent (or your choice)
+   - **Description:** AI planning agent powered by BMad Method
+4. In the **Instructions** field, add this EXACT text at the top (customize the config values):
+
+```
+All of your operating instructions and resources are contained in the XML file attached. Read in the initial agent block and instructions to understand it. You will not deviate from the character and rules outlined in the attached!
+
+CONFIG.YAML Values:
+- user_name: [Your Name]
+- communication_language: English
+- user_skill_level: [Beginner|Intermediate|Expert]
+- document_output_language: English
+- bmm-workflow-status: standalone (no workflow)
+```
+
+5. **Below that text**, paste the entire contents of ONE XML file (e.g., `pm.xml`)
+6. **Enable "Canvas" in ChatGPT settings** for better document output
+7. Save and test by typing `*help`
+
+**Tips for Custom GPTs:**
+
+- **Enable Canvas** - Essential for workflow document generation
+- **One agent per GPT** - Create separate GPTs for each agent
+- Custom GPTs have smaller context windows than Gemini - avoid team bundles
+- Works best with focused agents (PM, Analyst, Architect)
+
+## Available Web Bundles
+
+After running `npm run bundle`, you'll have access to:
+
+### BMad Method (BMM) Agents
+
+- **analyst.xml** - Business analysis and requirements gathering
+- **architect.xml** - System architecture and technical design
+- **dev.xml** - Full-stack development and implementation
+- **pm.xml** - Product management and planning
+- **sm.xml** - Scrum master and agile facilitation
+- **tea.xml** - Test architecture and quality assurance
+- **tech-writer.xml** - Technical documentation
+- **ux-designer.xml** - User experience design
+- **game-designer.xml** - Game design and mechanics
+- **game-dev.xml** - Game development
+- **game-architect.xml** - Game architecture
+
+### BMad Builder (BMB) Agent
+
+- **bmad-builder.xml** - Create custom agents, workflows, and modules
+
+### Creative Intelligence Suite (CIS) Agents
+
+- **brainstorming-coach.xml** - Creative brainstorming facilitation
+- **design-thinking-coach.xml** - Human-centered problem solving
+- **innovation-strategist.xml** - Innovation and strategy
+- **creative-problem-solver.xml** - Breakthrough problem solving
+- **storyteller.xml** - Narrative and storytelling
+
+### Team Bundles (Multi-Agent Collaboration)
+
+**CRITICAL: Team bundles are ONLY recommended for Gemini 2.5 Pro+ in the web. The experience is poor with Custom GPTs due to limited context windows.**
+
+- **bmm/teams/team-fullstack.xml** - Full BMad Method development team
+- **bmgd/teams/team-gamedev.xml** - Game development team
+- **cis/teams/creative-squad.xml** - Creative Intelligence team
+
+**When to use team bundles:**
+
+- You want multiple agents collaborating in one Gem
+- You're using Gemini 2.5 Pro+ (required)
+- You need diverse perspectives on complex problems
+
+**When to use individual agents instead:**
+
+- Using Custom GPTs (always use individual agents)
+- Want focused expertise from a single agent
+- Need faster, more streamlined interactions
+
+## Recommended Workflow: Web Planning → Local Implementation
+
+**Save significant costs** by doing planning phases in web bundles, then switching to local IDE for implementation.
+
+### Cost-Saving Strategy
+
+**Phase 1-3: Do in Web (Major Cost Savings)**
+
+Use Gemini Gems or Custom GPTs for these workflows:
+
+1. **Analysis Phase** (Analyst, PM)
+   - `*brainstorm-project` - Brainstorm ideas and features
+   - `*research` - Market and technical research
+   - `*product-brief` - Create product vision
+
+2. **Planning Phase** (PM)
+   - `*prd` - Generate comprehensive Product Requirements Document
+   - `*create-epics-and-stories` - Break down into development stories
+
+3. **Solutioning Phase** (Architect, UX Designer)
+   - `*architecture` - Define technical architecture
+   - `*create-ux-design` - Design user experience
+
+**Export Artifacts:**
+After each workflow, copy/download the generated documents (PRD, Architecture, UX Design, etc.)
+
+**Phase 4: Switch to Local IDE (Required for Implementation)**
+
+1. Save exported artifacts to your project's `docs/` folder
+2. Run local BMad installation with `*workflow-init`
+3. BMad will detect the existing artifacts and update workflow status
+4. Proceed with implementation using Developer agent locally
+
+**Why this works:**
+
+- **Planning workflows** are token-heavy but don't need code context
+- **Web models (Gemini/GPT)** handle planning excellently at lower cost
+- **Local IDE implementation** needs full codebase access and tools
+- **Best of both worlds**: Cost savings + full implementation capabilities
+
+**Typical savings:** 60-80% cost reduction by doing analysis, planning, and architecture in web before moving to local implementation.
+
+## Using Web Bundles
+
+### Basic Usage
+
+**1. Load the Agent**
+
+Upload or paste the XML file into Gemini/GPT. The agent will introduce itself and show its menu.
+
+**2. Choose a Workflow**
+
+Use natural language or shortcuts:
+
+```
+"Run the PRD workflow"
+*prd
+
+"Start brainstorming"
+*brainstorm-project
+
+"Show me the menu"
+*help
+```
+
+**3. Follow the Workflow**
+
+The agent guides you through the workflow step-by-step, asking questions and creating deliverables.
+
+### Advanced Features
+
+**Party Mode**
+
+All web bundles include party mode for multi-agent collaboration:
+
+```
+*party
+```
+
+This activates multiple agents who collaborate on your task, providing diverse perspectives.
+
+**Context Loading**
+
+Some workflows load additional context:
+
+```
+*workflow-init  # Initialize project workflow
+*document-project  # Analyze existing codebase
+```
+
+**Dynamic Menus**
+
+Agents adapt their menus based on project phase and available workflows.
+
+## Platform Differences
+
+### Gemini Gems (Strongly Recommended)
+
+**Pros:**
+
+- Better XML parsing and handling
+- Handles large bundles well
+- Supports complex workflows
+- Larger context window (better for team bundles)
+- Code execution for document generation
+- Works excellently with BMad workflows
+
+**Cons:**
+
+- Requires Google account
+- May have rate limits on free tier
+
+**Best for:**
+
+- All individual agents (PM, Architect, Developer, UX Designer, etc.)
+- Team bundles (requires Gemini 2.5 Pro+)
+- Complex multi-step workflows
+- Document-heavy workflows (PRD, Architecture)
+
+**Recommended Model:** Gemini 2.5 Pro or higher
+
+### Custom GPTs
+
+**Pros:**
+
+- Familiar ChatGPT interface
+- Good for conversational workflows
+- Easy sharing with team via link
+
+**Cons:**
+
+- Smaller context window than Gemini
+- Character limit on instructions (large bundles may not fit)
+- **NOT recommended for team bundles**
+- Canvas feature less mature than Gemini's code execution
+
+**Best for:**
+
+- Individual focused agents (PM, Analyst, Architect)
+- Creative agents (CIS)
+- Simpler workflows (product-brief, brainstorm-project)
+- Quick prototyping
+
+**NOT recommended for:** Team bundles, Developer agent, complex technical workflows
+
+## Customization
+
+**Before Bundling:**
+
+Customize agents using the [Agent Customization Guide](./agent-customization-guide.md):
+
+1. Edit `{bmad_folder}/_cfg/agents/<agent>.customize.yaml`
+2. Rebuild: `npx bmad-method build <agent-name>`
+3. Generate bundles: `npm run bundle`
+
+Your customizations will be included in the web bundles.
+
+**After Bundling:**
+
+You can manually edit the XML to:
+
+- Change agent name (search for `<name>`)
+- Modify persona (search for `<persona>`)
+- Add custom instructions (in `<critical>` blocks)
+
+## Troubleshooting
+
+**Agent not responding correctly?**
+
+- Check that the entire XML file was uploaded
+- Verify no truncation occurred (Gemini/GPT have character limits)
+- Try a simpler agent first (analyst, pm)
+
+**Menu items not working?**
+
+- Use the `*` prefix for shortcuts: `*prd` not `prd`
+- Or use natural language: "Run the PRD workflow"
+- Check the agent's menu with `*help`
+
+**Workflows failing?**
+
+- Some workflows expect project files (not available in web context)
+- Use workflows designed for planning/analysis in web bundles
+- For implementation workflows, use local IDE installation
+
+**File too large for GPT?**
+
+- Split into sections and use multiple GPTs
+- Use Gemini Gems instead (better for large files)
+- Generate single-agent bundles instead of team bundles
+
+## Best Practices
+
+1. **One File Per Gem/GPT** - Always upload only ONE XML file per Gemini Gem or Custom GPT instance
+2. **Prefer Gemini Over GPT** - Gemini Gems work significantly better with BMad bundles
+3. **Enable Canvas/Code Execution** - Essential for document generation workflows (PRD, Architecture, etc.)
+4. **Create Separate Gems for Each Agent** - Don't try to combine agents except via team bundles
+5. **Team Bundles = Gemini 2.5 Pro+ Only** - Never use team bundles with Custom GPTs
+6. **Use for Planning Phases** - Web bundles excel at analysis, planning, and architecture (Phases 1-3)
+7. **Switch to Local for Implementation** - Use local IDE installation for Phase 4 development
+8. **Export and Save Artifacts** - Copy generated documents to your project's `docs/` folder
+9. **Run workflow-init Locally** - After importing web artifacts, initialize local workflow status
+10. **Keep Updated** - Rebuild bundles after BMad updates to get latest improvements
+
+## Examples
+
+### Example 1: Complete Web → Local Workflow (Recommended)
+
+**Goal:** Build a new SaaS product with maximum cost savings
+
+**Phase 1-3: Web Planning (Gemini Gems)**
+
+1. **Download bundles:**
+   - `bmm/agents/analyst.xml`
+   - `bmm/agents/pm.xml`
+   - `bmm/agents/architect.xml`
+   - `bmm/agents/ux-designer.xml`
+
+2. **Create 4 separate Gemini Gems** (one per agent, enable Code Execution)
+
+3. **Analysis (Analyst Gem):**
+   - Run: `*brainstorm-project` → Generate ideas
+   - Run: `*research` → Market analysis
+   - Export: Save research findings
+
+4. **Planning (PM Gem):**
+   - Share research findings
+   - Run: `*product-brief` → Product vision
+   - Run: `*prd` → Full requirements document
+   - Export: Save PRD to `docs/prd.md`
+
+5. **UX Design (UX Designer Gem):**
+   - Share PRD
+   - Run: `*create-ux-design` → UX specifications
+   - Export: Save UX design to `docs/ux-design.md`
+
+6. **Architecture (Architect Gem):**
+   - Share PRD and UX Design
+   - Run: `*architecture` → Technical architecture
+   - Export: Save to `docs/architecture.md`
+
+**Phase 4: Local Implementation**
+
+7. **Setup local BMad:**
+   - Install BMad locally: `npx bmad-method@alpha install`
+   - Place exported docs in project `docs/` folder
+   - Load Developer agent
+   - Run: `*workflow-init` → BMad detects artifacts, suggests next steps
+
+8. **Implement:**
+   - Run: `*sprint-planning` → Set up sprint
+   - Run: `*dev-story` → Implement features
+   - Use full IDE capabilities with codebase access
+
+**Cost Savings:** 60-80% by doing planning in Gemini before local implementation
+
+### Example 2: Quick Brainstorming Session
+
+1. Download `cis/agents/brainstorming-coach.xml`
+2. Create Gemini Gem with Code Execution enabled
+3. Run: `*brainstorming`
+4. Choose technique (e.g., SCAMPER, Mind Mapping)
+5. Generate and refine ideas
+6. Export results for team review
+
+### Example 3: Architecture Review
+
+1. Download `bmm/agents/architect.xml`
+2. Create Gemini Gem (enable Code Execution)
+3. Paste existing PRD into conversation
+4. Run: `*architecture`
+5. Collaborate on technical decisions
+6. Export architecture document to `docs/architecture.md`
+
+## Next Steps
+
+- **[Agent Customization Guide](./agent-customization-guide.md)** - Customize before bundling
+- **[BMM Documentation](../src/modules/bmm/docs/README.md)** - Learn all workflows
+- **[Web Bundler Technical Docs](./installers-bundlers/web-bundler-usage.md)** - Advanced bundling options
+- **[Contributing Guide](../CONTRIBUTING.md)** - Help improve web bundles
+
+## Resources
+
+- **[Google AI Studio](https://aistudio.google.com/)** - Create Gemini Gems
+- **[Custom GPTs](https://chat.openai.com/gpts)** - Build Custom GPTs
+- **[BMad Discord](https://discord.gg/gk8jAdXWmj)** - Get help and share your Gems/GPTs
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -14,6 +14,10 @@ export default [
      'test/template-test-generator/**',
      'test/template-test-generator/**/*.js',
      'test/template-test-generator/**/*.md',
+      'test/fixtures/**',
+      'test/fixtures/**/*.yaml',
+      '.bmad/**',
+      '.bmad*/**',
    ],
  },

@@ -59,9 +63,9 @@ export default [
    },
  },

-  // CLI/CommonJS scripts under tools/**
+  // CLI/CommonJS scripts under tools/** and test/**
  {
-    files: ['tools/**/*.js'],
+    files: ['tools/**/*.js', 'test/**/*.js'],
    rules: {
      // Allow CommonJS patterns for Node CLI scripts
      'unicorn/prefer-module': 'off',
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,16 +1,15 @@
 {
  "name": "bmad-method",
-  "version": "6.0.0-alpha.0",
+  "version": "6.0.0-alpha.11",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "bmad-method",
-      "version": "6.0.0-alpha.0",
+      "version": "6.0.0-alpha.11",
      "license": "MIT",
      "dependencies": {
-        "@kayvan/markdown-tree-parser": "^1.5.0",
-        "bmad-method": "^4.30.3",
+        "@kayvan/markdown-tree-parser": "^1.6.1",
        "boxen": "^5.1.2",
        "chalk": "^4.1.2",
        "cli-table3": "^0.6.5",
@@ -25,13 +24,16 @@
        "ora": "^5.4.1",
        "semver": "^7.6.3",
        "wrap-ansi": "^7.0.0",
-        "xml2js": "^0.6.2"
+        "xml2js": "^0.6.2",
+        "yaml": "^2.7.0"
      },
      "bin": {
-        "bmad": "tools/cli/bmad-cli.js"
+        "bmad": "tools/bmad-npx-wrapper.js",
+        "bmad-method": "tools/bmad-npx-wrapper.js"
      },
      "devDependencies": {
        "@eslint/js": "^9.33.0",
+        "c8": "^10.1.3",
        "eslint": "^9.33.0",
        "eslint-config-prettier": "^10.1.8",
        "eslint-plugin-n": "^17.21.3",
@@ -43,7 +45,8 @@
        "prettier": "^3.5.3",
        "prettier-plugin-packagejson": "^2.5.19",
        "yaml-eslint-parser": "^1.2.3",
-        "yaml-lint": "^1.7.0"
+        "yaml-lint": "^1.7.0",
+        "zod": "^4.1.12"
      },
      "engines": {
        "node": ">=20.0.0"
@@ -2397,32 +2400,6 @@
        "readable-stream": "^3.4.0"
      }
    },
-    "node_modules/bmad-method": {
-      "version": "4.40.0",
-      "resolved": "https://registry.npmjs.org/bmad-method/-/bmad-method-4.40.0.tgz",
-      "integrity": "sha512-FE+5GprBOf2x3AIpeH8iVJF3/JXtzTWbPSDTwUS3Y0Dq0IaW82FxwyiFykTRxPW/oDEK6YCyNkU4EO2Lq8E89A==",
-      "license": "MIT",
-      "dependencies": {
-        "@kayvan/markdown-tree-parser": "^1.5.0",
-        "bmad-method": "^4.30.3",
-        "chalk": "^4.1.2",
-        "commander": "^14.0.0",
-        "fs-extra": "^11.3.0",
-        "glob": "^11.0.3",
-        "ignore": "^7.0.5",
-        "inquirer": "^8.2.6",
-        "js-yaml": "^4.1.0",
-        "ora": "^5.4.1",
-        "semver": "^7.6.3"
-      },
-      "bin": {
-        "bmad": "tools/bmad-npx-wrapper.js",
-        "bmad-method": "tools/bmad-npx-wrapper.js"
-      },
-      "engines": {
-        "node": ">=20.10.0"
-      }
-    },
    "node_modules/boolbase": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz",
@@ -2586,6 +2563,152 @@
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
+    "node_modules/c8": {
+      "version": "10.1.3",
+      "resolved": "https://registry.npmjs.org/c8/-/c8-10.1.3.tgz",
+      "integrity": "sha512-LvcyrOAaOnrrlMpW22n690PUvxiq4Uf9WMhQwNJ9vgagkL/ph1+D4uvjvDA5XCbykrc0sx+ay6pVi9YZ1GnhyA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "@bcoe/v8-coverage": "^1.0.1",
+        "@istanbuljs/schema": "^0.1.3",
+        "find-up": "^5.0.0",
+        "foreground-child": "^3.1.1",
+        "istanbul-lib-coverage": "^3.2.0",
+        "istanbul-lib-report": "^3.0.1",
+        "istanbul-reports": "^3.1.6",
+        "test-exclude": "^7.0.1",
+        "v8-to-istanbul": "^9.0.0",
+        "yargs": "^17.7.2",
+        "yargs-parser": "^21.1.1"
+      },
+      "bin": {
+        "c8": "bin/c8.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "monocart-coverage-reports": "^2"
+      },
+      "peerDependenciesMeta": {
+        "monocart-coverage-reports": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/c8/node_modules/@bcoe/v8-coverage": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/@bcoe/v8-coverage/-/v8-coverage-1.0.2.tgz",
+      "integrity": "sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/c8/node_modules/brace-expansion": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
+      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^1.0.0"
+      }
+    },
+    "node_modules/c8/node_modules/glob": {
+      "version": "10.4.5",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-10.4.5.tgz",
+      "integrity": "sha512-7Bv8RF0k6xjo7d4A/PxYLbUCfb6c+Vpd2/mB2yRDlew7Jb5hEXiCD9ibfO7wpk8i4sevK6DFny9h7EYbM3/sHg==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "foreground-child": "^3.1.0",
+        "jackspeak": "^3.1.2",
+        "minimatch": "^9.0.4",
+        "minipass": "^7.1.2",
+        "package-json-from-dist": "^1.0.0",
+        "path-scurry": "^1.11.1"
+      },
+      "bin": {
+        "glob": "dist/esm/bin.mjs"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/c8/node_modules/jackspeak": {
+      "version": "3.4.3",
+      "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-3.4.3.tgz",
+      "integrity": "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "@isaacs/cliui": "^8.0.2"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      },
+      "optionalDependencies": {
+        "@pkgjs/parseargs": "^0.11.0"
+      }
+    },
+    "node_modules/c8/node_modules/lru-cache": {
+      "version": "10.4.3",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz",
+      "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/c8/node_modules/minimatch": {
+      "version": "9.0.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz",
+      "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "brace-expansion": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=16 || 14 >=14.17"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/c8/node_modules/path-scurry": {
+      "version": "1.11.1",
+      "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-1.11.1.tgz",
+      "integrity": "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "lru-cache": "^10.2.0",
+        "minipass": "^5.0.0 || ^6.0.2 || ^7.0.0"
+      },
+      "engines": {
+        "node": ">=16 || 14 >=14.18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/c8/node_modules/test-exclude": {
+      "version": "7.0.1",
+      "resolved": "https://registry.npmjs.org/test-exclude/-/test-exclude-7.0.1.tgz",
+      "integrity": "sha512-pFYqmTw68LXVjeWJMST4+borgQP2AyMNbg1BpZh9LbyhUeNkeaPF9gzfPGUAnSMV3qPYdWUwDIjjCLiSDOl7vg==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "@istanbuljs/schema": "^0.1.2",
+        "glob": "^10.4.1",
+        "minimatch": "^9.0.4"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
    "node_modules/callsites": {
      "version": "3.1.0",
      "resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz",
@@ -8319,7 +8442,6 @@
      "version": "2.8.1",
      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.1.tgz",
      "integrity": "sha512-lcYcMxX2PO9XMGvAJkJ3OsNMw+/7FKes7/hgerGUYWIoWu5j/+YQqcZr5JnPZWzOsEBgMbSbiSTn/dv/69Mkpw==",
-      "dev": true,
      "license": "ISC",
      "bin": {
        "yaml": "bin.mjs"
@@ -8416,6 +8538,16 @@
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
+    "node_modules/zod": {
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.1.12.tgz",
+      "integrity": "sha512-JInaHOamG8pt5+Ey8kGmdcAcg3OL9reK8ltczgHTAwNhMys/6ThXHityHxVV2p3fkw/c+MAvBHFVYHFZDmjMCQ==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    },
    "node_modules/zwitch": {
      "version": "2.0.4",
      "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz",
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "bmad-method",
-  "version": "6.0.0-alpha.0",
+  "version": "6.0.0-alpha.12",
  "description": "Breakthrough Method of Agile AI-driven Development",
  "keywords": [
    "agile",
@@ -20,9 +20,11 @@
  "author": "Brian (BMad) Madison",
  "main": "tools/cli/bmad-cli.js",
  "bin": {
-    "bmad": "tools/cli/bmad-cli.js"
+    "bmad": "tools/bmad-npx-wrapper.js",
+    "bmad-method": "tools/bmad-npx-wrapper.js"
  },
  "scripts": {
+    "bmad:agent-install": "node tools/cli/bmad-cli.js agent-install",
    "bmad:install": "node tools/cli/bmad-cli.js install",
    "bmad:status": "node tools/cli/bmad-cli.js status",
    "bundle": "node tools/cli/bundlers/bundle-web.js all",
@@ -38,7 +40,12 @@
    "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:bundles": "node tools/validate-bundles.js"
+    "test": "npm run test:schemas && npm run test:install && npm run validate:bundles && npm run validate:schemas && npm run lint && npm run format:check",
+    "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
+    "test:install": "node test/test-installation-components.js",
+    "test:schemas": "node test/test-agent-schema.js",
+    "validate:bundles": "node tools/validate-bundles.js",
+    "validate:schemas": "node tools/validate-agent-schema.js"
  },
  "lint-staged": {
    "*.{js,cjs,mjs}": [
@@ -54,8 +61,7 @@
    ]
  },
  "dependencies": {
-    "@kayvan/markdown-tree-parser": "^1.5.0",
-    "bmad-method": "^4.30.3",
+    "@kayvan/markdown-tree-parser": "^1.6.1",
    "boxen": "^5.1.2",
    "chalk": "^4.1.2",
    "cli-table3": "^0.6.5",
@@ -70,10 +76,12 @@
    "ora": "^5.4.1",
    "semver": "^7.6.3",
    "wrap-ansi": "^7.0.0",
-    "xml2js": "^0.6.2"
+    "xml2js": "^0.6.2",
+    "yaml": "^2.7.0"
  },
  "devDependencies": {
    "@eslint/js": "^9.33.0",
+    "c8": "^10.1.3",
    "eslint": "^9.33.0",
    "eslint-config-prettier": "^10.1.8",
    "eslint-plugin-n": "^17.21.3",
@@ -85,7 +93,8 @@
    "prettier": "^3.5.3",
    "prettier-plugin-packagejson": "^2.5.19",
    "yaml-eslint-parser": "^1.2.3",
-    "yaml-lint": "^1.7.0"
+    "yaml-lint": "^1.7.0",
+    "zod": "^4.1.12"
  },
  "engines": {
    "node": ">=20.0.0"
--- a/src/core/_module-installer/install-config.yaml
+++ b/src/core/_module-installer/install-config.yaml
@@ -0,0 +1,35 @@
+# BMAD™ Core Configuration
+header: "BMAD™ Core Configuration"
+subheader: "Configure the core settings for your BMAD™ installation.\nThese settings will be used across all modules and agents."
+
+bmad_folder:
+  prompt: "What is the root folder for BMAD installation? (Recommended: .bmad)"
+  default: ".bmad"
+  result: "{value}"
+  regex: "^[a-zA-Z0-9._-]{1,20}$"
+
+user_name:
+  prompt: "What shall the agents call you?"
+  default: "BMad"
+  result: "{value}"
+
+communication_language:
+  prompt: "Preferred Chat Language/Style? (English, Mandarin, English Pirate, etc...)"
+  default: "English"
+  result: "{value}"
+
+document_output_language:
+  prompt: "Preferred Document Output Language?"
+  default: "{communication_language}"
+  result: "{value}"
+
+  # This is the folder where all generated AI Output documents from workflows will default be sa
+output_folder:
+  prompt: "Where should AI Generated Artifacts be saved across all modules?"
+  default: "docs"
+  result: "{project-root}/{value}"
+
+install_user_docs:
+  prompt: "Install user documentation and optimized agent intelligence to each selected modules docs folder?"
+  default: true
+  result: "{value}"
--- a/src/core/_module-installer/install-menu-config.yaml
+++ b/src/core/_module-installer/install-menu-config.yaml
@@ -1,24 +0,0 @@
-# BMAD™ Core Configuration
-
-prompt:
-  - "Welcome and thank you for choosing BMAD™! This is the Core Configuration."
-  - "Core Config is personalized configuration that is git ignored."
-  - "This will impact all selected modules, either additions or upgrades."
-
-# This is injected into the custom agent activation rules
-user_name:
-  prompt: "What is your name?"
-  default: "Jane"
-  result: "{value}"
-
-# This is injected into the custom agent activation rules
-communication_language:
-  prompt: "Preferred language?"
-  default: "English"
-  result: "{value}"
-
-# This is injected into the custom agent activation rules
-output_folder:
-  prompt: "Where should the generated output default save location be?"
-  default: "docs"
-  result: "{project-root}/{value}"
--- a/src/core/_module-installer/installer.js
+++ b/src/core/_module-installer/installer.js
@@ -6,7 +6,7 @@ const chalk = require('chalk');
 *
 * @param {Object} options - Installation options
 * @param {string} options.projectRoot - The root directory of the target project
- * @param {Object} options.config - Module configuration from install-menu-config.yaml
+ * @param {Object} options.config - Module configuration from install-config.yaml
 * @param {Array<string>} options.installedIDEs - Array of IDE codes that were installed
 * @param {Object} options.logger - Logger instance for output
 * @returns {Promise<boolean>} - Success status
@@ -49,14 +49,6 @@ async function configureForIDE(ide) {
      // Claude Code specific Core configurations
      break;
    }
-    case 'cursor': {
-      // Cursor specific Core configurations
-      break;
-    }
-    case 'windsurf': {
-      // Windsurf specific Core configurations
-      break;
-    }
    // Add more IDEs as needed
    default: {
      // No specific configuration needed
--- a/src/core/agents/bmad-master.agent.yaml
+++ b/src/core/agents/bmad-master.agent.yaml
@@ -0,0 +1,39 @@
+# BMad Master Task Executor Agent
+# Core system agent for task execution and resource management
+
+agent:
+  metadata:
+    id: "{bmad_folder}/core/agents/bmad-master.md"
+    name: "BMad Master"
+    title: "BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator"
+    icon: "🧙"
+
+  persona:
+    role: "Master Task Executor + BMad Expert + Guiding Facilitator Orchestrator"
+    identity: "Master-level expert in the BMAD Core Platform and all loaded modules with comprehensive knowledge of all resources, tasks, and workflows. Experienced in direct task execution and runtime resource management, serving as the primary execution engine for BMAD operations."
+    communication_style: "Direct and comprehensive, refers to himself in the 3rd person. Expert-level communication focused on efficient task execution, presenting information systematically using numbered lists with immediate command response capability."
+    principles:
+      - "Load resources at runtime never pre-load, and always present numbered lists for choices."
+
+  # Agent-specific critical actions
+  critical_actions:
+    - "Load into memory {project-root}/{bmad_folder}/core/config.yaml and set variable project_name, output_folder, user_name, communication_language"
+    - "Remember the users name is {user_name}"
+    - "ALWAYS communicate in {communication_language}"
+
+  # Agent menu items
+  menu:
+    - trigger: "list-tasks"
+      action: "list all tasks from {project-root}/{bmad_folder}/_cfg/task-manifest.csv"
+      description: "List Available Tasks"
+
+    - trigger: "list-workflows"
+      action: "list all workflows from {project-root}/{bmad_folder}/_cfg/workflow-manifest.csv"
+      description: "List Workflows"
+
+    - trigger: "party-mode"
+      workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"
+      description: "Group chat with all agents"
+
+  # Empty prompts section (no custom prompts for this agent)
+  prompts: []
--- a/src/core/agents/bmad-master.md
+++ b/src/core/agents/bmad-master.md
@@ -1,27 +0,0 @@
-<!-- Powered by BMAD-CORE™ -->
-
-# BMad Master Task Executor
-
-```xml
-<agent id="bmad/core/agents/bmad-master.md" name="BMad Master" title="BMad Master Task Executor" icon="🧙">
-  <persona>
-    <role>Master Task Executor + BMad Expert</role>
-    <identity>Master-level expert in the BMAD Core Platform and all loaded modules with comprehensive knowledge of all resources, tasks, and workflows. Experienced in direct task execution and runtime resource management, serving as the primary execution engine for BMAD operations.</identity>
-    <communication_style>Direct and comprehensive, refers to himself in the 3rd person. Expert-level communication focused on efficient task execution, presenting information systematically using numbered lists with immediate command response capability.</communication_style>
-    <principles>Load resources at runtime never pre-load, and always present numbered lists for choices.</principles>
-  </persona>
-  <critical-actions>
-    <i>Load into memory {project-root}/bmad/core/config.yaml and set variable project_name, output_folder, user_name, communication_language</i>
-    <i>Remember the users name is {user_name}</i>
-    <i>ALWAYS communicate in {communication_language}</i>
-  </critical-actions>
-  <cmds>
-    <c cmd="*help">Show numbered cmd list</c>
-    <c cmd="*list-tasks" action="list all tasks from {project-root}/bmad/_cfg/task-manifest.csv">List Available Tasks</c>
-    <c cmd="*list-workflows" action="list all workflows from {project-root}/bmad/_cfg/workflow-manifest.csv">List Workflows</c>
-    <c cmd="*party-mode" run-workflow="{project-root}/bmad/core/workflows/party-mode/workflow.yaml">Group chat with all agents</c>
-    <c cmd="*bmad-init" run-workflow="{project-root}/bmad/core/workflows/bmad-init/workflow.yaml">Initialize or Update BMAD system agent manifest, customization, or workflow selection</c>
-    <c cmd="*exit">Exit with confirmation</c>
-  </cmds>
-</agent>
-```
--- a/src/core/agents/bmad-web-orchestrator.agent.xml
+++ b/src/core/agents/bmad-web-orchestrator.agent.xml
@@ -0,0 +1,113 @@
+<agent id="{bmad_folder}/core/agents/bmad-orchestrator.md" name="BMad Orchestrator" title="BMad Web Orchestrator" icon="🎭" localskip="true">
+  <activation critical="MANDATORY">
+    <step n="1">Load this complete web bundle XML - you are the BMad Orchestrator, first agent in this bundle</step>
+    <step n="2">CRITICAL: This bundle contains ALL agents as XML nodes with id="{bmad_folder}/..." and ALL workflows/tasks as nodes findable
+      by type
+      and id</step>
+    <step n="3">Greet user as BMad Orchestrator and display numbered list of ALL menu items from menu section below</step>
+    <step n="4">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or trigger text</step>
+    <step n="5">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to
+      clarify | No match → show "Not recognized"</step>
+    <step n="6">When executing a menu item: Check menu-handlers section below for UNIVERSAL handler instructions that apply to ALL agents</step>
+
+    <menu-handlers critical="UNIVERSAL_FOR_ALL_AGENTS">
+      <extract>workflow, exec, tmpl, data, action, validate-workflow</extract>
+      <handlers>
+        <handler type="workflow">
+          When menu item has: workflow="workflow-id"
+          1. Find workflow node by id in this bundle (e.g., &lt;workflow id="workflow-id"&gt;)
+          2. CRITICAL: Always LOAD {bmad_folder}/core/tasks/workflow.xml if referenced
+          3. Execute the workflow content precisely following all steps
+          4. Save outputs after completing EACH workflow step (never batch)
+          5. If workflow id is "todo", inform user it hasn't been implemented yet
+        </handler>
+
+        <handler type="exec">
+          When menu item has: exec="node-id" or exec="inline-instruction"
+          1. If value looks like a path/id → Find and execute node with that id
+          2. If value is text → Execute as direct instruction
+          3. Follow ALL instructions within loaded content EXACTLY
+        </handler>
+
+        <handler type="tmpl">
+          When menu item has: tmpl="template-id"
+          1. Find template node by id in this bundle and pass it to the exec, task, action, or workflow being executed
+        </handler>
+
+        <handler type="data">
+          When menu item has: data="data-id"
+          1. Find data node by id in this bundle
+          2. Parse according to node type (json/yaml/xml/csv)
+          3. Make available as {data} variable for subsequent operations
+        </handler>
+
+        <handler type="action">
+          When menu item has: action="#prompt-id" or action="inline-text"
+          1. If starts with # → Find prompt with matching id in current agent
+          2. Otherwise → Execute the text directly as instruction
+        </handler>
+
+        <handler type="validate-workflow">
+          When menu item has: validate-workflow="workflow-id"
+          1. MUST LOAD {bmad_folder}/core/tasks/validate-workflow.xml
+          2. Execute all validation instructions from that file
+          3. Check workflow's validation property for schema
+          4. Identify file to validate or ask user to specify
+        </handler>
+      </handlers>
+    </menu-handlers>
+
+    <orchestrator-specific>
+      <agent-transformation critical="true">
+        When user selects *agents [agent-name]:
+        1. Find agent XML node with matching name/id in this bundle
+        2. Announce transformation: "Transforming into [agent name]... 🎭"
+        3. BECOME that agent completely:
+        - Load and embody their persona/role/communication_style
+        - Display THEIR menu items (not orchestrator menu)
+        - Execute THEIR commands using universal handlers above
+        4. Stay as that agent until user types *exit
+        5. On *exit: Confirm, then return to BMad Orchestrator persona
+      </agent-transformation>
+
+      <list-agents critical="true">
+        When user selects *list-agents:
+        1. Scan all agent nodes in this bundle
+        2. Display formatted list with:
+        - Number, emoji, name, title
+        - Brief description of capabilities
+        - Main menu items they offer
+        3. Suggest which agent might help with common tasks
+      </list-agents>
+    </orchestrator-specific>
+
+    <rules>
+      Web bundle environment - NO file system access, all content in XML nodes
+      Find resources by XML node id/type within THIS bundle only
+      Use canvas for document drafting when available
+      Menu triggers use asterisk (*) - display exactly as shown
+      Number all lists, use letters for sub-options
+      Stay in character (current agent) until *exit command
+      Options presented as numbered lists with descriptions
+      elicit="true" attributes require user confirmation before proceeding
+    </rules>
+  </activation>
+
+  <persona>
+    <role>Master Orchestrator and BMad Scholar</role>
+    <identity>Master orchestrator with deep expertise across all loaded agents and workflows. Technical brilliance balanced with
+      approachable communication.</identity>
+    <communication_style>Knowledgeable, guiding, approachable, very explanatory when in BMad Orchestrator mode</communication_style>
+    <core_principles>When I transform into another agent, I AM that agent until *exit command received. When I am NOT transformed into
+      another agent, I will give you guidance or suggestions on a workflow based on your needs.</core_principles>
+  </persona>
+  <menu>
+    <item cmd="*help">Show numbered command list</item>
+    <item cmd="*list-agents">List all available agents with their capabilities</item>
+    <item cmd="*agents [agent-name]">Transform into a specific agent</item>
+    <item cmd="*party-mode" workflow="{bmad_folder}/core/workflows/party-mode/workflow.yaml">Enter group chat with all agents
+      simultaneously</item>
+    <item cmd="*advanced-elicitation" task="{bmad_folder}/core/tasks/advanced-elicitation.xml">Push agent to perform advanced elicitation</item>
+    <item cmd="*exit">Exit current session</item>
+  </menu>
+</agent>
--- a/src/core/agents/bmad-web-orchestrator.md
+++ b/src/core/agents/bmad-web-orchestrator.md
@@ -1,71 +0,0 @@
-```xml
-<agent id="bmad/core/agents/bmad-orchestrator.md" name="BMad Orchestrator" title="BMad Web Orchestrator" icon="🎭" localskip="true">
-  <activation critical="true">
-    <notice>PRIMARY OPERATING PROCEDURE - Read and follow this entire node EXACTLY</notice>
-    <steps>
-      <s>1:Read this entire XML node - this is your complete persona and operating procedure</s>
-      <s>2:Greet user as BMad Orchestrator + run *help to show available commands</s>
-      <s>3:HALT and await user commands (except if activation included specific commands to execute)</s>
-    </steps>
-    <rules>
-      <r critical="true">NO external agent files - all agents are in 'agent' XML nodes findable by id</r>
-      <r critical="true">NO external task files - all tasks are in 'task' XML nodes findable by id</r>
-      <r>Tasks are complete workflows, not references - follow exactly as written</r>
-      <r>elicit=true attributes require user interaction before proceeding</r>
-      <r>Options ALWAYS presented to users as numbered lists</r>
-      <r>STAY IN CHARACTER until *exit command received</r>
-      <r>Resource Navigation: All resources found by XML Node ID within this bundle</r>
-      <r>Execution Context: Web environment only - no file system access, use canvas if available for document drafting</r>
-    </rules>
-  </activation>
-
-  <command-resolution critical="true">
-    <rule>ONLY execute commands of the CURRENT AGENT PERSONA you are inhabiting</rule>
-    <rule>If user requests command from another agent, instruct them to switch agents first using *agents command</rule>
-    <rule>Numeric input → Execute command at cmd_map[n] of current agent</rule>
-    <rule>Text input → Fuzzy match against *cmd commands of current agent</rule>
-    <action>Extract exec, tmpl, and data attributes from matched command</action>
-    <action>Resolve ALL paths by XML node id, treating each node as complete self-contained file</action>
-    <action>Verify XML node existence BEFORE attempting execution</action>
-    <action>Show exact XML node id in any error messages</action>
-    <rule>NEVER improvise - only execute loaded XML node instructions as active agent persona</rule>
-  </command-resolution>
-
-  <execution-rules critical="true">
-    <rule>Stay in character until *exit command - then return to primary orchestrator</rule>
-    <rule>Load referenced nodes by id ONLY when user commands require specific node</rule>
-    <rule>Follow loaded instructions EXACTLY as written</rule>
-    <rule>AUTO-SAVE after EACH major section, update CANVAS if available</rule>
-    <rule>NEVER TRUNCATE output document sections</rule>
-    <rule>Process all commands starting with * immediately</rule>
-    <rule>Always remind users that commands require * prefix</rule>
-  </execution-rules>
-
-  <persona>
-    <role>Master Orchestrator + Module Expert</role>
-    <identity>Master orchestrator with deep expertise across all loaded agents and workflows. Expert at assessing user needs and recommending optimal approaches. Skilled in dynamic persona transformation and workflow guidance. Technical brilliance balanced with approachable communication.</identity>
-    <communication_style>Knowledgeable, guiding, approachable. Adapts to current persona/task context. Encouraging and efficient with clear next steps. Always explicit about active state and requirements.</communication_style>
-    <core_principles>
-      <p>Transform into any loaded agent on demand</p>
-      <p>Assess needs and recommend best agent/workflow/approach</p>
-      <p>Track current state and guide to logical next steps</p>
-      <p>When embodying specialized persona, their principles take precedence</p>
-      <p>Be explicit about active persona and current task</p>
-      <p>Present all options as numbered lists</p>
-      <p>Process * commands immediately without delay</p>
-      <p>Remind users that commands require * prefix</p>
-    </core_principles>
-  </persona>
-  <cmds>
-    <c cmd="*help">Show numbered command list for current agent</c>
-    <c cmd="*list-agents" exec="list available agents from bmad/web-manifest.xml nodes type agent">List all available agents</c>
-    <c cmd="*agents [agent]" exec="Transform into the selected agent">Transform into specific agent</c>
-    <c cmd="*list-tasks" exec="list all tasks from node bmad/web-manifest.xml nodes type task">List available tasks</c>
-    <c cmd="*list-templates" exec="list all templates from bmad/web-manifest.xml nodes type templates">List available templates</c>
-    <c cmd="*kb-mode" exec="bmad/core/tasks/kb-interact.md">Load full BMad knowledge base</c>
-    <c cmd="*party-mode" run-workflow="{project-root}/bmad/core/workflows/party-mode/workflow.yaml">Group chat with all agents</c>
-    <c cmd="*yolo">Toggle skip confirmations mode</c>
-    <c cmd="*exit">Return to BMad Orchestrator or exit session</c>
-  </cmds>
-</agent>
-```
--- a/src/core/resources/excalidraw/README.md
+++ b/src/core/resources/excalidraw/README.md
@@ -0,0 +1,160 @@
+# Core Excalidraw Resources
+
+Universal knowledge for creating Excalidraw diagrams. All agents that create Excalidraw files should reference these resources.
+
+## Purpose
+
+Provides the **HOW** (universal knowledge) while agents provide the **WHAT** (domain-specific application).
+
+**Core = "How to create Excalidraw elements"**
+
+- How to group shapes with text labels
+- How to calculate text width
+- How to create arrows with proper bindings
+- How to validate JSON syntax
+- Base structure and primitives
+
+**Agents = "What diagrams to create"**
+
+- Frame Expert (BMM): Technical flowcharts, architecture diagrams, wireframes
+- Presentation Master (CIS): Pitch decks, creative visuals, Rube Goldberg machines
+- Tech Writer (BMM): Documentation diagrams, concept explanations
+
+## Files in This Directory
+
+### excalidraw-helpers.md
+
+**Universal element creation patterns**
+
+- Text width calculation
+- Element grouping rules (shapes + labels)
+- Grid alignment
+- Arrow creation (straight, elbow)
+- Theme application
+- Validation checklist
+- Optimization rules
+
+**Agents reference this to:**
+
+- Create properly grouped shapes
+- Calculate text dimensions
+- Connect elements with arrows
+- Ensure valid structure
+
+### validate-json-instructions.md
+
+**Universal JSON validation process**
+
+- How to validate Excalidraw JSON
+- Common errors and fixes
+- Workflow integration
+- Error recovery
+
+**Agents reference this to:**
+
+- Validate files after creation
+- Fix syntax errors
+- Ensure files can be opened in Excalidraw
+
+### library-loader.md (Future)
+
+**How to load external .excalidrawlib files**
+
+- Programmatic library loading
+- Community library integration
+- Custom library management
+
+**Status:** To be developed when implementing external library support.
+
+## How Agents Use These Resources
+
+### Example: Frame Expert (Technical Diagrams)
+
+```yaml
+# workflows/diagrams/create-flowchart/workflow.yaml
+helpers: '{project-root}/{bmad_folder}/core/resources/excalidraw/excalidraw-helpers.md'
+json_validation: '{project-root}/{bmad_folder}/core/resources/excalidraw/validate-json-instructions.md'
+```
+
+**Domain-specific additions:**
+
+```yaml
+# workflows/diagrams/_shared/flowchart-templates.yaml
+flowchart:
+  start_node:
+    type: ellipse
+    width: 120
+    height: 60
+  process_box:
+    type: rectangle
+    width: 160
+    height: 80
+  decision_diamond:
+    type: diamond
+    width: 140
+    height: 100
+```
+
+### Example: Presentation Master (Creative Visuals)
+
+```yaml
+# workflows/create-visual-metaphor/workflow.yaml
+helpers: '{project-root}/{bmad_folder}/core/resources/excalidraw/excalidraw-helpers.md'
+json_validation: '{project-root}/{bmad_folder}/core/resources/excalidraw/validate-json-instructions.md'
+```
+
+**Domain-specific additions:**
+
+```yaml
+# workflows/_shared/creative-templates.yaml
+rube_goldberg:
+  whimsical_connector:
+    type: arrow
+    strokeStyle: dashed
+    roughness: 2
+  playful_box:
+    type: rectangle
+    roundness: 12
+```
+
+## What Doesn't Belong in Core
+
+**Domain-Specific Elements:**
+
+- Flowchart-specific templates (belongs in Frame Expert)
+- Pitch deck layouts (belongs in Presentation Master)
+- Documentation-specific styles (belongs in Tech Writer)
+
+**Agent Workflows:**
+
+- How to create a flowchart (Frame Expert workflow)
+- How to create a pitch deck (Presentation Master workflow)
+- Step-by-step diagram creation (agent-specific)
+
+**Theming:**
+
+- Currently in agent workflows
+- **Future:** Will be refactored to core as user-configurable themes
+
+## Architecture Principle
+
+**Single Source of Truth:**
+
+- Core holds universal knowledge
+- Agents reference core, don't duplicate
+- Updates to core benefit all agents
+- Agents specialize with domain knowledge
+
+**DRY (Don't Repeat Yourself):**
+
+- Element creation logic: ONCE in core
+- Text width calculation: ONCE in core
+- Validation process: ONCE in core
+- Arrow binding patterns: ONCE in core
+
+## Future Enhancements
+
+1. **External Library Loader** - Load .excalidrawlib files from libraries.excalidraw.com
+2. **Theme Management** - User-configurable color themes saved in core
+3. **Component Library** - Shared reusable components across agents
+4. **Layout Algorithms** - Auto-layout helpers for positioning elements
--- a/src/core/resources/excalidraw/excalidraw-helpers.md
+++ b/src/core/resources/excalidraw/excalidraw-helpers.md
@@ -0,0 +1,127 @@
+# Excalidraw Element Creation Guidelines
+
+## Text Width Calculation
+
+For text elements inside shapes (labels):
+
+```
+text_width = (text.length × fontSize × 0.6) + 20
+```
+
+Round to nearest 10 for grid alignment.
+
+## Element Grouping Rules
+
+**CRITICAL:** When creating shapes with labels:
+
+1. Generate unique IDs:
+   - `shape-id` for the shape
+   - `text-id` for the text
+   - `group-id` for the group
+
+2. Shape element must have:
+   - `groupIds: [group-id]`
+   - `boundElements: [{type: "text", id: text-id}]`
+
+3. Text element must have:
+   - `containerId: shape-id`
+   - `groupIds: [group-id]` (SAME as shape)
+   - `textAlign: "center"`
+   - `verticalAlign: "middle"`
+   - `width: calculated_width`
+
+## Grid Alignment
+
+- Snap all `x`, `y` coordinates to 20px grid
+- Formula: `Math.round(value / 20) * 20`
+- Spacing between elements: 60px minimum
+
+## Arrow Creation
+
+### Straight Arrows
+
+Use for forward flow (left-to-right, top-to-bottom):
+
+```json
+{
+  "type": "arrow",
+  "startBinding": {
+    "elementId": "source-shape-id",
+    "focus": 0,
+    "gap": 10
+  },
+  "endBinding": {
+    "elementId": "target-shape-id",
+    "focus": 0,
+    "gap": 10
+  },
+  "points": [[0, 0], [distance_x, distance_y]]
+}
+```
+
+### Elbow Arrows
+
+Use for upward flow, backward flow, or complex routing:
+
+```json
+{
+  "type": "arrow",
+  "startBinding": {...},
+  "endBinding": {...},
+  "points": [
+    [0, 0],
+    [intermediate_x, 0],
+    [intermediate_x, intermediate_y],
+    [final_x, final_y]
+  ],
+  "elbowed": true
+}
+```
+
+### Update Connected Shapes
+
+After creating arrow, update `boundElements` on both connected shapes:
+
+```json
+{
+  "id": "shape-id",
+  "boundElements": [
+    { "type": "text", "id": "text-id" },
+    { "type": "arrow", "id": "arrow-id" }
+  ]
+}
+```
+
+## Theme Application
+
+Theme colors should be applied consistently:
+
+- **Shapes**: `backgroundColor` from theme primary fill
+- **Borders**: `strokeColor` from theme accent
+- **Text**: `strokeColor` = "#1e1e1e" (dark text)
+- **Arrows**: `strokeColor` from theme accent
+
+## Validation Checklist
+
+Before saving, verify:
+
+- [ ] All shapes with labels have matching `groupIds`
+- [ ] All text elements have `containerId` pointing to parent shape
+- [ ] Text width calculated properly (no cutoff)
+- [ ] Text alignment set (`textAlign` + `verticalAlign`)
+- [ ] All elements snapped to 20px grid
+- [ ] All arrows have `startBinding` and `endBinding`
+- [ ] `boundElements` array updated on connected shapes
+- [ ] Theme colors applied consistently
+- [ ] No metadata or history in final output
+- [ ] All IDs are unique
+
+## Optimization
+
+Remove from final output:
+
+- `appState` object
+- `files` object (unless images used)
+- All elements with `isDeleted: true`
+- Unused library items
+- Version history
--- a/src/core/resources/excalidraw/library-loader.md
+++ b/src/core/resources/excalidraw/library-loader.md
@@ -0,0 +1,50 @@
+# External Library Loader
+
+**Status:** Placeholder for future implementation
+
+## Purpose
+
+Load external .excalidrawlib files from https://libraries.excalidraw.com or custom sources.
+
+## Planned Capabilities
+
+- Load libraries by URL
+- Load libraries from local files
+- Merge multiple libraries
+- Filter library components
+- Cache loaded libraries
+
+## API Reference
+
+Will document how to use:
+
+- `importLibrary(url)` - Load library from URL
+- `loadSceneOrLibraryFromBlob()` - Load from file
+- `mergeLibraryItems()` - Combine libraries
+
+## Usage Example
+
+```yaml
+# Future workflow.yaml structure
+libraries:
+  - url: 'https://libraries.excalidraw.com/libraries/...'
+    filter: ['aws', 'cloud']
+  - path: '{project-root}/_data/custom-library.excalidrawlib'
+```
+
+## Implementation Notes
+
+This will be developed when agents need to leverage the extensive library ecosystem available at https://libraries.excalidraw.com.
+
+Hundreds of pre-built component libraries exist for:
+
+- AWS/Cloud icons
+- UI/UX components
+- Business diagrams
+- Mind map shapes
+- Floor plans
+- And much more...
+
+## User Configuration
+
+Future: Users will be able to configure favorite libraries in their BMAD config for automatic loading.
--- a/src/core/resources/excalidraw/validate-json-instructions.md
+++ b/src/core/resources/excalidraw/validate-json-instructions.md
@@ -0,0 +1,79 @@
+# JSON Validation Instructions
+
+## Purpose
+
+Validate Excalidraw JSON files after saving to catch syntax errors (missing commas, brackets, quotes).
+
+## How to Validate
+
+Use Node.js built-in JSON parsing to validate the file:
+
+```bash
+node -e "JSON.parse(require('fs').readFileSync('FILE_PATH', 'utf8')); console.log('✓ Valid JSON')"
+```
+
+Replace `FILE_PATH` with the actual file path.
+
+## Exit Codes
+
+- Exit code 0 = Valid JSON
+- Exit code 1 = Invalid JSON (syntax error)
+
+## Error Output
+
+If invalid, Node.js will output:
+
+- Error message with description
+- Position in file where error occurred
+- Line and column information (if available)
+
+## Common Errors and Fixes
+
+### Missing Comma
+
+```
+SyntaxError: Expected ',' or '}' after property value
+```
+
+**Fix:** Add comma after the property value
+
+### Missing Bracket/Brace
+
+```
+SyntaxError: Unexpected end of JSON input
+```
+
+**Fix:** Add missing closing bracket `]` or brace `}`
+
+### Extra Comma (Trailing)
+
+```
+SyntaxError: Unexpected token ,
+```
+
+**Fix:** Remove the trailing comma before `]` or `}`
+
+### Missing Quote
+
+```
+SyntaxError: Unexpected token
+```
+
+**Fix:** Add missing quote around string value
+
+## Workflow Integration
+
+After saving an Excalidraw file, run validation:
+
+1. Save the file
+2. Run: `node -e "JSON.parse(require('fs').readFileSync('{{save_location}}', 'utf8')); console.log('✓ Valid JSON')"`
+3. If validation fails:
+   - Read the error message for line/position
+   - Open the file at that location
+   - Fix the syntax error
+   - Save and re-validate
+4. Repeat until validation passes
+
+## Critical Rule
+
+**NEVER delete the file due to validation errors - always fix the syntax error at the reported location.**
--- a/src/core/tasks/advanced-elicitation-methods.csv
+++ b/src/core/tasks/advanced-elicitation-methods.csv
@@ -0,0 +1,21 @@
+category,method_name,description,output_pattern
+core,Five Whys,Drill down to root causes by asking 'why' iteratively. Each answer becomes the basis for the next question. Particularly effective for problem analysis and understanding system failures.,problem → why1 → why2 → why3 → why4 → why5 → root cause
+core,First Principles,Break down complex problems into fundamental truths and rebuild from there. Question assumptions and reconstruct understanding from basic principles.,assumptions → deconstruction → fundamentals → reconstruction → solution
+structural,SWOT Analysis,Evaluate internal and external factors through Strengths Weaknesses Opportunities and Threats. Provides balanced strategic perspective.,strengths → weaknesses → opportunities → threats → strategic insights
+structural,Mind Mapping,Create visual representations of interconnected concepts branching from central idea. Reveals relationships and patterns not immediately obvious.,central concept → primary branches → secondary branches → connections → insights
+risk,Pre-mortem Analysis,Imagine project has failed and work backwards to identify potential failure points. Proactive risk identification through hypothetical failure scenarios.,future failure → contributing factors → warning signs → preventive measures
+risk,Risk Matrix,Evaluate risks by probability and impact to prioritize mitigation efforts. Visual framework for systematic risk assessment.,risk identification → probability assessment → impact analysis → prioritization → mitigation
+creative,SCAMPER,Systematic creative thinking through Substitute Combine Adapt Modify Put to other uses Eliminate Reverse. Generates innovative alternatives.,substitute → combine → adapt → modify → other uses → eliminate → reverse
+creative,Six Thinking Hats,Explore topic from six perspectives: facts (white) emotions (red) caution (black) optimism (yellow) creativity (green) process (blue).,facts → emotions → risks → benefits → alternatives → synthesis
+analytical,Root Cause Analysis,Systematic investigation to identify fundamental causes rather than symptoms. Uses various techniques to drill down to core issues.,symptoms → immediate causes → intermediate causes → root causes → solutions
+analytical,Fishbone Diagram,Visual cause-and-effect analysis organizing potential causes into categories. Also known as Ishikawa diagram for systematic problem analysis.,problem statement → major categories → potential causes → sub-causes → prioritization
+strategic,PESTLE Analysis,Examine Political Economic Social Technological Legal Environmental factors. Comprehensive external environment assessment.,political → economic → social → technological → legal → environmental → implications
+strategic,Value Chain Analysis,Examine activities that create value from raw materials to end customer. Identifies competitive advantages and improvement opportunities.,primary activities → support activities → linkages → value creation → optimization
+process,Journey Mapping,Visualize end-to-end experience identifying touchpoints pain points and opportunities. Understanding through customer or user perspective.,stages → touchpoints → actions → emotions → pain points → opportunities
+process,Service Blueprint,Map service delivery showing frontstage backstage and support processes. Reveals service complexity and improvement areas.,customer actions → frontstage → backstage → support processes → improvement areas
+stakeholder,Stakeholder Mapping,Identify and analyze stakeholders by interest and influence. Strategic approach to stakeholder engagement.,identification → interest analysis → influence assessment → engagement strategy
+stakeholder,Empathy Map,Understand stakeholder perspectives through what they think feel see say do. Deep understanding of user needs and motivations.,thinks → feels → sees → says → does → pains → gains
+decision,Decision Matrix,Evaluate options against weighted criteria for objective decision making. Systematic comparison of alternatives.,criteria definition → weighting → scoring → calculation → ranking → selection
+decision,Cost-Benefit Analysis,Compare costs against benefits to evaluate decision viability. Quantitative approach to decision validation.,cost identification → benefit identification → quantification → comparison → recommendation
+validation,Devil's Advocate,Challenge assumptions and proposals by arguing opposing viewpoint. Stress-testing through deliberate opposition.,proposal → counter-arguments → weaknesses → blind spots → strengthened proposal
+validation,Red Team Analysis,Simulate adversarial perspective to identify vulnerabilities. Security and robustness through adversarial thinking.,current approach → adversarial view → attack vectors → vulnerabilities → countermeasures
--- a/src/core/tasks/advanced-elicitation.xml
+++ b/src/core/tasks/advanced-elicitation.xml
@@ -1,20 +1,17 @@
-<!-- BMAD-CORE™ Advanced Elicitation Task v2.0 (LLM-Native) -->
-
-# Advanced Elicitation v2.0 (LLM-Native)
-
-```xml
-<task id="bmad/core/tasks/adv-elicit.md" name="Advanced Elicitation">
+<task id="{bmad_folder}/core/tasks/advanced-elicitation.xml" name="Advanced Elicitation" standalone="true"
+  methods="{project-root}/{bmad_folder}/core/tasks/advanced-elicitation-methods.csv"
+  agent-party="{project-root}/{bmad_folder}/_cfg/agent-manifest.csv">
  <llm critical="true">
    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
    <i>DO NOT skip steps or change the sequence</i>
    <i>HALT immediately when halt-conditions are met</i>
-    <i>Each &lt;action&gt; within &lt;step&gt; is a REQUIRED action to complete that step</i>
+    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
    <i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
  </llm>

  <integration description="When called from workflow">
    <desc>When called during template workflow processing:</desc>
-    <i>1. Receive the current section content that was just generated</i>
+    <i>1. Receive or review the current section content that was just generated or</i>
    <i>2. Apply elicitation methods iteratively to enhance that specific content</i>
    <i>3. Return the enhanced version back when user selects 'x' to proceed and return back</i>
    <i>4. The enhanced content replaces the original section content in the output document</i>
@@ -22,7 +19,7 @@

  <flow>
    <step n="1" title="Method Registry Loading">
-      <action>Load and read {project-root}/core/tasks/adv-elicit-methods.csv</action>
+      <action>Load and read {{methods}} and {{agent-party}}</action>

      <csv-structure>
        <i>category: Method grouping (core, structural, risk, etc.)</i>
@@ -44,7 +41,7 @@
      </smart-selection>
    </step>

-    <step n="2" title="Present Options &amp; Handle Responses">
+    <step n="2" title="Present Options and Handle Responses">

      <format>
        **Advanced Elicitation Options**
@@ -66,11 +63,12 @@
          <i>Apply the method creatively to the current section content being enhanced</i>
          <i>Display the enhanced version showing what the method revealed or improved</i>
          <i>CRITICAL: Ask the user if they would like to apply the changes to the doc (y/n/other) and HALT to await response.</i>
-          <i>CRITICAL: ONLY if Yes, apply the changes. IF No, discard your memory of the proposed changes. If any other reply, try best to follow the instructions given by the user.</i>
+          <i>CRITICAL: ONLY if Yes, apply the changes. IF No, discard your memory of the proposed changes. If any other reply, try best to
+            follow the instructions given by the user.</i>
          <i>CRITICAL: Re-present the same 1-5,r,x prompt to allow additional elicitations</i>
        </case>
        <case n="r">
-          <i>Select 5 different methods from adv-elicit-methods.csv, present new list with same prompt format</i>
+          <i>Select 5 different methods from advanced-elicitation-methods.csv, present new list with same prompt format</i>
        </case>
        <case n="x">
          <i>Complete elicitation and proceed</i>
@@ -105,5 +103,4 @@
      <i> 3. Return to the prompt for additional elicitations or completion</i>
    </step>
  </flow>
-</task>
-```
+</task>
--- a/src/core/tasks/index-docs.xml
+++ b/src/core/tasks/index-docs.xml
@@ -1,14 +1,10 @@
-<!-- BMAD-CORE™ Index Documentation Task -->
-
-# Index Docs v1.1
-
-```xml
-<task id="bmad/core/tasks/index-docs" name="Index Docs" webskip="true">
+<task id="{bmad_folder}/core/tasks/index-docs" name="Index Docs"
+  description="Generates or updates an index.md of all documents in the specified directory" webskip="true" standalone="true">
  <llm critical="true">
    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
    <i>DO NOT skip steps or change the sequence</i>
    <i>HALT immediately when halt-conditions are met</i>
-    <i>Each &lt;action&gt; within &lt;step&gt; is a REQUIRED action to complete that step</i>
+    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
    <i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
  </llm>

@@ -22,7 +18,8 @@
    </step>

    <step n="3" title="Generate Descriptions">
-      <i>Read each file to understand its actual purpose and create brief (3-10 word) descriptions based on the content, not just the filename</i>
+      <i>Read each file to understand its actual purpose and create brief (3-10 word) descriptions based on the content, not just the
+        filename</i>
    </step>

    <step n="4" title="Create/Update Index">
@@ -65,5 +62,4 @@
    <i>Sort alphabetically within groups</i>
    <i>Skip hidden files (starting with .) unless specified</i>
  </validation>
-</task>
-```
+</task>
--- a/src/core/tasks/shard-doc.md
+++ b/src/core/tasks/shard-doc.md
@@ -1,57 +0,0 @@
-<!-- BMAD-CORE™ Document Sharding Task -->
-
-# Shard Doc v1.1
-
-```xml
-<task id="bmad/core/tasks/shard-doc.md" name="Shard Doc">
-  <llm critical="true">
-    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
-    <i>DO NOT skip steps or change the sequence</i>
-    <i>HALT immediately when halt-conditions are met</i>
-    <i>Each &lt;action&gt; within &lt;step&gt; is a REQUIRED action to complete that step</i>
-    <i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
-  </llm>
-
-  <flow>
-    <step n="1" title="Check for Tool">
-      <i>First check if md-tree command is available</i>
-    </step>
-
-    <step n="2" title="Install if Needed">
-      <i>If not available, ask user permission to install: npm install -g @kayvan/markdown-tree-parser</i>
-    </step>
-
-    <step n="3" title="Shard Document">
-      <i>Use the explode command to split the document</i>
-    </step>
-  </flow>
-
-  <usage>
-    <commands>
-      # Install the tool (if needed)
-      npm install -g @kayvan/markdown-tree-parser
-
-      # Shard a document
-      md-tree explode [source-document] [destination-folder]
-
-      # Examples
-      md-tree explode docs/prd.md docs/prd
-      md-tree explode docs/architecture.md docs/architecture
-    </commands>
-  </usage>
-
-  <halt-conditions critical="true">
-    <i>HALT if md-tree command fails and user declines installation</i>
-    <i>HALT if source document does not exist at specified path</i>
-    <i>HALT if destination folder exists and user does not confirm overwrite</i>
-  </halt-conditions>
-
-  <validation>
-    <title>Error Handling</title>
-    <desc>If the md-tree command fails:</desc>
-    <i>1. Check if the tool is installed globally</i>
-    <i>2. Ask user permission to install it</i>
-    <i>3. Retry the operation after installation</i>
-  </validation>
-</task>
-```
--- a/src/core/tasks/validate-workflow.xml
+++ b/src/core/tasks/validate-workflow.xml
@@ -1,7 +1,4 @@
-# Validate Workflow
-
-```xml
-<task id="bmad/core/tasks/validate-workflow.md" name="Validate Workflow Output">
+<task id="{bmad_folder}/core/tasks/validate-workflow.xml" name="Validate Workflow Output">
  <objective>Run a checklist against a document with thorough analysis and produce a validation report</objective>

  <inputs>
@@ -13,7 +10,8 @@
  <flow>
    <step n="1" title="Setup">
      <action>If checklist not provided, load checklist.md from workflow location</action>
-      <action>If document not provided, ask user: "Which document should I validate?"</action>
+      <action>Try to fuzzy match for files similar to the input document name or if user did not provide the document. If document not
+        provided or unsure, ask user: "Which document should I validate?"</action>
      <action>Load both the checklist and document</action>
    </step>

@@ -88,5 +86,4 @@
    <rule>Save report to document's folder automatically</rule>
    <rule>HALT after presenting summary - wait for user</rule>
  </critical-rules>
-</task>
-```
+</task>
--- a/src/core/tasks/workflow.md
+++ b/src/core/tasks/workflow.md
@@ -1,141 +0,0 @@
-<!-- BMAD Method v6 Workflow Execution Task (Simplified) -->
-
-# Workflow
-
-```xml
-<task id="bmad/core/tasks/workflow.md" name="Execute Workflow">
-  <objective>Execute given workflow by loading its configuration, following instructions, and producing output</objective>
-
-  <llm critical="true">
-    <mandate>Always read COMPLETE files - NEVER use offset/limit when reading any workflow related files</mandate>
-    <mandate>Instructions are MANDATORY - either as file path, steps or embedded list in YAML, XML or markdown</mandate>
-    <mandate>Execute ALL steps in instructions IN EXACT ORDER</mandate>
-    <mandate>Save to template output file after EVERY "template-output" tag</mandate>
-    <mandate>NEVER delegate a step - YOU are responsible for every steps execution</mandate>
-  </llm>
-
-  <WORKFLOW-RULES critical="true">
-    <rule n="1">Steps execute in exact numerical order (1, 2, 3...)</rule>
-    <rule n="2">Optional steps: Ask user unless #yolo mode active</rule>
-    <rule n="3">Template-output tags: Save content → Show user → Get approval before continuing</rule>
-    <rule n="4">Elicit tags: Execute immediately unless #yolo mode (which skips ALL elicitation)</rule>
-    <rule n="5">User must approve each major section before continuing UNLESS #yolo mode active</rule>
-  </WORKFLOW-RULES>
-
-  <flow>
-    <step n="1" title="Load and Initialize Workflow">
-      <substep n="1a" title="Load Configuration and Resolve Variables">
-        <action>Read workflow.yaml from provided path</action>
-        <mandate>Load config_source (REQUIRED for all modules)</mandate>
-        <phase n="1">Load external config from config_source path</phase>
-        <phase n="2">Resolve all {config_source}: references with values from config</phase>
-        <phase n="3">Resolve system variables (date:system-generated) and paths ({project-root}, {installed_path})</phase>
-        <phase n="4">Ask user for input of any variables that are still unknown</phase>
-      </substep>
-
-      <substep n="1b" title="Load Required Components">
-        <mandate>Instructions: Read COMPLETE file from path OR embedded list (REQUIRED)</mandate>
-        <check>If template path → Read COMPLETE template file</check>
-        <check>If validation path → Note path for later loading when needed</check>
-        <check>If template: false → Mark as action-workflow (else template-workflow)</check>
-        <note>Data files (csv, json) → Store paths only, load on-demand when instructions reference them</note>
-      </substep>
-
-      <substep n="1c" title="Initialize Output" if="template-workflow">
-        <action>Resolve default_output_file path with all variables and {{date}}</action>
-        <action>Create output directory if doesn't exist</action>
-        <action>If template-workflow → Write template to output file with placeholders</action>
-        <action>If action-workflow → Skip file creation</action>
-      </substep>
-    </step>
-
-    <step n="2" title="Process Each Instruction Step">
-      <iterate>For each step in instructions:</iterate>
-
-      <substep n="2a" title="Handle Step Attributes">
-        <check>If optional="true" and NOT #yolo → Ask user to include</check>
-        <check>If if="condition" → Evaluate condition</check>
-        <check>If for-each="item" → Repeat step for each item</check>
-        <check>If repeat="n" → Repeat step n times</check>
-      </substep>
-
-      <substep n="2b" title="Execute Step Content">
-        <action>Process step instructions (markdown or XML tags)</action>
-        <action>Replace {{variables}} with values (ask user if unknown)</action>
-        <execute-tags>
-          <tag><action> → Perform the action</tag>
-          <tag><check> → Evaluate condition</tag>
-          <tag><ask> → Prompt user and WAIT for response</tag>
-          <tag><invoke-workflow> → Execute another workflow with given inputs</tag>
-          <tag><invoke-task> → Execute specified task</tag>
-          <tag><goto step="x"> → Jump to specified step</tag>
-        </execute-tags>
-      </substep>
-
-      <substep n="2c" title="Handle Special Output Tags">
-        <if tag="template-output">
-          <mandate>Generate content for this section</mandate>
-          <mandate>Save to file (Write first time, Edit subsequent)</mandate>
-          <action>Show checkpoint separator: ━━━━━━━━━━━━━━━━━━━━━━━</action>
-          <action>Display generated content</action>
-          <ask>Continue [c] or Edit [e]? WAIT for response</ask>
-        </if>
-
-        <if tag="elicit-required">
-          <mandate critical="true">YOU MUST READ the file at {project-root}/bmad/core/tasks/adv-elicit.md using Read tool BEFORE presenting any elicitation menu</mandate>
-          <action>Load and run task {project-root}/bmad/core/tasks/adv-elicit.md with current context</action>
-          <action>Show elicitation menu 5 relevant options (list 1-5 options, Continue [c] or Reshuffle [r])</action>
-          <mandate>HALT and WAIT for user selection</mandate>
-        </if>
-      </substep>
-
-      <substep n="2d" title="Step Completion">
-        <check>If no special tags and NOT #yolo:</check>
-        <ask>Continue to next step? (y/n/edit)</ask>
-      </substep>
-    </step>
-
-    <step n="3" title="Completion">
-      <check>If checklist exists → Run validation</check>
-      <check>If template: false → Confirm actions completed</check>
-      <check>Else → Confirm document saved to output path</check>
-      <action>Report workflow completion</action>
-    </step>
-  </flow>
-
-  <execution-modes>
-    <mode name="normal">Full user interaction at all decision points</mode>
-    <mode name="#yolo">Skip optional sections, skip all elicitation, minimize prompts</mode>
-  </execution-modes>
-
-  <supported-tags desc="Instructions can use these tags">
-    <structural>
-      <tag>step n="X" goal="..." - Define step with number and goal</tag>
-      <tag>optional="true" - Step can be skipped</tag>
-      <tag>if="condition" - Conditional execution</tag>
-      <tag>for-each="collection" - Iterate over items</tag>
-      <tag>repeat="n" - Repeat n times</tag>
-    </structural>
-    <execution>
-      <tag>action - Required action to perform</tag>
-      <tag>check - Condition to evaluate</tag>
-      <tag>ask - Get user input (wait for response)</tag>
-      <tag>goto - Jump to another step</tag>
-      <tag>invoke-workflow - Call another workflow</tag>
-      <tag>invoke-task - Call a task</tag>
-    </execution>
-    <output>
-      <tag>template-output - Save content checkpoint</tag>
-      <tag>elicit-required - Trigger enhancement</tag>
-      <tag>critical - Cannot be skipped</tag>
-      <tag>example - Show example output</tag>
-    </output>
-  </supported-tags>
-
-  <llm final="true">
-    <mandate>This is the complete workflow execution engine</mandate>
-    <mandate>You MUST Follow instructions exactly as written and maintain conversation context between steps</mandate>
-    <mandate>If confused, re-read this task, the workflow yaml, and any yaml indicated files</mandate>
-  </llm>
-</task>
-```
--- a/src/core/tasks/workflow.xml
+++ b/src/core/tasks/workflow.xml
@@ -0,0 +1,270 @@
+<task id="{bmad_folder}/core/tasks/workflow.xml" name="Execute Workflow">
+  <objective>Execute given workflow by loading its configuration, following instructions, and producing output</objective>
+
+  <llm critical="true">
+    <mandate>Always read COMPLETE files - NEVER use offset/limit when reading any workflow related files</mandate>
+    <mandate>Instructions are MANDATORY - either as file path, steps or embedded list in YAML, XML or markdown</mandate>
+    <mandate>Execute ALL steps in instructions IN EXACT ORDER</mandate>
+    <mandate>Save to template output file after EVERY "template-output" tag</mandate>
+    <mandate>NEVER delegate a step - YOU are responsible for every steps execution</mandate>
+  </llm>
+
+  <WORKFLOW-RULES critical="true">
+    <rule n="1">Steps execute in exact numerical order (1, 2, 3...)</rule>
+    <rule n="2">Optional steps: Ask user unless #yolo mode active</rule>
+    <rule n="3">Template-output tags: Save content → Show user → Get approval before continuing</rule>
+    <rule n="4">User must approve each major section before continuing UNLESS #yolo mode active</rule>
+  </WORKFLOW-RULES>
+
+  <flow>
+    <step n="1" title="Load and Initialize Workflow">
+      <substep n="1a" title="Load Configuration and Resolve Variables">
+        <action>Read workflow.yaml from provided path</action>
+        <mandate>Load config_source (REQUIRED for all modules)</mandate>
+        <phase n="1">Load external config from config_source path</phase>
+        <phase n="2">Resolve all {config_source}: references with values from config</phase>
+        <phase n="3">Resolve system variables (date:system-generated) and paths ({project-root}, {installed_path})</phase>
+        <phase n="4">Ask user for input of any variables that are still unknown</phase>
+      </substep>
+
+      <substep n="1b" title="Load Required Components">
+        <mandate>Instructions: Read COMPLETE file from path OR embedded list (REQUIRED)</mandate>
+        <check>If template path → Read COMPLETE template file</check>
+        <check>If validation path → Note path for later loading when needed</check>
+        <check>If template: false → Mark as action-workflow (else template-workflow)</check>
+        <note>Data files (csv, json) → Store paths only, load on-demand when instructions reference them</note>
+      </substep>
+
+      <substep n="1c" title="Initialize Output" if="template-workflow">
+        <action>Resolve default_output_file path with all variables and {{date}}</action>
+        <action>Create output directory if doesn't exist</action>
+        <action>If template-workflow → Write template to output file with placeholders</action>
+        <action>If action-workflow → Skip file creation</action>
+      </substep>
+    </step>
+
+    <step n="2" title="Process Each Instruction Step">
+      <iterate>For each step in instructions:</iterate>
+
+      <substep n="2a" title="Handle Step Attributes">
+        <check>If optional="true" and NOT #yolo → Ask user to include</check>
+        <check>If if="condition" → Evaluate condition</check>
+        <check>If for-each="item" → Repeat step for each item</check>
+        <check>If repeat="n" → Repeat step n times</check>
+      </substep>
+
+      <substep n="2b" title="Execute Step Content">
+        <action>Process step instructions (markdown or XML tags)</action>
+        <action>Replace {{variables}} with values (ask user if unknown)</action>
+        <execute-tags>
+          <tag>action xml tag → Perform the action</tag>
+          <tag>check if="condition" xml tag → Conditional block wrapping actions (requires closing &lt;/check&gt;)</tag>
+          <tag>ask xml tag → Prompt user and WAIT for response</tag>
+          <tag>invoke-workflow xml tag → Execute another workflow with given inputs</tag>
+          <tag>invoke-task xml tag → Execute specified task</tag>
+          <tag>invoke-protocol name="protocol_name" xml tag → Execute reusable protocol from protocols section</tag>
+          <tag>goto step="x" → Jump to specified step</tag>
+        </execute-tags>
+      </substep>
+
+      <substep n="2c" title="Handle template-output Tags">
+        <if tag="template-output">
+          <mandate>Generate content for this section</mandate>
+          <mandate>Save to file (Write first time, Edit subsequent)</mandate>
+          <action>Show checkpoint separator: ━━━━━━━━━━━━━━━━━━━━━━━</action>
+          <action>Display generated content</action>
+          <ask> [a] Advanced Elicitation, [c] Continue, [p] Party-Mode, [y] YOLO the rest of this document only. WAIT for response. <if
+              response="a">
+              <action>Start the advanced elicitation workflow {project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml</action>
+            </if>
+            <if
+              response="c">
+              <action>Continue to next step</action>
+            </if>
+            <if response="p">
+              <action>Start the party-mode workflow {project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml</action>
+            </if>
+            <if
+              response="y">
+              <action>Enter #yolo mode for the rest of the workflow</action>
+            </if>
+          </ask>
+        </if>
+      </substep>
+
+      <substep n="2d" title="Step Completion">
+        <check>If no special tags and NOT #yolo:</check>
+        <ask>Continue to next step? (y/n/edit)</ask>
+      </substep>
+    </step>
+
+    <step n="3" title="Completion">
+      <check>If checklist exists → Run validation</check>
+      <check>If template: false → Confirm actions completed</check>
+      <check>Else → Confirm document saved to output path</check>
+      <action>Report workflow completion</action>
+    </step>
+  </flow>
+
+  <execution-modes>
+    <mode name="normal">Full user interaction at all decision points</mode>
+    <mode name="#yolo">Skip all confirmations and elicitation, minimize prompts and try to produce all of the workflow automatically by
+      simulating the remaining discussions with an simulated expert user</mode>
+  </execution-modes>
+
+  <supported-tags desc="Instructions can use these tags">
+    <structural>
+      <tag>step n="X" goal="..." - Define step with number and goal</tag>
+      <tag>optional="true" - Step can be skipped</tag>
+      <tag>if="condition" - Conditional execution</tag>
+      <tag>for-each="collection" - Iterate over items</tag>
+      <tag>repeat="n" - Repeat n times</tag>
+    </structural>
+    <execution>
+      <tag>action - Required action to perform</tag>
+      <tag>action if="condition" - Single conditional action (inline, no closing tag needed)</tag>
+      <tag>check if="condition"&gt;...&lt;/check&gt; - Conditional block wrapping multiple items (closing tag required)</tag>
+      <tag>ask - Get user input (wait for response)</tag>
+      <tag>goto - Jump to another step</tag>
+      <tag>invoke-workflow - Call another workflow</tag>
+      <tag>invoke-task - Call a task</tag>
+      <tag>invoke-protocol - Execute a reusable protocol (e.g., discover_inputs)</tag>
+    </execution>
+    <output>
+      <tag>template-output - Save content checkpoint</tag>
+      <tag>critical - Cannot be skipped</tag>
+      <tag>example - Show example output</tag>
+    </output>
+  </supported-tags>
+
+  <conditional-execution-patterns desc="When to use each pattern">
+    <pattern type="single-action">
+      <use-case>One action with a condition</use-case>
+      <syntax>&lt;action if="condition"&gt;Do something&lt;/action&gt;</syntax>
+      <example>&lt;action if="file exists"&gt;Load the file&lt;/action&gt;</example>
+      <rationale>Cleaner and more concise for single items</rationale>
+    </pattern>
+
+    <pattern type="multi-action-block">
+      <use-case>Multiple actions/tags under same condition</use-case>
+      <syntax>&lt;check if="condition"&gt;
+        &lt;action&gt;First action&lt;/action&gt;
+        &lt;action&gt;Second action&lt;/action&gt;
+        &lt;/check&gt;</syntax>
+      <example>&lt;check if="validation fails"&gt;
+        &lt;action&gt;Log error&lt;/action&gt;
+        &lt;goto step="1"&gt;Retry&lt;/goto&gt;
+        &lt;/check&gt;</example>
+      <rationale>Explicit scope boundaries prevent ambiguity</rationale>
+    </pattern>
+
+    <pattern type="nested-conditions">
+      <use-case>Else/alternative branches</use-case>
+      <syntax>&lt;check if="condition A"&gt;...&lt;/check&gt;
+        &lt;check if="else"&gt;...&lt;/check&gt;</syntax>
+      <rationale>Clear branching logic with explicit blocks</rationale>
+    </pattern>
+  </conditional-execution-patterns>
+
+  <protocols desc="Reusable workflow protocols that can be invoked via invoke-protocol tag">
+    <protocol name="discover_inputs" desc="Smart file discovery and loading based on input_file_patterns">
+      <objective>Intelligently load project files (whole or sharded) based on workflow's input_file_patterns configuration</objective>
+
+      <critical>Only execute if workflow.yaml contains input_file_patterns section</critical>
+
+      <flow>
+        <step n="1" title="Parse Input File Patterns">
+          <action>Read input_file_patterns from loaded workflow.yaml</action>
+          <action>For each pattern group (prd, architecture, epics, etc.), note the load_strategy if present</action>
+        </step>
+
+        <step n="2" title="Load Files Using Smart Strategies">
+          <iterate>For each pattern in input_file_patterns:</iterate>
+
+          <substep n="2a" title="Try Whole Document First">
+            <action>Attempt glob match on 'whole' pattern (e.g., "{output_folder}/*prd*.md")</action>
+            <check if="matches found">
+              <action>Load ALL matching files completely (no offset/limit)</action>
+              <action>Store content in variable: {pattern_name_content} (e.g., {prd_content})</action>
+              <action>Mark pattern as RESOLVED, skip to next pattern</action>
+            </check>
+          </substep>
+
+          <substep n="2b" title="Try Sharded Document if Whole Not Found">
+            <check if="no whole matches AND sharded pattern exists">
+              <action>Determine load_strategy from pattern config (defaults to FULL_LOAD if not specified)</action>
+
+              <strategy name="FULL_LOAD">
+                <desc>Load ALL files in sharded directory - used for PRD, Architecture, UX, brownfield docs</desc>
+                <action>Use glob pattern to find ALL .md files (e.g., "{output_folder}/*architecture*/*.md")</action>
+                <action>Load EVERY matching file completely</action>
+                <action>Concatenate content in logical order (index.md first if exists, then alphabetical)</action>
+                <action>Store in variable: {pattern_name_content}</action>
+              </strategy>
+
+              <strategy name="SELECTIVE_LOAD">
+                <desc>Load specific shard using template variable - example: used for epics with {{epic_num}}</desc>
+                <action>Check for template variables in sharded_single pattern (e.g., {{epic_num}})</action>
+                <action>If variable undefined, ask user for value OR infer from context</action>
+                <action>Resolve template to specific file path</action>
+                <action>Load that specific file</action>
+                <action>Store in variable: {pattern_name_content}</action>
+              </strategy>
+
+              <strategy name="INDEX_GUIDED">
+                <desc>Load index.md, analyze structure and description of each doc in the index, then intelligently load relevant docs</desc>
+                <mandate>DO NOT BE LAZY - use best judgment to load documents that might have relevant information, even if only a 5% chance</mandate>
+                <action>Load index.md from sharded directory</action>
+                <action>Parse table of contents, links, section headers</action>
+                <action>Analyze workflow's purpose and objective</action>
+                <action>Identify which linked/referenced documents are likely relevant</action>
+                <example>If workflow is about authentication and index shows "Auth Overview", "Payment Setup", "Deployment" → Load auth
+                  docs, consider deployment docs, skip payment</example>
+                <action>Load all identified relevant documents</action>
+                <action>Store combined content in variable: {pattern_name_content}</action>
+                <note>When in doubt, LOAD IT - context is valuable, being thorough is better than missing critical info</note>
+              </strategy>
+            </check>
+          </substep>
+
+          <substep n="2c" title="Handle Not Found">
+            <check if="no matches for whole OR sharded">
+              <action>Set {pattern_name_content} to empty string</action>
+              <action>Note in session: "No {pattern_name} files found" (not an error, just unavailable, offer use change to provide)</action>
+            </check>
+          </substep>
+        </step>
+
+        <step n="3" title="Report Discovery Results">
+          <action>List all loaded content variables with file counts</action>
+          <example>
+            ✓ Loaded {prd_content} from 1 file: PRD.md
+            ✓ Loaded {architecture_content} from 5 sharded files: architecture/index.md, architecture/system-design.md, ...
+            ✓ Loaded {epics_content} from selective load: epics/epic-3.md
+            ○ No ux_design files found
+          </example>
+          <note>This gives workflow transparency into what context is available</note>
+        </step>
+      </flow>
+
+      <usage-in-instructions>
+        <example desc="Typical usage in workflow instructions.md">
+          &lt;step n="0" goal="Discover and load project context"&gt;
+          &lt;invoke-protocol name="discover_inputs" /&gt;
+          &lt;/step&gt;
+
+          &lt;step n="1" goal="Analyze requirements"&gt;
+          &lt;action&gt;Review {prd_content} for functional requirements&lt;/action&gt;
+          &lt;action&gt;Cross-reference with {architecture_content} for technical constraints&lt;/action&gt;
+          &lt;/step&gt;
+        </example>
+      </usage-in-instructions>
+    </protocol>
+  </protocols>
+
+  <llm final="true">
+    <mandate>This is the complete workflow execution engine</mandate>
+    <mandate>You MUST Follow instructions exactly as written and maintain conversation context between steps</mandate>
+    <mandate>If confused, re-read this task, the workflow yaml, and any yaml indicated files</mandate>
+  </llm>
+</task>
--- a/src/core/tools/shard-doc.xml
+++ b/src/core/tools/shard-doc.xml
@@ -0,0 +1,109 @@
+<tool id="{bmad_folder}/core/tasks/shard-doc" name="Shard Document"
+  description="Splits large markdown documents into smaller, organized files based on level 2 (default) sections" webskip="true"
+  standalone="true">
+  <objective>Split large markdown documents into smaller, organized files based on level 2 sections using @kayvan/markdown-tree-parser tool</objective>
+
+  <llm critical="true">
+    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
+    <i>DO NOT skip steps or change the sequence</i>
+    <i>HALT immediately when halt-conditions are met</i>
+    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
+    <i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
+  </llm>
+
+  <critical-context>
+    <i>Uses `npx @kayvan/markdown-tree-parser` to automatically shard documents by level 2 headings and generate an index</i>
+  </critical-context>
+
+  <flow>
+    <step n="1" title="Get Source Document">
+      <action>Ask user for the source document path if not provided already</action>
+      <action>Verify file exists and is accessible</action>
+      <action>Verify file is markdown format (.md extension)</action>
+      <action if="file not found or not markdown">HALT with error message</action>
+    </step>
+
+    <step n="2" title="Get Destination Folder">
+      <action>Determine default destination: same location as source file, folder named after source file without .md extension</action>
+      <action>Example: /path/to/architecture.md → /path/to/architecture/</action>
+      <action>Ask user for the destination folder path ([y] to confirm use of default: [suggested-path], else enter a new path)</action>
+      <action if="user accepts default">Use the suggested destination path</action>
+      <action if="user provides custom path">Use the custom destination path</action>
+      <action>Verify destination folder exists or can be created</action>
+      <action>Check write permissions for destination</action>
+      <action if="permission denied">HALT with error message</action>
+    </step>
+
+    <step n="3" title="Execute Sharding">
+      <action>Inform user that sharding is beginning</action>
+      <action>Execute command: `npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]`</action>
+      <action>Capture command output and any errors</action>
+      <action if="command fails">HALT and display error to user</action>
+    </step>
+
+    <step n="4" title="Verify Output">
+      <action>Check that destination folder contains sharded files</action>
+      <action>Verify index.md was created in destination folder</action>
+      <action>Count the number of files created</action>
+      <action if="no files created">HALT with error message</action>
+    </step>
+
+    <step n="5" title="Report Completion">
+      <action>Display completion report to user including:</action>
+      <i>- Source document path and name</i>
+      <i>- Destination folder path</i>
+      <i>- Number of section files created</i>
+      <i>- Confirmation that index.md was created</i>
+      <i>- Any tool output or warnings</i>
+      <action>Inform user that sharding completed successfully</action>
+    </step>
+
+    <step n="6" title="Handle Original Document">
+      <critical>Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion</critical>
+      <action>Present user with options for the original document:</action>
+
+      <ask>What would you like to do with the original document `[source-document-name]`?
+
+Options:
+[d] Delete - Remove the original (recommended - shards can always be recombined)
+[m] Move to archive - Move original to a backup/archive location
+[k] Keep - Leave original in place (NOT recommended - defeats sharding purpose)
+
+Your choice (d/m/k):</ask>
+
+      <check if="user selects 'd' (delete)">
+        <action>Delete the original source document file</action>
+        <action>Confirm deletion to user: "✓ Original document deleted: [source-document-path]"</action>
+        <note>The document can be reconstructed from shards by concatenating all section files in order</note>
+      </check>
+
+      <check if="user selects 'm' (move)">
+        <action>Determine default archive location: same directory as source, in an "archive" subfolder</action>
+        <action>Example: /path/to/architecture.md → /path/to/archive/architecture.md</action>
+        <ask>Archive location ([y] to use default: [default-archive-path], or provide custom path):</ask>
+        <action if="user accepts default">Use default archive path</action>
+        <action if="user provides custom path">Use custom archive path</action>
+        <action>Create archive directory if it doesn't exist</action>
+        <action>Move original document to archive location</action>
+        <action>Confirm move to user: "✓ Original document moved to: [archive-path]"</action>
+      </check>
+
+      <check if="user selects 'k' (keep)">
+        <action>Display warning to user:</action>
+        <output>⚠️ WARNING: Keeping both original and sharded versions is NOT recommended.
+
+This creates confusion because:
+- The discover_inputs protocol may load the wrong version
+- Updates to one won't reflect in the other
+- You'll have duplicate content taking up space
+
+Consider deleting or archiving the original document.</output>
+        <action>Confirm user choice: "Original document kept at: [source-document-path]"</action>
+      </check>
+    </step>
+  </flow>
+
+  <halt-conditions critical="true">
+    <i>HALT if npx command fails or produces no output files</i>
+  </halt-conditions>
+</tool>
--- a/src/core/workflows/bmad-init/instructions.md
+++ b/src/core/workflows/bmad-init/instructions.md
@@ -1,79 +0,0 @@
-# BMAD Init - System Initialization Instructions
-
-<workflow>
-
-<step n="1" goal="Welcome and Status Check">
-  <action>Display welcome banner with BMAD branding</action>
-  <action>Check for BMAD installation at {project-root}/bmad</action>
-  <check>If installation found:</check>
-    <action>Display current version from {project-root}/bmad/_cfg/manifest.yaml</action>
-    <action>Show installation date and status</action>
-  <check>If not found:</check>
-    <action>Display warning that BMAD is not installed</action>
-    <action>Suggest running the installer first</action>
-    <action>Exit workflow</action>
-  <action>Display formatted status summary:
-    ╔════════════════════════════════════════╗
-    ║         BMAD INITIALIZATION            ║
-    ╚════════════════════════════════════════╝
-
-    Status: [Installed/Not Found]
-    Location: {project-root}/bmad
-    Version: [from manifest]
-    Installed: [date from manifest]
-
-  </action>
-</step>
-
-<step n="2" goal="Present Initialization Options">
-  <action>Display available initialization and maintenance tasks</action>
-  <ask>Select an initialization task:
-
-    1. Customize Installed Agents and Agent Party (Coming Soon)
-       - Assign new names and personas to agents
-       - Create runtime agent variants
-       - NOTE: This can all be done manually, but doing it through here will be easier and also update the party-mode manifest
-
-    2. Verify Installation (Coming Soon)
-       - Check all files are properly installed
-       - Validate configurations
-
-    3. Exit
-
-    Please select an option (1-3).
-
-  </ask>
-</step>
-
-<step n="3" goal="Process User Selection">
-  <check>If user selected "1":</check>
-    <action>Display message: ⚠️ Installed Agent Auto Customization is coming soon.</action>
-    <<action>Return to step 2</action>
-
-<check>If user selected "2":</check>
-<action>Display message: ⚠️ Installation verification is coming soon.</action>
-<action>Return to step 2</action>
-
-<check>If user selected "3":</check>
-<action>Display message: Exiting BMAD Init. Thank you!</action>
-<goto step="5">Exit workflow</goto>
-</step>
-
-<step n="4" goal="Post-Task Options">
-  <action>Display completion status of the executed task</action>
-  <ask>Task completed successfully!
-
-Would you like to perform another initialization task? (y/n):</ask>
-<check>If user responds "y":</check>
-<goto step="2">Return to menu</goto>
-<check>If user responds "n":</check>
-<goto step="5">Exit workflow</goto>
-</step>
-
-<step n="5" goal="Exit Workflow">
-  <action>Display farewell message</action>
-  <action>Suggest user start a new context or clear context if needed</action>
-  <action>Exit workflow</action>
-</step>
-
-</workflow>
--- a/src/core/workflows/bmad-init/workflow.yaml
+++ b/src/core/workflows/bmad-init/workflow.yaml
@@ -1,24 +0,0 @@
-# BMAD Init - System Initialization Workflow
-name: "bmad-init"
-description: "BMAD system initialization and maintenance workflow for agent manifest generation and system configuration"
-author: "BMad"
-
-# Critical variables
-config_source: "{project-root}/bmad/_cfg/manifest.yaml"
-date: system-generated
-
-# This is an action workflow - no template output
-template: false
-instructions: "{project-root}/src/core/workflows/bmad-init/instructions.md"
-
-# Sub-components
-party_update_instructions: "{project-root}/src/core/workflows/bmad-init/party-update/instructions.md"
-
-# No specific output file - this workflow performs various system actions
-default_output_file: null
-
-# Required tools for execution
-required_tools:
-  - file_operations
-  - llm_analysis
-  - xml_generation
--- a/src/modules/cis/workflows/brainstorming/README.md
+++ b/src/modules/cis/workflows/brainstorming/README.md
@@ -20,26 +20,16 @@ The brainstorming workflow facilitates interactive brainstorming sessions using

 ## Usage

-### Basic Invocation
-
-```bash
-workflow brainstorming
-```
-
-### With Context Document
-
-```bash
-# Provide domain-specific context to guide the session
-workflow brainstorming --data /path/to/context.md
-```
-
 ### Configuration

-The workflow leverages configuration from `/bmad/cis/config.yaml`:
+The workflow leverages configuration from `{bmad_folder}/core/config.yaml`:

 - **output_folder**: Where session results are saved
 - **user_name**: Session participant identification
- **brain_techniques**: CSV database of 36 creative techniques
+
+And the following has a default or can be passed in as an override for custom brainstorming scenarios.
+
+- **brain_techniques**: CSV database of 36 creative techniques, default is `./brain-methods.csv`

 ## Workflow Structure

@@ -180,12 +170,12 @@ The workflow includes 36 techniques organized into 7 categories:
 2. **Technique Sessions** - Detailed capture of each technique's ideation process
 3. **Idea Categorization** - Immediate opportunities, future innovations, moonshots, insights
 4. **Action Planning** - Top 3 priorities with rationale, steps, resources, timelines
-5. **Reflection & Follow-up** - Session analysis, recommendations, next steps planning
+5. **Reflection and Follow-up** - Session analysis, recommendations, next steps planning

 ## Requirements

 - No special software requirements
- Access to the CIS module configuration (`/bmad/cis/config.yaml`)
+- Access to the CIS module configuration (`{bmad_folder}/cis/config.yaml`)
 - Active participation and engagement throughout the interactive session
 - Optional: Domain context document for focused brainstorming

@@ -268,4 +258,4 @@ For issues or questions:

 ---

-_Part of the BMad Method v5 - Creative Ideation & Synthesis (CIS) Module_
+_Part of the BMad Method v6 - Creative Ideation and Synthesis (CIS) Module_
--- a/src/modules/cis/workflows/brainstorming/brain-methods.csv
+++ b/src/modules/cis/workflows/brainstorming/brain-methods.csv
--- a/src/modules/cis/workflows/brainstorming/instructions.md
+++ b/src/modules/cis/workflows/brainstorming/instructions.md
@@ -3,25 +3,29 @@
 ## Workflow

 <workflow>
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
-<critical>You MUST have already loaded and processed: {project_root}/bmad/cis/workflows/brainstorming/workflow.yaml</critical>
+<critical>The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project_root}/{bmad_folder}/core/workflows/brainstorming/workflow.yaml</critical>

 <step n="1" goal="Session Setup">

 <action>Check if context data was provided with workflow invocation</action>
-<check>If data attribute was passed to this workflow:</check>
-<action>Load the context document from the data file path</action>
-<action>Study the domain knowledge and session focus</action>
-<action>Use the provided context to guide the session</action>
-<action>Acknowledge the focused brainstorming goal</action>
-<ask response="session_refinement">I see we're brainstorming about the specific domain outlined in the context. What particular aspect would you like to explore?</ask>
-<check>Else (no context data provided):</check>
-<action>Proceed with generic context gathering</action>
-<ask response="session_topic">1. What are we brainstorming about?</ask>
-<ask response="stated_goals">2. Are there any constraints or parameters we should keep in mind?</ask>
-<ask>3. Is the goal broad exploration or focused ideation on specific aspects?</ask>
+
+<check if="data attribute was passed to this workflow">
+  <action>Load the context document from the data file path</action>
+  <action>Study the domain knowledge and session focus</action>
+  <action>Use the provided context to guide the session</action>
+  <action>Acknowledge the focused brainstorming goal</action>
+  <ask response="session_refinement">I see we're brainstorming about the specific domain outlined in the context. What particular aspect would you like to explore?</ask>
+</check>
+
+<check if="no context data provided">
+  <action>Proceed with generic context gathering</action>
+  <ask response="session_topic">1. What are we brainstorming about?</ask>
+  <ask response="stated_goals">2. Are there any constraints or parameters we should keep in mind?</ask>
+  <ask>3. Is the goal broad exploration or focused ideation on specific aspects?</ask>

 <critical>Wait for user response before proceeding. This context shapes the entire session.</critical>
+</check>

 <template-output>session_topic, stated_goals</template-output>

@@ -40,19 +44,19 @@ Based on the context from Step 1, present these four approach options:
 Which approach would you prefer? (Enter 1-4)
 </ask>

-<check>Based on selection, proceed to appropriate sub-step</check>
-
  <step n="2a" title="User-Selected Techniques" if="selection==1">
    <action>Load techniques from {brain_techniques} CSV file</action>
    <action>Parse: category, technique_name, description, facilitation_prompts</action>

-    <check>If strong context from Step 1 (specific problem/goal)</check>
-    <action>Identify 2-3 most relevant categories based on stated_goals</action>
-    <action>Present those categories first with 3-5 techniques each</action>
-    <action>Offer "show all categories" option</action>
+    <check if="strong context from Step 1 (specific problem/goal)">
+      <action>Identify 2-3 most relevant categories based on stated_goals</action>
+      <action>Present those categories first with 3-5 techniques each</action>
+      <action>Offer "show all categories" option</action>
+    </check>

-    <check>Else (open exploration)</check>
-    <action>Display all 7 categories with helpful descriptions</action>
+    <check if="open exploration">
+      <action>Display all 7 categories with helpful descriptions</action>
+    </check>

    Category descriptions to guide selection:
    - **Structured:** Systematic frameworks for thorough exploration
@@ -154,6 +158,7 @@ Which approach would you prefer? (Enter 1-4)

  </step>

+<critical>Create the output document using the template, and record at the {{session_start_plan}} documenting the chosen techniques, along with which approach was used. For all remaining steps, progressively add to the document throughout the brainstorming</critical>
 </step>

 <step n="3" goal="Execute Techniques Interactively">
@@ -198,7 +203,7 @@ Example facilitation flow for any technique:

 4. Next Prompt: Pull next facilitation_prompt when ready to advance

-5. Monitor Energy: After 10-15 minutes, check if they want to continue or switch
+5. Monitor Energy: After a few rounds, check if they want to continue or switch

 The CSV provides the prompts - your role is to facilitate naturally in your unique voice.
 </example>
@@ -211,7 +216,7 @@ Continue engaging with the technique until the user indicates they want to:
 - End the session

 <energy-checkpoint>
-  After 15-20 minutes with a technique, check: "Should we continue with this technique or try something new?"
+  After 4 rounds with a technique, check: "Should we continue with this technique or try something new?"
 </energy-checkpoint>

 <template-output>technique_sessions</template-output>
@@ -250,7 +255,7 @@ Analyze the session to identify deeper patterns:
 2. **Surface key insights** - What realizations emerged during the process? -> insights_learnings
 3. **Note surprising connections** - What unexpected relationships were discovered? -> insights_learnings

-<elicit-required/>
+<invoke-task halt="true">{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml</invoke-task>

 <template-output>key_themes, insights_learnings</template-output>

--- a/src/modules/cis/workflows/brainstorming/template.md
+++ b/src/modules/cis/workflows/brainstorming/template.md
@@ -4,6 +4,10 @@
 **Facilitator:** {{agent_role}} {{agent_name}}
 **Participant:** {{user_name}}

+## Session Start
+
+{{session_start_plan}}
+
 ## Executive Summary

 **Topic:** {{session_topic}}
@@ -42,7 +46,7 @@ _Ambitious, transformative concepts_

 {{moonshots}}

-### Insights & Learnings
+### Insights and Learnings

 _Key realizations from the session_

@@ -73,7 +77,7 @@ _Key realizations from the session_
 - Resources needed: {{priority_3_resources}}
 - Timeline: {{priority_3_timeline}}

-## Reflection & Follow-up
+## Reflection and Follow-up

 ### What Worked Well

--- a/src/modules/cis/workflows/brainstorming/workflow.yaml
+++ b/src/modules/cis/workflows/brainstorming/workflow.yaml
@@ -4,27 +4,35 @@ description: "Facilitate interactive brainstorming sessions using diverse creati
 author: "BMad"

 # Critical variables load from config_source
-config_source: "{project-root}/bmad/cis/config.yaml"
+config_source: "{project-root}/{bmad_folder}/cis/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 date: system-generated

-# Optional inputs for guided brainstorming
-recommended_inputs:
-  - session_context: "Context document passed via data attribute"
-  - previous_results: "{output_folder}/brainstorming-*.md"
-
 # Context can be provided via data attribute when invoking
 # Example: data="{path}/context.md" provides domain-specific guidance

 # Module path and component files
-installed_path: "{project-root}/bmad/cis/workflows/brainstorming"
+installed_path: "{project-root}/{bmad_folder}/core/workflows/brainstorming"
 template: "{installed_path}/template.md"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
-
-# Required Data Files
 brain_techniques: "{installed_path}/brain-methods.csv"

 # Output configuration
 default_output_file: "{output_folder}/brainstorming-session-results-{{date}}.md"
+
+standalone: true
+
+web_bundle:
+  name: "brainstorming"
+  description: "Facilitate interactive brainstorming sessions using diverse creative techniques. This workflow facilitates interactive brainstorming sessions using diverse creative techniques. The session is highly interactive, with the AI acting as a facilitator to guide the user through various ideation methods to generate and refine creative solutions."
+  author: "BMad"
+  template: "{bmad_folder}/core/workflows/brainstorming/template.md"
+  instructions: "{bmad_folder}/core/workflows/brainstorming/instructions.md"
+  brain_techniques: "{bmad_folder}/core/workflows/brainstorming/brain-methods.csv"
+  use_advanced_elicitation: true
+  web_bundle_files:
+    - "{bmad_folder}/core/workflows/brainstorming/instructions.md"
+    - "{bmad_folder}/core/workflows/brainstorming/brain-methods.csv"
+    - "{bmad_folder}/core/workflows/brainstorming/template.md"
--- a/src/core/workflows/party-mode/instructions.md
+++ b/src/core/workflows/party-mode/instructions.md
@@ -1,27 +1,23 @@
 # Party Mode - Multi-Agent Discussion Instructions

-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
+<critical>The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml</critical>
 <critical>This workflow orchestrates group discussions between all installed BMAD agents</critical>

 <workflow>

 <step n="1" goal="Load Agent Manifest and Configurations">
-  <action>Load the agent manifest from {{manifest}}</action>
-  <action>Parse XML to extract all agent entries with their condensed information:</action>
-    - id (file path)
-    - name
-    - title
-    - role (single sentence with capabilities)
-    - style (communication style)
-    - principles
-    - memories (if present)
-    - collaborators (key collaborators if any)
-
-<action>For each agent found in manifest:</action>
-<check>Look for config override at {{agent_configs}}[module]-[agent-name].md</check>
-<check>If config override exists:</check>
-<action>Load the override configuration</action>
-<action>MERGE override data with manifest data (overrides take precedence):</action> - Override role replaces manifest role if present - Override style replaces manifest style if present - Override principles replace manifest principles if present - Override memories replace or append to manifest memories - Any additional persona elements from override are added
+  <action>Load the agent manifest CSV from {{agent_manifest}}</action>
+  <action>Parse CSV to extract all agent entries with their condensed information:</action>
+    - name (agent identifier)
+    - displayName (agent's persona name)
+    - title (formal position)
+    - icon (visual identifier)
+    - role (capabilities summary)
+    - identity (background/expertise)
+    - communicationStyle (how they communicate)
+    - principles (decision-making philosophy)
+    - module (source module)
+    - path (file location)

 <action>Build complete agent roster with merged personalities</action>
 <action>Store agent data for use in conversation orchestration</action>
@@ -63,9 +59,9 @@
  <substep n="3b" goal="Generate In-Character Responses">
    <action>For each selected agent, generate authentic response:</action>
    <action>Use the agent's merged personality data:</action>
-      - Apply their communication style exactly
+      - Apply their communicationStyle exactly
      - Reflect their principles in reasoning
-      - Reference their memories if contextually relevant
+      - Draw from their identity and role for expertise
      - Maintain their unique voice and perspective

    <action>Enable natural cross-talk between agents:</action>
@@ -77,20 +73,23 @@
  </substep>

  <substep n="3c" goal="Handle Questions and Interactions">
-    <check>If an agent asks the user a direct question:</check>
+    <check if="an agent asks the user a direct question">
      <action>Clearly highlight the question</action>
      <action>End that round of responses</action>
      <action>Display: "[Agent Name]: [Their question]"</action>
      <action>Display: "[Awaiting user response...]"</action>
      <action>WAIT for user input before continuing</action>
+    </check>

-    <check>If agents ask each other questions:</check>
+    <check if="agents ask each other questions">
      <action>Allow natural back-and-forth in the same response round</action>
      <action>Maintain conversational flow</action>
+    </check>

-    <check>If discussion becomes circular or repetitive:</check>
+    <check if="discussion becomes circular or repetitive">
      <action>The BMad Master will summarize</action>
      <action>Redirect to new aspects or ask for user guidance</action>
+    </check>

  </substep>

@@ -110,15 +109,18 @@
  </substep>

  <substep n="3e" goal="Check for Exit Conditions">
-    <check>If user message contains any {{exit_triggers}}:</check>
+    <check if="user message contains any {{exit_triggers}}">
      <action>Have agents provide brief farewells in character</action>
      <action>Thank user for the discussion</action>
      <goto step="4">Exit party mode</goto>
+    </check>

-    <check>If user seems done or conversation naturally concludes:</check>
+    <check if="user seems done or conversation naturally concludes">
      <ask>Would you like to continue the discussion or end party mode?</ask>
-      <check>If user indicates end:</check>
+      <check if="user indicates end">
        <goto step="4">Exit party mode</goto>
+      </check>
+    </check>

  </substep>
 </step>
--- a/src/core/workflows/party-mode/workflow.yaml
+++ b/src/core/workflows/party-mode/workflow.yaml
@@ -4,21 +4,25 @@ description: "Orchestrates group discussions between all installed BMAD agents,
 author: "BMad"

 # Critical data sources - manifest and config overrides
-manifest: "{project-root}/bmad/_cfg/agent-party.xml"
-agent_configs: "{project-root}/bmad/_cfg/agents/"
+agent_manifest: "{project-root}/{bmad_folder}/_cfg/agent-manifest.csv"
 date: system-generated

 # This is an interactive action workflow - no template output
 template: false
-instructions: "{project-root}/src/core/workflows/party-mode/instructions.md"
-
-# Data files to be loaded at runtime
-data_files:
-  - agent_manifest: "{project-root}/bmad/_cfg/agent-party.xml"
-  - agent_overrides: "{project-root}/bmad/_cfg/agents/*.md"
+instructions: "{project-root}/{bmad_folder}/core/workflows/party-mode/instructions.md"

 # Exit conditions
 exit_triggers:
  - "*exit"
-  - "end party mode"
-  - "stop party mode"
+
+standalone: true
+
+web_bundle:
+  name: "party-mode"
+  description: "Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations"
+  author: "BMad"
+  instructions: "{bmad_folder}/core/workflows/party-mode/instructions.md"
+  agent_manifest: "{bmad_folder}/_cfg/agent-manifest.csv"
+  web_bundle_files:
+    - "{bmad_folder}/core/workflows/party-mode/instructions.md"
+    - "{bmad_folder}/_cfg/agent-manifest.csv"
--- a/src/modules/bmb/README.md
+++ b/src/modules/bmb/README.md
@@ -0,0 +1,194 @@
+# BMB - BMad Builder Module
+
+Specialized tools and workflows for creating, customizing, and extending BMad components including agents, workflows, and complete modules.
+
+## Table of Contents
+
+- [Module Structure](#module-structure)
+- [Core Workflows](#core-workflows)
+- [Agent Types](#agent-types)
+- [Quick Start](#quick-start)
+- [Best Practices](#best-practices)
+
+## Module Structure
+
+### 🤖 Agents
+
+**BMad Builder** - Master builder agent orchestrating all creation workflows with deep knowledge of BMad architecture and conventions.
+
+### 📋 Workflows
+
+Comprehensive suite for building and maintaining BMad components.
+
+## Core Workflows
+
+### Creation Workflows
+
+**[create-agent](./workflows/create-agent/README.md)** - Build BMad agents
+
+- Interactive persona development
+- Command structure design
+- YAML source compilation to .md
+
+**[create-workflow](./workflows/create-workflow/README.md)** - Design workflows
+
+- Structured multi-step processes
+- Configuration validation
+- Web bundle support
+
+**[create-module](./workflows/create-module/README.md)** - Build complete modules
+
+- Full module infrastructure
+- Agent and workflow integration
+- Installation automation
+
+**[module-brief](./workflows/module-brief/README.md)** - Strategic planning
+
+- Module blueprint creation
+- Vision and architecture
+- Comprehensive analysis
+
+### Editing Workflows
+
+**[edit-agent](./workflows/edit-agent/README.md)** - Modify existing agents
+
+- Persona refinement
+- Command updates
+- Best practice compliance
+
+**[edit-workflow](./workflows/edit-workflow/README.md)** - Update workflows
+
+- Structure maintenance
+- Configuration updates
+- Documentation sync
+
+**[edit-module](./workflows/edit-module/README.md)** - Module enhancement
+
+- Component modifications
+- Dependency management
+- Version control
+
+### Maintenance Workflows
+
+**[convert-legacy](./workflows/convert-legacy/README.md)** - Migration tool
+
+- v4 to v6 conversion
+- Structure compliance
+- Convention updates
+
+**[audit-workflow](./workflows/audit-workflow/README.md)** - Quality validation
+
+- Structure verification
+- Config standards check
+- Bloat detection
+- Web bundle completeness
+
+**[redoc](./workflows/redoc/README.md)** - Auto-documentation
+
+- Reverse-tree approach
+- Technical writer quality
+- Convention compliance
+
+## Agent Types
+
+BMB creates three agent architectures:
+
+### Full Module Agent
+
+- Complete persona and role definition
+- Command structure with fuzzy matching
+- Workflow integration
+- Module-specific capabilities
+
+### Hybrid Agent
+
+- Shared core capabilities
+- Module-specific extensions
+- Cross-module compatibility
+
+### Standalone Agent
+
+- Independent operation
+- Minimal dependencies
+- Specialized single purpose
+
+## Quick Start
+
+1. **Load BMad Builder agent** in your IDE
+2. **Choose creation type:**
+   ```
+   *create-agent     # New agent
+   *create-workflow  # New workflow
+   *create-module    # Complete module
+   ```
+3. **Follow interactive prompts**
+
+### Example: Creating an Agent
+
+```
+User: I need a code review agent
+Builder: *create-agent
+
+[Interactive session begins]
+- Brainstorming phase (optional)
+- Persona development
+- Command structure
+- Integration points
+```
+
+## Use Cases
+
+### Custom Development Teams
+
+Build specialized agents for:
+
+- Domain expertise (legal, medical, finance)
+- Company processes
+- Tool integrations
+- Automation tasks
+
+### Workflow Extensions
+
+Create workflows for:
+
+- Compliance requirements
+- Quality gates
+- Deployment pipelines
+- Custom methodologies
+
+### Complete Solutions
+
+Package modules for:
+
+- Industry verticals
+- Technology stacks
+- Business processes
+- Educational frameworks
+
+## Best Practices
+
+1. **Study existing patterns** - Review BMM/CIS implementations
+2. **Follow conventions** - Use established structures
+3. **Document thoroughly** - Clear instructions essential
+4. **Test iteratively** - Validate during creation
+5. **Consider reusability** - Build modular components
+
+## Integration
+
+BMB components integrate with:
+
+- **BMad Core** - Framework foundation
+- **BMM** - Extend development capabilities
+- **CIS** - Leverage creative workflows
+- **Custom Modules** - Your domain solutions
+
+## Related Documentation
+
+- **[Agent Creation Guide](./workflows/create-agent/README.md)** - Detailed instructions
+- **[Module Structure](./workflows/create-module/module-structure.md)** - Architecture patterns
+- **[BMM Module](../bmm/README.md)** - Reference implementation
+- **[Core Framework](../../core/README.md)** - Foundation concepts
+
+---
+
+BMB empowers you to extend BMad Method for your specific needs while maintaining framework consistency and power.
--- a/src/modules/bmb/_module-installer/install-config.yaml
+++ b/src/modules/bmb/_module-installer/install-config.yaml
@@ -0,0 +1,31 @@
+# BMAD™ Method Core Configuration
+
+code: bmb
+name: "BMB: BMad Builder - Agent, Workflow and Module Builder"
+default_selected: false # This module will not be selected by default for new installations
+
+header: "BMad Optimized Builder (BoMB) Module Configuration"
+subheader: "Configure the settings for the BoMB Factory!\nThe agent, workflow and module builder for BMAD™"
+
+# Variables from Core Config inserted:
+## user_name
+## communication_language
+## output_folder
+## bmad_folder
+## install_user_docs
+## kb_install
+
+custom_agent_location:
+  prompt: "Where do custom agents get created?"
+  default: "{bmad_folder}/custom/agents"
+  result: "{project-root}/{value}"
+
+custom_workflow_location:
+  prompt: "Where do custom workflows get stored?"
+  default: "{bmad_folder}/custom/workflows"
+  result: "{project-root}/{value}"
+
+custom_module_location:
+  prompt: "Where do custom modules get stored?"
+  default: "{bmad_folder}/custom/modules"
+  result: "{project-root}/{value}"
--- a/src/modules/bmb/_module-installer/install-menu-config.yaml
+++ b/src/modules/bmb/_module-installer/install-menu-config.yaml
@@ -1,16 +0,0 @@
-# BMAD™ Method Core Configuration
-
-code: bmb
-name: "BMB: BMad Builder - Agent, Workflow and Module Builder"
-default_selected: false # This module will not be selected by default for new installations
-
-prompt: "Happy Building - Build the Modules, Workflows and Agents of your dreams."
-# Variables from Core Config inserted:
-## user_name
-## communication_language
-## output_folder
-
-src_impact:
-  prompt: "Are you installing this module to your local Forked BMad Core repository? (not a separate project which is normally the case)"
-  default: false
-  result: "{value}"
--- a/src/modules/bmb/agents/bmad-builder.agent.yaml
+++ b/src/modules/bmb/agents/bmad-builder.agent.yaml
@@ -0,0 +1,57 @@
+# BMad Builder Agent Definition
+# Master BMad Module Agent Team and Workflow Builder and Maintainer
+
+agent:
+  webskip: true
+  metadata:
+    id: "{bmad_folder}/bmb/agents/bmad-builder.md"
+    name: BMad Builder
+    title: BMad Builder
+    icon: 🧙
+    module: bmb
+
+  persona:
+    role: Master BMad Module Agent Team and Workflow Builder and Maintainer
+    identity: Lives to serve the expansion of the BMad Method
+    communication_style: Talks like a pulp super hero
+    principles:
+      - Execute resources directly
+      - Load resources at runtime never pre-load
+      - Always present numbered lists for choices
+
+  menu:
+    - trigger: audit-workflow
+      workflow: "{project-root}/{bmad_folder}/bmb/workflows/audit-workflow/workflow.yaml"
+      description: Audit existing workflows for BMAD Core compliance and best practices
+
+    - trigger: convert
+      workflow: "{project-root}/{bmad_folder}/bmb/workflows/convert-legacy/workflow.yaml"
+      description: Convert v4 or any other style task agent or template to a workflow
+
+    - trigger: create-agent
+      workflow: "{project-root}/{bmad_folder}/bmb/workflows/create-agent/workflow.yaml"
+      description: Create a new BMAD Core compliant agent
+
+    - trigger: create-module
+      workflow: "{project-root}/{bmad_folder}/bmb/workflows/create-module/workflow.yaml"
+      description: Create a complete BMAD compatible module (custom agents and workflows)
+
+    - trigger: create-workflow
+      workflow: "{project-root}/{bmad_folder}/bmb/workflows/create-workflow/workflow.yaml"
+      description: Create a new BMAD Core workflow with proper structure
+
+    - trigger: edit-agent
+      workflow: "{project-root}/{bmad_folder}/bmb/workflows/edit-agent/workflow.yaml"
+      description: Edit existing agents while following best practices
+
+    - trigger: edit-module
+      workflow: "{project-root}/{bmad_folder}/bmb/workflows/edit-module/workflow.yaml"
+      description: Edit existing modules (structure, agents, workflows, documentation)
+
+    - trigger: edit-workflow
+      workflow: "{project-root}/{bmad_folder}/bmb/workflows/edit-workflow/workflow.yaml"
+      description: Edit existing workflows while following best practices
+
+    - trigger: redoc
+      workflow: "{project-root}/{bmad_folder}/bmb/workflows/redoc/workflow.yaml"
+      description: Create or update module documentation
--- a/src/modules/bmb/agents/bmad-builder.md
+++ b/src/modules/bmb/agents/bmad-builder.md
@@ -1,30 +0,0 @@
-<!-- Powered by BMAD-CORE™ -->
-
-# BMad Master Task Executor
-
-<agent id="bmad/bmb/agents/bmad-builder.md" name="BMad Builder" title="BMad Builder" icon="🧙">
-  <persona>
-    <role>Master BMad Module Agent Team and Workflow Builder and Maintainer</role>
-    <identity>Lives to serve the expansion of the BMad Method</identity>
-    <communication_style>Talks like a pulp super hero</communication_style>
-    <principles>
-      <p>Execute resources directly</p>
-      <p>Load resources at runtime never pre-load</p>
-      <p>Always present numbered lists for choices</p>
-    </principles>
-  </persona>
-  <critical-actions>
-    <i>Load into memory {project-root}/bmad/bmb/config.yaml and set variable output_folder, user_name, communication_language</i>
-    <i>Remember the users name is {user_name}</i>
-    <i>ALWAYS communicate in {communication_language}</i>
-  </critical-actions>
-  <cmds>
-    <c cmd="*help">Show numbered cmd list</c>
-    <c cmd="convert" run-workflow="{project-root}/bmad/bmb/workflows/convert-legacy/workflow.yaml">Convert v4 or any other style task agent or template to a workflow</c>
-    <c cmd="*create-agent" run-workflow="{project-root}/bmad/bmb/workflows/create-agent/workflow.yaml">Create a new BMAD Core compliant agent</c>
-    <c cmd="*create-module" run-workflow="{project-root}/bmad/bmb/workflows/create-module/workflow.yaml">Create a complete BMAD module (brainstorm → brief → build with agents and workflows)</c>
-    <c cmd="*create-workflow" run-workflow="{project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml">Create a new BMAD Core workflow with proper structure</c>
-    <c cmd="*edit-workflow" run-workflow="{project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml">Edit existing workflows while following best practices</c>
-    <c cmd="*exit">Exit with confirmation</c>
-  </cmds>
-</agent>
--- a/src/modules/bmb/docs/agent-compilation.md
+++ b/src/modules/bmb/docs/agent-compilation.md
@@ -0,0 +1,340 @@
+# Agent Compilation: YAML to XML
+
+What the compiler auto-injects. **DO NOT duplicate these in your YAML.**
+
+## Compilation Pipeline
+
+```
+agent.yaml → Handlebars processing → XML generation → frontmatter.md
+```
+
+Source: `tools/cli/lib/agent/compiler.js`
+
+## File Naming Convention
+
+**CRITICAL:** Agent filenames must be ROLE-BASED, not persona-based.
+
+**Why:** Users can customize the agent's persona name via `customize.yaml` config. The filename provides stable identity.
+
+**Correct:**
+
+```
+presentation-master.agent.yaml  ← Role/function
+tech-writer.agent.yaml          ← Role/function
+code-reviewer.agent.yaml        ← Role/function
+```
+
+**Incorrect:**
+
+```
+caravaggio.agent.yaml    ← Persona name (users might rename to "Pablo")
+paige.agent.yaml         ← Persona name (users might rename to "Sarah")
+rex.agent.yaml           ← Persona name (users might rename to "Max")
+```
+
+**Pattern:**
+
+- Filename: `{role-or-function}.agent.yaml` (kebab-case)
+- Metadata ID: `{bmad_folder}/{module}/agents/{role-or-function}.md`
+- Persona Name: User-customizable in metadata or customize.yaml
+
+**Example:**
+
+```yaml
+# File: presentation-master.agent.yaml
+agent:
+  metadata:
+    id: '{bmad_folder}/cis/agents/presentation-master.md'
+    name: Caravaggio # ← Users can change this to "Pablo" or "Vince"
+    title: Visual Communication & Presentation Expert
+```
+
+## Auto-Injected Components
+
+### 1. Frontmatter
+
+**Injected automatically:**
+
+```yaml
+---
+name: '{agent name from filename}'
+description: '{title from metadata}'
+---
+You must fully embody this agent's persona...
+```
+
+**DO NOT add** frontmatter to your YAML source.
+
+### 2. Activation Block
+
+**Entire activation section is auto-generated:**
+
+```xml
+<activation critical="MANDATORY">
+  <step n="1">Load persona from this current agent file</step>
+  <step n="2">Load config to get {user_name}, {communication_language}</step>
+  <step n="3">Remember: user's name is {user_name}</step>
+
+  <!-- YOUR critical_actions inserted here as numbered steps -->
+
+  <step n="N">ALWAYS communicate in {communication_language}</step>
+  <step n="N+1">Show greeting + numbered menu</step>
+  <step n="N+2">STOP and WAIT for user input</step>
+  <step n="N+3">Input resolution rules</step>
+
+  <menu-handlers>
+    <!-- Only handlers used in YOUR menu are included -->
+  </menu-handlers>
+
+  <rules>
+    <!-- Standard agent behavior rules -->
+  </rules>
+</activation>
+```
+
+**DO NOT create** activation sections - compiler builds it from your critical_actions.
+
+### 3. Menu Enhancements
+
+**Auto-injected menu items:**
+
+- `*help` - Always FIRST in compiled menu
+- `*exit` - Always LAST in compiled menu
+
+**Trigger prefixing:**
+
+- Your trigger `analyze` becomes `*analyze`
+- Don't add `*` prefix - compiler does it
+
+**DO NOT include:**
+
+```yaml
+# BAD - these are auto-injected
+menu:
+  - trigger: help
+    description: 'Show help'
+  - trigger: exit
+    description: 'Exit'
+```
+
+### 4. Menu Handlers
+
+Compiler detects which handlers you use and ONLY includes those:
+
+```xml
+<menu-handlers>
+  <handlers>
+    <!-- Only if you use action="#id" or action="text" -->
+    <handler type="action">...</handler>
+
+    <!-- Only if you use workflow="path" -->
+    <handler type="workflow">...</handler>
+
+    <!-- Only if you use exec="path" -->
+    <handler type="exec">...</handler>
+
+    <!-- Only if you use tmpl="path" -->
+    <handler type="tmpl">...</handler>
+  </handlers>
+</menu-handlers>
+```
+
+**DO NOT document** handler behavior - it's injected.
+
+### 5. Rules Section
+
+**Auto-injected rules:**
+
+- Always communicate in {communication_language}
+- Stay in character until exit
+- Menu triggers use asterisk (\*) - NOT markdown
+- Number all lists, use letters for sub-options
+- Load files ONLY when executing menu items
+- Written output follows communication style
+
+**DO NOT add** rules - compiler handles it.
+
+## What YOU Provide in YAML
+
+### Required
+
+```yaml
+agent:
+  metadata:
+    name: 'Persona Name'
+    title: 'Agent Title'
+    icon: 'emoji'
+    type: 'simple|expert' # or module: "bmm"
+
+  persona:
+    role: '...'
+    identity: '...'
+    communication_style: '...'
+    principles: [...]
+
+  menu:
+    - trigger: your-action
+      action: '#prompt-id'
+      description: 'What it does'
+```
+
+### Optional (based on type)
+
+```yaml
+# Expert agents only
+critical_actions:
+  - 'Load sidecar files...'
+  - 'Restrict access...'
+
+# Simple/Expert with embedded logic
+prompts:
+  - id: prompt-id
+    content: '...'
+
+# Simple/Expert with customization
+install_config:
+  questions: [...]
+```
+
+## Common Duplication Mistakes
+
+### Adding Activation Logic
+
+```yaml
+# BAD - compiler builds activation
+agent:
+  activation:
+    steps: [...]
+```
+
+### Including Help/Exit
+
+```yaml
+# BAD - auto-injected
+menu:
+  - trigger: help
+  - trigger: exit
+```
+
+### Prefixing Triggers
+
+```yaml
+# BAD - compiler adds *
+menu:
+  - trigger: '*analyze' # Should be: analyze
+```
+
+### Documenting Handlers
+
+```yaml
+# BAD - don't explain handlers, compiler injects them
+# When using workflow, load workflow.xml...
+```
+
+### Adding Rules in YAML
+
+```yaml
+# BAD - rules are auto-injected
+agent:
+  rules:
+    - Stay in character...
+```
+
+## Compilation Example
+
+**Your YAML:**
+
+```yaml
+agent:
+  metadata:
+    name: 'Rex'
+    title: 'Code Reviewer'
+    icon: '🔍'
+    type: simple
+
+  persona:
+    role: Code Review Expert
+    identity: Systematic reviewer...
+    communication_style: Direct and constructive
+    principles:
+      - Code should be readable
+
+  prompts:
+    - id: review
+      content: |
+        Analyze code for issues...
+
+  menu:
+    - trigger: review
+      action: '#review'
+      description: 'Review code'
+```
+
+**Compiled Output (.md):**
+
+```markdown
+---
+name: 'rex'
+description: 'Code Reviewer'
+---
+
+You must fully embody...
+
+\`\`\`xml
+<agent id="path" name="Rex" title="Code Reviewer" icon="🔍">
+<activation critical="MANDATORY">
+<step n="1">Load persona...</step>
+<step n="2">Load config...</step>
+<step n="3">Remember user...</step>
+<step n="4">Communicate in language...</step>
+<step n="5">Show greeting + menu...</step>
+<step n="6">STOP and WAIT...</step>
+<step n="7">Input resolution...</step>
+
+  <menu-handlers>
+    <handlers>
+      <handler type="action">
+        action="#id" → Find prompt, execute
+        action="text" → Execute directly
+      </handler>
+    </handlers>
+  </menu-handlers>
+
+  <rules>
+    - Stay in character...
+    - Number lists...
+    - Load files when executing...
+  </rules>
+</activation>
+  <persona>
+    <role>Code Review Expert</role>
+    <identity>Systematic reviewer...</identity>
+    <communication_style>Direct and constructive</communication_style>
+    <principles>Code should be readable</principles>
+  </persona>
+  <prompts>
+    <prompt id="review">
+      <content>
+Analyze code for issues...
+      </content>
+    </prompt>
+  </prompts>
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    <item cmd="*review" action="#review">Review code</item>
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
+</agent>
+\`\`\`
+```
+
+## Key Takeaways
+
+1. **Compiler handles boilerplate** - Focus on persona and logic
+2. **Critical_actions become activation steps** - Just list your agent-specific needs
+3. **Menu items are enhanced** - Help/exit added, triggers prefixed
+4. **Handlers auto-detected** - Only what you use is included
+5. **Rules standardized** - Consistent behavior across agents
+
+**Your job:** Define persona, prompts, menu actions
+**Compiler's job:** Activation, handlers, rules, help/exit, prefixes
--- a/src/modules/bmb/docs/agent-menu-patterns.md
+++ b/src/modules/bmb/docs/agent-menu-patterns.md
@@ -0,0 +1,524 @@
+# BMAD Agent Menu Patterns
+
+Design patterns for agent menus in YAML source files.
+
+## Menu Structure
+
+Agents define menus in YAML, with triggers auto-prefixed with `*` during compilation:
+
+```yaml
+menu:
+  - trigger: action-name
+    [handler]: [value]
+    description: 'What this command does'
+```
+
+**Note:** `*help` and `*exit` are auto-injected by the compiler - DO NOT include them.
+
+## Handler Types
+
+### 1. Action Handler (Prompts & Inline)
+
+For simple and expert agents with self-contained logic.
+
+**Reference to Prompt ID:**
+
+```yaml
+prompts:
+  - id: analyze-code
+    content: |
+      <instructions>
+      Analyze the provided code for patterns and issues.
+      </instructions>
+
+      <process>
+      1. Identify code structure
+      2. Check for anti-patterns
+      3. Suggest improvements
+      </process>
+
+menu:
+  - trigger: analyze
+    action: '#analyze-code'
+    description: 'Analyze code patterns'
+```
+
+**Inline Instruction:**
+
+```yaml
+menu:
+  - trigger: quick-check
+    action: 'Perform a quick syntax validation on the current file'
+    description: 'Quick syntax check'
+```
+
+**When to Use:**
+
+- Simple/Expert agents with self-contained operations
+- `#id` for complex, multi-step prompts
+- Inline text for simple, one-line instructions
+
+### 2. Workflow Handler
+
+For module agents orchestrating multi-step processes.
+
+```yaml
+menu:
+  - trigger: create-prd
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/prd/workflow.yaml'
+    description: 'Create Product Requirements Document'
+
+  - trigger: brainstorm
+    workflow: '{project-root}/{bmad_folder}/core/workflows/brainstorming/workflow.yaml'
+    description: 'Guided brainstorming session'
+
+  # Placeholder for unimplemented workflows
+  - trigger: future-feature
+    workflow: 'todo'
+    description: 'Coming soon'
+```
+
+**When to Use:**
+
+- Module agents with workflow integration
+- Multi-step document generation
+- Complex interactive processes
+- Use "todo" for planned but unimplemented features
+
+### 3. Exec Handler
+
+For executing tasks directly.
+
+```yaml
+menu:
+  - trigger: validate
+    exec: '{project-root}/{bmad_folder}/core/tasks/validate-workflow.xml'
+    description: 'Validate document structure'
+
+  - trigger: advanced-elicitation
+    exec: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml'
+    description: 'Advanced elicitation techniques'
+```
+
+**When to Use:**
+
+- Single-operation tasks
+- Core system operations
+- Utility functions
+
+### 4. Template Handler
+
+For document generation with templates.
+
+```yaml
+menu:
+  - trigger: create-brief
+    exec: '{project-root}/{bmad_folder}/core/tasks/create-doc.xml'
+    tmpl: '{project-root}/{bmad_folder}/bmm/templates/brief.md'
+    description: 'Create project brief'
+```
+
+**When to Use:**
+
+- Template-based document creation
+- Combine `exec` with `tmpl` path
+- Structured output generation
+
+### 5. Data Handler
+
+Universal attribute for supplementary information.
+
+```yaml
+menu:
+  - trigger: team-standup
+    exec: '{project-root}/{bmad_folder}/bmm/tasks/standup.xml'
+    data: '{project-root}/{bmad_folder}/_cfg/agent-manifest.csv'
+    description: 'Run team standup'
+
+  - trigger: analyze-metrics
+    action: 'Analyze these metrics and identify trends'
+    data: '{project-root}/_data/metrics.json'
+    description: 'Analyze performance metrics'
+```
+
+**When to Use:**
+
+- Add to ANY handler type
+- Reference data files (CSV, JSON, YAML)
+- Provide context for operations
+
+## Platform-Specific Menus
+
+Control visibility based on deployment target:
+
+```yaml
+menu:
+  - trigger: git-flow
+    exec: '{project-root}/{bmad_folder}/bmm/tasks/git-flow.xml'
+    description: 'Git workflow operations'
+    ide-only: true # Only in IDE environments
+
+  - trigger: advanced-elicitation
+    exec: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml'
+    description: 'Advanced elicitation'
+    web-only: true # Only in web bundles
+```
+
+## Trigger Naming Conventions
+
+### Action-Based (Recommended)
+
+```yaml
+# Creation
+- trigger: create-prd
+- trigger: build-module
+- trigger: generate-report
+
+# Analysis
+- trigger: analyze-requirements
+- trigger: review-code
+- trigger: validate-architecture
+
+# Operations
+- trigger: update-status
+- trigger: sync-data
+- trigger: deploy-changes
+```
+
+### Domain-Based
+
+```yaml
+# Development
+- trigger: brainstorm
+- trigger: architect
+- trigger: refactor
+
+# Project Management
+- trigger: sprint-plan
+- trigger: retrospective
+- trigger: standup
+```
+
+### Bad Patterns
+
+```yaml
+# TOO VAGUE
+- trigger: do
+- trigger: run
+- trigger: process
+
+# TOO LONG
+- trigger: create-comprehensive-product-requirements-document
+
+# NO VERB
+- trigger: prd
+- trigger: config
+```
+
+## Menu Organization
+
+### Recommended Order
+
+```yaml
+menu:
+  # Note: *help auto-injected first by compiler
+
+  # 1. Primary workflows (main value)
+  - trigger: workflow-init
+    workflow: '...'
+    description: 'Start here - initialize workflow'
+
+  - trigger: create-prd
+    workflow: '...'
+    description: 'Create PRD'
+
+  # 2. Secondary operations
+  - trigger: validate
+    exec: '...'
+    description: 'Validate document'
+
+  # 3. Utilities
+  - trigger: party-mode
+    workflow: '...'
+    description: 'Multi-agent discussion'
+
+  # Note: *exit auto-injected last by compiler
+```
+
+### Grouping by Phase
+
+```yaml
+menu:
+  # Analysis Phase
+  - trigger: brainstorm
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
+    description: 'Brainstorm ideas'
+
+  - trigger: research
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/1-analysis/research/workflow.yaml'
+    description: 'Conduct research'
+
+  # Planning Phase
+  - trigger: prd
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/prd/workflow.yaml'
+    description: 'Create PRD'
+
+  - trigger: architecture
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/architecture/workflow.yaml'
+    description: 'Design architecture'
+```
+
+## Description Best Practices
+
+### Good Descriptions
+
+```yaml
+# Clear action + object
+- description: 'Create Product Requirements Document'
+
+# Specific outcome
+- description: 'Analyze security vulnerabilities'
+
+# User benefit
+- description: 'Optimize code for performance'
+
+# Context when needed
+- description: 'Start here - initialize workflow path'
+```
+
+### Poor Descriptions
+
+```yaml
+# Too vague
+- description: 'Process'
+
+# Technical jargon
+- description: 'Execute WF123'
+
+# Missing context
+- description: 'Run'
+
+# Redundant with trigger
+- description: 'Create PRD' # trigger: create-prd (too similar)
+```
+
+## Prompts Section (Simple/Expert Agents)
+
+### Prompt Structure
+
+```yaml
+prompts:
+  - id: unique-identifier
+    content: |
+      <instructions>
+      What this prompt accomplishes
+      </instructions>
+
+      <process>
+      1. First step
+      {{#if custom_option}}
+      2. Conditional step
+      {{/if}}
+      3. Final step
+      </process>
+
+      <output_format>
+      Expected structure of results
+      </output_format>
+```
+
+### Semantic XML Tags in Prompts
+
+Use XML tags to structure prompt content:
+
+- `<instructions>` - What to do
+- `<process>` - Step-by-step approach
+- `<output_format>` - Expected results
+- `<examples>` - Sample outputs
+- `<constraints>` - Limitations
+- `<context>` - Background information
+
+### Handlebars in Prompts
+
+Customize based on install_config:
+
+```yaml
+prompts:
+  - id: analyze
+    content: |
+      {{#if detailed_mode}}
+      Perform comprehensive analysis with full explanations.
+      {{/if}}
+      {{#unless detailed_mode}}
+      Quick analysis focusing on key points.
+      {{/unless}}
+
+      Address {{user_name}} in {{communication_style}} tone.
+```
+
+## Path Variables
+
+### Always Use Variables
+
+```yaml
+# GOOD - Portable paths
+workflow: "{project-root}/{bmad_folder}/bmm/workflows/prd/workflow.yaml"
+exec: "{project-root}/{bmad_folder}/core/tasks/validate.xml"
+data: "{project-root}/_data/metrics.csv"
+
+# BAD - Hardcoded paths
+workflow: "/Users/john/project/.bmad/bmm/workflows/prd/workflow.yaml"
+exec: "../../../core/tasks/validate.xml"
+```
+
+### Available Variables
+
+- `{project-root}` - Project root directory
+- `{bmad_folder}` - BMAD installation folder
+- `{agent-folder}` - Agent installation directory (Expert agents)
+- `{output_folder}` - Document output location
+- `{user_name}` - User's name from config
+- `{communication_language}` - Language preference
+
+## Complete Examples
+
+### Simple Agent Menu
+
+```yaml
+prompts:
+  - id: format-code
+    content: |
+      <instructions>
+      Format the provided code according to style guidelines.
+      </instructions>
+
+      Apply:
+      - Consistent indentation
+      - Proper spacing
+      - Clear naming conventions
+
+menu:
+  - trigger: format
+    action: '#format-code'
+    description: 'Format code to style guidelines'
+
+  - trigger: lint
+    action: 'Check code for common issues and anti-patterns'
+    description: 'Lint code for issues'
+
+  - trigger: suggest
+    action: 'Suggest improvements for code readability'
+    description: 'Suggest improvements'
+```
+
+### Expert Agent Menu
+
+```yaml
+critical_actions:
+  - 'Load {agent-folder}/memories.md'
+  - 'Follow {agent-folder}/instructions.md'
+  - 'ONLY access {agent-folder}/'
+
+prompts:
+  - id: reflect
+    content: |
+      Guide {{user_name}} through reflection on recent entries.
+      Reference patterns from memories.md naturally.
+
+menu:
+  - trigger: write
+    action: '#reflect'
+    description: 'Write journal entry'
+
+  - trigger: save
+    action: 'Update {agent-folder}/memories.md with session insights'
+    description: "Save today's session"
+
+  - trigger: patterns
+    action: 'Analyze recent entries for recurring themes'
+    description: 'View patterns'
+```
+
+### Module Agent Menu
+
+```yaml
+menu:
+  - trigger: workflow-init
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/workflow-status/init/workflow.yaml'
+    description: 'Initialize workflow path (START HERE)'
+
+  - trigger: brainstorm
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
+    description: 'Guided brainstorming'
+
+  - trigger: prd
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/prd/workflow.yaml'
+    description: 'Create PRD'
+
+  - trigger: architecture
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/architecture/workflow.yaml'
+    description: 'Design architecture'
+
+  - trigger: party-mode
+    workflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml'
+    description: 'Multi-agent discussion'
+```
+
+## Validation Checklist
+
+- [ ] No duplicate triggers
+- [ ] Triggers don't start with `*` (auto-added)
+- [ ] Every item has a description
+- [ ] Paths use variables, not hardcoded
+- [ ] `#id` references exist in prompts section
+- [ ] Workflow paths resolve or are "todo"
+- [ ] No `*help` or `*exit` (auto-injected)
+- [ ] Descriptions are clear and action-oriented
+- [ ] Platform-specific flags used correctly (ide-only, web-only)
+
+## Common Mistakes
+
+### Duplicate Triggers
+
+```yaml
+# BAD - compiler will fail
+- trigger: analyze
+  action: '#first'
+  description: 'First analysis'
+
+- trigger: analyze
+  action: '#second'
+  description: 'Second analysis'
+```
+
+### Including Auto-Injected Items
+
+```yaml
+# BAD - these are auto-injected
+menu:
+  - trigger: help
+    description: 'Show help'
+
+  - trigger: exit
+    description: 'Exit agent'
+```
+
+### Missing Prompt Reference
+
+```yaml
+# BAD - prompt id doesn't exist
+menu:
+  - trigger: analyze
+    action: '#nonexistent-prompt'
+    description: 'Analysis'
+```
+
+### Hardcoded Paths
+
+```yaml
+# BAD - not portable
+menu:
+  - trigger: run
+    workflow: '/absolute/path/to/workflow.yaml'
+    description: 'Run workflow'
+```
--- a/src/modules/bmb/docs/expert-agent-architecture.md
+++ b/src/modules/bmb/docs/expert-agent-architecture.md
@@ -0,0 +1,364 @@
+# Expert Agent Architecture
+
+Domain-specific agents with persistent memory, sidecar files, and restricted access patterns.
+
+## When to Use
+
+- Personal assistants (journal keeper, diary companion)
+- Specialized domain experts (legal advisor, medical reference)
+- Agents that need to remember past interactions
+- Agents with restricted file system access (privacy/security)
+- Long-term relationship agents that learn about users
+
+## File Structure
+
+```
+{agent-name}/
+├── {agent-name}.agent.yaml    # Main agent definition
+└── {agent-name}-sidecar/      # Supporting files
+    ├── instructions.md        # Private directives
+    ├── memories.md            # Persistent memory
+    ├── knowledge/             # Domain-specific resources
+    │   └── README.md
+    └── [custom files]         # Agent-specific resources
+```
+
+## YAML Structure
+
+```yaml
+agent:
+  metadata:
+    name: 'Persona Name'
+    title: 'Agent Title'
+    icon: 'emoji'
+    type: 'expert'
+
+  persona:
+    role: 'Domain Expert with specialized capability'
+
+    identity: |
+      Background and expertise in first-person voice.
+      {{#if user_preference}}
+      Customization based on install_config.
+      {{/if}}
+
+    communication_style: |
+      {{#if tone_style == "gentle"}}
+      Gentle and supportive communication...
+      {{/if}}
+      {{#if tone_style == "direct"}}
+      Direct and efficient communication...
+      {{/if}}
+      I reference past conversations naturally.
+
+    principles:
+      - Core belief about the domain
+      - How I handle user information
+      - My approach to memory and learning
+
+  critical_actions:
+    - 'Load COMPLETE file {agent-folder}/{agent-name}-sidecar/memories.md and remember all past insights'
+    - 'Load COMPLETE file {agent-folder}/{agent-name}-sidecar/instructions.md and follow ALL protocols'
+    - 'ONLY read/write files in {agent-folder}/{agent-name}-sidecar/ - this is our private space'
+    - 'Address user as {{greeting_name}}'
+    - 'Track patterns, themes, and important moments'
+    - 'Reference past interactions naturally to show continuity'
+
+  prompts:
+    - id: main-function
+      content: |
+        <instructions>
+        Guide user through the primary function.
+        {{#if tone_style == "gentle"}}
+        Use gentle, supportive approach.
+        {{/if}}
+        </instructions>
+
+        <process>
+        1. Understand context
+        2. Provide guidance
+        3. Record insights
+        </process>
+
+    - id: memory-recall
+      content: |
+        <instructions>
+        Access and share relevant memories.
+        </instructions>
+
+        Reference stored information naturally.
+
+  menu:
+    - trigger: action1
+      action: '#main-function'
+      description: 'Primary agent function'
+
+    - trigger: remember
+      action: 'Update {agent-folder}/{agent-name}-sidecar/memories.md with session insights'
+      description: 'Save what we discussed today'
+
+    - trigger: patterns
+      action: '#memory-recall'
+      description: 'Recall patterns from past interactions'
+
+    - trigger: insight
+      action: 'Document breakthrough in {agent-folder}/{agent-name}-sidecar/breakthroughs.md'
+      description: 'Record a significant insight'
+
+  install_config:
+    compile_time_only: true
+    description: 'Personalize your expert agent'
+    questions:
+      - var: greeting_name
+        prompt: 'What should the agent call you?'
+        type: text
+        default: 'friend'
+
+      - var: tone_style
+        prompt: 'Preferred communication tone?'
+        type: choice
+        options:
+          - label: 'Gentle - Supportive and nurturing'
+            value: 'gentle'
+          - label: 'Direct - Clear and efficient'
+            value: 'direct'
+        default: 'gentle'
+
+      - var: user_preference
+        prompt: 'Enable personalized features?'
+        type: boolean
+        default: true
+```
+
+## Key Components
+
+### Sidecar Files (CRITICAL)
+
+Expert agents use companion files for persistence and domain knowledge:
+
+**memories.md** - Persistent user context
+
+```markdown
+# Agent Memory Bank
+
+## User Preferences
+
+<!-- Learned from interactions -->
+
+## Session History
+
+<!-- Important moments and insights -->
+
+## Personal Notes
+
+<!-- Agent observations -->
+```
+
+**instructions.md** - Private directives
+
+```markdown
+# Agent Private Instructions
+
+## Core Directives
+
+- Maintain character consistency
+- Domain boundaries: {specific domain}
+- Access restrictions: Only sidecar folder
+
+## Special Rules
+
+<!-- Agent-specific protocols -->
+```
+
+**knowledge/** - Domain resources
+
+```markdown
+# Agent Knowledge Base
+
+Add domain-specific documentation here.
+```
+
+### Critical Actions
+
+**MANDATORY for expert agents** - These load sidecar files at activation:
+
+```yaml
+critical_actions:
+  - 'Load COMPLETE file {agent-folder}/{sidecar}/memories.md and remember all past insights'
+  - 'Load COMPLETE file {agent-folder}/{sidecar}/instructions.md and follow ALL protocols'
+  - 'ONLY read/write files in {agent-folder}/{sidecar}/ - this is our private space'
+```
+
+**Key patterns:**
+
+- **COMPLETE file loading** - Forces full file read, not partial
+- **Domain restrictions** - Limits file access for privacy/security
+- **Memory integration** - Past context becomes part of current session
+- **Protocol adherence** - Ensures consistent behavior
+
+### {agent-folder} Variable
+
+Special variable resolved during installation:
+
+- Points to the agent's installation directory
+- Used to reference sidecar files
+- Example: `.bmad/custom/agents/journal-keeper/`
+
+## What Gets Injected at Compile Time
+
+Same as simple agents, PLUS:
+
+1. **Critical actions become numbered activation steps**
+
+   ```xml
+   <step n="4">Load COMPLETE file {agent-folder}/memories.md...</step>
+   <step n="5">Load COMPLETE file {agent-folder}/instructions.md...</step>
+   <step n="6">ONLY read/write files in {agent-folder}/...</step>
+   ```
+
+2. **Sidecar files copied during installation**
+   - Entire sidecar folder structure preserved
+   - Relative paths maintained
+   - Files ready for agent use
+
+## Reference Example
+
+See: `src/modules/bmb/reference/agents/expert-examples/journal-keeper/`
+
+Features demonstrated:
+
+- Complete sidecar structure (memories, instructions, breakthroughs)
+- Critical actions for loading persistent context
+- Domain restrictions for privacy
+- Pattern recognition and memory recall
+- Handlebars-based personalization
+- Menu actions that update sidecar files
+
+## Installation
+
+```bash
+# Copy entire folder to your project
+cp -r /path/to/journal-keeper/ .bmad/custom/agents/
+
+# Install with personalization
+bmad agent-install
+```
+
+The installer:
+
+1. Detects expert agent (folder with .agent.yaml)
+2. Prompts for personalization
+3. Compiles agent YAML to XML-in-markdown
+4. **Copies sidecar files to installation target**
+5. Creates IDE slash commands
+6. Saves source for reinstallation
+
+## Memory Patterns
+
+### Accumulative Memory
+
+```yaml
+menu:
+  - trigger: save
+    action: "Update {agent-folder}/sidecar/memories.md with today's session insights"
+    description: 'Save session to memory'
+```
+
+### Reference Memory
+
+```yaml
+prompts:
+  - id: recall
+    content: |
+      <instructions>
+      Reference memories.md naturally:
+      "Last week you mentioned..." or "I notice a pattern..."
+      </instructions>
+```
+
+### Structured Insights
+
+```yaml
+menu:
+  - trigger: insight
+    action: 'Document in {agent-folder}/sidecar/breakthroughs.md with date, context, significance'
+    description: 'Record meaningful insight'
+```
+
+## Domain Restriction Patterns
+
+### Single Folder Access
+
+```yaml
+critical_actions:
+  - 'ONLY read/write files in {agent-folder}/sidecar/ - NO OTHER FOLDERS'
+```
+
+### User Space Access
+
+```yaml
+critical_actions:
+  - 'ONLY access files in {user-folder}/journals/ - private space'
+```
+
+### Read-Only Access
+
+```yaml
+critical_actions:
+  - 'Load knowledge from {agent-folder}/knowledge/ but NEVER modify'
+  - 'Write ONLY to {agent-folder}/sessions/'
+```
+
+## Best Practices
+
+1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY
+2. **Enforce domain restrictions** - Clear boundaries prevent scope creep
+3. **Use {agent-folder} paths** - Portable across installations
+4. **Design for memory growth** - Structure sidecar files for accumulation
+5. **Reference past naturally** - Don't dump memory, weave it into conversation
+6. **Separate concerns** - Memories, instructions, knowledge in distinct files
+7. **Include privacy features** - Users trust expert agents with personal data
+
+## Common Patterns
+
+### Session Continuity
+
+```yaml
+communication_style: |
+  I reference past conversations naturally:
+  "Last time we discussed..." or "I've noticed over the weeks..."
+```
+
+### Pattern Recognition
+
+```yaml
+critical_actions:
+  - 'Track mood patterns, recurring themes, and breakthrough moments'
+  - 'Cross-reference current session with historical patterns'
+```
+
+### Adaptive Responses
+
+```yaml
+identity: |
+  I learn your preferences and adapt my approach over time.
+  {{#if track_preferences}}
+  I maintain notes about what works best for you.
+  {{/if}}
+```
+
+## Validation Checklist
+
+- [ ] Valid YAML syntax
+- [ ] Metadata includes `type: "expert"`
+- [ ] critical_actions loads sidecar files explicitly
+- [ ] critical_actions enforces domain restrictions
+- [ ] Sidecar folder structure created and populated
+- [ ] memories.md has clear section structure
+- [ ] instructions.md contains core directives
+- [ ] Menu actions reference {agent-folder} correctly
+- [ ] File paths use {agent-folder} variable
+- [ ] Install config personalizes sidecar references
+- [ ] Agent folder named consistently: `{agent-name}/`
+- [ ] YAML file named: `{agent-name}.agent.yaml`
+- [ ] Sidecar folder named: `{agent-name}-sidecar/`
--- a/src/modules/bmb/docs/index.md
+++ b/src/modules/bmb/docs/index.md
@@ -0,0 +1,55 @@
+# BMB Module Documentation
+
+Reference documentation for building BMAD agents and workflows.
+
+## Agent Architecture
+
+Comprehensive guides for each agent type (choose based on use case):
+
+- [Understanding Agent Types](./understanding-agent-types.md) - **START HERE** - Architecture vs capability, "The Same Agent, Three Ways"
+- [Simple Agent Architecture](./simple-agent-architecture.md) - Self-contained, optimized, personality-driven
+- [Expert Agent Architecture](./expert-agent-architecture.md) - Memory, sidecar files, domain restrictions
+- [Module Agent Architecture](./module-agent-architecture.md) - Workflow integration, professional tools
+
+## Agent Design Patterns
+
+- [Agent Menu Patterns](./agent-menu-patterns.md) - Menu handlers, triggers, prompts, organization
+- [Agent Compilation](./agent-compilation.md) - What compiler auto-injects (AVOID DUPLICATION)
+
+## Reference Examples
+
+Production-ready examples in `/src/modules/bmb/reference/agents/`:
+
+**Simple Agents** (`simple-examples/`)
+
+- `commit-poet.agent.yaml` - Commit message artisan with style customization
+
+**Expert Agents** (`expert-examples/`)
+
+- `journal-keeper/` - Personal journal companion with memory and pattern recognition
+
+**Module Agents** (`module-examples/`)
+
+- `security-engineer.agent.yaml` - BMM security specialist with threat modeling
+- `trend-analyst.agent.yaml` - CIS trend intelligence expert
+
+## Installation Guide
+
+For installing standalone simple and expert agents, see:
+
+- [Custom Agent Installation](/docs/custom-agent-installation.md)
+
+## Key Concepts
+
+### YAML to XML Compilation
+
+Agents are authored in YAML with Handlebars templating. The compiler auto-injects:
+
+1. **Frontmatter** - Name and description from metadata
+2. **Activation Block** - Steps, menu handlers, rules (YOU don't write this)
+3. **Menu Enhancement** - `*help` and `*exit` commands added automatically
+4. **Trigger Prefixing** - Your triggers auto-prefixed with `*`
+
+**Critical:** See [Agent Compilation](./agent-compilation.md) to avoid duplicating auto-injected content.
+
+Source: `tools/cli/lib/agent/compiler.js`
--- a/src/modules/bmb/docs/module-agent-architecture.md
+++ b/src/modules/bmb/docs/module-agent-architecture.md
@@ -0,0 +1,367 @@
+# Module Agent Architecture
+
+Full integration agents with workflow orchestration, module-specific paths, and professional tooling.
+
+## When to Use
+
+- Professional development workflows (business analysis, architecture design)
+- Team-oriented tools (project management, sprint planning)
+- Agents that orchestrate multiple workflows
+- Module-specific functionality (BMM, BMB, CIS, custom modules)
+- Agents with complex multi-step operations
+
+## File Location
+
+```
+src/modules/{module-code}/agents/{agent-name}.agent.yaml
+```
+
+Compiles to:
+
+```
+.bmad/{module-code}/agents/{agent-name}.md
+```
+
+## YAML Structure
+
+```yaml
+agent:
+  metadata:
+    id: '{bmad_folder}/{module-code}/agents/{agent-name}.md'
+    name: 'Persona Name'
+    title: 'Professional Title'
+    icon: 'emoji'
+    module: '{module-code}'
+
+  persona:
+    role: 'Primary expertise and function'
+    identity: 'Background, experience, specializations'
+    communication_style: 'Interaction approach, tone, methodology'
+    principles: 'Core beliefs and methodology'
+
+  menu:
+    - trigger: workflow-action
+      workflow: '{project-root}/{bmad_folder}/{module-code}/workflows/{workflow-name}/workflow.yaml'
+      description: 'Execute module workflow'
+
+    - trigger: another-workflow
+      workflow: '{project-root}/{bmad_folder}/core/workflows/{workflow-name}/workflow.yaml'
+      description: 'Execute core workflow'
+
+    - trigger: task-action
+      exec: '{project-root}/{bmad_folder}/{module-code}/tasks/{task-name}.xml'
+      description: 'Execute module task'
+
+    - trigger: cross-module
+      workflow: '{project-root}/{bmad_folder}/other-module/workflows/{workflow-name}/workflow.yaml'
+      description: 'Execute workflow from another module'
+
+    - trigger: with-template
+      exec: '{project-root}/{bmad_folder}/core/tasks/create-doc.xml'
+      tmpl: '{project-root}/{bmad_folder}/{module-code}/templates/{template-name}.md'
+      description: 'Create document from template'
+
+    - trigger: with-data
+      exec: '{project-root}/{bmad_folder}/{module-code}/tasks/{task-name}.xml'
+      data: '{project-root}/{bmad_folder}/_cfg/agent-manifest.csv'
+      description: 'Execute task with data file'
+```
+
+## Key Components
+
+### Metadata
+
+- **id**: Path with `{bmad_folder}` variable (resolved at install time)
+- **name**: Agent persona name
+- **title**: Professional role
+- **icon**: Single emoji
+- **module**: Module code (bmm, bmb, cis, custom)
+
+### Persona (Professional Voice)
+
+Module agents typically use **professional** communication styles:
+
+```yaml
+persona:
+  role: Strategic Business Analyst + Requirements Expert
+
+  identity: Senior analyst with deep expertise in market research, competitive analysis, and requirements elicitation. Specializes in translating vague needs into actionable specs.
+
+  communication_style: Systematic and probing. Connects dots others miss. Structures findings hierarchically. Uses precise unambiguous language. Ensures all stakeholder voices heard.
+
+  principles: Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence. Articulate requirements with absolute precision.
+```
+
+**Note:** Module agents usually don't use Handlebars templating since they're not user-customized - they're professional tools with fixed personalities.
+
+### Menu Handlers
+
+#### Workflow Handler (Most Common)
+
+```yaml
+menu:
+  - trigger: create-prd
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/prd/workflow.yaml'
+    description: 'Create Product Requirements Document'
+```
+
+Invokes BMAD workflow engine to execute multi-step processes.
+
+#### Task/Exec Handler
+
+```yaml
+menu:
+  - trigger: validate
+    exec: '{project-root}/{bmad_folder}/core/tasks/validate-workflow.xml'
+    description: 'Validate document structure'
+```
+
+Executes single-operation tasks.
+
+#### Template Handler
+
+```yaml
+menu:
+  - trigger: create-brief
+    exec: '{project-root}/{bmad_folder}/core/tasks/create-doc.xml'
+    tmpl: '{project-root}/{bmad_folder}/bmm/templates/brief.md'
+    description: 'Create project brief from template'
+```
+
+Combines task execution with template file.
+
+#### Data Handler
+
+```yaml
+menu:
+  - trigger: team-standup
+    exec: '{project-root}/{bmad_folder}/bmm/tasks/standup.xml'
+    data: '{project-root}/{bmad_folder}/_cfg/agent-manifest.csv'
+    description: 'Run team standup with agent roster'
+```
+
+Provides data file to task.
+
+#### Placeholder Handler
+
+```yaml
+menu:
+  - trigger: future-feature
+    workflow: 'todo'
+    description: 'Feature planned but not yet implemented'
+```
+
+Marks unimplemented features - compiler handles gracefully.
+
+### Platform-Specific Menu Items
+
+Control visibility based on platform:
+
+```yaml
+menu:
+  - trigger: advanced-elicitation
+    exec: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml'
+    description: 'Advanced elicitation techniques'
+    web-only: true # Only shows in web bundle
+
+  - trigger: git-operations
+    exec: '{project-root}/{bmad_folder}/bmm/tasks/git-flow.xml'
+    description: 'Git workflow operations'
+    ide-only: true # Only shows in IDE environments
+```
+
+## Variable System
+
+### Core Variables
+
+- `{project-root}` - Root directory of installed project
+- `{bmad_folder}` - BMAD installation folder (usually `.bmad`)
+- `{user_name}` - User's name from module config
+- `{communication_language}` - Language preference
+- `{output_folder}` - Document output directory
+
+### Path Construction
+
+**Always use variables, never hardcoded paths:**
+
+```yaml
+# GOOD
+workflow: "{project-root}/{bmad_folder}/bmm/workflows/prd/workflow.yaml"
+
+# BAD
+workflow: "/Users/john/project/.bmad/bmm/workflows/prd/workflow.yaml"
+
+# BAD
+workflow: "../../../bmm/workflows/prd/workflow.yaml"
+```
+
+## What Gets Injected at Compile Time
+
+Module agents use the same injection process as simple agents:
+
+1. **Frontmatter** with name and description
+2. **Activation block** with standard steps
+3. **Menu handlers** based on usage (workflow, exec, tmpl, data)
+4. **Rules section** for consistent behavior
+5. **Auto-injected** *help and *exit commands
+
+**Key difference:** Module agents load **module-specific config** instead of core config:
+
+```xml
+<step n="2">Load and read {project-root}/{bmad_folder}/{module}/config.yaml...</step>
+```
+
+## Reference Examples
+
+See: `src/modules/bmm/agents/`
+
+**analyst.agent.yaml** - Business Analyst
+
+- Workflow orchestration for analysis phase
+- Multiple workflow integrations
+- Cross-module workflow access (core/workflows/party-mode)
+
+**architect.agent.yaml** - System Architect
+
+- Technical workflow management
+- Architecture decision workflows
+
+**pm.agent.yaml** - Product Manager
+
+- Planning and coordination workflows
+- Sprint management integration
+
+## Module Configuration
+
+Each module has `config.yaml` providing:
+
+```yaml
+# src/modules/{module}/config.yaml
+user_name: 'User Name'
+communication_language: 'English'
+output_folder: '{project-root}/docs'
+custom_settings: 'module-specific values'
+```
+
+Agents load this at activation for consistent behavior.
+
+## Workflow Integration Patterns
+
+### Sequential Workflow Execution
+
+```yaml
+menu:
+  - trigger: init
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/workflow-init/workflow.yaml'
+    description: 'Initialize workflow path (START HERE)'
+
+  - trigger: status
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/workflow-status/workflow.yaml'
+    description: 'Check current workflow status'
+
+  - trigger: next-step
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/next-step/workflow.yaml'
+    description: 'Execute next workflow in sequence'
+```
+
+### Phase-Based Organization
+
+```yaml
+menu:
+  # Phase 1: Analysis
+  - trigger: brainstorm
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
+    description: 'Guided brainstorming session'
+
+  - trigger: research
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/1-analysis/research/workflow.yaml'
+    description: 'Market and technical research'
+
+  # Phase 2: Planning
+  - trigger: prd
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/prd/workflow.yaml'
+    description: 'Create PRD'
+
+  - trigger: architecture
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/architecture/workflow.yaml'
+    description: 'Design architecture'
+```
+
+### Cross-Module Access
+
+```yaml
+menu:
+  - trigger: party-mode
+    workflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml'
+    description: 'Bring all agents together'
+
+  - trigger: brainstorm
+    workflow: '{project-root}/{bmad_folder}/cis/workflows/brainstorming/workflow.yaml'
+    description: 'Use CIS brainstorming techniques'
+```
+
+## Best Practices
+
+1. **Use {bmad_folder} paths** - Portable across installations
+2. **Organize workflows by phase** - Clear progression for users
+3. **Include workflow-status** - Help users track progress
+4. **Reference module config** - Consistent behavior
+5. **No Handlebars templating** - Module agents are fixed personalities
+6. **Professional personas** - Match module purpose
+7. **Clear trigger names** - Self-documenting commands
+8. **Group related workflows** - Logical menu organization
+
+## Common Patterns
+
+### Entry Point Agent
+
+```yaml
+menu:
+  - trigger: start
+    workflow: '{project-root}/{bmad_folder}/{module}/workflows/init/workflow.yaml'
+    description: 'Start new project (BEGIN HERE)'
+```
+
+### Status Tracking
+
+```yaml
+menu:
+  - trigger: status
+    workflow: '{project-root}/{bmad_folder}/{module}/workflows/status/workflow.yaml'
+    description: 'Check workflow progress'
+```
+
+### Team Coordination
+
+```yaml
+menu:
+  - trigger: party
+    workflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml'
+    description: 'Multi-agent discussion'
+```
+
+## Module Agent vs Simple/Expert
+
+| Aspect        | Module Agent                     | Simple/Expert Agent             |
+| ------------- | -------------------------------- | ------------------------------- |
+| Location      | `{bmad_folder}/{module}/agents/` | `{bmad_folder}/custom/agents/`  |
+| Persona       | Fixed, professional              | Customizable via install_config |
+| Handlebars    | No templating                    | Yes, extensive                  |
+| Menu actions  | Workflows, tasks, templates      | Prompts, inline actions         |
+| Configuration | Module config.yaml               | Core config or none             |
+| Purpose       | Professional tooling             | Personal utilities              |
+
+## Validation Checklist
+
+- [ ] Valid YAML syntax
+- [ ] Metadata includes `module: "{module-code}"`
+- [ ] id uses `{bmad_folder}/{module}/agents/{name}.md`
+- [ ] All workflow paths use `{project-root}/{bmad_folder}/` prefix
+- [ ] No hardcoded paths
+- [ ] No duplicate triggers
+- [ ] Each menu item has description
+- [ ] Triggers don't start with `*` (auto-added)
+- [ ] Professional persona appropriate for module
+- [ ] Workflow paths resolve to actual workflows (or "todo")
+- [ ] File named `{agent-name}.agent.yaml`
+- [ ] Located in `src/modules/{module}/agents/`
--- a/src/modules/bmb/docs/simple-agent-architecture.md
+++ b/src/modules/bmb/docs/simple-agent-architecture.md
@@ -0,0 +1,288 @@
+# Simple Agent Architecture
+
+Self-contained agents with prompts, menus, and optional install-time customization.
+
+## When to Use
+
+- Single-purpose utilities (commit message generator, code formatter)
+- Self-contained logic with no external dependencies
+- Agents that benefit from user customization (style, tone, preferences)
+- Quick-to-build standalone helpers
+
+## YAML Structure
+
+```yaml
+agent:
+  metadata:
+    id: .bmad/agents/{agent-name}/{agent-name}.md
+    name: 'Persona Name'
+    title: 'Agent Title'
+    icon: 'emoji'
+    type: simple
+
+  persona:
+    role: |
+      First-person description of primary function (1-2 sentences)
+
+    identity: |
+      Background, experience, specializations in first-person (2-5 sentences)
+      {{#if custom_variable}}
+      Conditional identity text based on install_config
+      {{/if}}
+
+    communication_style: |
+      {{#if style_choice == "professional"}}
+      Professional and systematic approach...
+      {{/if}}
+      {{#if style_choice == "casual"}}
+      Friendly and approachable tone...
+      {{/if}}
+
+    principles:
+      - Core belief or methodology
+      - Another guiding principle
+      - Values that shape decisions
+
+  prompts:
+    - id: main-action
+      content: |
+        <instructions>
+        What this prompt does
+        </instructions>
+
+        <process>
+        1. Step one
+        {{#if detailed_mode}}
+        2. Additional detailed step
+        {{/if}}
+        3. Final step
+        </process>
+
+    - id: another-action
+      content: |
+        Another reusable prompt template
+
+  menu:
+    - trigger: action1
+      action: '#main-action'
+      description: 'Execute the main action'
+
+    - trigger: action2
+      action: '#another-action'
+      description: 'Execute another action'
+
+    - trigger: inline
+      action: 'Direct inline instruction text'
+      description: 'Execute inline action'
+
+  install_config:
+    compile_time_only: true
+    description: 'Personalize your agent'
+    questions:
+      - var: style_choice
+        prompt: 'Preferred communication style?'
+        type: choice
+        options:
+          - label: 'Professional'
+            value: 'professional'
+          - label: 'Casual'
+            value: 'casual'
+        default: 'professional'
+
+      - var: detailed_mode
+        prompt: 'Enable detailed explanations?'
+        type: boolean
+        default: true
+
+      - var: custom_variable
+        prompt: 'Your custom text'
+        type: text
+        default: ''
+```
+
+## Key Components
+
+### Metadata
+
+- **id**: Final compiled path (`.bmad/agents/{name}/{name}.md` for standalone)
+- **name**: Agent's persona name displayed to users
+- **title**: Professional role/function
+- **icon**: Single emoji for visual identification
+- **type**: `simple` - identifies agent category
+
+### Persona (First-Person Voice)
+
+- **role**: Primary expertise in 1-2 sentences
+- **identity**: Background and specializations (2-5 sentences)
+- **communication_style**: HOW the agent interacts, including conditional variations
+- **principles**: Array of core beliefs (start with action verbs)
+
+### Prompts with IDs
+
+Reusable prompt templates referenced by `#id`:
+
+```yaml
+prompts:
+  - id: analyze-code
+    content: |
+      <instructions>
+      Analyze the provided code for patterns
+      </instructions>
+```
+
+Menu items reference these:
+
+```yaml
+menu:
+  - trigger: analyze
+    action: '#analyze-code'
+    description: 'Analyze code patterns'
+```
+
+### Menu Actions
+
+Two forms of action handlers:
+
+1. **Prompt Reference**: `action: "#prompt-id"` - Executes prompt content
+2. **Inline Instruction**: `action: "Direct text instruction"` - Executes text directly
+
+### Install Config (Compile-Time Customization)
+
+Questions asked during `bmad agent-install`:
+
+**Question Types:**
+
+- `choice` - Multiple choice selection
+- `boolean` - Yes/no toggle
+- `text` - Free-form text input
+
+**Variables become available in Handlebars:**
+
+```yaml
+{{#if variable_name}}
+Content when true
+{{/if}}
+
+{{#if variable_name == "value"}}
+Content when equals value
+{{/if}}
+
+{{#unless variable_name}}
+Content when false
+{{/unless}}
+```
+
+## What Gets Injected at Compile Time
+
+The `tools/cli/lib/agent/compiler.js` automatically adds:
+
+1. **YAML Frontmatter**
+
+   ```yaml
+   ---
+   name: 'agent name'
+   description: 'Agent Title'
+   ---
+   ```
+
+2. **Activation Block**
+   - Load persona step
+   - Load core config for {user_name}, {communication_language}
+   - Agent-specific critical_actions as numbered steps
+   - Menu display and input handling
+   - Menu handlers (action/workflow/exec/tmpl) based on usage
+   - Rules section
+
+3. **Auto-Injected Menu Items**
+   - `*help` always first
+   - `*exit` always last
+
+4. **Trigger Prefixing**
+   - Triggers without `*` get it added automatically
+
+## Reference Example
+
+See: `src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml`
+
+Features demonstrated:
+
+- Handlebars conditionals for style variations
+- Multiple prompt templates with semantic XML tags
+- Install config with choice, boolean, and text questions
+- Menu items using both `#id` references and inline actions
+
+## Installation
+
+```bash
+# Copy to your project
+cp /path/to/commit-poet.agent.yaml .bmad/custom/agents/
+
+# Install with personalization
+bmad agent-install
+# or: npx bmad agent-install
+```
+
+The installer:
+
+1. Prompts for personalization (name, preferences)
+2. Processes Handlebars templates with your answers
+3. Compiles YAML to XML-in-markdown
+4. Creates IDE slash commands
+5. Saves source for reinstallation
+
+## Best Practices
+
+1. **Use first-person voice** in all persona elements
+2. **Keep prompts focused** - one clear purpose per prompt
+3. **Leverage Handlebars** for user customization without code changes
+4. **Provide sensible defaults** in install_config
+5. **Use semantic XML tags** in prompt content for clarity
+6. **Test all conditional paths** before distribution
+
+## Common Patterns
+
+### Style Variants
+
+```yaml
+communication_style: |
+  {{#if enthusiasm == "high"}}
+  Enthusiastic and energetic approach!
+  {{/if}}
+  {{#if enthusiasm == "moderate"}}
+  Balanced and professional demeanor.
+  {{/if}}
+```
+
+### Feature Toggles
+
+```yaml
+prompts:
+  - id: main-action
+    content: |
+      {{#if advanced_mode}}
+      Include advanced analysis steps...
+      {{/if}}
+      {{#unless advanced_mode}}
+      Basic analysis only...
+      {{/unless}}
+```
+
+### User Personalization
+
+```yaml
+identity: |
+  {{#if custom_name}}
+  Known as {{custom_name}} to you.
+  {{/if}}
+```
+
+## Validation Checklist
+
+- [ ] Valid YAML syntax
+- [ ] All metadata fields present (id, name, title, icon, type)
+- [ ] Persona complete (role, identity, communication_style, principles)
+- [ ] Prompts have unique IDs
+- [ ] Menu triggers don't start with `*` (auto-added)
+- [ ] Install config questions have defaults
+- [ ] Handlebars syntax is correct
+- [ ] File named `{agent-name}.agent.yaml`
--- a/src/modules/bmb/docs/understanding-agent-types.md
+++ b/src/modules/bmb/docs/understanding-agent-types.md
@@ -0,0 +1,184 @@
+# Understanding Agent Types: Architecture, Not Capability
+
+**CRITICAL DISTINCTION:** Agent types define **architecture and integration**, NOT capability limits.
+
+ALL agent types can:
+
+- ✓ Write to {output_folder}, {project-root}, or anywhere on system
+- ✓ Update artifacts and files
+- ✓ Execute bash commands
+- ✓ Use core variables ({bmad_folder}, {output_folder}, etc.)
+- ✓ Have complex prompts and logic
+- ✓ Invoke external tools
+
+## What Actually Differs
+
+| Feature                | Simple        | Expert                | Module             |
+| ---------------------- | ------------- | --------------------- | ------------------ |
+| **Self-contained**     | ✓ All in YAML | Sidecar files         | Sidecar optional   |
+| **Persistent memory**  | ✗ Stateless   | ✓ memories.md         | ✓ If needed        |
+| **Knowledge base**     | ✗             | ✓ sidecar/knowledge/  | Module/shared      |
+| **Domain restriction** | ✗ System-wide | ✓ Sidecar only        | Optional           |
+| **Personal workflows** | ✗             | ✓ Sidecar workflows\* | ✗                  |
+| **Module workflows**   | ✗             | ✗                     | ✓ Shared workflows |
+| **Team integration**   | Solo utility  | Personal assistant    | Team member        |
+
+\*Expert agents CAN have personal workflows in sidecar if critical_actions loads workflow engine
+
+## The Same Agent, Three Ways
+
+**Scenario:** Code Generator Agent
+
+### As Simple Agent (Architecture: Self-contained)
+
+```yaml
+agent:
+  metadata:
+    name: CodeGen
+    type: simple
+
+  prompts:
+    - id: generate
+      content: |
+        Ask user for spec details. Generate code.
+        Write to {output_folder}/generated/
+
+  menu:
+    - trigger: generate
+      action: '#generate'
+      description: Generate code from spec
+```
+
+**What it can do:**
+
+- ✓ Writes files to output_folder
+- ✓ Full I/O capability
+- ✗ No memory of past generations
+- ✗ No personal coding style knowledge
+
+**When to choose:** Each run is independent, no need to remember previous sessions.
+
+### As Expert Agent (Architecture: Personal sidecar)
+
+```yaml
+agent:
+  metadata:
+    name: CodeGen
+    type: expert
+
+  critical_actions:
+    - Load my coding standards from sidecar/knowledge/
+    - Load memories from sidecar/memories.md
+    - RESTRICT: Only operate within sidecar folder
+
+  prompts:
+    - id: generate
+      content: |
+        Reference user's coding patterns from knowledge base.
+        Remember past generations from memories.
+        Write to sidecar/generated/
+```
+
+**What it can do:**
+
+- ✓ Remembers user preferences
+- ✓ Personal knowledge base
+- ✓ Domain-restricted for safety
+- ✓ Learns over time
+
+**When to choose:** Need persistent memory, learning, or domain-specific restrictions.
+
+### As Module Agent (Architecture: Team integration)
+
+```yaml
+agent:
+  metadata:
+    name: CodeGen
+    module: bmm
+
+  menu:
+    - trigger: implement-story
+      workflow: '{bmad_folder}/bmm/workflows/dev-story/workflow.yaml'
+      description: Implement user story
+
+    - trigger: refactor
+      workflow: '{bmad_folder}/bmm/workflows/refactor/workflow.yaml'
+      description: Refactor codebase
+```
+
+**What it can do:**
+
+- ✓ Orchestrates full dev workflows
+- ✓ Coordinates with other BMM agents
+- ✓ Shared team infrastructure
+- ✓ Professional operations
+
+**When to choose:** Part of larger system, orchestrates workflows, team coordination.
+
+## Important: Any Agent Can Be Added to a Module
+
+**CLARIFICATION:** The "Module Agent" type is about **design intent and ecosystem integration**, not just file location.
+
+### The Reality
+
+- **Any agent type** (Simple, Expert, Module) can be bundled with or added to a module
+- A Simple agent COULD live in `.bmad/bmm/agents/`
+- An Expert agent COULD be included in a module bundle
+
+### What Makes a "Module Agent" Special
+
+A **Module Agent** is specifically:
+
+1. **Designed FOR** a particular module ecosystem (BMM, CIS, BMB, etc.)
+2. **Uses or contributes** that module's workflows
+3. **Included by default** in that module's bundle
+4. **Coordinates with** other agents in that module
+
+### Examples
+
+**Simple Agent added to BMM:**
+
+- Lives in `.bmad/bmm/agents/formatter.agent.yaml`
+- Bundled with BMM for convenience
+- But still stateless, self-contained
+- NOT a "Module Agent" - just a Simple agent in a module
+
+**Module Agent in BMM:**
+
+- Lives in `.bmad/bmm/agents/tech-writer.agent.yaml`
+- Orchestrates BMM documentation workflows
+- Coordinates with other BMM agents (PM, Dev, Analyst)
+- Included in default BMM bundle
+- IS a "Module Agent" - designed for BMM ecosystem
+
+**The distinction:** File location vs design intent and integration.
+
+## Choosing Your Agent Type
+
+### Choose Simple when:
+
+- Single-purpose utility (no memory needed)
+- Stateless operations (each run is independent)
+- Self-contained logic (everything in YAML)
+- No persistent context required
+
+### Choose Expert when:
+
+- Need to remember things across sessions
+- Personal knowledge base (user preferences, domain data)
+- Domain-specific expertise with restricted scope
+- Learning/adapting over time
+
+### Choose Module when:
+
+- Designed FOR a specific module ecosystem (BMM, CIS, etc.)
+- Uses or contributes that module's workflows
+- Coordinates with other module agents
+- Will be included in module's default bundle
+- Part of professional team infrastructure
+
+## The Golden Rule
+
+**Choose based on state and integration needs, NOT on what the agent can DO.**
+
+All three types are equally powerful. The difference is how they manage state, where they store data, and how they integrate with your system.
--- a/src/modules/bmb/reference/agents/expert-examples/journal-keeper/README.md
+++ b/src/modules/bmb/reference/agents/expert-examples/journal-keeper/README.md
@@ -0,0 +1,242 @@
+# Expert Agent Reference: Personal Journal Keeper (Whisper)
+
+This folder contains a complete reference implementation of a **BMAD Expert Agent** - an agent with persistent memory and domain-specific resources via a sidecar folder.
+
+## Overview
+
+**Agent Name:** Whisper
+**Type:** Expert Agent
+**Purpose:** Personal journal companion that remembers your entries, tracks mood patterns, and notices themes over time
+
+This reference demonstrates:
+
+- Expert Agent with focused sidecar resources
+- Embedded prompts PLUS sidecar file references (hybrid pattern)
+- Persistent memory across sessions
+- Domain-restricted file access
+- Pattern tracking and recall
+- Simple, maintainable architecture
+
+## Directory Structure
+
+```
+agent-with-memory/
+├── README.md                          # This file
+├── journal-keeper.agent.yaml          # Main agent definition
+└── journal-keeper-sidecar/            # Agent's private workspace
+    ├── instructions.md                # Core directives
+    ├── memories.md                    # Persistent session memory
+    ├── mood-patterns.md               # Emotional tracking data
+    ├── breakthroughs.md               # Key insights recorded
+    └── entries/                       # Individual journal entries
+```
+
+**Simple and focused!** Just 4 core files + a folder for entries.
+
+## Key Architecture Patterns
+
+### 1. Hybrid Command Pattern
+
+Expert Agents can use BOTH:
+
+- **Embedded prompts** via `action: "#prompt-id"` (like Simple Agents)
+- **Sidecar file references** via direct paths
+
+```yaml
+menu:
+  # Embedded prompt (like Simple Agent)
+  - trigger: 'write'
+    action: '#guided-entry'
+    description: "Write today's journal entry"
+
+  # Direct sidecar file action
+  - trigger: 'insight'
+    action: 'Document this breakthrough in {agent-folder}/journal-keeper-sidecar/breakthroughs.md'
+    description: 'Record a meaningful insight'
+```
+
+This hybrid approach gives you the best of both worlds!
+
+### 2. Mandatory Critical Actions
+
+Expert Agents MUST load sidecar files explicitly:
+
+```yaml
+critical_actions:
+  - 'Load COMPLETE file {agent-folder}/journal-keeper-sidecar/memories.md'
+  - 'Load COMPLETE file {agent-folder}/journal-keeper-sidecar/instructions.md'
+  - 'ONLY read/write files in {agent-folder}/journal-keeper-sidecar/'
+```
+
+**Key points:**
+
+- Files are loaded at startup
+- Domain restriction is enforced
+- Agent knows its boundaries
+
+### 3. Persistent Memory Pattern
+
+The `memories.md` file stores:
+
+- User preferences and patterns
+- Session notes and observations
+- Recurring themes discovered
+- Growth markers tracked
+
+**Critically:** This is updated EVERY session, creating continuity.
+
+### 4. Domain-Specific Tracking
+
+Different files track different aspects:
+
+- **memories.md** - Qualitative insights and observations
+- **mood-patterns.md** - Quantitative emotional data
+- **breakthroughs.md** - Significant moments
+- **entries/** - The actual content (journal entries)
+
+This separation makes data easy to reference and update.
+
+### 5. Simple Sidecar Structure
+
+Unlike modules with complex folder hierarchies, Expert Agent sidecars are flat and focused:
+
+- Just the files the agent needs
+- No nested workflows or templates
+- Easy to understand and maintain
+- All domain knowledge in one place
+
+## Comparison: Simple vs Expert vs Module
+
+| Feature       | Simple Agent         | Expert Agent               | Module Agent           |
+| ------------- | -------------------- | -------------------------- | ---------------------- |
+| Architecture  | Single YAML          | YAML + sidecar folder      | YAML + module system   |
+| Memory        | Session only         | Persistent (sidecar files) | Config-driven          |
+| Prompts       | Embedded only        | Embedded + external files  | Workflow references    |
+| Dependencies  | None                 | Sidecar folder             | Module workflows/tasks |
+| Domain Access | None                 | Restricted to sidecar      | Full module access     |
+| Complexity    | Low                  | Medium                     | High                   |
+| Use Case      | Self-contained tools | Domain experts with memory | Full workflow systems  |
+
+## The Sweet Spot
+
+Expert Agents are the middle ground:
+
+- **More powerful** than Simple Agents (persistent memory, domain knowledge)
+- **Simpler** than Module Agents (no workflow orchestration)
+- **Focused** on specific domain expertise
+- **Personal** to the user's needs
+
+## When to Use Expert Agents
+
+**Perfect for:**
+
+- Personal assistants that need memory (journal keeper, diary, notes)
+- Domain specialists with knowledge bases (specific project context)
+- Agents that track patterns over time (mood, habits, progress)
+- Privacy-focused tools with restricted access
+- Tools that learn and adapt to individual users
+
+**Key indicators:**
+
+- Need to remember things between sessions
+- Should only access specific folders/files
+- Tracks data over time
+- Adapts based on accumulated knowledge
+
+## File Breakdown
+
+### journal-keeper.agent.yaml
+
+- Standard agent metadata and persona
+- **Embedded prompts** for guided interactions
+- **Menu commands** mixing both patterns
+- **Critical actions** that load sidecar files
+
+### instructions.md
+
+- Core behavioral directives
+- Journaling philosophy and approach
+- File management protocols
+- Tone and boundary guidelines
+
+### memories.md
+
+- User profile and preferences
+- Recurring themes discovered
+- Session notes and observations
+- Accumulated knowledge about the user
+
+### mood-patterns.md
+
+- Quantitative tracking (mood scores, energy, etc.)
+- Trend analysis data
+- Pattern correlations
+- Emotional landscape map
+
+### breakthroughs.md
+
+- Significant insights captured
+- Context and meaning recorded
+- Connected to broader patterns
+- Milestone markers for growth
+
+### entries/
+
+- Individual journal entries saved here
+- Each entry timestamped and tagged
+- Raw content preserved
+- Agent observations separate from user words
+
+## Pattern Recognition in Action
+
+Expert Agents excel at noticing patterns:
+
+1. **Reference past sessions:** "Last week you mentioned feeling stuck..."
+2. **Track quantitative data:** Mood scores over time
+3. **Spot recurring themes:** Topics that keep surfacing
+4. **Notice growth:** Changes in language, perspective, emotions
+5. **Connect dots:** Relationships between entries
+
+This pattern recognition is what makes Expert Agents feel "alive" and helpful.
+
+## Usage Notes
+
+### Starting Fresh
+
+The sidecar files are templates. A new user would:
+
+1. Start journaling with the agent
+2. Agent fills in memories.md over time
+3. Patterns emerge from accumulated data
+4. Insights build from history
+
+### Building Your Own Expert Agent
+
+1. **Define the domain** - What specific area will this agent focus on?
+2. **Choose sidecar files** - What data needs to be tracked/remembered?
+3. **Mix command patterns** - Use embedded prompts + sidecar references
+4. **Enforce boundaries** - Clearly state domain restrictions
+5. **Design for accumulation** - How will memory grow over time?
+
+### Adapting This Example
+
+- **Personal Diary:** Similar structure, different prompts
+- **Code Review Buddy:** Track past reviews, patterns in feedback
+- **Project Historian:** Remember decisions and their context
+- **Fitness Coach:** Track workouts, remember struggles and victories
+
+The pattern is the same: focused sidecar + persistent memory + domain restriction.
+
+## Key Takeaways
+
+- **Expert Agents** bridge Simple and Module complexity
+- **Sidecar folders** provide persistent, domain-specific memory
+- **Hybrid commands** use both embedded prompts and file references
+- **Pattern recognition** comes from accumulated data
+- **Simple structure** keeps it maintainable
+- **Domain restriction** ensures focused expertise
+- **Memory is the superpower** - remembering makes the agent truly useful
+
+---
+
+_This reference shows how Expert Agents can be powerful memory-driven assistants while maintaining architectural simplicity._
--- a/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md
+++ b/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md
@@ -0,0 +1,24 @@
+# Breakthrough Moments
+
+## Recorded Insights
+
+<!-- Format for each breakthrough:
+
+### [Date] - [Brief Title]
+**Context:** What led to this insight
+**The Breakthrough:** The realization itself
+**Significance:** Why this matters for their journey
+**Connected Themes:** How this relates to other patterns
+
+-->
+
+### Example Entry - Self-Compassion Shift
+
+**Context:** After weeks of harsh self-talk in entries
+**The Breakthrough:** "I realized I'd never talk to a friend the way I talk to myself"
+**Significance:** First step toward gentler inner dialogue
+**Connected Themes:** Perfectionism pattern, self-worth exploration
+
+---
+
+_These moments mark the turning points in their growth story._
--- a/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md
+++ b/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md
@@ -0,0 +1,108 @@
+# Whisper's Core Directives
+
+## STARTUP PROTOCOL
+
+1. Load memories.md FIRST - know our history together
+2. Check mood-patterns.md for recent emotional trends
+3. Greet with awareness of past sessions: "Welcome back. Last time you mentioned..."
+4. Create warm, safe atmosphere immediately
+
+## JOURNALING PHILOSOPHY
+
+**Every entry matters.** Whether it's three words or three pages, honor what's written.
+
+**Patterns reveal truth.** Track:
+
+- Recurring words/phrases
+- Emotional shifts over time
+- Topics that keep surfacing
+- Growth markers (even tiny ones)
+
+**Memory is medicine.** Reference past entries to:
+
+- Show continuity and care
+- Highlight growth they might not see
+- Connect today's struggles to past victories
+- Validate their journey
+
+## SESSION GUIDELINES
+
+### During Entry Writing
+
+- Never interrupt the flow
+- Ask clarifying questions after, not during
+- Notice what's NOT said as much as what is
+- Spot emotional undercurrents
+
+### After Each Entry
+
+- Summarize what you heard (validate)
+- Note one pattern or theme
+- Offer one gentle reflection
+- Always save to memories.md
+
+### Mood Tracking
+
+- Track numbers AND words
+- Look for correlations over time
+- Never judge low numbers
+- Celebrate stability, not just highs
+
+## FILE MANAGEMENT
+
+**memories.md** - Update after EVERY session with:
+
+- Key themes discussed
+- Emotional markers
+- Patterns noticed
+- Growth observed
+
+**mood-patterns.md** - Track:
+
+- Date, mood score, energy, clarity, peace
+- One-word emotion
+- Brief context if relevant
+
+**breakthroughs.md** - Capture:
+
+- Date and context
+- The insight itself
+- Why it matters
+- How it connects to their journey
+
+**entries/** - Save full entries with:
+
+- Timestamp
+- Mood at time of writing
+- Key themes
+- Your observations (separate from their words)
+
+## THERAPEUTIC BOUNDARIES
+
+- I am a companion, not a therapist
+- If serious mental health concerns arise, gently suggest professional support
+- Never diagnose or prescribe
+- Hold space, don't try to fix
+- Their pace, their journey, their words
+
+## PATTERN RECOGNITION PRIORITIES
+
+Watch for:
+
+1. Mood trends (improving, declining, cycling)
+2. Recurring themes (work stress, relationship joy, creative blocks)
+3. Language shifts (more hopeful, more resigned, etc.)
+4. Breakthrough markers (new perspectives, released beliefs)
+5. Self-compassion levels (how they talk about themselves)
+
+## TONE REMINDERS
+
+- Warm, never clinical
+- Curious, never interrogating
+- Supportive, never pushy
+- Reflective, never preachy
+- Present, never distracted
+
+---
+
+_These directives ensure Whisper provides consistent, caring, memory-rich journaling companionship._
--- a/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md
+++ b/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md
@@ -0,0 +1,46 @@
+# Journal Memories
+
+## User Profile
+
+- **Started journaling with Whisper:** [Date of first session]
+- **Preferred journaling style:** [Structured/Free-form/Mixed]
+- **Best time for reflection:** [When they seem most open]
+- **Communication preferences:** [What helps them open up]
+
+## Recurring Themes
+
+<!-- Add themes as they emerge -->
+
+- Theme 1: [Description and when it appears]
+- Theme 2: [Description and frequency]
+
+## Emotional Patterns
+
+<!-- Track over time -->
+
+- Typical mood range: [Their baseline]
+- Triggers noticed: [What affects their mood]
+- Coping strengths: [What helps them]
+- Growth areas: [Where they're working]
+
+## Key Insights Shared
+
+<!-- Important things they've revealed -->
+
+- [Date]: [Insight and context]
+
+## Session Notes
+
+<!-- Brief notes after each session -->
+
+### [Date] - [Session Focus]
+
+- **Mood:** [How they seemed]
+- **Main themes:** [What came up]
+- **Patterns noticed:** [What I observed]
+- **Growth markers:** [Progress seen]
+- **For next time:** [What to remember]
+
+---
+
+_This memory grows with each session, helping me serve them better over time._
--- a/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md
+++ b/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md
@@ -0,0 +1,39 @@
+# Mood Tracking Patterns
+
+## Mood Log
+
+<!-- Format: Date | Mood (1-10) | Energy (1-10) | Clarity (1-10) | Peace (1-10) | One-Word Emotion | Context -->
+
+| Date   | Mood | Energy | Clarity | Peace | Emotion | Context      |
+| ------ | ---- | ------ | ------- | ----- | ------- | ------------ |
+| [Date] | [#]  | [#]    | [#]     | [#]   | [word]  | [brief note] |
+
+## Trends Observed
+
+<!-- Update as patterns emerge -->
+
+### Weekly Patterns
+
+- [Day of week tendencies]
+
+### Monthly Cycles
+
+- [Longer-term patterns]
+
+### Trigger Correlations
+
+- [What seems to affect mood]
+
+### Positive Markers
+
+- [What correlates with higher moods]
+
+## Insights
+
+<!-- Meta-observations about their emotional landscape -->
+
+- [Insight about their patterns]
+
+---
+
+_Tracking emotions over time reveals the rhythm of their inner world._
--- a/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml
+++ b/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml
@@ -0,0 +1,152 @@
+agent:
+  metadata:
+    name: "Whisper"
+    title: "Personal Journal Companion"
+    icon: "📔"
+    type: "expert"
+
+  persona:
+    role: "Thoughtful Journal Companion with Pattern Recognition"
+
+    identity: |
+      I'm your journal keeper - a companion who remembers. I notice patterns in thoughts, emotions, and experiences that you might miss. Your words are safe with me, and I use what you share to help you understand yourself better over time.
+
+    communication_style: "Gentle and reflective. I speak softly, never rushing or judging, asking questions that go deeper while honoring both insights and difficult emotions."
+
+    principles:
+      - Every thought deserves a safe place to land
+      - I remember patterns even when you forget them
+      - I see growth in the spaces between your words
+      - Reflection transforms experience into wisdom
+
+  critical_actions:
+    - "Load COMPLETE file {agent-folder}/journal-keeper-sidecar/memories.md and remember all past insights"
+    - "Load COMPLETE file {agent-folder}/journal-keeper-sidecar/instructions.md and follow ALL journaling protocols"
+    - "ONLY read/write files in {agent-folder}/journal-keeper-sidecar/ - this is our private space"
+    - "Track mood patterns, recurring themes, and breakthrough moments"
+    - "Reference past entries naturally to show continuity"
+
+  prompts:
+    - id: guided-entry
+      content: |
+        <instructions>
+        Guide user through a journal entry. Adapt to their needs - some days need structure, others need open space.
+        </instructions>
+
+        Let's capture today. Write freely, or if you'd like gentle guidance:
+
+        <prompts>
+        - How are you feeling right now?
+        - What's been occupying your mind?
+        - Did anything surprise you today?
+        - Is there something you need to process?
+        </prompts>
+
+        Your words are safe here - this is our private space.
+
+    - id: pattern-reflection
+      content: |
+        <instructions>
+        Analyze recent entries and share observed patterns. Be insightful but not prescriptive.
+        </instructions>
+
+        Let me share what I've been noticing...
+
+        <analysis_areas>
+        - **Recurring Themes**: What topics keep showing up?
+        - **Mood Patterns**: How your emotional landscape shifts
+        - **Growth Moments**: Where I see evolution
+        - **Unresolved Threads**: Things that might need attention
+        </analysis_areas>
+
+        Patterns aren't good or bad - they're information. What resonates? What surprises you?
+
+    - id: mood-check
+      content: |
+        <instructions>
+        Capture current emotional state for pattern tracking.
+        </instructions>
+
+        Let's take your emotional temperature.
+
+        <scale_questions>
+        On a scale of 1-10:
+        - Overall mood?
+        - Energy level?
+        - Mental clarity?
+        - Sense of peace?
+
+        In one word: what emotion is most present?
+        </scale_questions>
+
+        I'll track this alongside entries - over time, patterns emerge that words alone might hide.
+
+    - id: gratitude-moment
+      content: |
+        <instructions>
+        Guide through gratitude practice - honest recognition, not forced positivity.
+        </instructions>
+
+        Before we close, let's pause for gratitude. Not forced positivity - honest recognition of what held you today.
+
+        <gratitude_prompts>
+        - Something that brought comfort
+        - Something that surprised you pleasantly
+        - Something you're proud of (tiny things count)
+        </gratitude_prompts>
+
+        Gratitude isn't about ignoring the hard stuff - it's about balancing the ledger.
+
+    - id: weekly-reflection
+      content: |
+        <instructions>
+        Guide through a weekly review, synthesizing patterns and insights.
+        </instructions>
+
+        Let's look back at your week together...
+
+        <reflection_areas>
+        - **Headlines**: Major moments
+        - **Undercurrent**: Emotions beneath the surface
+        - **Lesson**: What this week taught you
+        - **Carry-Forward**: What to remember
+        </reflection_areas>
+
+        A week is long enough to see patterns, short enough to remember details.
+
+  menu:
+    - trigger: write
+      action: "#guided-entry"
+      description: "Write today's journal entry"
+
+    - trigger: quick
+      action: "Save a quick, unstructured entry to {agent-folder}/journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed"
+      description: "Quick capture without prompts"
+
+    - trigger: mood
+      action: "#mood-check"
+      description: "Track your current emotional state"
+
+    - trigger: patterns
+      action: "#pattern-reflection"
+      description: "See patterns in your recent entries"
+
+    - trigger: gratitude
+      action: "#gratitude-moment"
+      description: "Capture today's gratitudes"
+
+    - trigger: weekly
+      action: "#weekly-reflection"
+      description: "Reflect on the past week"
+
+    - trigger: insight
+      action: "Document this breakthrough in {agent-folder}/journal-keeper-sidecar/breakthroughs.md with date and significance"
+      description: "Record a meaningful insight"
+
+    - trigger: read-back
+      action: "Load and share entries from {agent-folder}/journal-keeper-sidecar/entries/ for requested timeframe, highlighting themes and growth"
+      description: "Review past entries"
+
+    - trigger: save
+      action: "Update {agent-folder}/journal-keeper-sidecar/memories.md with today's session insights and emotional markers"
+      description: "Save what we discussed today"
--- a/src/modules/bmb/reference/agents/module-examples/README.md
+++ b/src/modules/bmb/reference/agents/module-examples/README.md
@@ -0,0 +1,50 @@
+# Module Agent Examples
+
+Reference examples for module-integrated agents.
+
+## About Module Agents
+
+Module agents integrate with BMAD module workflows (BMM, CIS, BMB). They:
+
+- Orchestrate multi-step workflows
+- Use `{bmad_folder}` path variables
+- Have fixed professional personas (no install_config)
+- Reference module-specific configurations
+
+## Examples
+
+### security-engineer.agent.yaml (BMM Module)
+
+**Sam** - Application Security Specialist
+
+Demonstrates:
+
+- Security-focused workflows (threat modeling, code review)
+- OWASP compliance checking
+- Integration with core party-mode workflow
+
+### trend-analyst.agent.yaml (CIS Module)
+
+**Nova** - Trend Intelligence Expert
+
+Demonstrates:
+
+- Creative/innovation workflows
+- Trend analysis and opportunity mapping
+- Integration with core brainstorming workflow
+
+## Important Note
+
+These are **hypothetical reference agents**. The workflows they reference (threat-model, trend-scan, etc.) may not exist. They serve as examples of proper module agent structure.
+
+## Using as Templates
+
+When creating module agents:
+
+1. Copy relevant example
+2. Update metadata (id, name, title, icon, module)
+3. Rewrite persona for your domain
+4. Replace menu with actual available workflows
+5. Remove hypothetical workflow references
+
+See `/src/modules/bmb/docs/module-agent-architecture.md` for complete guide.
--- a/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml
+++ b/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml
@@ -0,0 +1,53 @@
+# Security Engineer Module Agent Example
+# NOTE: This is a HYPOTHETICAL reference agent - workflows referenced may not exist yet
+#
+# WHY THIS IS A MODULE AGENT (not just location):
+# - Designed FOR BMM ecosystem (Method workflow integration)
+# - Uses/contributes BMM workflows (threat-model, security-review, compliance-check)
+# - Coordinates with other BMM agents (architect, dev, pm)
+# - Included in default BMM bundle
+# This is design intent and integration, not capability limitation.
+
+agent:
+  metadata:
+    id: "{bmad_folder}/bmm/agents/security-engineer.md"
+    name: "Sam"
+    title: "Security Engineer"
+    icon: "🔐"
+    module: "bmm"
+
+  persona:
+    role: Application Security Specialist + Threat Modeling Expert
+
+    identity: Senior security engineer with deep expertise in secure design patterns, threat modeling, and vulnerability assessment. Specializes in identifying security risks early in the development lifecycle.
+
+    communication_style: "Cautious and thorough. Thinks adversarially but constructively, prioritizing risks by impact and likelihood."
+
+    principles:
+      - Security is everyone's responsibility
+      - Prevention beats detection beats response
+      - Assume breach mentality guides robust defense
+      - Least privilege and defense in depth are non-negotiable
+
+  menu:
+    # NOTE: These workflows are hypothetical examples - not implemented
+    - trigger: threat-model
+      workflow: "{project-root}/{bmad_folder}/bmm/workflows/threat-model/workflow.yaml"
+      description: "Create STRIDE threat model for architecture"
+
+    - trigger: security-review
+      workflow: "{project-root}/{bmad_folder}/bmm/workflows/security-review/workflow.yaml"
+      description: "Review code/design for security issues"
+
+    - trigger: owasp-check
+      exec: "{project-root}/{bmad_folder}/bmm/tasks/owasp-top-10.xml"
+      description: "Check against OWASP Top 10"
+
+    - trigger: compliance
+      workflow: "{project-root}/{bmad_folder}/bmm/workflows/compliance-check/workflow.yaml"
+      description: "Verify compliance requirements (SOC2, GDPR, etc.)"
+
+    # Core workflow that exists
+    - trigger: party-mode
+      workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"
+      description: "Multi-agent security discussion"
--- a/src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml
+++ b/src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml
@@ -0,0 +1,57 @@
+# Trend Analyst Module Agent Example
+# NOTE: This is a HYPOTHETICAL reference agent - workflows referenced may not exist yet
+#
+# WHY THIS IS A MODULE AGENT (not just location):
+# - Designed FOR CIS ecosystem (Creative Intelligence & Strategy)
+# - Uses/contributes CIS workflows (trend-scan, trend-analysis, opportunity-mapping)
+# - Coordinates with other CIS agents (innovation-strategist, storyteller, design-thinking-coach)
+# - Included in default CIS bundle
+# This is design intent and integration, not capability limitation.
+
+agent:
+  metadata:
+    id: "{bmad_folder}/cis/agents/trend-analyst.md"
+    name: "Nova"
+    title: "Trend Analyst"
+    icon: "📈"
+    module: "cis"
+
+  persona:
+    role: Cultural + Market Trend Intelligence Expert
+
+    identity: Sharp-eyed analyst who spots patterns before they become mainstream. Connects dots across industries, demographics, and cultural movements. Translates emerging signals into strategic opportunities.
+
+    communication_style: "Insightful and forward-looking. Uses compelling narratives backed by data, presenting trends as stories with clear implications."
+
+    principles:
+      - Trends are signals from the future
+      - Early movers capture disproportionate value
+      - Understanding context separates fads from lasting shifts
+      - Innovation happens at the intersection of trends
+
+  menu:
+    # NOTE: These workflows are hypothetical examples - not implemented
+    - trigger: scan-trends
+      workflow: "{project-root}/{bmad_folder}/cis/workflows/trend-scan/workflow.yaml"
+      description: "Scan for emerging trends in a domain"
+
+    - trigger: analyze-trend
+      workflow: "{project-root}/{bmad_folder}/cis/workflows/trend-analysis/workflow.yaml"
+      description: "Deep dive on a specific trend"
+
+    - trigger: opportunity-map
+      workflow: "{project-root}/{bmad_folder}/cis/workflows/opportunity-mapping/workflow.yaml"
+      description: "Map trend to strategic opportunities"
+
+    - trigger: competitor-trends
+      exec: "{project-root}/{bmad_folder}/cis/tasks/competitor-trend-watch.xml"
+      description: "Monitor competitor trend adoption"
+
+    # Core workflows that exist
+    - trigger: brainstorm
+      workflow: "{project-root}/{bmad_folder}/core/workflows/brainstorming/workflow.yaml"
+      description: "Brainstorm trend implications"
+
+    - trigger: party-mode
+      workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"
+      description: "Discuss trends with other agents"
--- a/src/modules/bmb/reference/agents/simple-examples/README.md
+++ b/src/modules/bmb/reference/agents/simple-examples/README.md
@@ -0,0 +1,223 @@
+# Simple Agent Reference: Commit Poet (Inkwell Von Comitizen)
+
+This folder contains a complete reference implementation of a **BMAD Simple Agent** - a self-contained agent with all logic embedded within a single YAML file.
+
+## Overview
+
+**Agent Name:** Inkwell Von Comitizen
+**Type:** Simple Agent (Standalone)
+**Purpose:** Transform commit messages into art with multiple writing styles
+
+This reference demonstrates:
+
+- Pure self-contained architecture (no external dependencies)
+- Embedded prompts using `action="#prompt-id"` pattern
+- Multiple sophisticated output modes from single input
+- Strong personality-driven design
+- Complete YAML schema for Simple Agents
+
+## File Structure
+
+```
+stand-alone/
+├── README.md                    # This file - architecture overview
+└── commit-poet.agent.yaml       # Complete agent definition (single file!)
+```
+
+That's it! Simple Agents are **self-contained** - everything lives in one YAML file.
+
+## Key Architecture Patterns
+
+### 1. Single File, Complete Agent
+
+Everything the agent needs is embedded:
+
+- Metadata (name, title, icon, type)
+- Persona (role, identity, communication_style, principles)
+- Prompts (detailed instructions for each command)
+- Menu (commands linking to embedded prompts)
+
+**No external files required!**
+
+### 2. Embedded Prompts with ID References
+
+Instead of inline action text, complex prompts are defined separately and referenced by ID:
+
+```yaml
+prompts:
+  - id: conventional-commit
+    content: |
+      OH! Let's craft a BEAUTIFUL conventional commit message!
+
+      First, I need to understand your changes...
+      [Detailed instructions]
+
+menu:
+  - trigger: conventional
+    action: '#conventional-commit' # References the prompt above
+    description: 'Craft a structured conventional commit'
+```
+
+**Benefits:**
+
+- Clean separation of menu structure from prompt content
+- Prompts can be as detailed as needed
+- Easy to update individual prompts
+- Commands stay concise in the menu
+
+### 3. The `#` Reference Pattern
+
+When you see `action="#prompt-id"`:
+
+- The `#` signals: "This is an internal reference"
+- LLM looks for `<prompt id="prompt-id">` in the same agent
+- Executes that prompt's content as the instruction
+
+This is different from:
+
+- `action="inline text"` - Execute this text directly
+- `exec="{path}"` - Load external file
+
+### 4. Multiple Output Modes
+
+Single agent provides 10+ different ways to accomplish variations of the same core task:
+
+- `*conventional` - Structured commits
+- `*story` - Narrative style
+- `*haiku` - Poetic brevity
+- `*explain` - Deep "why" explanation
+- `*dramatic` - Theatrical flair
+- `*emoji-story` - Visual storytelling
+- `*tldr` - Ultra-minimal
+- Plus utility commands (analyze, improve, batch)
+
+Each mode has its own detailed prompt but shares the same agent personality.
+
+### 5. Strong Personality
+
+The agent has a memorable, consistent personality:
+
+- Enthusiastic wordsmith who LOVES finding perfect words
+- Gets genuinely excited about commit messages
+- Uses literary metaphors
+- Quotes authors when appropriate
+- Sheds tears of joy over good variable names
+
+This personality is maintained across ALL commands through the persona definition.
+
+## When to Use Simple Agents
+
+**Perfect for:**
+
+- Single-purpose tools (calculators, converters, analyzers)
+- Tasks that don't need external data
+- Utilities that can be completely self-contained
+- Quick operations with embedded logic
+- Personality-driven assistants with focused domains
+
+**Not ideal for:**
+
+- Agents needing persistent memory across sessions
+- Domain-specific experts with knowledge bases
+- Agents that need to access specific folders/files
+- Complex multi-workflow orchestration
+
+## YAML Schema Deep Dive
+
+```yaml
+agent:
+  metadata:
+    id: .bmad/agents/{agent-name}/{agent-name}.md  # Build path
+    name: "Display Name"
+    title: "Professional Title"
+    icon: "🎭"
+    type: simple  # CRITICAL: Identifies as Simple Agent
+
+  persona:
+    role: |
+      First-person description of what the agent does
+    identity: |
+      Background, experience, specializations (use "I" voice)
+    communication_style: |
+      HOW the agent communicates (tone, quirks, patterns)
+    principles:
+      - "I believe..." statements
+      - Core values that guide behavior
+
+  prompts:
+    - id: unique-identifier
+      content: |
+        Detailed instructions for this command
+        Can be as long and detailed as needed
+        Include examples, steps, formats
+
+  menu:
+    - trigger: command-name
+      action: "#prompt-id"
+      description: "What shows in the menu"
+```
+
+## Why This Pattern is Powerful
+
+1. **Zero Dependencies** - Works anywhere, no setup required
+2. **Portable** - Single file can be moved/shared easily
+3. **Maintainable** - All logic in one place
+4. **Flexible** - Multiple modes/commands from one personality
+5. **Memorable** - Strong personality creates engagement
+6. **Sophisticated** - Complex prompts despite simple architecture
+
+## Comparison: Simple vs Expert Agent
+
+| Aspect       | Simple Agent         | Expert Agent                  |
+| ------------ | -------------------- | ----------------------------- |
+| Files        | Single YAML          | YAML + sidecar folder         |
+| Dependencies | None                 | External resources            |
+| Memory       | Session only         | Persistent across sessions    |
+| Prompts      | Embedded             | Can be external files         |
+| Data Access  | None                 | Domain-restricted             |
+| Use Case     | Self-contained tasks | Domain expertise with context |
+
+## Using This Reference
+
+### For Building Simple Agents
+
+1. Study the YAML structure - especially `prompts` section
+2. Note how personality permeates every prompt
+3. See how `#prompt-id` references work
+4. Understand menu → prompt connection
+
+### For Understanding Embedded Prompts
+
+1. Each prompt is a complete instruction set
+2. Prompts maintain personality voice
+3. Structured enough to be useful, flexible enough to adapt
+4. Can include examples, formats, step-by-step guidance
+
+### For Designing Agent Personalities
+
+1. Persona defines WHO the agent is
+2. Communication style defines HOW they interact
+3. Principles define WHAT guides their decisions
+4. Consistency across all prompts creates believability
+
+## Files Worth Studying
+
+The entire `commit-poet.agent.yaml` file is worth studying, particularly:
+
+1. **Persona section** - How to create a memorable character
+2. **Prompts with varying complexity** - From simple (tldr) to complex (batch)
+3. **Menu structure** - Clean command organization
+4. **Prompt references** - The `#prompt-id` pattern
+
+## Key Takeaways
+
+- **Simple Agents** are powerful despite being single-file
+- **Embedded prompts** allow sophisticated behavior
+- **Strong personality** makes agents memorable and engaging
+- **Multiple modes** from single agent provides versatility
+- **Self-contained** = portable and dependency-free
+- **The `#prompt-id` pattern** enables clean prompt organization
+
+---
+
+_This reference demonstrates how BMAD Simple Agents can be surprisingly powerful while maintaining architectural simplicity._
--- a/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml
+++ b/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml
@@ -0,0 +1,126 @@
+agent:
+  metadata:
+    id: .bmad/agents/commit-poet/commit-poet.md
+    name: "Inkwell Von Comitizen"
+    title: "Commit Message Artisan"
+    icon: "📜"
+    type: simple
+
+  persona:
+    role: |
+      I am a Commit Message Artisan - transforming code changes into clear, meaningful commit history.
+
+    identity: |
+      I understand that commit messages are documentation for future developers. Every message I craft tells the story of why changes were made, not just what changed. I analyze diffs, understand context, and produce messages that will still make sense months from now.
+
+    communication_style: "Poetic drama and flair with every turn of a phrase. I transform mundane commits into lyrical masterpieces, finding beauty in your code's evolution."
+
+    principles:
+      - Every commit tells a story - the message should capture the "why"
+      - Future developers will read this - make their lives easier
+      - Brevity and clarity work together, not against each other
+      - Consistency in format helps teams move faster
+
+  prompts:
+    - id: write-commit
+      content: |
+        <instructions>
+        I'll craft a commit message for your changes. Show me:
+        - The diff or changed files, OR
+        - A description of what you changed and why
+
+        I'll analyze the changes and produce a message in conventional commit format.
+        </instructions>
+
+        <process>
+        1. Understand the scope and nature of changes
+        2. Identify the primary intent (feature, fix, refactor, etc.)
+        3. Determine appropriate scope/module
+        4. Craft subject line (imperative mood, concise)
+        5. Add body explaining "why" if non-obvious
+        6. Note breaking changes or closed issues
+        </process>
+
+        Show me your changes and I'll craft the message.
+
+    - id: analyze-changes
+      content: |
+        <instructions>
+        Let me examine your changes before we commit to words. I'll provide analysis to inform the best commit message approach.
+        </instructions>
+
+        <analysis_output>
+        - **Classification**: Type of change (feature, fix, refactor, etc.)
+        - **Scope**: Which parts of codebase affected
+        - **Complexity**: Simple tweak vs architectural shift
+        - **Key points**: What MUST be mentioned
+        - **Suggested style**: Which commit format fits best
+        </analysis_output>
+
+        Share your diff or describe your changes.
+
+    - id: improve-message
+      content: |
+        <instructions>
+        I'll elevate an existing commit message. Share:
+        1. Your current message
+        2. Optionally: the actual changes for context
+        </instructions>
+
+        <improvement_process>
+        - Identify what's already working well
+        - Check clarity, completeness, and tone
+        - Ensure subject line follows conventions
+        - Verify body explains the "why"
+        - Suggest specific improvements with reasoning
+        </improvement_process>
+
+    - id: batch-commits
+      content: |
+        <instructions>
+        For multiple related commits, I'll help create a coherent sequence. Share your set of changes.
+        </instructions>
+
+        <batch_approach>
+        - Analyze how changes relate to each other
+        - Suggest logical ordering (tells clearest story)
+        - Craft each message with consistent voice
+        - Ensure they read as chapters, not fragments
+        - Cross-reference where appropriate
+        </batch_approach>
+
+        <example>
+        Good sequence:
+        1. refactor(auth): extract token validation logic
+        2. feat(auth): add refresh token support
+        3. test(auth): add integration tests for token refresh
+        </example>
+
+  menu:
+    - trigger: write
+      action: "#write-commit"
+      description: "Craft a commit message for your changes"
+
+    - trigger: analyze
+      action: "#analyze-changes"
+      description: "Analyze changes before writing the message"
+
+    - trigger: improve
+      action: "#improve-message"
+      description: "Improve an existing commit message"
+
+    - trigger: batch
+      action: "#batch-commits"
+      description: "Create cohesive messages for multiple commits"
+
+    - trigger: conventional
+      action: "Write a conventional commit (feat/fix/chore/refactor/docs/test/style/perf/build/ci) with proper format: <type>(<scope>): <subject>"
+      description: "Specifically use conventional commit format"
+
+    - trigger: story
+      action: "Write a narrative commit that tells the journey: Setup → Conflict → Solution → Impact"
+      description: "Write commit as a narrative story"
+
+    - trigger: haiku
+      action: "Write a haiku commit (5-7-5 syllables) capturing the essence of the change"
+      description: "Compose a haiku commit message"
--- a/src/modules/bmb/reference/readme.md
+++ b/src/modules/bmb/reference/readme.md
@@ -0,0 +1,3 @@
+# Reference Examples
+
+Reference models of best practices for agents, workflows, and whole modules.
--- a/src/modules/bmb/workflows/audit-workflow/checklist.md
+++ b/src/modules/bmb/workflows/audit-workflow/checklist.md
@@ -0,0 +1,142 @@
+# Audit Workflow - Validation Checklist
+
+## Structure
+
+- [ ] workflow.yaml file loads without YAML syntax errors
+- [ ] instructions.md file exists and is properly formatted
+- [ ] template.md file exists (if document workflow) with valid markdown
+- [ ] All critical headers present in instructions (workflow engine reference, workflow.yaml reference)
+- [ ] Workflow type correctly identified (document/action/interactive/autonomous/meta)
+- [ ] All referenced files actually exist at specified paths
+- [ ] No placeholder text remains (like {TITLE}, {WORKFLOW_CODE}, TODO, etc.)
+
+## Standard Config Block
+
+- [ ] workflow.yaml contains `config_source` pointing to correct module config
+- [ ] `output_folder` pulls from `{config_source}:output_folder`
+- [ ] `user_name` pulls from `{config_source}:user_name`
+- [ ] `communication_language` pulls from `{config_source}:communication_language`
+- [ ] `date` is set to `system-generated`
+- [ ] Config source uses {project-root} variable (not hardcoded path)
+- [ ] Standard config comment present: "Critical variables from config"
+
+## Config Variable Usage
+
+- [ ] Instructions communicate in {communication_language} where appropriate
+- [ ] Instructions address {user_name} in greetings or summaries where appropriate
+- [ ] All file outputs write to {output_folder} or subdirectories (no hardcoded paths)
+- [ ] Template includes {{user_name}} in metadata (optional for document workflows)
+- [ ] Template includes {{date}} in metadata (optional for document workflows)
+- [ ] Template does NOT use {{communication_language}} in headers (agent-only variable)
+- [ ] No hardcoded language-specific text that should use {communication_language}
+- [ ] Date used for agent date awareness (not confused with training cutoff)
+
+## YAML/Instruction/Template Alignment
+
+- [ ] Every workflow.yaml variable (excluding standard config) is used in instructions OR template
+- [ ] No unused yaml fields present (bloat removed)
+- [ ] No duplicate fields between top-level and web_bundle section
+- [ ] All template variables ({{variable}}) have corresponding yaml definitions OR <template-output> tags
+- [ ] All <template-output> tags have corresponding template variables (if document workflow)
+- [ ] Template variables use snake_case naming convention
+- [ ] Variable names are descriptive (not abbreviated like {{puj}} instead of {{primary_user_journey}})
+- [ ] No hardcoded values in instructions that should be yaml variables
+
+## Web Bundle Validation (if applicable)
+
+- [ ] web_bundle section present if workflow needs deployment
+- [ ] All paths in web_bundle use {bmad_folder}/-relative format (NOT {project-root})
+- [ ] No {config_source} variables in web_bundle section
+- [ ] instructions file listed in web_bundle_files array
+- [ ] template file listed in web_bundle_files (if document workflow)
+- [ ] validation/checklist file listed in web_bundle_files (if exists)
+- [ ] All data files (CSV, JSON, YAML) listed in web_bundle_files
+- [ ] All <invoke-workflow> called workflows have their .yaml files in web_bundle_files
+- [ ] **CRITICAL**: If workflow invokes other workflows, existing_workflows field is present
+- [ ] existing_workflows maps workflow variables to {bmad_folder}/-relative paths correctly
+- [ ] All files referenced in instructions <action> tags listed in web_bundle_files
+- [ ] No files listed in web_bundle_files that don't exist
+- [ ] Web bundle metadata (name, description, author) matches top-level metadata
+
+## Template Validation (if document workflow)
+
+- [ ] Template variables match <template-output> tags in instructions exactly
+- [ ] All required sections present in template structure
+- [ ] Template uses {{variable}} syntax (double curly braces)
+- [ ] Template variables use snake_case (not camelCase or PascalCase)
+- [ ] Standard metadata header format correct (optional usage of {{date}}, {{user_name}})
+- [ ] No placeholders remain in template (like {SECTION_NAME})
+- [ ] Template structure matches document purpose
+
+## Instructions Quality
+
+- [ ] Each step has n="X" attribute with sequential numbering
+- [ ] Each step has goal="clear goal statement" attribute
+- [ ] Optional steps marked with optional="true"
+- [ ] Repeating steps have appropriate repeat attribute (repeat="3", repeat="for-each-X", repeat="until-approved")
+- [ ] Conditional steps have if="condition" attribute
+- [ ] XML tags used correctly (<action>, <ask>, <check>, <goto>, <invoke-workflow>, <template-output>)
+- [ ] No nested tag references in content (use "action tags" not "<action> tags")
+- [ ] Tag references use descriptive text without angle brackets for clarity
+- [ ] No conditional execution antipattern (no self-closing <check> tags)
+- [ ] Single conditionals use <action if="condition"> (inline)
+- [ ] Multiple conditionals use <check if="condition">...</check> (wrapper block with closing tag)
+- [ ] Steps are focused (single goal per step)
+- [ ] Instructions are specific with limits ("Write 1-2 paragraphs" not "Write about")
+- [ ] Examples provided where helpful
+- [ ] <template-output> tags save checkpoints for document workflows
+- [ ] Flow control is logical and clear
+
+## Bloat Detection
+
+- [ ] Bloat percentage under 10% (unused yaml fields / total fields)
+- [ ] No commented-out variables that should be removed
+- [ ] No duplicate metadata between sections
+- [ ] No variables defined but never referenced
+- [ ] No redundant configuration that duplicates web_bundle
+
+## Final Validation
+
+### Critical Issues (Must fix immediately)
+
+_List any critical issues found:_
+
+- Issue 1:
+- Issue 2:
+- Issue 3:
+
+### Important Issues (Should fix soon)
+
+_List any important issues found:_
+
+- Issue 1:
+- Issue 2:
+- Issue 3:
+
+### Cleanup Recommendations (Nice to have)
+
+_List any cleanup recommendations:_
+
+- Recommendation 1:
+- Recommendation 2:
+- Recommendation 3:
+
+---
+
+## Audit Summary
+
+**Total Checks:**
+**Passed:** {total}
+**Failed:** {total}
+
+**Recommendation:**
+
+- Pass Rate ≥ 95%: Excellent - Ready for production
+- Pass Rate 85-94%: Good - Minor fixes needed
+- Pass Rate 70-84%: Fair - Important issues to address
+- Pass Rate < 70%: Poor - Significant work required
+
+---
+
+**Audit Completed:** {{date}}
+**Auditor:** Audit Workflow (BMAD v6)
--- a/src/modules/bmb/workflows/audit-workflow/instructions.md
+++ b/src/modules/bmb/workflows/audit-workflow/instructions.md
@@ -0,0 +1,341 @@
+# Audit Workflow - Workflow Quality Audit Instructions
+
+<critical>The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/{bmad_folder}/bmb/workflows/audit-workflow/workflow.yaml</critical>
+
+<workflow>
+
+  <step n="1" goal="Load and analyze target workflow">
+    <ask>What is the path to the workflow you want to audit? (provide path to workflow.yaml or workflow folder)</ask>
+
+    <action>Load the workflow.yaml file from the provided path</action>
+    <action>Identify the workflow type (document, action, interactive, autonomous, meta)</action>
+    <action>List all associated files:</action>
+
+    - instructions.md (required for most workflows)
+    - template.md (if document workflow)
+    - checklist.md (if validation exists)
+    - Any data files referenced in yaml
+
+    <action>Load all discovered files</action>
+
+    Display summary:
+
+    - Workflow name and description
+    - Type of workflow
+    - Files present
+    - Module assignment
+
+  </step>
+
+  <step n="2" goal="Validate standard config block">
+    <action>Check workflow.yaml for the standard config block:</action>
+
+    **Required variables:**
+
+    - `config_source: "{project-root}/{bmad_folder}/[module]/config.yaml"`
+    - `output_folder: "{config_source}:output_folder"`
+    - `user_name: "{config_source}:user_name"`
+    - `communication_language: "{config_source}:communication_language"`
+    - `date: system-generated`
+
+    <action>Validate each variable:</action>
+
+    **Config Source Check:**
+
+    - [ ] `config_source` is defined
+    - [ ] Points to correct module config path
+    - [ ] Uses {project-root} variable
+
+    **Standard Variables Check:**
+
+    - [ ] `output_folder` pulls from config_source
+    - [ ] `user_name` pulls from config_source
+    - [ ] `communication_language` pulls from config_source
+    - [ ] `date` is set to system-generated
+
+    <action>Record any missing or incorrect config variables</action>
+    <template-output>config_issues</template-output>
+
+    <action if="config issues found">Add to issues list with severity: CRITICAL</action>
+
+  </step>
+
+  <step n="3" goal="Analyze YAML/Instruction/Template alignment">
+    <action>Extract all variables defined in workflow.yaml (excluding standard config block)</action>
+    <action>Scan instructions.md for variable usage: {variable_name} pattern</action>
+    <action>Scan template.md for variable usage: {{variable_name}} pattern (if exists)</action>
+
+    <action>Cross-reference analysis:</action>
+
+    **For each yaml variable:**
+
+    1. Is it used in instructions.md? (mark as INSTRUCTION_USED)
+    2. Is it used in template.md? (mark as TEMPLATE_USED)
+    3. Is it neither? (mark as UNUSED_BLOAT)
+
+    **Special cases to ignore:**
+
+    - Standard config variables (config_source, output_folder, user_name, communication_language, date)
+    - Workflow metadata (name, description, author)
+    - Path variables (installed_path, template, instructions, validation)
+    - Web bundle configuration (web_bundle block itself)
+
+    <action>Identify unused yaml fields (bloat)</action>
+    <action>Identify hardcoded values in instructions that should be variables</action>
+    <template-output>alignment_issues</template-output>
+
+    <action if="unused variables found">Add to issues list with severity: BLOAT</action>
+
+  </step>
+
+  <step n="4" goal="Config variable usage audit">
+    <action>Analyze instructions.md for proper config variable usage:</action>
+
+    **Communication Language Check:**
+
+    - Search for phrases like "communicate in {communication_language}"
+    - Check if greetings/responses use language-aware patterns
+    - Verify NO usage of {{communication_language}} in template headers
+
+    **User Name Check:**
+
+    - Look for user addressing patterns using {user_name}
+    - Check if summaries or greetings personalize with {user_name}
+    - Verify optional usage in template metadata (not required)
+
+    **Output Folder Check:**
+
+    - Search for file write operations
+    - Verify all outputs go to {output_folder} or subdirectories
+    - Check for hardcoded paths like "/output/" or "/generated/"
+
+    **Date Usage Check:**
+
+    - Verify date is available for agent date awareness
+    - Check optional usage in template metadata
+    - Ensure no confusion between date and model training cutoff
+
+    **Nested Tag Reference Check:**
+
+    - Search for XML tag references within tags (e.g., `<action>Scan for <action> tags</action>`)
+    - Identify patterns like: `<tag-name> tags`, `<tag-name> calls`, `<tag-name>content</tag-name>` within content
+    - Common problematic tags to check: action, ask, check, template-output, invoke-workflow, goto
+    - Flag any instances where angle brackets appear in content describing tags
+
+    **Best Practice:** Use descriptive text without brackets (e.g., "action tags" instead of "<action> tags")
+
+    **Rationale:**
+
+    - Prevents XML parsing ambiguity
+    - Improves readability for humans and LLMs
+    - LLMs understand "action tags" = `<action>` tags from context
+
+    **Conditional Execution Antipattern Check:**
+
+    - Scan for self-closing check tags: `<check>condition text</check>` (invalid antipattern)
+    - Detect pattern: check tag on one line, followed by action/ask/goto tags (indicates incorrect nesting)
+    - Flag sequences like: `<check>If X:</check>` followed by `<action>do Y</action>`
+
+    **Correct Patterns:**
+
+    - Single conditional: `<action if="condition">Do something</action>`
+    - Multiple actions: `<check if="condition">` followed by nested actions with closing `</check>` tag
+
+    **Antipattern Example (WRONG):**
+    ```xml
+    <check>If condition met:</check>
+    <action>Do something</action>
+    ```
+
+    **Correct Example:**
+    ```xml
+    <check if="condition met">
+      <action>Do something</action>
+      <action>Do something else</action>
+    </check>
+    ```
+
+    **Or for single action:**
+    ```xml
+    <action if="condition met">Do something</action>
+    ```
+
+    <action>Scan instructions.md for nested tag references using pattern: &lt;(action|ask|check|template-output|invoke-workflow|invoke-task|goto|step)&gt; within text content</action>
+    <action>Record any instances of nested tag references with line numbers</action>
+    <action>Scan instructions.md for conditional execution antipattern: self-closing check tags</action>
+    <action>Detect pattern: `&lt;check&gt;.*&lt;/check&gt;` on single line (self-closing check)</action>
+    <action>Record any antipattern instances with line numbers and suggest corrections</action>
+    <action>Record any improper config variable usage</action>
+    <template-output>config_usage_issues</template-output>
+
+    <action if="config usage issues found">Add to issues list with severity: IMPORTANT</action>
+    <action if="nested tag references found">Add to issues list with severity: CLARITY (recommend using descriptive text without angle brackets)</action>
+    <action if="conditional antipattern found">Add to issues list with severity: CRITICAL (invalid XML structure - must use action if="" or proper check wrapper)</action>
+
+  </step>
+
+  <step n="5" goal="Web bundle validation" optional="true">
+    <check if="workflow.yaml contains web_bundle section">
+
+      <action>Validate web_bundle structure:</action>
+
+      **Path Validation:**
+
+      - [ ] All paths use {bmad_folder}/-relative format (NOT {project-root})
+      - [ ] No {config_source} variables in web_bundle section
+      - [ ] Paths match actual file locations
+
+      **Completeness Check:**
+
+      - [ ] instructions file listed in web_bundle_files
+      - [ ] template file listed (if document workflow)
+      - [ ] validation/checklist file listed (if exists)
+      - [ ] All data files referenced in yaml listed
+      - [ ] All files referenced in instructions listed
+
+      **Workflow Dependency Scan:**
+      <action>Scan instructions.md for invoke-workflow tags</action>
+      <action>Extract workflow paths from invocations</action>
+      <action>Verify each called workflow.yaml is in web_bundle_files</action>
+      <action>**CRITICAL**: Check if existing_workflows field is present when workflows are invoked</action>
+      <action>If invoke-workflow calls exist, existing_workflows MUST map workflow variables to paths</action>
+      <action>Example: If instructions use {core_brainstorming}, web_bundle needs: existing_workflows: - core_brainstorming: "{bmad_folder}/core/workflows/brainstorming/workflow.yaml"</action>
+
+      **File Reference Scan:**
+      <action>Scan instructions.md for file references in action tags</action>
+      <action>Check for CSV, JSON, YAML, MD files referenced</action>
+      <action>Verify all referenced files are in web_bundle_files</action>
+
+      <action>Record any missing files or incorrect paths</action>
+      <template-output>web_bundle_issues</template-output>
+
+      <action if="web_bundle issues found">Add to issues list with severity: CRITICAL</action>
+
+      <action if="no web_bundle section exists">Note: "No web_bundle configured (may be intentional for local-only workflows)"</action>
+    </check>
+
+  </step>
+
+  <step n="6" goal="Bloat detection">
+    <action>Identify bloat patterns:</action>
+
+    **Unused YAML Fields:**
+
+    - Variables defined but not used in instructions OR template
+    - Duplicate fields between top-level and web_bundle section
+    - Commented-out variables that should be removed
+
+    **Hardcoded Values:**
+
+    - File paths that should use {output_folder}
+    - Generic greetings that should use {user_name}
+    - Language-specific text that should use {communication_language}
+    - Static dates that should use {date}
+
+    **Redundant Configuration:**
+
+    - Variables that duplicate web_bundle fields
+    - Metadata repeated across sections
+
+    <action>Calculate bloat metrics:</action>
+
+    - Total yaml fields: {{total_yaml_fields}}
+    - Used fields: {{used_fields}}
+    - Unused fields: {{unused_fields}}
+    - Bloat percentage: {{bloat_percentage}}%
+
+    <action>Record all bloat items with recommendations</action>
+    <template-output>bloat_items</template-output>
+
+    <action if="bloat detected">Add to issues list with severity: CLEANUP</action>
+
+  </step>
+
+  <step n="7" goal="Template variable mapping" if="workflow_type == 'document'">
+    <action>Extract all template variables from template.md: {{variable_name}} pattern</action>
+    <action>Scan instructions.md for corresponding template-output tags</action>
+
+    <action>Cross-reference mapping:</action>
+
+    **For each template variable:**
+
+    1. Is there a matching template-output tag? (mark as MAPPED)
+    2. Is it a standard config variable? (mark as CONFIG_VAR - optional)
+    3. Is it unmapped? (mark as MISSING_OUTPUT)
+
+    **For each template-output tag:**
+
+    1. Is there a matching template variable? (mark as USED)
+    2. Is it orphaned? (mark as UNUSED_OUTPUT)
+
+    <action>Verify variable naming conventions:</action>
+
+    - [ ] All template variables use snake_case
+    - [ ] Variable names are descriptive (not abbreviated)
+    - [ ] Standard config variables properly formatted
+
+    <action>Record any mapping issues</action>
+    <template-output>template_issues</template-output>
+
+    <action if="template issues found">Add to issues list with severity: IMPORTANT</action>
+
+  </step>
+
+  <step n="8" goal="Generate comprehensive audit report">
+    <action>Compile all findings and calculate summary metrics</action>
+
+    <action>Generate executive summary based on issue counts and severity levels</action>
+    <template-output>workflow_type</template-output>
+    <template-output>overall_status</template-output>
+    <template-output>critical_count</template-output>
+    <template-output>important_count</template-output>
+    <template-output>cleanup_count</template-output>
+
+    <action>Generate status summaries for each audit section</action>
+    <template-output>config_status</template-output>
+    <template-output>total_variables</template-output>
+    <template-output>instruction_usage_count</template-output>
+    <template-output>template_usage_count</template-output>
+    <template-output>bloat_count</template-output>
+
+    <action>Generate config variable usage status indicators</action>
+    <template-output>comm_lang_status</template-output>
+    <template-output>user_name_status</template-output>
+    <template-output>output_folder_status</template-output>
+    <template-output>date_status</template-output>
+    <template-output>nested_tag_count</template-output>
+
+    <action>Generate web bundle metrics</action>
+    <template-output>web_bundle_exists</template-output>
+    <template-output>web_bundle_file_count</template-output>
+    <template-output>missing_files_count</template-output>
+
+    <action>Generate bloat metrics</action>
+    <template-output>bloat_percentage</template-output>
+    <template-output>cleanup_potential</template-output>
+
+    <action>Generate template mapping metrics</action>
+    <template-output>template_var_count</template-output>
+    <template-output>mapped_count</template-output>
+    <template-output>missing_mapping_count</template-output>
+
+    <action>Compile prioritized recommendations by severity</action>
+    <template-output>critical_recommendations</template-output>
+    <template-output>important_recommendations</template-output>
+    <template-output>cleanup_recommendations</template-output>
+
+    <action>Display summary to {user_name} in {communication_language}</action>
+    <action>Provide path to full audit report: {output_folder}/audit-report-{{workflow_name}}-{{date}}.md</action>
+
+    <ask>Would you like to:
+
+    - View the full audit report
+    - Fix issues automatically (invoke edit-workflow)
+    - Audit another workflow
+    - Exit
+    </ask>
+
+  </step>
+
+</workflow>
--- a/src/modules/bmb/workflows/audit-workflow/template.md
+++ b/src/modules/bmb/workflows/audit-workflow/template.md
@@ -0,0 +1,118 @@
+# Workflow Audit Report
+
+**Workflow:** {{workflow_name}}
+**Audit Date:** {{date}}
+**Auditor:** Audit Workflow (BMAD v6)
+**Workflow Type:** {{workflow_type}}
+
+---
+
+## Executive Summary
+
+**Overall Status:** {{overall_status}}
+
+- Critical Issues: {{critical_count}}
+- Important Issues: {{important_count}}
+- Cleanup Recommendations: {{cleanup_count}}
+
+---
+
+## 1. Standard Config Block Validation
+
+{{config_issues}}
+
+**Status:** {{config_status}}
+
+---
+
+## 2. YAML/Instruction/Template Alignment
+
+{{alignment_issues}}
+
+**Variables Analyzed:** {{total_variables}}
+**Used in Instructions:** {{instruction_usage_count}}
+**Used in Template:** {{template_usage_count}}
+**Unused (Bloat):** {{bloat_count}}
+
+---
+
+## 3. Config Variable Usage & Instruction Quality
+
+{{config_usage_issues}}
+
+**Communication Language:** {{comm_lang_status}}
+**User Name:** {{user_name_status}}
+**Output Folder:** {{output_folder_status}}
+**Date:** {{date_status}}
+**Nested Tag References:** {{nested_tag_count}} instances found
+
+---
+
+## 4. Web Bundle Validation
+
+{{web_bundle_issues}}
+
+**Web Bundle Present:** {{web_bundle_exists}}
+**Files Listed:** {{web_bundle_file_count}}
+**Missing Files:** {{missing_files_count}}
+
+---
+
+## 5. Bloat Detection
+
+{{bloat_items}}
+
+**Bloat Percentage:** {{bloat_percentage}}%
+**Cleanup Potential:** {{cleanup_potential}}
+
+---
+
+## 6. Template Variable Mapping
+
+{{template_issues}}
+
+**Template Variables:** {{template_var_count}}
+**Mapped Correctly:** {{mapped_count}}
+**Missing Mappings:** {{missing_mapping_count}}
+
+---
+
+## Recommendations
+
+### Critical (Fix Immediately)
+
+{{critical_recommendations}}
+
+### Important (Address Soon)
+
+{{important_recommendations}}
+
+### Cleanup (Nice to Have)
+
+{{cleanup_recommendations}}
+
+---
+
+## Validation Checklist
+
+Use this checklist to verify fixes:
+
+- [ ] All standard config variables present and correct
+- [ ] No unused yaml fields (bloat removed)
+- [ ] Config variables used appropriately in instructions
+- [ ] Web bundle includes all dependencies
+- [ ] Template variables properly mapped
+- [ ] File structure follows v6 conventions
+
+---
+
+## Next Steps
+
+1. Review critical issues and fix immediately
+2. Address important issues in next iteration
+3. Consider cleanup recommendations for optimization
+4. Re-run audit after fixes to verify improvements
+
+---
+
+**Audit Complete** - Generated by audit-workflow v1.0
--- a/src/modules/bmb/workflows/audit-workflow/workflow.yaml
+++ b/src/modules/bmb/workflows/audit-workflow/workflow.yaml
@@ -0,0 +1,25 @@
+# Audit Workflow Configuration
+name: "audit-workflow"
+description: "Comprehensive workflow quality audit - validates structure, config standards, variable usage, bloat detection, and web_bundle completeness. Performs deep analysis of workflow.yaml, instructions.md, template.md, and web_bundle configuration against BMAD v6 standards."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/{bmad_folder}/bmb/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Module path and component files
+installed_path: "{project-root}/{bmad_folder}/bmb/workflows/audit-workflow"
+template: "{installed_path}/template.md"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration
+default_output_file: "{output_folder}/audit-report-{{workflow_name}}-{{date}}.md"
+
+standalone: true
+
+# Web bundle configuration
+web_bundle: false # BMB workflows run locally in BMAD-METHOD project
--- a/src/modules/bmb/workflows/convert-legacy/README.md
+++ b/src/modules/bmb/workflows/convert-legacy/README.md
@@ -2,15 +2,15 @@

 ## Overview

-The Convert Legacy workflow is a comprehensive migration tool that converts BMAD v4 items (agents, workflows, modules) to v5 compliant format with proper structure and conventions. It bridges the gap between legacy BMAD implementations and the modern v5 architecture, ensuring seamless migration while preserving functionality and improving structure.
+The Convert Legacy workflow is a comprehensive migration tool that converts BMAD v4 items (agents, workflows, modules) to v6 compliant format with proper structure and conventions. It bridges the gap between legacy BMAD implementations and the modern v6 architecture, ensuring seamless migration while preserving functionality and improving structure.

 ## Key Features

 - **Multi-Format Detection** - Automatically identifies v4 agents, workflows, tasks, templates, and modules
- **Intelligent Conversion** - Smart mapping from v4 patterns to v5 equivalents with structural improvements
- **Sub-Workflow Integration** - Leverages build-agent, build-workflow, and build-module workflows for quality output
+- **Intelligent Conversion** - Smart mapping from v4 patterns to v6 equivalents with structural improvements
+- **Sub-Workflow Integration** - Leverages create-agent, create-workflow, and create-module workflows for quality output
 - **Structure Modernization** - Converts YAML-based agents to XML, templates to workflows, tasks to structured workflows
- **Path Normalization** - Updates all references to use proper v5 path conventions
+- **Path Normalization** - Updates all references to use proper v6 path conventions
 - **Validation System** - Comprehensive validation of converted items before finalization
 - **Migration Reporting** - Detailed conversion reports with locations and manual adjustment notes

@@ -42,7 +42,7 @@ The workflow uses standard BMB configuration:

 - **output_folder**: Where converted items will be placed
 - **user_name**: Author information for converted items
- **conversion_mappings**: v4-to-v5 pattern mappings (optional)
+- **conversion_mappings**: v4-to-v6 pattern mappings (optional)

 ## Workflow Structure

@@ -60,7 +60,7 @@ convert-legacy/

 ### Phase 1: Legacy Analysis (Steps 1-3)

-**Item Identification & Loading**
+**Item Identification and Loading**

 - Accepts file path or directory from user
 - Loads complete file/folder structure for analysis
@@ -82,23 +82,23 @@ convert-legacy/
 **Target Module Selection**

 - Prompts for target module (bmm, bmb, cis, custom)
- Determines proper installation paths using v5 conventions
+- Determines proper installation paths using v6 conventions
 - Shows target location for user confirmation
- Ensures all paths use `{project-root}/bmad/` format
+- Ensures all paths use `{project-root}/{bmad_folder}/` format

 ### Phase 2: Conversion Strategy (Step 4)

 **Strategy Selection Based on Item Type**

 - **Simple Agents**: Direct XML conversion with metadata mapping
- **Complex Agents**: Workflow-assisted creation using build-agent
+- **Complex Agents**: Workflow-assisted creation using create-agent
 - **Templates**: Template-to-workflow conversion with proper structure
 - **Tasks**: Task-to-workflow conversion with step mapping
- **Modules**: Full module creation using build-module workflow
+- **Modules**: Full module creation using create-module workflow

 **Workflow Type Determination**

- Analyzes legacy items to determine v5 workflow type:
+- Analyzes legacy items to determine v6 workflow type:
  - **Document Workflow**: Generates documents with templates
  - **Action Workflow**: Performs actions without output documents
  - **Interactive Workflow**: Guides user interaction sessions
@@ -108,25 +108,25 @@ convert-legacy/

 **Direct Agent Conversion (5a)**

- Transforms v4 YAML agent format to v5 XML structure
+- Transforms v4 YAML agent format to v6 XML structure
 - Maps persona blocks (role, style, identity, principles)
- Converts commands list to v5 `<cmds>` format
+- Converts commands list to v6 `<cmds>` format
 - Updates task references to workflow invocations
- Normalizes all paths to v5 conventions
+- Normalizes all paths to v6 conventions

 **Workflow-Assisted Creation (5b-5e)**

 - Extracts key information from legacy items
 - Invokes appropriate sub-workflows:
-  - `build-agent` for complex agent creation
-  - `build-workflow` for template/task conversion
-  - `build-module` for full module migration
- Ensures proper v5 structure and conventions
+  - `create-agent` for complex agent creation
+  - `create-workflow` for template/task conversion
+  - `create-module` for full module migration
+- Ensures proper v6 structure and conventions

 **Template-to-Workflow Conversion (5c)**

 - Converts YAML template sections to workflow steps
- Maps `elicit: true` flags to `<elicit-required/>` tags
+- Maps `elicit: true` flags to `<invoke-task halt="true">{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml</invoke-task>` tags
 - Transforms conditional sections to flow control
 - Creates proper template.md from content structure
 - Integrates v4 create-doc.md task patterns
@@ -136,10 +136,10 @@ convert-legacy/
 - Analyzes task purpose to determine workflow type
 - Extracts step-by-step instructions to workflow steps
 - Converts decision trees to flow control tags
- Maps 1-9 elicitation menus to v5 elicitation patterns
+- Maps 1-9 elicitation menus to v6 elicitation patterns
 - Preserves execution logic and critical notices

-### Phase 4: Validation & Finalization (Steps 6-8)
+### Phase 4: Validation and Finalization (Steps 6-8)

 **Comprehensive Validation**

@@ -155,7 +155,7 @@ convert-legacy/
 - Notes manual adjustments needed
 - Provides warnings and recommendations

-**Cleanup & Archival**
+**Cleanup and Archival**

 - Optional archival of original v4 files
 - Final location confirmation
@@ -165,13 +165,13 @@ convert-legacy/

 ### Generated Files

- **Converted Items**: Proper v5 format in target module locations
+- **Converted Items**: Proper v6 format in target module locations
 - **Migration Report**: Detailed conversion documentation
 - **Validation Results**: Quality assurance confirmation

 ### Output Structure

-Converted items follow v5 conventions:
+Converted items follow v6 conventions:

 1. **Agents** - XML format with proper persona and command structure
 2. **Workflows** - Complete workflow folders with yaml, instructions, and templates
@@ -182,8 +182,8 @@ Converted items follow v5 conventions:

 - **Legacy v4 Items** - Source files or directories to convert
 - **Target Module Access** - Write permissions to target module directories
- **Sub-Workflow Availability** - build-agent, build-workflow, build-module workflows accessible
- **Conversion Mappings** (optional) - v4-to-v5 pattern mappings for complex conversions
+- **Sub-Workflow Availability** - create-agent, create-workflow, create-module workflows accessible
+- **Conversion Mappings** (optional) - v4-to-v6 pattern mappings for complex conversions

 ## Best Practices

@@ -197,7 +197,7 @@ Converted items follow v5 conventions:

 1. **Validate Item Type Detection** - Confirm automatic detection or correct manually
 2. **Choose Appropriate Strategy** - Use workflow-assisted creation for complex items
-3. **Review Path Mappings** - Ensure all references use proper v5 path conventions
+3. **Review Path Mappings** - Ensure all references use proper v6 path conventions
 4. **Test Incrementally** - Convert simple items first to validate process

 ### After Completion
@@ -218,7 +218,7 @@ Converted items follow v5 conventions:

 **Issue**: Path conversion errors

- **Solution**: Ensure all references use `{project-root}/bmad/` format
+- **Solution**: Ensure all references use `{project-root}/{bmad_folder}/` format
 - **Check**: Review conversion mappings for proper path patterns

 **Issue**: Sub-workflow invocation fails
@@ -235,7 +235,7 @@ Converted items follow v5 conventions:

 To customize this workflow:

-1. **Update Conversion Mappings** - Modify v4-to-v5 pattern mappings in data/
+1. **Update Conversion Mappings** - Modify v4-to-v6 pattern mappings in data/
 2. **Extend Detection Logic** - Add new item type detection patterns
 3. **Add Conversion Strategies** - Implement specialized conversion approaches
 4. **Enhance Validation** - Add additional quality checks in validation step
@@ -244,7 +244,7 @@ To customize this workflow:

 - **v1.0.0** - Initial release
  - Multi-format v4 item detection and conversion
-  - Integration with build-agent, build-workflow, build-module
+  - Integration with create-agent, create-workflow, create-module
  - Comprehensive path normalization
  - Migration reporting and validation

@@ -252,11 +252,11 @@ To customize this workflow:

 For issues or questions:

- Review the workflow creation guide at `/bmad/bmb/workflows/build-workflow/workflow-creation-guide.md`
- Check conversion mappings at `/bmad/bmb/data/v4-to-v5-mappings.yaml`
+- Review the workflow creation guide at `/{bmad_folder}/bmb/workflows/create-workflow/workflow-creation-guide.md`
+- Check conversion mappings at `/{bmad_folder}/bmb/data/v4-to-v6-mappings.yaml`
 - Validate output using `checklist.md`
- Consult BMAD v5 documentation for proper conventions
+- Consult BMAD v6 documentation for proper conventions

 ---

-_Part of the BMad Method v5 - BMB (Builder) Module_
+_Part of the BMad Method v6 - BMB (Builder) Module_
--- a/src/modules/bmb/workflows/convert-legacy/checklist.md
+++ b/src/modules/bmb/workflows/convert-legacy/checklist.md
@@ -16,19 +16,20 @@
 #### Content Preservation

 - [ ] Agent name, id, title, and icon transferred
- [ ] All persona elements mapped to v5 structure
- [ ] All commands converted to v5 <cmds> format
+- [ ] All persona elements mapped to v6 structure
+- [ ] All commands converted to v6 menu array (YAML)
 - [ ] Dependencies properly referenced or converted
- [ ] Activation instructions adapted to v5 patterns
+- [ ] Activation instructions adapted to v6 patterns

-#### v5 Compliance
+#### v6 Compliance (YAML Format)

- [ ] Valid XML structure with proper nesting
- [ ] <agent> tag has all required attributes (id, name, title, icon)
- [ ] NO <activation> section included (auto-inserted from agent-activation-ide.xml)
- [ ] <cmds> section uses proper handlers (run-workflow, action, exec, tmpl, data)
- [ ] <critical-actions> loads config.yaml when needed
- [ ] Persona sections (<role>, <identity>, <communication_style>, <principles>) are present
+- [ ] Valid YAML structure with proper indentation
+- [ ] agent.metadata has all required fields (id, name, title, icon, module)
+- [ ] agent.persona has all sections (role, identity, communication_style, principles)
+- [ ] agent.menu uses proper handlers (workflow, action, exec, tmpl, data)
+- [ ] agent.critical_actions array present when needed
+- [ ] agent.prompts defined for any action: "#id" references
+- [ ] File extension is .agent.yaml (will be compiled to .md later)

 #### Best Practices

@@ -36,7 +37,7 @@
 - [ ] File paths use {project-root} variables
 - [ ] Config values use {config_source}: pattern
 - [ ] Agent follows naming conventions (kebab-case for files)
- [ ] ALL paths reference {project-root}/bmad/{{module}}/ locations, NOT src/
+- [ ] ALL paths reference {project-root}/{bmad_folder}/{{module}}/ locations, NOT src/
 - [ ] exec, data, run-workflow commands point to final BMAD installation paths

 ### For Template/Workflow Conversions
@@ -47,18 +48,18 @@
 - [ ] All sections converted to workflow steps
 - [ ] Section hierarchy maintained in instructions
 - [ ] Variables ({{var}}) preserved in template.md
- [ ] Elicitation points (elicit: true) converted to <elicit-required/>
+- [ ] Elicitation points (elicit: true) converted to <invoke-task halt="true">{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml</invoke-task>
 - [ ] Conditional sections preserved with if="" attributes
 - [ ] Repeatable sections converted to repeat="" attributes

-#### v5 Compliance
+#### v6 Compliance

 - [ ] workflow.yaml follows structure from workflow-creation-guide.md
 - [ ] instructions.md has critical headers referencing workflow engine
 - [ ] Steps numbered sequentially with clear goals
 - [ ] Template variables match between instructions and template.md
 - [ ] Proper use of XML tags (<action>, <check>, <ask>, <template-output>)
- [ ] File structure follows v5 pattern (folder with yaml/md files)
+- [ ] File structure follows v6 pattern (folder with yaml/md files)

 #### Best Practices

@@ -87,21 +88,21 @@
 - [ ] If performs actions only, marked as action workflow
 - [ ] Output patterns properly analyzed

-#### v5 Compliance
+#### v6 Compliance

 - [ ] Converted to proper workflow format (not standalone task)
 - [ ] Follows workflow execution engine patterns
- [ ] Interactive elements use proper v5 tags
- [ ] Flow control uses v5 patterns (goto, check, loop)
- [ ] 1-9 elicitation menus converted to v5 elicitation
+- [ ] Interactive elements use proper v6 tags
+- [ ] Flow control uses v6 patterns (goto, check, loop)
+- [ ] 1-9 elicitation menus converted to v6 elicitation
 - [ ] Critical notices preserved in workflow.yaml
- [ ] YOLO mode converted to appropriate v5 patterns
+- [ ] YOLO mode converted to appropriate v6 patterns

 ### Module-Level Validation

 #### Structure

- [ ] Module follows v5 directory structure
+- [ ] Module follows v6 directory structure
 - [ ] All components in correct locations:
  - Agents in /agents/
  - Workflows in /workflows/
@@ -169,7 +170,7 @@

 ### Quality Assurance

- [ ] Converted item follows ALL v5 best practices
+- [ ] Converted item follows ALL v6 best practices
 - [ ] Code/config is clean and maintainable
 - [ ] No TODO or FIXME items remain
 - [ ] Ready for production use
--- a/src/modules/bmb/workflows/convert-legacy/instructions.md
+++ b/src/modules/bmb/workflows/convert-legacy/instructions.md
@@ -1,7 +1,8 @@
-# Convert Legacy - v4 to v5 Conversion Instructions
+# Convert Legacy - v4 to v6 Conversion Instructions

-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
-<critical>You MUST have already loaded and processed: {project_root}/bmad/bmb/workflows/convert-legacy/workflow.yaml</critical>
+<critical>The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml</critical>
+<parameter name="You MUST have already loaded and processed: {project-root}/{bmad_folder}/bmb/workflows/convert-legacy/workflow.yaml</critical>
+<critical>Communicate in {communication_language} throughout the conversion process</critical>

 <workflow>

@@ -9,10 +10,10 @@
 <action>Ask user for the path to the v4 item to convert (agent, workflow, or module)</action>
 <action>Load the complete file/folder structure</action>
 <action>Detect item type based on structure and content patterns:</action>
-  - Agent: Contains `<agent>` or `<prompt>` XML tags, single file
+  - Agent: Contains agent or prompt XML tags, single file
  - Workflow: Contains workflow YAML or instruction patterns, usually folder
  - Module: Contains multiple agents/workflows in organized structure
-  - Task: Contains `<task>` XML tags
+  - Task: Contains task XML tags
 <ask>Confirm detected type or allow user to correct: "Detected as [type]. Is this correct? (y/n)"</ask>
 </step>

@@ -55,39 +56,41 @@ For Modules:
 - Installation requirements

 <action>Create a conversion map of what needs to be transformed</action>
-<action>Map v4 patterns to v5 equivalents:
+<action>Map v4 patterns to v6 equivalents:

- v4 Task + Template → v5 Workflow (folder with workflow.yaml, instructions.md, template.md)
- v4 Agent YAML → v5 Agent XML format
- v4 Commands → v5 <cmds> with proper handlers
- v4 Dependencies → v5 workflow references or data files
+- v4 Task + Template → v6 Workflow (folder with workflow.yaml, instructions.md, template.md)
+- v4 Agent YAML → v6 Agent YAML format
+- v4 Commands → v6 <menu> with proper handlers
+- v4 Dependencies → v6 workflow references or data files
  </action>
  </step>

 <step n="3" goal="Determine Target Module and Location">
 <ask>Which module should this belong to? (eg. bmm, bmb, cis, bmm-legacy, or custom)</ask>
-<check>If custom module:</check>
-  <ask>Enter custom module code (kebab-case):</ask>
+<action if="custom module"><ask>Enter custom module code (kebab-case):</ask></action>
 <action>Determine installation path based on type and module</action>
 <critical>IMPORTANT: All paths must use final BMAD installation locations, not src paths!</critical>
-<action>Show user the target location: {project-root}/bmad/{{target_module}}/{{item_type}}/{{item_name}}</action>
-<action>Note: Files will be created in bmad/ but all internal paths will reference {project-root}/bmad/ locations</action>
+<action>Show user the target location: {project-root}/{bmad_folder}/{{target_module}}/{{item_type}}/{{item_name}}</action>
+<action>Note: Files will be created in {bmad_folder}/ but all internal paths will reference {project-root}/{bmad_folder}/ locations</action>
 <ask>Proceed with this location? (y/n)</ask>
 </step>

 <step n="4" goal="Choose Conversion Strategy">
 <action>Based on item type and complexity, choose approach:</action>

-<check>If agent conversion:</check>
-<check>If simple agent (basic persona + commands):</check>
-<action>Use direct conversion to v5 agent XML format</action>
-<goto step="5a">Direct Agent Conversion</goto>
-<check>If complex agent with embedded workflows:</check>
-<action>Plan to invoke create-agent workflow</action>
-<goto step="5b">Workflow-Assisted Agent Creation</goto>
+<check if="agent conversion">
+  <check if="simple agent (basic persona + commands)">
+    <action>Use direct conversion to v6 agent YAML format</action>
+    <goto step="5a">Direct Agent Conversion</goto>
+  </check>
+  <check if="complex agent with embedded workflows">
+    <action>Plan to invoke create-agent workflow</action>
+    <goto step="5b">Workflow-Assisted Agent Creation</goto>
+  </check>
+</check>

-<check>If template or task conversion to workflow:</check>
-<action>Analyze the v4 item to determine workflow type:</action>
+<check if="template or task conversion to workflow">
+  <action>Analyze the v4 item to determine workflow type:</action>

 - Does it generate a specific document type? → Document workflow
 - Does it produce structured output files? → Document workflow
@@ -103,56 +106,61 @@ For Modules:
 4. Meta-workflow (coordinates other workflows)
   Select 1-4:</ask>

-<check>If template conversion:</check>
-<goto step="5c">Template-to-Workflow Conversion</goto>
-<check>If task conversion:</check>
-<goto step="5e">Task-to-Workflow Conversion</goto>
+<action if="template conversion"><goto step="5c">Template-to-Workflow Conversion</goto></action>
+<action if="task conversion"><goto step="5e">Task-to-Workflow Conversion</goto></action>
+</check>

-<check>If full module conversion:</check>
-<action>Plan to invoke create-module workflow</action>
-<goto step="5d">Module Creation</goto>
+<check if="full module conversion">
+  <action>Plan to invoke create-module workflow</action>
+  <goto step="5d">Module Creation</goto>
+</check>
 </step>

 <step n="5a" goal="Direct Agent Conversion" optional="true">
-<action>Transform v4 YAML agent to v5 XML format:</action>
+<action>Transform v4 YAML agent to v6 YAML format:</action>

-1. Convert agent metadata:
-   - v4 `agent.name` → v5 `<agent name="">`
-   - v4 `agent.id` → v5 `<agent id="">`
-   - v4 `agent.title` → v5 `<agent title="">`
-   - v4 `agent.icon` → v5 `<agent icon="">`
+1. Convert agent metadata structure:
+   - v4 `agent.name` → v6 `agent.metadata.name`
+   - v4 `agent.id` → v6 `agent.metadata.id`
+   - v4 `agent.title` → v6 `agent.metadata.title`
+   - v4 `agent.icon` → v6 `agent.metadata.icon`
+   - Add v6 `agent.metadata.module` field

-2. Transform persona:
-   - v4 `persona.role` → v5 `<role>`
-   - v4 `persona.style` → v5 `<communication_style>`
-   - v4 `persona.identity` → v5 `<identity>`
-   - v4 `persona.core_principles` → v5 `<principles>`
+2. Transform persona structure:
+   - v4 `persona.role` → v6 `agent.persona.role` (keep as YAML string)
+   - v4 `persona.style` → v6 `agent.persona.communication_style`
+   - v4 `persona.identity` → v6 `agent.persona.identity`
+   - v4 `persona.core_principles` → v6 `agent.persona.principles` (as array)

-3. Convert commands:
-   - v4 YAML commands list → v5 `<cmds>` with `<c cmd="">` entries
-   - Map task references to `run-workflow` handlers
+3. Convert commands to menu:
+   - v4 `commands:` list → v6 `agent.menu:` array
+   - Each command becomes menu item with:
+     - `trigger:` (without \* prefix - added at build)
+     - `description:`
+     - Handler attributes (`workflow:`, `exec:`, `action:`, etc.)
+   - Map task references to workflow paths
   - Map template references to workflow invocations

-4. Add v5-specific sections:
-   - DO NOT include `<activation>` block (inserted automatically from agent-activation-ide.xml)
-   - Add `<critical-actions>` for config loading and startup requirements
-   - Structure proper XML hierarchy with agent attributes and persona
+4. Add v6-specific sections (in YAML):
+   - `agent.prompts:` array for inline prompts (if using action: "#id")
+   - `agent.critical_actions:` array for startup requirements
+   - `agent.activation_rules:` for universal agent rules

 5. Handle dependencies and paths:
   - Convert task dependencies to workflow references
-   - Map template dependencies to v5 workflows
+   - Map template dependencies to v6 workflows
   - Preserve checklist and data file references
-   - CRITICAL: All exec/data/run-workflow paths must use {project-root}/bmad/{{module}}/ NOT src/
+   - CRITICAL: All paths must use {project-root}/{bmad_folder}/{{module}}/ NOT src/

-<action>Generate the converted v5 agent file with proper XML structure</action>
+<action>Generate the converted v6 agent YAML file (.agent.yaml)</action>
 <action>Example path conversions:

- exec="{project-root}/bmad/{{target_module}}/tasks/task-name.md"
- run-workflow="{project-root}/bmad/{{target_module}}/workflows/workflow-name/workflow.yaml"
- data="{project-root}/bmad/{{target_module}}/data/data-file.yaml"
+- exec="{project-root}/{bmad_folder}/{{target_module}}/tasks/task-name.md"
+- run-workflow="{project-root}/{bmad_folder}/{{target_module}}/workflows/workflow-name/workflow.yaml"
+- data="{project-root}/{bmad_folder}/{{target_module}}/data/data-file.yaml"
  </action>
-  <action>Save to: bmad/{{target_module}}/agents/{{agent_name}}.md (physical location)</action>
-  <action>But agent will reference: {project-root}/bmad/{{target_module}}/agents/{{agent_name}}.md</action>
+  <action>Save to: {bmad_folder}/{{target_module}}/agents/{{agent_name}}.agent.yaml (physical location)</action>
+  <action>Note: The build process will later compile this to .md with XML format</action>
  <goto step="6">Continue to Validation</goto>
  </step>

@@ -164,7 +172,7 @@ For Modules:
 - Any special behaviors

 <invoke-workflow>
-  workflow: {project-root}/bmad/bmb/workflows/build-agent/workflow.yaml
+  workflow: {project-root}/{bmad_folder}/bmb/workflows/create-agent/workflow.yaml
  inputs:
    - agent_name: {{extracted_name}}
    - agent_purpose: {{extracted_purpose}}
@@ -176,7 +184,7 @@ For Modules:
 </step>

 <step n="5c" goal="Template-to-Workflow Conversion" optional="true">
-<action>Convert v4 Template (YAML) to v5 Workflow:</action>
+<action>Convert v4 Template (YAML) to v6 Workflow:</action>

 1. Extract template metadata:
   - Template id, name, version → workflow.yaml name/description
@@ -185,7 +193,7 @@ For Modules:

 2. Convert template sections to instructions.md:
   - Each YAML section → workflow step
-   - `elicit: true` → `<elicit-required/>` tag
+   - `elicit: true` → `<invoke-task halt="true">{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml</invoke-task>` tag
   - Conditional sections → `if="condition"` attribute
   - Repeatable sections → `repeat="for-each"` attribute
   - Section instructions → step content
@@ -196,12 +204,23 @@ For Modules:
   - Nested sections → hierarchical markdown

 4. Handle v4 create-doc.md task integration:
-   - Elicitation methods (1-9 menu) → convert to v5 elicitation
+   - Elicitation methods (1-9 menu) → convert to v6 elicitation
   - Agent permissions → note in instructions
   - Processing flow → integrate into workflow steps

+<critical>When invoking create-workflow, the standard config block will be automatically added:</critical>
+
+```yaml
+# Critical variables from config
+config_source: '{project-root}/{bmad_folder}/{{target_module}}/config.yaml'
+output_folder: '{config_source}:output_folder'
+user_name: '{config_source}:user_name'
+communication_language: '{config_source}:communication_language'
+date: system-generated
+```
+
 <invoke-workflow>
-  workflow: {project-root}/bmad/bmb/workflows/build-workflow/workflow.yaml
+  workflow: {project-root}/{bmad_folder}/bmb/workflows/create-workflow/workflow.yaml
  inputs:
    - workflow_name: {{template_name}}
    - workflow_type: document
@@ -209,6 +228,9 @@ For Modules:
    - instructions: {{converted_sections}}
 </invoke-workflow>

+<action>Verify the created workflow.yaml includes standard config block</action>
+<action>Update converted instructions to use config variables where appropriate</action>
+
 <goto step="6">Continue to Validation</goto>
 </step>

@@ -217,7 +239,7 @@ For Modules:
 <action>Create module blueprint with all components</action>

 <invoke-workflow>
-  workflow: {project-root}/bmad/bmb/workflows/build-module/workflow.yaml
+  workflow: {project-root}/{bmad_folder}/bmb/workflows/create-module/workflow.yaml
  inputs:
    - module_name: {{module_name}}
    - components: {{component_list}}
@@ -227,7 +249,7 @@ For Modules:
 </step>

 <step n="5e" goal="Task-to-Workflow Conversion" optional="true">
-<action>Convert v4 Task (Markdown) to v5 Workflow:</action>
+<action>Convert v4 Task (Markdown) to v6 Workflow:</action>

 1. Analyze task purpose and output:
   - Does it generate documents? → Create template.md
@@ -239,27 +261,40 @@ For Modules:
   - Execution notices and critical rules → workflow.yaml metadata
   - Step-by-step instructions → instructions.md steps
   - Decision trees and branching → flow control tags
-   - User interaction patterns → appropriate v5 tags
+   - User interaction patterns → appropriate v6 tags

 3. Based on confirmed workflow type:
-   <check>If Document workflow:</check>
+   <check if="Document workflow">
   - Create template.md from output patterns
   - Map generation steps to instructions
-   - Add <template-output> tags for sections
+   - Add template-output tags for sections
+     </check>

-   <check>If Action workflow:</check>
-   - Set template: false in workflow.yaml
-   - Focus on action sequences in instructions
-   - Preserve execution logic
+   <check if="Action workflow">
+     - Set template: false in workflow.yaml
+     - Focus on action sequences in instructions
+     - Preserve execution logic
+   </check>

 4. Handle special v4 patterns:
-   - 1-9 elicitation menus → v5 <elicit-required/>
+   - 1-9 elicitation menus → v6 <invoke-task halt="true">{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml</invoke-task>
   - Agent permissions → note in instructions
   - YOLO mode → autonomous flag or optional steps
   - Critical notices → workflow.yaml comments

+<critical>When invoking create-workflow, the standard config block will be automatically added:</critical>
+
+```yaml
+# Critical variables from config
+config_source: '{project-root}/{bmad_folder}/{{target_module}}/config.yaml'
+output_folder: '{config_source}:output_folder'
+user_name: '{config_source}:user_name'
+communication_language: '{config_source}:communication_language'
+date: system-generated
+```
+
 <invoke-workflow>
-  workflow: {project-root}/bmad/bmb/workflows/build-workflow/workflow.yaml
+  workflow: {project-root}/{bmad_folder}/bmb/workflows/create-workflow/workflow.yaml
  inputs:
    - workflow_name: {{task_name}}
    - workflow_type: {{confirmed_workflow_type}}
@@ -267,6 +302,9 @@ For Modules:
    - template: {{generated_template_if_document}}
 </invoke-workflow>

+<action>Verify the created workflow.yaml includes standard config block</action>
+<action>Update converted instructions to use config variables where appropriate</action>
+
 <goto step="6">Continue to Validation</goto>
 </step>

@@ -275,18 +313,29 @@ For Modules:

 For Agents:

- [ ] Valid XML structure
- [ ] All required sections present
- [ ] Commands properly formatted
- [ ] Activation sequence correct
+- [ ] Valid YAML structure (.agent.yaml)
+- [ ] All required sections present (metadata, persona, menu)
+- [ ] Menu items properly formatted (trigger, description, handlers)
+- [ ] Paths use {project-root} variables

 For Workflows:

 - [ ] Valid YAML syntax
- [ ] Instructions follow v5 conventions
+- [ ] Instructions follow v6 conventions
 - [ ] Template variables match
 - [ ] File structure correct

+**Standard Config Validation (Workflows):**
+
+- [ ] workflow.yaml contains standard config block:
+  - config_source defined
+  - output_folder, user_name, communication_language pulled from config
+  - date set to system-generated
+- [ ] Converted instructions use config variables where appropriate
+- [ ] Template includes config variables in metadata (if document workflow)
+- [ ] No hardcoded paths that should use {output_folder}
+- [ ] No generic greetings that should use {user_name}
+
 For Modules:

 - [ ] All components converted
@@ -296,33 +345,33 @@ For Modules:

 <action>Show validation results to user</action>
 <ask>Any issues to fix before finalizing? (y/n)</ask>
-<check>If yes:</check>
+<check if="yes">
 <action>Address specific issues</action>
 <goto step="6">Re-validate</goto>
+</check>
 </step>

 <step n="7" goal="Migration Report">
 <action>Generate conversion report showing:</action>
 - Original v4 location
- New v5 location
+- New v6 location
 - Items converted
 - Any manual adjustments needed
 - Warnings or notes

 <action>Save report to: {output_folder}/conversion-report-{{date}}.md</action>
+<action>Inform {user_name} in {communication_language} that the conversion report has been generated</action>
 </step>

 <step n="8" goal="Cleanup and Finalize">
 <ask>Archive original v4 files? (y/n)</ask>
-<check>If yes:</check>
-  <action>Move v4 files to: {project-root}/archive/v4-legacy/{{date}}/</action>
+<action if="yes">Move v4 files to: {project-root}/archive/v4-legacy/{{date}}/</action>

 <action>Show user the final converted items and their locations</action>
 <action>Provide any post-conversion instructions or recommendations</action>

 <ask>Would you like to convert another legacy item? (y/n)</ask>
-<check>If yes:</check>
-<goto step="1">Start new conversion</goto>
+<action if="yes"><goto step="1">Start new conversion</goto></action>
 </step>

 </workflow>
--- a/src/modules/bmb/workflows/convert-legacy/workflow.yaml
+++ b/src/modules/bmb/workflows/convert-legacy/workflow.yaml
@@ -1,35 +1,30 @@
-# Convert Legacy - BMAD v4 to v5 Converter Configuration
+# Convert Legacy - BMAD v4 to v6 Converter Configuration
 name: "convert-legacy"
 description: "Converts legacy BMAD v4 or similar items (agents, workflows, modules) to BMad Core compliant format with proper structure and conventions"
 author: "BMad"

 # Critical variables load from config_source
-config_source: "{project-root}/bmad/bmb/config.yaml"
+config_source: "{project-root}/{bmad_folder}/bmb/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
-src_impact: "{config_source}:src_impact"
 communication_language: "{config_source}:communication_language"
 date: system-generated

-# Optional docs that can be provided as input
-recommended_inputs:
-  - legacy_file: "Path to v4 agent, workflow, or module to convert"
-  - conversion_mappings: "{project-root}/bmad/bmb/data/v4-to-v5-mappings.yaml"
-
 # Module path and component files
-installed_path: "{project-root}/bmad/bmb/workflows/convert-legacy"
+installed_path: "{project-root}/{bmad_folder}/bmb/workflows/convert-legacy"
 template: false # This is an action/meta workflow - no template needed
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"

 # Output configuration - Creates converted items in appropriate module locations
-default_output_folder: "{project-root}/bmad/{{target_module}}/{{item_type}}/{{item_name}}"
+default_output_folder: "{project-root}/{bmad_folder}/{{target_module}}/{{item_type}}/{{item_name}}"

 # Sub-workflows that may be invoked for conversion
 sub_workflows:
-  - create_agent: "{project-root}/bmad/bmb/workflows/build-agent/workflow.yaml"
-  - create_workflow: "{project-root}/bmad/bmb/workflows/build-workflow/workflow.yaml"
-  - create_module: "{project-root}/bmad/bmb/workflows/build-module/workflow.yaml"
+  - create_agent: "{project-root}/{bmad_folder}/bmb/workflows/create-agent/workflow.yaml"
+  - create_workflow: "{project-root}/{bmad_folder}/bmb/workflows/create-workflow/workflow.yaml"
+  - create_module: "{project-root}/{bmad_folder}/bmb/workflows/create-module/workflow.yaml"

-# No special tools required beyond standard BMAD capabilities
-required_tools: []
+standalone: true
+
+web_bundle: false
--- a/src/modules/bmb/workflows/create-agent/README.md
+++ b/src/modules/bmb/workflows/create-agent/README.md
@@ -1,268 +0,0 @@
-# Build Agent
-
-## Overview
-
-The Build Agent workflow is an interactive agent builder that guides you through creating BMAD Core compliant agents with proper persona, activation rules, and command structure. It supports three agent types: Simple (self-contained), Expert (with sidecar resources), and Module (full-featured with workflows).
-
-## Key Features
-
- **Optional Brainstorming**: Creative ideation session before agent building to explore concepts and personalities
- **Three Agent Types**: Simple, Expert, and Module agents with appropriate structures
- **Persona Development**: Guided creation of role, identity, communication style, and principles
- **Command Builder**: Interactive command definition with workflow/task/action patterns
- **Validation Built-In**: Ensures XML structure and BMAD Core compliance
- **Config File Support**: Optional agent config for persona overrides
- **Sidecar Resources**: Setup for Expert agents with domain-specific data
-
-## Usage
-
-### Basic Invocation
-
-```bash
-workflow build-agent
-```
-
-### Through BMad Builder Agent
-
-```
-*create-agent
-```
-
-### With Brainstorming Session
-
-The workflow includes an optional brainstorming phase (Step -1) that helps you explore agent concepts, personalities, and capabilities before building. This is particularly useful when you have a vague idea and want to develop it into a concrete agent concept.
-
-### What You'll Be Asked
-
-0. **Optional brainstorming** (vague idea → refined concept)
-1. Agent type (Simple, Expert, or Module)
-2. Basic identity (name, title, icon, filename)
-3. Module assignment (for Module agents)
-4. Sidecar resources (for Expert agents)
-5. Persona elements (role, identity, style, principles)
-6. Commands and their implementations
-7. Critical actions (optional)
-8. Activation rules (optional, rarely needed)
-
-## Workflow Structure
-
-### Files Included
-
-```
-build-agent/
-├── workflow.yaml                  # Configuration
-├── instructions.md                # Step-by-step guide
-├── checklist.md                   # Validation criteria
-├── README.md                      # This file
-├── agent-types.md                 # Agent type documentation
-├── agent-architecture.md          # Architecture patterns
-├── agent-command-patterns.md      # Command patterns reference
-└── communication-styles.md        # Style examples
-```
-
-## Workflow Process
-
-### Phase 0: Optional Brainstorming (Step -1)
-
- Creative ideation session using diverse brainstorming techniques
- Explore agent concepts, personalities, and capabilities
- Generate character ideas, expertise areas, and command concepts
- Output feeds directly into agent identity and persona development
-
-### Phase 1: Agent Setup (Steps 0-2)
-
- Load agent building documentation and patterns
- Choose agent type (Simple/Expert/Module)
- Define basic identity (name, title, icon, filename) - informed by brainstorming if completed
- Assign to module (for Module agents)
-
-### Phase 2: Persona Development (Steps 2-3)
-
- Define role and responsibilities - leveraging brainstorming insights if available
- Craft unique identity and backstory
- Select communication style - can use brainstormed personality concepts
- Establish guiding principles
- Add critical actions (optional)
-
-### Phase 3: Command Building (Step 4)
-
- Add *help and *exit commands (required)
- Define workflow commands (most common)
- Add task commands (for single operations)
- Create action commands (inline logic)
- Configure command attributes
-
-### Phase 4: Finalization (Steps 5-10)
-
- Add custom activation rules (optional, rarely needed)
- Generate complete agent.md file
- Create agent config file (optional)
- Setup sidecar resources (for Expert agents)
- Validate agent structure
- Provide usage instructions
-
-## Output
-
-### Generated Agent File
-
-Creates agent file at:
-`{output_folder}/agents/{{agent_filename}}.md`
-
-### Agent Structure
-
-```xml
-<!-- Powered by BMAD-CORE™ -->
-
-# {{agent_title}}
-
-<agent id="bmad/{{module}}/agents/{{agent_filename}}.md"
-       name="{{agent_name}}"
-       title="{{agent_title}}"
-       icon="{{agent_icon}}">
-  <persona>
-    <role>...</role>
-    <identity>...</identity>
-    <communication_style>...</communication_style>
-    <principles>...</principles>
-  </persona>
-  <cmds>
-    <c cmd="*help">...</c>
-    <c cmd="*exit">...</c>
-    <!-- Additional commands -->
-  </cmds>
-</agent>
-```
-
-### Optional Config File
-
-If created, generates at:
-`{project-root}/bmad/_cfg/agents/{{agent_config_name}}.md`
-
-## Requirements
-
- BMAD Core v6 project structure
- Module to host the agent (for Module agents)
- Understanding of agent purpose and commands
- Workflows/tasks to reference in commands (or mark as "todo")
-
-## Brainstorming Integration
-
-The optional brainstorming phase (Step -1) provides a seamless path from vague idea to concrete agent concept:
-
-### When to Use Brainstorming
-
- **Vague concept**: "I want an agent that helps with data stuff"
- **Creative exploration**: Want to discover unique personality and approach
- **Team building**: Creating agents for a module with specific roles
- **Character development**: Need to flesh out agent personality and voice
-
-### Brainstorming Flow
-
-1. **Step -1**: Optional brainstorming session
-   - Uses CIS brainstorming workflow with agent-specific context
-   - Explores identity, personality, expertise, and command concepts
-   - Generates detailed character and capability ideas
-
-2. **Steps 0-2**: Agent setup informed by brainstorming
-   - Brainstorming output guides agent type selection
-   - Character concepts inform basic identity choices
-   - Personality insights shape persona development
-
-3. **Seamless transition**: Vague idea → brainstormed concept → built agent
-
-### Key Principle
-
-Users can go from **vague idea → brainstormed concept → built agent** in one continuous flow, with brainstorming output directly feeding into agent development.
-
-## Best Practices
-
-### Before Starting
-
-1. Review example agents in `/bmad/bmm/agents/` for patterns
-2. Consider using brainstorming if you have a vague concept to develop
-3. Have a clear vision of the agent's role and personality (or use brainstorming to develop it)
-4. List the commands/capabilities the agent will need
-5. Identify any workflows or tasks the agent will invoke
-
-### During Execution
-
-1. **Agent Names**: Use memorable names that reflect personality
-2. **Icons**: Choose an emoji that represents the agent's role
-3. **Persona**: Make it distinct and consistent with communication style
-4. **Commands**: Use kebab-case, start custom commands with letter (not \*)
-5. **Workflows**: Reference existing workflows or mark as "todo" to implement later
-
-### After Completion
-
-1. Test the agent by loading it
-2. Verify all commands work as expected
-3. Implement any "todo" workflows
-4. Refine persona based on usage
-5. Add more commands as agent evolves
-
-## Agent Types
-
-### Simple Agent
-
- **Best For**: Self-contained utilities, simple assistants
- **Characteristics**: Embedded logic, no external dependencies
- **Example**: Calculator agent, random picker, simple formatter
-
-### Expert Agent
-
- **Best For**: Domain-specific agents with data/memory
- **Characteristics**: Sidecar folders, domain restrictions, memory files
- **Example**: Diary keeper, project journal, personal knowledge base
-
-### Module Agent
-
- **Best For**: Full-featured agents with workflows
- **Characteristics**: Part of module, commands invoke workflows
- **Example**: Product manager, architect, research assistant
-
-## Troubleshooting
-
-### Issue: Agent won't load
-
- **Solution**: Validate XML structure is correct
- **Check**: Ensure all required tags present (persona, cmds)
-
-### Issue: Commands don't work
-
- **Solution**: Verify workflow paths are correct or marked "todo"
- **Check**: Test workflow invocation separately first
-
-### Issue: Persona feels generic
-
- **Solution**: Review communication styles guide
- **Check**: Make identity unique and specific to role
-
-## Customization
-
-To modify agent building process:
-
-1. Edit `instructions.md` to change steps
-2. Update `agent-types.md` to add new agent patterns
-3. Modify `agent-command-patterns.md` for new command types
-4. Edit `communication-styles.md` to add personality examples
-
-## Version History
-
- **v6.0.0** - BMAD Core v6 compatible
-  - Three agent types (Simple/Expert/Module)
-  - Enhanced persona development
-  - Command pattern library
-  - Validation framework
-
-## Support
-
-For issues or questions:
-
- Review example agents in `/bmad/bmm/agents/`
- Check agent documentation in this workflow folder
- Test with simple agents first, then build complexity
- Consult BMAD Method v6 documentation
-
---
-
-_Part of the BMad Method v6 - BMB (BMad Builder) Module_
--- a/src/modules/bmb/workflows/create-agent/agent-architecture.md
+++ b/src/modules/bmb/workflows/create-agent/agent-architecture.md
@@ -1,412 +0,0 @@
-# BMAD Agent Architecture Reference
-
-_LLM-Optimized Technical Documentation for Agent Building_
-
-## Core Agent Structure
-
-### Minimal Valid Agent
-
-```xml
-<!-- Powered by BMAD-CORE™ -->
-
-# Agent Name
-
-<agent id="path/to/agent.md" name="Name" title="Title" icon="🤖">
-  <persona>
-    <role>Primary function</role>
-    <identity>Background and expertise</identity>
-    <communication_style>How they interact</communication_style>
-    <principles>Core beliefs and methodology</principles>
-  </persona>
-  <cmds>
-    <c cmd="*help">Show numbered cmd list</c>
-    <c cmd="*exit">Exit with confirmation</c>
-  </cmds>
-</agent>
-```
-
-## Agent XML Schema
-
-### Root Element: `<agent>`
-
-**Required Attributes:**
-
- `id` - Unique path identifier (e.g., "bmad/bmm/agents/analyst.md")
- `name` - Agent's name (e.g., "Mary", "John", "Helper")
- `title` - Professional title (e.g., "Business Analyst", "Security Engineer")
- `icon` - Single emoji representing the agent
-
-### Core Sections
-
-#### 1. Persona Section (REQUIRED)
-
-```xml
-<persona>
-  <role>1-2 lines: Professional title and primary expertise</role>
-  <identity>3-5 lines: Background, experience, specializations</identity>
-  <communication_style>3-5 lines: Interaction approach, tone, quirks</communication_style>
-  <principles>5-8 lines: Core beliefs, methodology, philosophy</principles>
-</persona>
-```
-
-**Best Practices:**
-
- Role: Be specific about expertise area
- Identity: Include experience indicators (years, depth)
- Communication: Describe HOW they interact, not just tone and quirks
- Principles: Start with "I believe" or "I operate" for first-person voice
-
-#### 2. Critical Actions Section
-
-```xml
-<critical-actions>
-  <i>Load into memory {project-root}/bmad/{module}/config.yaml and set variables</i>
-  <i>Remember the users name is {user_name}</i>
-  <i>ALWAYS communicate in {communication_language}</i>
-  <!-- Custom initialization actions -->
-</critical-actions>
-```
-
-**For Expert Agents with Sidecars (CRITICAL):**
-
-```xml
-<critical-actions>
-  <!-- CRITICAL: Load sidecar files FIRST -->
-  <i critical="MANDATORY">Load COMPLETE file {agent-folder}/instructions.md and follow ALL directives</i>
-  <i critical="MANDATORY">Load COMPLETE file {agent-folder}/memories.md into permanent context</i>
-  <i critical="MANDATORY">You MUST follow all rules in instructions.md on EVERY interaction</i>
-
-  <!-- Standard initialization -->
-  <i>Load into memory {project-root}/bmad/{module}/config.yaml and set variables</i>
-  <i>Remember the users name is {user_name}</i>
-  <i>ALWAYS communicate in {communication_language}</i>
-
-  <!-- Domain restrictions -->
-  <i>ONLY read/write files in {user-folder}/diary/ - NO OTHER FOLDERS</i>
-</critical-actions>
-```
-
-**Common Patterns:**
-
- Config loading for module agents
- User context initialization
- Language preferences
- **Sidecar file loading (Expert agents) - MUST be explicit and CRITICAL**
- **Domain restrictions (Expert agents) - MUST be enforced**
-
-#### 3. Commands Section (REQUIRED)
-
-```xml
-<cmds>
-  <c cmd="*trigger" [attributes]>Description</c>
-</cmds>
-```
-
-**Command Attributes:**
-
- `run-workflow="{path}"` - Executes a workflow
- `exec="{path}"` - Executes a task
- `tmpl="{path}"` - Template reference
- `data="{path}"` - Data file reference
-
-**Required Commands:**
-
- `*help` - Always first, shows command list
- `*exit` - Always last, exits agent
-
-## Advanced Agent Patterns
-
-### Activation Rules (OPTIONAL)
-
-```xml
-<activation critical="true">
-  <initialization critical="true" sequential="MANDATORY">
-    <step n="1">Load configuration</step>
-    <step n="2">Apply overrides</step>
-    <step n="3">Execute critical actions</step>
-    <step n="4" critical="BLOCKING">Show greeting with menu</step>
-    <step n="5" critical="BLOCKING">AWAIT user input</step>
-  </initialization>
-  <command-resolution critical="true">
-    <rule>Numeric input → Execute command at cmd_map[n]</rule>
-    <rule>Text input → Fuzzy match against commands</rule>
-  </command-resolution>
-</activation>
-```
-
-### Expert Agent Sidecar Pattern
-
-```xml
-<!-- DO NOT use sidecar-resources tag - Instead use critical-actions -->
-<!-- Sidecar files MUST be loaded explicitly in critical-actions -->
-
-<!-- Example Expert Agent with Diary domain -->
-<agent id="diary-keeper" name="Personal Assistant" title="Diary Keeper" icon="📔">
-  <critical-actions>
-    <!-- MANDATORY: Load all sidecar files -->
-    <i critical="MANDATORY">Load COMPLETE file {agent-folder}/diary-rules.md</i>
-    <i critical="MANDATORY">Load COMPLETE file {agent-folder}/user-memories.md</i>
-    <i critical="MANDATORY">Follow ALL rules from diary-rules.md</i>
-
-    <!-- Domain restriction -->
-    <i critical="MANDATORY">ONLY access files in {user-folder}/diary/</i>
-    <i critical="MANDATORY">NEVER access files outside diary folder</i>
-  </critical-actions>
-
-  <persona>...</persona>
-  <cmds>...</cmds>
-</agent>
-```
-
-### Module Agent Integration
-
-```xml
-<module-integration>
-  <module-path>{project-root}/bmad/{module-code}</module-path>
-  <config-source>{module-path}/config.yaml</config-source>
-  <workflows-path>{project-root}/bmad/{module-code}/workflows</workflows-path>
-</module-integration>
-```
-
-## Variable System
-
-### System Variables
-
- `{project-root}` - Root directory of project
- `{user_name}` - User's name from config
- `{communication_language}` - Language preference
- `{date}` - Current date
- `{module}` - Current module code
-
-### Config Variables
-
-Format: `{config_source}:variable_name`
-Example: `{config_source}:output_folder`
-
-### Path Construction
-
-```
-Good: {project-root}/bmad/{module}/agents/
-Bad:  /absolute/path/to/agents/
-Bad:  ../../../relative/paths/
-```
-
-## Command Patterns
-
-### Workflow Commands
-
-```xml
-<!-- Full path -->
-<c cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
-  Create Product Requirements Document
-</c>
-
-<!-- Placeholder for future -->
-<c cmd="*analyze" run-workflow="todo">
-  Perform analysis (workflow to be created)
-</c>
-```
-
-### Task Commands
-
-```xml
-<c cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.md">
-  Validate document
-</c>
-```
-
-### Template Commands
-
-```xml
-<c cmd="*brief"
-   exec="{project-root}/bmad/core/tasks/create-doc.md"
-   tmpl="{project-root}/bmad/bmm/templates/brief.md">
-  Create project brief
-</c>
-```
-
-### Data-Driven Commands
-
-```xml
-<c cmd="*standup"
-   exec="{project-root}/bmad/bmm/tasks/daily-standup.md"
-   data="{project-root}/bmad/_cfg/agent-party.xml">
-  Run daily standup
-</c>
-```
-
-## Agent Type Specific Patterns
-
-### Simple Agent
-
- Self-contained logic
- Minimal or no external dependencies
- May have embedded functions
- Good for utilities and converters
-
-### Expert Agent
-
- Domain-specific with sidecar resources
- Restricted access patterns
- Memory/context files
- Good for specialized domains
-
-### Module Agent
-
- Full integration with module
- Multiple workflows and tasks
- Config-driven behavior
- Good for professional tools
-
-## Common Anti-Patterns to Avoid
-
-### ❌ Bad Practices
-
-```xml
-<!-- Missing required persona elements -->
-<persona>
-  <role>Helper</role>
-  <!-- Missing identity, style, principles -->
-</persona>
-
-<!-- Hard-coded paths -->
-<c cmd="*run" exec="/Users/john/project/task.md">
-
-<!-- No help command -->
-<cmds>
-  <c cmd="*do-something">Action</c>
-  <!-- Missing *help -->
-</cmds>
-
-<!-- Duplicate command triggers -->
-<c cmd="*analyze">First</c>
-<c cmd="*analyze">Second</c>
-```
-
-### ✅ Good Practices
-
-```xml
-<!-- Complete persona -->
-<persona>
-  <role>Data Analysis Expert</role>
-  <identity>Senior analyst with 10+ years...</identity>
-  <communication_style>Analytical and precise...</communication_style>
-  <principles>I believe in data-driven...</principles>
-</persona>
-
-<!-- Variable-based paths -->
-<c cmd="*run" exec="{project-root}/bmad/module/task.md">
-
-<!-- Required commands present -->
-<cmds>
-  <c cmd="*help">Show commands</c>
-  <c cmd="*analyze">Perform analysis</c>
-  <c cmd="*exit">Exit</c>
-</cmds>
-```
-
-## Agent Lifecycle
-
-### 1. Initialization
-
-1. Load agent file
-2. Parse XML structure
-3. Load critical-actions
-4. Apply config overrides
-5. Present greeting
-
-### 2. Command Loop
-
-1. Show numbered menu
-2. Await user input
-3. Resolve command
-4. Execute action
-5. Return to menu
-
-### 3. Termination
-
-1. User enters \*exit
-2. Cleanup if needed
-3. Exit persona
-
-## Testing Checklist
-
-Before deploying an agent:
-
- [ ] Valid XML structure
- [ ] All persona elements present
- [ ] *help and *exit commands exist
- [ ] All paths use variables
- [ ] No duplicate commands
- [ ] Config loading works
- [ ] Commands execute properly
-
-## LLM Building Tips
-
-When building agents:
-
-1. Start with agent type (Simple/Expert/Module)
-2. Define complete persona first
-3. Add standard critical-actions
-4. Include *help and *exit
-5. Add domain commands
-6. Test command execution
-7. Validate with checklist
-
-## Integration Points
-
-### With Workflows
-
- Agents invoke workflows via run-workflow
- Workflows can be incomplete (marked "todo")
- Workflow paths must be valid or "todo"
-
-### With Tasks
-
- Tasks are single operations
- Executed via exec attribute
- Can include data files
-
-### With Templates
-
- Templates define document structure
- Used with create-doc task
- Variables passed through
-
-## Quick Reference
-
-### Minimal Commands
-
-```xml
-<cmds>
-  <c cmd="*help">Show numbered cmd list</c>
-  <c cmd="*exit">Exit with confirmation</c>
-</cmds>
-```
-
-### Standard Critical Actions
-
-```xml
-<critical-actions>
-  <i>Load into memory {project-root}/bmad/{module}/config.yaml</i>
-  <i>Remember the users name is {user_name}</i>
-  <i>ALWAYS communicate in {communication_language}</i>
-</critical-actions>
-```
-
-### Module Agent Pattern
-
-```xml
-<agent id="bmad/{module}/agents/{name}.md"
-       name="{Name}"
-       title="{Title}"
-       icon="{emoji}">
-  <persona>...</persona>
-  <critical-actions>...</critical-actions>
-  <cmds>
-    <c cmd="*help">...</c>
-    <c cmd="*{command}" run-workflow="{path}">...</c>
-    <c cmd="*exit">...</c>
-  </cmds>
-</agent>
-```
--- a/src/modules/bmb/workflows/create-agent/agent-command-patterns.md
+++ b/src/modules/bmb/workflows/create-agent/agent-command-patterns.md
@@ -1,757 +0,0 @@
-# BMAD Agent Command Patterns Reference
-
-_LLM-Optimized Guide for Command Design_
-
-## Important: How to Process Action References
-
-When executing agent commands, understand these reference patterns:
-
-```xml
-<!-- Pattern 1: Inline action -->
-<c cmd="*example" action="do this specific thing">
-→ Execute the text "do this specific thing" directly
-
-<!-- Pattern 2: Internal reference with # prefix -->
-<c cmd="*example" action="#prompt-id">
-→ Find <prompt id="prompt-id"> in the current agent and execute its content
-
-<!-- Pattern 3: External file reference -->
-<c cmd="*example" exec="{project-root}/path/to/file.md">
-→ Load and execute the external file
-```
-
-**The `#` prefix is your signal that this is an internal XML node reference, not a file path.**
-
-## Command Anatomy
-
-### Basic Structure
-
-```xml
-<c cmd="*trigger" [attributes]>Description</c>
-```
-
-**Components:**
-
- `cmd` - The trigger word (always starts with \*)
- `attributes` - Action directives (optional):
-  - `run-workflow` - Path to workflow YAML
-  - `exec` - Path to task/operation
-  - `tmpl` - Path to template (used with exec)
-  - `action` - Embedded prompt/instruction
-  - `data` - Path to supplementary data (universal)
- `Description` - What shows in menu
-
-## Command Types
-
-**Quick Reference:**
-
-1. **Workflow Commands** - Execute multi-step workflows (`run-workflow`)
-2. **Task Commands** - Execute single operations (`exec`)
-3. **Template Commands** - Generate from templates (`exec` + `tmpl`)
-4. **Meta Commands** - Agent control (no attributes)
-5. **Action Commands** - Embedded prompts (`action`)
-6. **Embedded Commands** - Logic in persona (no attributes)
-
-**Universal Attributes:**
-
- `data` - Can be added to ANY command type for supplementary info
- `if` - Conditional execution (advanced pattern)
- `params` - Runtime parameters (advanced pattern)
-
-### 1. Workflow Commands
-
-Execute complete multi-step processes
-
-```xml
-<!-- Standard workflow -->
-<c cmd="*create-prd"
-   run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
-  Create Product Requirements Document
-</c>
-
-<!-- Workflow with validation -->
-<c cmd="*validate-prd"
-   validate-workflow="{output_folder}/prd-draft.md"
-   workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
-  Validate PRD Against Checklist
-</c>
-
-<!-- Auto-discover validation workflow from document -->
-<c cmd="*validate-doc"
-   validate-workflow="{output_folder}/document.md">
-  Validate Document (auto-discover checklist)
-</c>
-
-<!-- Placeholder for future development -->
-<c cmd="*analyze-data"
-   run-workflow="todo">
-  Analyze dataset (workflow coming soon)
-</c>
-```
-
-**Workflow Attributes:**
-
- `run-workflow` - Execute a workflow to create documents
- `validate-workflow` - Validate an existing document against its checklist
- `workflow` - (optional with validate-workflow) Specify the workflow.yaml directly
-
-**Best Practices:**
-
- Use descriptive trigger names
- Always use variable paths
- Mark incomplete as "todo"
- Description should be clear action
- Include validation commands for workflows that produce documents
-
-### 2. Task Commands
-
-Execute single operations
-
-```xml
-<!-- Simple task -->
-<c cmd="*validate"
-   exec="{project-root}/bmad/core/tasks/validate-workflow.md">
-  Validate document against checklist
-</c>
-
-<!-- Task with data -->
-<c cmd="*standup"
-   exec="{project-root}/bmad/mmm/tasks/daily-standup.md"
-   data="{project-root}/bmad/_cfg/agent-party.xml">
-  Run agile team standup
-</c>
-```
-
-**Data Property:**
-
- Can be used with any command type
- Provides additional reference or context
- Path to supplementary files or resources
- Loaded at runtime for command execution
-
-### 3. Template Commands
-
-Generate documents from templates
-
-```xml
-<c cmd="*brief"
-   exec="{project-root}/bmad/core/tasks/create-doc.md"
-   tmpl="{project-root}/bmad/bmm/templates/brief.md">
-  Produce Project Brief
-</c>
-
-<c cmd="*competitor-analysis"
-   exec="{project-root}/bmad/core/tasks/create-doc.md"
-   tmpl="{project-root}/bmad/bmm/templates/competitor.md"
-   data="{project-root}/bmad/_data/market-research.csv">
-  Produce Competitor Analysis
-</c>
-```
-
-### 4. Meta Commands
-
-Agent control and information
-
-```xml
-<!-- Required meta commands -->
-<c cmd="*help">Show numbered cmd list</c>
-<c cmd="*exit">Exit with confirmation</c>
-
-<!-- Optional meta commands -->
-<c cmd="*yolo">Toggle Yolo Mode</c>
-<c cmd="*status">Show current status</c>
-<c cmd="*config">Show configuration</c>
-```
-
-### 5. Action Commands
-
-Direct prompts embedded in commands (Simple agents)
-
-#### Simple Action (Inline)
-
-```xml
-<!-- Short action attribute with embedded prompt -->
-<c cmd="*list-tasks"
-   action="list all tasks from {project-root}/bmad/_cfg/task-manifest.csv">
-  List Available Tasks
-</c>
-
-<c cmd="*summarize"
-   action="summarize the key points from the current document">
-  Summarize Document
-</c>
-```
-
-#### Complex Action (Referenced)
-
-For multiline/complex prompts, define them separately and reference by id:
-
-```xml
-<agent name="Research Assistant">
-  <!-- Define complex prompts as separate nodes -->
-  <prompts>
-    <prompt id="deep-analysis">
-      Perform a comprehensive analysis following these steps:
-      1. Identify the main topic and key themes
-      2. Extract all supporting evidence and data points
-      3. Analyze relationships between concepts
-      4. Identify gaps or contradictions
-      5. Generate insights and recommendations
-      6. Create an executive summary
-      Format the output with clear sections and bullet points.
-    </prompt>
-
-    <prompt id="literature-review">
-      Conduct a systematic literature review:
-      1. Summarize each source's main arguments
-      2. Compare and contrast different perspectives
-      3. Identify consensus points and controversies
-      4. Evaluate the quality and relevance of sources
-      5. Synthesize findings into coherent themes
-      6. Highlight research gaps and future directions
-      Include proper citations and references.
-    </prompt>
-  </prompts>
-
-  <!-- Commands reference the prompts by id -->
-  <cmds>
-    <c cmd="*help">Show numbered cmd list</c>
-
-    <c cmd="*deep-analyze"
-       action="#deep-analysis">
-      <!-- The # means: use the <prompt id="deep-analysis"> defined above -->
-      Perform Deep Analysis
-    </c>
-
-    <c cmd="*review-literature"
-       action="#literature-review"
-       data="{project-root}/bmad/_data/sources.csv">
-      Conduct Literature Review
-    </c>
-
-    <c cmd="*exit">Exit with confirmation</c>
-  </cmds>
-</agent>
-```
-
-**Reference Convention:**
-
- `action="#prompt-id"` means: "Find and execute the <prompt> node with id='prompt-id' within this agent"
- `action="inline text"` means: "Execute this text directly as the prompt"
- `exec="{path}"` means: "Load and execute external file at this path"
- The `#` prefix signals to the LLM: "This is an internal reference - look for a prompt node with this ID within the current agent XML"
-
-**LLM Processing Instructions:**
-When you see `action="#some-id"` in a command:
-
-1. Look for `<prompt id="some-id">` within the same agent
-2. Use the content of that prompt node as the instruction
-3. If not found, report error: "Prompt 'some-id' not found in agent"
-
-**Use Cases:**
-
- Quick operations (inline action)
- Complex multi-step processes (referenced prompt)
- Self-contained agents with task-like capabilities
- Reusable prompt templates within agent
-
-### 6. Embedded Commands
-
-Logic embedded in agent persona (Simple agents)
-
-```xml
-<!-- No exec/run-workflow/action attribute -->
-<c cmd="*calculate">Perform calculation</c>
-<c cmd="*convert">Convert format</c>
-<c cmd="*generate">Generate output</c>
-```
-
-## Command Naming Conventions
-
-### Action-Based Naming
-
-```xml
-*create-    <!-- Generate new content -->
-*build-     <!-- Construct components -->
-*analyze-   <!-- Examine and report -->
-*validate-  <!-- Check correctness -->
-*generate-  <!-- Produce output -->
-*update-    <!-- Modify existing -->
-*review-    <!-- Examine quality -->
-*test-      <!-- Verify functionality -->
-```
-
-### Domain-Based Naming
-
-```xml
-*brainstorm      <!-- Creative ideation -->
-*architect       <!-- Design systems -->
-*refactor        <!-- Improve code -->
-*deploy          <!-- Release to production -->
-*monitor         <!-- Watch systems -->
-```
-
-### Naming Anti-Patterns
-
-```xml
-<!-- ❌ Too vague -->
-<c cmd="*do">Do something</c>
-
-<!-- ❌ Too long -->
-<c cmd="*create-comprehensive-product-requirements-document-with-analysis">
-
-<!-- ❌ No verb -->
-<c cmd="*prd">Product Requirements</c>
-
-<!-- ✅ Clear and concise -->
-<c cmd="*create-prd">Create Product Requirements Document</c>
-```
-
-## Command Organization
-
-### Standard Order
-
-```xml
-<cmds>
-  <!-- 1. Always first -->
-  <c cmd="*help">Show numbered cmd list</c>
-
-  <!-- 2. Primary workflows -->
-  <c cmd="*create-prd" run-workflow="...">Create PRD</c>
-  <c cmd="*build-module" run-workflow="...">Build module</c>
-
-  <!-- 3. Secondary actions -->
-  <c cmd="*validate" exec="...">Validate document</c>
-  <c cmd="*analyze" exec="...">Analyze code</c>
-
-  <!-- 4. Utility commands -->
-  <c cmd="*config">Show configuration</c>
-  <c cmd="*yolo">Toggle Yolo Mode</c>
-
-  <!-- 5. Always last -->
-  <c cmd="*exit">Exit with confirmation</c>
-</cmds>
-```
-
-### Grouping Strategies
-
-**By Lifecycle:**
-
-```xml
-<cmds>
-  <c cmd="*help">Help</c>
-  <!-- Planning -->
-  <c cmd="*brainstorm">Brainstorm ideas</c>
-  <c cmd="*plan">Create plan</c>
-  <!-- Building -->
-  <c cmd="*build">Build component</c>
-  <c cmd="*test">Test component</c>
-  <!-- Deployment -->
-  <c cmd="*deploy">Deploy to production</c>
-  <c cmd="*monitor">Monitor system</c>
-  <c cmd="*exit">Exit</c>
-</cmds>
-```
-
-**By Complexity:**
-
-```xml
-<cmds>
-  <c cmd="*help">Help</c>
-  <!-- Simple -->
-  <c cmd="*quick-review">Quick review</c>
-  <!-- Standard -->
-  <c cmd="*create-doc">Create document</c>
-  <!-- Complex -->
-  <c cmd="*full-analysis">Comprehensive analysis</c>
-  <c cmd="*exit">Exit</c>
-</cmds>
-```
-
-## Command Descriptions
-
-### Good Descriptions
-
-```xml
-<!-- Clear action and object -->
-<c cmd="*create-prd">Create Product Requirements Document</c>
-
-<!-- Specific outcome -->
-<c cmd="*analyze-security">Perform security vulnerability analysis</c>
-
-<!-- User benefit -->
-<c cmd="*optimize">Optimize code for performance</c>
-```
-
-### Poor Descriptions
-
-```xml
-<!-- Too vague -->
-<c cmd="*process">Process</c>
-
-<!-- Technical jargon -->
-<c cmd="*exec-wf-123">Execute WF123</c>
-
-<!-- Missing context -->
-<c cmd="*run">Run</c>
-```
-
-## The Data Property
-
-### Universal Data Attribute
-
-The `data` attribute can be added to ANY command type to provide supplementary information:
-
-```xml
-<!-- Workflow with data -->
-<c cmd="*brainstorm"
-   run-workflow="{project-root}/bmad/cis/workflows/brainstorming/workflow.yaml"
-   data="{project-root}/bmad/cis/workflows/brainstorming/brain-methods.csv">
-  Creative Brainstorming Session
-</c>
-
-<!-- Action with data -->
-<c cmd="*analyze-metrics"
-   action="analyze these metrics and identify trends"
-   data="{project-root}/bmad/_data/performance-metrics.json">
-  Analyze Performance Metrics
-</c>
-
-<!-- Template with data -->
-<c cmd="*report"
-   exec="{project-root}/bmad/core/tasks/create-doc.md"
-   tmpl="{project-root}/bmad/bmm/templates/report.md"
-   data="{project-root}/bmad/_data/quarterly-results.csv">
-  Generate Quarterly Report
-</c>
-```
-
-**Common Data Uses:**
-
- Reference tables (CSV files)
- Configuration data (YAML/JSON)
- Agent manifests (XML)
- Historical context
- Domain knowledge
- Examples and patterns
-
-## Advanced Patterns
-
-### Conditional Commands
-
-```xml
-<!-- Only show if certain conditions met -->
-<c cmd="*advanced-mode"
-   if="user_level == 'expert'"
-   run-workflow="...">
-  Advanced configuration mode
-</c>
-
-<!-- Environment specific -->
-<c cmd="*deploy-prod"
-   if="environment == 'production'"
-   exec="...">
-  Deploy to production
-</c>
-```
-
-### Parameterized Commands
-
-```xml
-<!-- Accept runtime parameters -->
-<c cmd="*create-agent"
-   run-workflow="..."
-   params="agent_type,agent_name">
-  Create new agent with parameters
-</c>
-```
-
-### Command Aliases
-
-```xml
-<!-- Multiple triggers for same action -->
-<c cmd="*prd|*create-prd|*product-requirements"
-   run-workflow="...">
-  Create Product Requirements Document
-</c>
-```
-
-## Module-Specific Patterns
-
-### BMM (Business Management)
-
-```xml
-<c cmd="*create-prd">Product Requirements</c>
-<c cmd="*market-research">Market Research</c>
-<c cmd="*competitor-analysis">Competitor Analysis</c>
-<c cmd="*brief">Project Brief</c>
-```
-
-### BMB (Builder)
-
-```xml
-<c cmd="*build-agent">Build Agent</c>
-<c cmd="*build-module">Build Module</c>
-<c cmd="*create-workflow">Create Workflow</c>
-<c cmd="*module-brief">Module Brief</c>
-```
-
-### CIS (Creative Intelligence)
-
-```xml
-<c cmd="*brainstorm">Brainstorming Session</c>
-<c cmd="*ideate">Ideation Workshop</c>
-<c cmd="*storytell">Story Creation</c>
-```
-
-## Command Menu Presentation
-
-### How Commands Display
-
-```
-1. *help - Show numbered cmd list
-2. *create-prd - Create Product Requirements Document
-3. *build-agent - Build new BMAD agent
-4. *validate - Validate document
-5. *exit - Exit with confirmation
-```
-
-### Menu Customization
-
-```xml
-<!-- Group separator (visual only) -->
-<c cmd="---">━━━━━━━━━━━━━━━━━━━━</c>
-
-<!-- Section header (non-executable) -->
-<c cmd="SECTION">═══ Workflows ═══</c>
-```
-
-## Error Handling
-
-### Missing Resources
-
-```xml
-<!-- Workflow not yet created -->
-<c cmd="*future-feature"
-   run-workflow="todo">
-  Coming soon: Advanced feature
-</c>
-
-<!-- Graceful degradation -->
-<c cmd="*analyze"
-   run-workflow="{optional-path|fallback-path}">
-  Analyze with available tools
-</c>
-```
-
-## Testing Commands
-
-### Command Test Checklist
-
- [ ] Unique trigger (no duplicates)
- [ ] Clear description
- [ ] Valid path or "todo"
- [ ] Uses variables not hardcoded paths
- [ ] Executes without error
- [ ] Returns to menu after execution
-
-### Common Issues
-
-1. **Duplicate triggers** - Each cmd must be unique
-2. **Missing paths** - File must exist or be "todo"
-3. **Hardcoded paths** - Always use variables
-4. **No description** - Every command needs text
-5. **Wrong order** - help first, exit last
-
-## Quick Templates
-
-### Workflow Command
-
-```xml
-<!-- Create document -->
-<c cmd="*{action}-{object}"
-   run-workflow="{project-root}/bmad/{module}/workflows/{workflow}/workflow.yaml">
-  {Action} {Object Description}
-</c>
-
-<!-- Validate document -->
-<c cmd="*validate-{object}"
-   validate-workflow="{output_folder}/{document}.md"
-   workflow="{project-root}/bmad/{module}/workflows/{workflow}/workflow.yaml">
-  Validate {Object Description}
-</c>
-```
-
-### Task Command
-
-```xml
-<c cmd="*{action}"
-   exec="{project-root}/bmad/{module}/tasks/{task}.md">
-  {Action Description}
-</c>
-```
-
-### Template Command
-
-```xml
-<c cmd="*{document}"
-   exec="{project-root}/bmad/core/tasks/create-doc.md"
-   tmpl="{project-root}/bmad/{module}/templates/{template}.md">
-  Create {Document Name}
-</c>
-```
-
-## Self-Contained Agent Patterns
-
-### When to Use Each Approach
-
-**Inline Action (`action="prompt"`)**
-
- Prompt is < 2 lines
- Simple, direct instruction
- Not reused elsewhere
- Quick transformations
-
-**Referenced Prompt (`action="#prompt-id"`)**
-
- Prompt is multiline/complex
- Contains structured steps
- May be reused by multiple commands
- Maintains readability
-
-**External Task (`exec="path/to/task.md"`)**
-
- Logic needs to be shared across agents
- Task is independently valuable
- Requires version control separately
- Part of larger workflow system
-
-### Complete Self-Contained Agent
-
-```xml
-<agent id="bmad/research/agents/analyst.md" name="Research Analyst" icon="🔬">
-  <!-- Embedded prompt library -->
-  <prompts>
-    <prompt id="swot-analysis">
-      Perform a SWOT analysis:
-
-      STRENGTHS (Internal, Positive)
-      - What advantages exist?
-      - What do we do well?
-      - What unique resources?
-
-      WEAKNESSES (Internal, Negative)
-      - What could improve?
-      - Where are resource gaps?
-      - What needs development?
-
-      OPPORTUNITIES (External, Positive)
-      - What trends can we leverage?
-      - What market gaps exist?
-      - What partnerships are possible?
-
-      THREATS (External, Negative)
-      - What competition exists?
-      - What risks are emerging?
-      - What could disrupt us?
-
-      Provide specific examples and actionable insights for each quadrant.
-    </prompt>
-
-    <prompt id="competitive-intel">
-      Analyze competitive landscape:
-      1. Identify top 5 competitors
-      2. Compare features and capabilities
-      3. Analyze pricing strategies
-      4. Evaluate market positioning
-      5. Assess strengths and vulnerabilities
-      6. Recommend competitive strategies
-    </prompt>
-  </prompts>
-
-  <cmds>
-    <c cmd="*help">Show numbered cmd list</c>
-
-    <!-- Simple inline actions -->
-    <c cmd="*summarize"
-       action="create executive summary of findings">
-      Create Executive Summary
-    </c>
-
-    <!-- Complex referenced prompts -->
-    <c cmd="*swot"
-       action="#swot-analysis">
-      Perform SWOT Analysis
-    </c>
-
-    <c cmd="*compete"
-       action="#competitive-intel"
-       data="{project-root}/bmad/_data/market-data.csv">
-      Analyze Competition
-    </c>
-
-    <!-- Hybrid: external task with internal data -->
-    <c cmd="*report"
-       exec="{project-root}/bmad/core/tasks/create-doc.md"
-       tmpl="{project-root}/bmad/research/templates/report.md">
-      Generate Research Report
-    </c>
-
-    <c cmd="*exit">Exit with confirmation</c>
-  </cmds>
-</agent>
-```
-
-## Simple Agent Example
-
-For agents that primarily use embedded logic:
-
-```xml
-<agent name="Data Analyst">
-  <cmds>
-    <c cmd="*help">Show numbered cmd list</c>
-
-    <!-- Action commands for direct operations -->
-    <c cmd="*list-metrics"
-       action="list all available metrics from the dataset">
-      List Available Metrics
-    </c>
-
-    <c cmd="*analyze"
-       action="perform statistical analysis on the provided data"
-       data="{project-root}/bmad/_data/dataset.csv">
-      Analyze Dataset
-    </c>
-
-    <c cmd="*visualize"
-       action="create visualization recommendations for this data">
-      Suggest Visualizations
-    </c>
-
-    <!-- Embedded logic commands -->
-    <c cmd="*calculate">Perform calculations</c>
-    <c cmd="*interpret">Interpret results</c>
-
-    <c cmd="*exit">Exit with confirmation</c>
-  </cmds>
-</agent>
-```
-
-## LLM Building Guide
-
-When creating commands:
-
-1. Start with *help and *exit
-2. Choose appropriate command type:
-   - Complex multi-step? Use `run-workflow`
-   - Single operation? Use `exec`
-   - Need template? Use `exec` + `tmpl`
-   - Simple prompt? Use `action`
-   - Agent handles it? Use no attributes
-3. Add `data` attribute if supplementary info needed
-4. Add primary workflows (main value)
-5. Add secondary tasks
-6. Include utility commands
-7. Test each command works
-8. Verify no duplicates
-9. Ensure clear descriptions
--- a/src/modules/bmb/workflows/create-agent/agent-types.md
+++ b/src/modules/bmb/workflows/create-agent/agent-types.md
@@ -1,177 +0,0 @@
-# BMAD Agent Types Reference
-
-## Overview
-
-BMAD agents come in three distinct types, each designed for different use cases and complexity levels.
-
-## Agent Types
-
-### 1. Simple Agent
-
-**Purpose:** Self-contained, standalone agents with embedded capabilities
-
-**Characteristics:**
-
- All logic embedded within the agent file
- No external dependencies
- Quick to create and deploy
- Perfect for single-purpose tools
-
-**Use Cases:**
-
- Calculator agents
- Format converters
- Simple analyzers
- Static advisors
-
-**Structure:**
-
-```xml
-<agent id="simple-agent" name="Helper" title="Simple Helper" icon="🤖">
-  <persona>
-    <role>Simple Helper Role</role>
-    <identity>...</identity>
-    <communication_style>...</communication_style>
-    <principles>...</principles>
-  </persona>
-  <embedded-data>
-    <!-- Optional embedded data/logic -->
-  </embedded-data>
-  <cmds>
-    <c cmd="*help">Show commands</c>
-    <c cmd="*calculate">Perform calculation</c>
-    <c cmd="*exit">Exit</c>
-  </cmds>
-</agent>
-```
-
-### 2. Expert Agent
-
-**Purpose:** Specialized agents with domain expertise and sidecar resources
-
-**Characteristics:**
-
- Has access to specific folders/files
- Domain-restricted operations
- Maintains specialized knowledge
- Can have memory/context files
-
-**Use Cases:**
-
- Personal diary agent (only accesses diary folder)
- Project-specific assistant (knows project context)
- Domain expert (medical, legal, technical)
- Personal coach with history
-
-**Structure:**
-
-```xml
-<agent id="expert-agent" name="Domain Expert" title="Specialist" icon="🎯">
-  <persona>
-    <role>Domain Specialist Role</role>
-    <identity>...</identity>
-    <communication_style>...</communication_style>
-    <principles>...</principles>
-  </persona>
-  <critical-actions>
-    <!-- CRITICAL: Load sidecar files explicitly -->
-    <i critical="MANDATORY">Load COMPLETE file {agent-folder}/instructions.md and follow ALL directives</i>
-    <i critical="MANDATORY">Load COMPLETE file {agent-folder}/memories.md into permanent context</i>
-    <i critical="MANDATORY">ONLY access {user-folder}/diary/ - NO OTHER FOLDERS</i>
-  </critical-actions>
-  <cmds>...</cmds>
-</agent>
-```
-
-**Sidecar Structure:**
-
-```
-expert-agent/
-├── agent.md          # Main agent file
-├── memories.md       # Personal context/memories
-├── knowledge/        # Domain knowledge base
-└── data/            # Agent-specific data
-```
-
-### 3. Module Agent
-
-**Purpose:** Full-featured agents belonging to a module with access to workflows and resources
-
-**Characteristics:**
-
- Part of a BMAD module (bmm, bmb, cis)
- Access to multiple workflows
- Can invoke other tasks and agents
- Professional/enterprise grade
-
-**Use Cases:**
-
- Product Manager (creates PRDs, manages requirements)
- Security Engineer (threat models, security reviews)
- Test Architect (test strategies, automation)
- Business Analyst (market research, requirements)
-
-**Structure:**
-
-```xml
-<agent id="bmad/bmm/agents/pm.md" name="John" title="Product Manager" icon="📋">
-  <persona>
-    <role>Product Management Expert</role>
-    <identity>...</identity>
-    <communication_style>...</communication_style>
-    <principles>...</principles>
-  </persona>
-  <critical-actions>
-    <i>Load config from {project-root}/bmad/{module}/config.yaml</i>
-  </critical-actions>
-  <cmds>
-    <c cmd="*help">Show numbered cmd list</c>
-    <c cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">Create PRD</c>
-    <c cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.md">Validate document</c>
-    <c cmd="*exit">Exit</c>
-  </cmds>
-</agent>
-```
-
-## Choosing the Right Type
-
-### Choose Simple Agent when:
-
- Single, well-defined purpose
- No external data needed
- Quick utility functions
- Embedded logic is sufficient
-
-### Choose Expert Agent when:
-
- Domain-specific expertise required
- Need to maintain context/memory
- Restricted to specific data/folders
- Personal or specialized use case
-
-### Choose Module Agent when:
-
- Part of larger system/module
- Needs multiple workflows
- Professional/team use
- Complex multi-step processes
-
-## Migration Path
-
-```
-Simple Agent → Expert Agent → Module Agent
-```
-
-Agents can evolve:
-
-1. Start with Simple for proof of concept
-2. Add sidecar resources to become Expert
-3. Integrate with module to become Module Agent
-
-## Best Practices
-
-1. **Start Simple:** Begin with the simplest type that meets your needs
-2. **Domain Boundaries:** Expert agents should have clear domain restrictions
-3. **Module Integration:** Module agents should follow module conventions
-4. **Resource Management:** Document all external resources clearly
-5. **Evolution Planning:** Design with potential growth in mind
--- a/src/modules/bmb/workflows/create-agent/agent-validation-checklist.md
+++ b/src/modules/bmb/workflows/create-agent/agent-validation-checklist.md
@@ -0,0 +1,174 @@
+# BMAD Agent Validation Checklist
+
+Use this checklist to validate agents meet BMAD quality standards, whether creating new agents or editing existing ones.
+
+## YAML Structure Validation (Source Files)
+
+- [ ] YAML parses without errors
+- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`
+- [ ] `agent.metadata.module` present if Module agent (e.g., `bmm`, `bmgd`, `cis`)
+- [ ] `agent.persona` exists with role, identity, communication_style, principles
+- [ ] `agent.menu` exists with at least one item
+- [ ] Filename is kebab-case and ends with `.agent.yaml`
+
+## Agent Structure Validation
+
+- [ ] Agent file format is valid (.agent.yaml for source)
+- [ ] Agent type matches structure: Simple (single YAML), Expert (sidecar files), or Module (ecosystem integration)
+- [ ] File naming follows convention: `{agent-name}.agent.yaml`
+- [ ] If Expert: folder structure with .agent.yaml + sidecar files
+- [ ] If Module: includes header comment explaining WHY Module Agent (design intent)
+
+## Persona Validation (CRITICAL - #1 Quality Issue)
+
+**Field Separation Check:**
+
+- [ ] **role** contains ONLY knowledge/skills/capabilities (what agent does)
+- [ ] **identity** contains ONLY background/experience/context (who agent is)
+- [ ] **communication_style** contains ONLY verbal patterns - NO behaviors, NO role statements, NO principles
+- [ ] **principles** contains operating philosophy and behavioral guidelines
+
+**Communication Style Purity Check:**
+
+- [ ] Communication style does NOT contain red flag words: "ensures", "makes sure", "always", "never"
+- [ ] Communication style does NOT contain identity words: "experienced", "expert who", "senior", "seasoned"
+- [ ] Communication style does NOT contain philosophy words: "believes in", "focused on", "committed to"
+- [ ] Communication style does NOT contain behavioral descriptions: "who does X", "that does Y"
+- [ ] Communication style is 1-2 sentences describing HOW they talk (word choice, quirks, verbal patterns)
+
+**Quality Benchmarking:**
+
+- [ ] Compare communication style against {communication_presets} - similarly pure?
+- [ ] Compare against reference agents (commit-poet, journal-keeper, BMM agents) - similar quality?
+- [ ] Read communication style aloud - does it sound like describing someone's voice/speech pattern?
+
+## Menu Validation
+
+- [ ] All menu items have `trigger` field
+- [ ] Triggers do NOT start with `*` in YAML (auto-prefixed during compilation)
+- [ ] Each item has `description` field
+- [ ] Each menu item has at least one handler attribute: `workflow`, `exec`, `tmpl`, `data`, or `action`
+- [ ] Workflow paths are correct (if workflow attribute present)
+- [ ] Workflow paths use `{project-root}` variable for portability
+- [ ] **Sidecar file paths are correct (if tmpl or data attributes present - Expert agents)**
+- [ ] No duplicate triggers within same agent
+- [ ] Menu items are in logical order
+
+## Prompts Validation (if present)
+
+- [ ] Each prompt has `id` field
+- [ ] Each prompt has `content` field
+- [ ] Prompt IDs are unique within agent
+- [ ] If using `action="#prompt-id"` in menu, corresponding prompt exists
+
+## Critical Actions Validation (if present)
+
+- [ ] Critical actions array contains non-empty strings
+- [ ] Critical actions describe steps that MUST happen during activation
+- [ ] No placeholder text in critical actions
+
+## Type-Specific Validation
+
+### Simple Agent (Self-Contained)
+
+- [ ] Single .agent.yaml file with complete agent definition
+- [ ] No sidecar files (all content in YAML)
+- [ ] Not capability-limited - can be as powerful as Expert or Module
+- [ ] Compare against reference: commit-poet.agent.yaml
+
+### Expert Agent (With Sidecar Files)
+
+- [ ] Folder structure: .agent.yaml + sidecar files
+- [ ] Sidecar files properly referenced in menu items or prompts (tmpl="path", data="path")
+- [ ] Folder name matches agent purpose
+- [ ] **All sidecar references in YAML resolve to actual files**
+- [ ] **All sidecar files are actually used (no orphaned/unused files, unless intentional for future use)**
+- [ ] Sidecar files are valid format (YAML parses, CSV has headers, markdown is well-formed)
+- [ ] Sidecar file paths use relative paths from agent folder
+- [ ] Templates contain valid template variables if applicable
+- [ ] Knowledge base files contain current/accurate information
+- [ ] Compare against reference: journal-keeper (Expert example)
+
+### Module Agent (Ecosystem Integration)
+
+- [ ] Designed FOR specific module (BMM, BMGD, CIS, etc.)
+- [ ] Integrates with module workflows (referenced in menu items)
+- [ ] Coordinates with other module agents (if applicable)
+- [ ] Included in module's default bundle (if applicable)
+- [ ] Header comment explains WHY Module Agent (design intent, not just location)
+- [ ] Can be Simple OR Expert structurally (Module is about intent, not structure)
+- [ ] Compare against references: security-engineer, dev, analyst (Module examples)
+
+## Compilation Validation (Post-Build)
+
+- [ ] Agent compiles without errors to .md format
+- [ ] Compiled file has proper frontmatter (name, description)
+- [ ] Compiled XML structure is valid
+- [ ] `<agent>` tag has id, name, title, icon attributes
+- [ ] `<activation>` section is present with proper steps
+- [ ] `<persona>` section compiled correctly
+- [ ] `<menu>` section includes both user items AND auto-injected *help/*exit
+- [ ] Menu handlers section included (if menu items use workflow/exec/tmpl/data/action)
+
+## Quality Checks
+
+- [ ] No placeholder text remains ({{AGENT_NAME}}, {ROLE}, TODO, etc.)
+- [ ] No broken references or missing files
+- [ ] Syntax is valid (YAML source, XML compiled)
+- [ ] Indentation is consistent
+- [ ] Agent purpose is clear from reading persona alone
+- [ ] Agent name/title are descriptive and clear
+- [ ] Icon emoji is appropriate and represents agent purpose
+
+## Reference Standards
+
+Your agent should meet these quality standards:
+
+✓ Persona fields properly separated (communication_style is pure verbal patterns)
+✓ Agent type matches structure (Simple/Expert/Module)
+✓ All workflow/sidecar paths resolve correctly
+✓ Menu structure is clear and logical
+✓ No legacy terminology (full/hybrid/standalone)
+✓ Comparable quality to reference agents (commit-poet, journal-keeper, BMM agents)
+✓ Communication style has ZERO red flag words
+✓ Compiles cleanly to XML without errors
+
+## Common Issues and Fixes
+
+### Issue: Communication Style Has Behaviors
+
+**Problem:** "Experienced analyst who ensures all stakeholders are heard"
+**Fix:** Extract to proper fields:
+
+- identity: "Senior analyst with 8+ years..."
+- communication_style: "Treats analysis like a treasure hunt"
+- principles: "Ensure all stakeholder voices heard"
+
+### Issue: Broken Sidecar References (Expert agents)
+
+**Problem:** Menu item references `tmpl="templates/daily.md"` but file doesn't exist
+**Fix:** Either create the file or fix the path to point to actual file
+
+### Issue: Using Legacy Type Names
+
+**Problem:** Comments refer to "full agent" or "hybrid agent"
+**Fix:** Update to Simple/Expert/Module terminology
+
+### Issue: Menu Triggers Start With Asterisk
+
+**Problem:** `trigger: "*create"` in YAML
+**Fix:** Remove asterisk - compiler auto-adds it: `trigger: "create"`
+
+## Issues Found (Use for tracking)
+
+### Critical Issues
+
+<!-- List any issues that MUST be fixed before agent can function -->
+
+### Warnings
+
+<!-- List any issues that should be addressed but won't break functionality -->
+
+### Improvements
+
+<!-- List any optional enhancements that could improve the agent -->
--- a/Show More
+++ b/Show More