Merge branch 'main' into feature/ring-of-fire-sessions

fix(bmm): normalize dev-story trigger naming

.coderabbit.yaml

@@ -0,0 +1,40 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+
+language: "en-US"
+early_access: true
+reviews:
+  profile: chill
+  high_level_summary: false # don't post summary until explicitly invoked
+  request_changes_workflow: false
+  review_status: false
+  commit_status: false # don't set commit status until explicitly invoked
+  collapse_walkthrough: false
+  poem: false
+  auto_review:
+    enabled: false # must be manually triggered with @coderabbit review
+    drafts: true # Can review drafts. Since it's manually triggered, it's fine.
+    auto_incremental_review: false # always review the whole PR, not just new commits
+    base_branches:
+      - main
+  path_filters:
+    - "!**/node_modules/**"
+  path_instructions:
+    - path: "**/*"
+      instructions: |
+        Focus on inconsistencies, contradictions, edge cases and serious issues.
+        Avoid commenting on minor issues such as linting, formatting and style issues.
+        When providing code suggestions, use GitHub's suggestion format:
+        ```suggestion
+        <code changes>
+        ```
+    - path: "**/*.js"
+      instructions: |
+        CLI tooling code. Check for: missing error handling on fs operations,
+        path.join vs string concatenation, proper cleanup in error paths.
+        Flag any process.exit() without error message.
+chat:
+  auto_reply: true # Response to mentions in comments, a la @coderabbit review
+issue_enrichment:
+  auto_enrich:
+    enabled: false # don't auto-comment on issues
+

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+the official BMAD Discord server (<https://discord.com/invite/gk8jAdXWmj>) - DM a moderator or flag a post.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.

.github/ISSUE_TEMPLATE/idea_submission.md

@@ -8,7 +8,7 @@ assignees: ''
 
 # Idea: [Replace with a clear, actionable title]
 
-### PASS Framework
+## PASS Framework
 
 **P**roblem:
 

.github/scripts/discord-helpers.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Discord notification helper functions
+
+# Escape markdown special chars and @mentions for safe Discord display
+# Bracket expression: ] must be first, then other chars. In POSIX bracket expr, \ is literal.
+esc() { sed -e 's/[][\*_()~`>]/\\&/g' -e 's/@/@ /g'; }
+
+# Truncate to $1 chars (or 80 if wall-of-text with <3 spaces)
+trunc() {
+  local max=$1
+  local txt=$(tr '\n\r' '  ' | cut -c1-"$max")
+  local spaces=$(printf '%s' "$txt" | tr -cd ' ' | wc -c)
+  [ "$spaces" -lt 3 ] && [ ${#txt} -gt 80 ] && txt=$(printf '%s' "$txt" | cut -c1-80)
+  printf '%s' "$txt"
+}

.github/workflows/discord.yaml

@@ -1,16 +1,286 @@
 name: Discord Notification
 
-"on": [pull_request, release, create, delete, issue_comment, pull_request_review, pull_request_review_comment]
+on:
+  pull_request:
+    types: [opened, closed, reopened, ready_for_review]
+  release:
+    types: [published]
+  create:
+  delete:
+  issue_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, closed, reopened]
+
+env:
+  MAX_TITLE: 100
+  MAX_BODY: 250
 
 jobs:
-  notify:
+  pull_request:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          sparse-checkout: .github/scripts
+          sparse-checkout-cone-mode: false
+      - name: Notify Discord
+        env:
+          WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+          ACTION: ${{ github.event.action }}
+          MERGED: ${{ github.event.pull_request.merged }}
+          PR_NUM: ${{ github.event.pull_request.number }}
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_USER: ${{ github.event.pull_request.user.login }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          set -o pipefail
+          source .github/scripts/discord-helpers.sh
+          [ -z "$WEBHOOK" ] && exit 0
+
+          if [ "$ACTION" = "opened" ]; then ICON="🔀"; LABEL="New PR"
+          elif [ "$ACTION" = "closed" ] && [ "$MERGED" = "true" ]; then ICON="🎉"; LABEL="Merged"
+          elif [ "$ACTION" = "closed" ]; then ICON="❌"; LABEL="Closed"
+          elif [ "$ACTION" = "reopened" ]; then ICON="🔄"; LABEL="Reopened"
+          else ICON="📋"; LABEL="Ready"; fi
+
+          TITLE=$(printf '%s' "$PR_TITLE" | trunc $MAX_TITLE | esc)
+          [ ${#PR_TITLE} -gt $MAX_TITLE ] && TITLE="${TITLE}..."
+          BODY=$(printf '%s' "$PR_BODY" | trunc $MAX_BODY | esc)
+          [ -n "$PR_BODY" ] && [ ${#PR_BODY} -gt $MAX_BODY ] && BODY="${BODY}..."
+          [ -n "$BODY" ] && BODY=" · $BODY"
+          USER=$(printf '%s' "$PR_USER" | esc)
+
+          MSG="$ICON **[$LABEL #$PR_NUM: $TITLE](<$PR_URL>)**"$'\n'"by @$USER$BODY"
+          jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-
+
+  issues:
+    if: github.event_name == 'issues'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          sparse-checkout: .github/scripts
+          sparse-checkout-cone-mode: false
+      - name: Notify Discord
+        env:
+          WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+          ACTION: ${{ github.event.action }}
+          ISSUE_NUM: ${{ github.event.issue.number }}
+          ISSUE_URL: ${{ github.event.issue.html_url }}
+          ISSUE_TITLE: ${{ github.event.issue.title }}
+          ISSUE_USER: ${{ github.event.issue.user.login }}
+          ISSUE_BODY: ${{ github.event.issue.body }}
+          ACTOR: ${{ github.actor }}
+        run: |
+          set -o pipefail
+          source .github/scripts/discord-helpers.sh
+          [ -z "$WEBHOOK" ] && exit 0
+
+          if [ "$ACTION" = "opened" ]; then ICON="🐛"; LABEL="New Issue"; USER="$ISSUE_USER"
+          elif [ "$ACTION" = "closed" ]; then ICON="✅"; LABEL="Closed"; USER="$ACTOR"
+          else ICON="🔄"; LABEL="Reopened"; USER="$ACTOR"; fi
+
+          TITLE=$(printf '%s' "$ISSUE_TITLE" | trunc $MAX_TITLE | esc)
+          [ ${#ISSUE_TITLE} -gt $MAX_TITLE ] && TITLE="${TITLE}..."
+          BODY=$(printf '%s' "$ISSUE_BODY" | trunc $MAX_BODY | esc)
+          [ -n "$ISSUE_BODY" ] && [ ${#ISSUE_BODY} -gt $MAX_BODY ] && BODY="${BODY}..."
+          [ -n "$BODY" ] && BODY=" · $BODY"
+          USER=$(printf '%s' "$USER" | esc)
+
+          MSG="$ICON **[$LABEL #$ISSUE_NUM: $TITLE](<$ISSUE_URL>)**"$'\n'"by @$USER$BODY"
+          jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-
+
+  issue_comment:
+    if: github.event_name == 'issue_comment'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          sparse-checkout: .github/scripts
+          sparse-checkout-cone-mode: false
+      - name: Notify Discord
+        env:
+          WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+          IS_PR: ${{ github.event.issue.pull_request && 'true' || 'false' }}
+          ISSUE_NUM: ${{ github.event.issue.number }}
+          ISSUE_TITLE: ${{ github.event.issue.title }}
+          COMMENT_URL: ${{ github.event.comment.html_url }}
+          COMMENT_USER: ${{ github.event.comment.user.login }}
+          COMMENT_BODY: ${{ github.event.comment.body }}
+        run: |
+          set -o pipefail
+          source .github/scripts/discord-helpers.sh
+          [ -z "$WEBHOOK" ] && exit 0
+
+          [ "$IS_PR" = "true" ] && TYPE="PR" || TYPE="Issue"
+
+          TITLE=$(printf '%s' "$ISSUE_TITLE" | trunc $MAX_TITLE | esc)
+          [ ${#ISSUE_TITLE} -gt $MAX_TITLE ] && TITLE="${TITLE}..."
+          BODY=$(printf '%s' "$COMMENT_BODY" | trunc $MAX_BODY | esc)
+          [ ${#COMMENT_BODY} -gt $MAX_BODY ] && BODY="${BODY}..."
+          USER=$(printf '%s' "$COMMENT_USER" | esc)
+
+          MSG="💬 **[Comment on $TYPE #$ISSUE_NUM: $TITLE](<$COMMENT_URL>)**"$'\n'"@$USER: $BODY"
+          jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-
+
+  pull_request_review:
+    if: github.event_name == 'pull_request_review'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          sparse-checkout: .github/scripts
+          sparse-checkout-cone-mode: false
+      - name: Notify Discord
+        env:
+          WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+          STATE: ${{ github.event.review.state }}
+          PR_NUM: ${{ github.event.pull_request.number }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          REVIEW_URL: ${{ github.event.review.html_url }}
+          REVIEW_USER: ${{ github.event.review.user.login }}
+          REVIEW_BODY: ${{ github.event.review.body }}
+        run: |
+          set -o pipefail
+          source .github/scripts/discord-helpers.sh
+          [ -z "$WEBHOOK" ] && exit 0
+
+          if [ "$STATE" = "approved" ]; then ICON="✅"; LABEL="Approved"
+          elif [ "$STATE" = "changes_requested" ]; then ICON="🔧"; LABEL="Changes Requested"
+          else ICON="👀"; LABEL="Reviewed"; fi
+
+          TITLE=$(printf '%s' "$PR_TITLE" | trunc $MAX_TITLE | esc)
+          [ ${#PR_TITLE} -gt $MAX_TITLE ] && TITLE="${TITLE}..."
+          BODY=$(printf '%s' "$REVIEW_BODY" | trunc $MAX_BODY | esc)
+          [ -n "$REVIEW_BODY" ] && [ ${#REVIEW_BODY} -gt $MAX_BODY ] && BODY="${BODY}..."
+          [ -n "$BODY" ] && BODY=": $BODY"
+          USER=$(printf '%s' "$REVIEW_USER" | esc)
+
+          MSG="$ICON **[$LABEL PR #$PR_NUM: $TITLE](<$REVIEW_URL>)**"$'\n'"@$USER$BODY"
+          jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-
+
+  pull_request_review_comment:
+    if: github.event_name == 'pull_request_review_comment'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          sparse-checkout: .github/scripts
+          sparse-checkout-cone-mode: false
+      - name: Notify Discord
+        env:
+          WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+          PR_NUM: ${{ github.event.pull_request.number }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          COMMENT_URL: ${{ github.event.comment.html_url }}
+          COMMENT_USER: ${{ github.event.comment.user.login }}
+          COMMENT_BODY: ${{ github.event.comment.body }}
+        run: |
+          set -o pipefail
+          source .github/scripts/discord-helpers.sh
+          [ -z "$WEBHOOK" ] && exit 0
+
+          TITLE=$(printf '%s' "$PR_TITLE" | trunc $MAX_TITLE | esc)
+          [ ${#PR_TITLE} -gt $MAX_TITLE ] && TITLE="${TITLE}..."
+          BODY=$(printf '%s' "$COMMENT_BODY" | trunc $MAX_BODY | esc)
+          [ ${#COMMENT_BODY} -gt $MAX_BODY ] && BODY="${BODY}..."
+          USER=$(printf '%s' "$COMMENT_USER" | esc)
+
+          MSG="💭 **[Review Comment PR #$PR_NUM: $TITLE](<$COMMENT_URL>)**"$'\n'"@$USER: $BODY"
+          jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-
+
+  release:
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          sparse-checkout: .github/scripts
+          sparse-checkout-cone-mode: false
+      - name: Notify Discord
+        env:
+          WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+          TAG: ${{ github.event.release.tag_name }}
+          NAME: ${{ github.event.release.name }}
+          URL: ${{ github.event.release.html_url }}
+          RELEASE_BODY: ${{ github.event.release.body }}
+        run: |
+          set -o pipefail
+          source .github/scripts/discord-helpers.sh
+          [ -z "$WEBHOOK" ] && exit 0
+
+          REL_NAME=$(printf '%s' "$NAME" | trunc $MAX_TITLE | esc)
+          [ ${#NAME} -gt $MAX_TITLE ] && REL_NAME="${REL_NAME}..."
+          BODY=$(printf '%s' "$RELEASE_BODY" | trunc $MAX_BODY | esc)
+          [ -n "$RELEASE_BODY" ] && [ ${#RELEASE_BODY} -gt $MAX_BODY ] && BODY="${BODY}..."
+          [ -n "$BODY" ] && BODY=" · $BODY"
+          TAG_ESC=$(printf '%s' "$TAG" | esc)
+
+          MSG="🚀 **[Release $TAG_ESC: $REL_NAME](<$URL>)**"$'\n'"$BODY"
+          jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-
+
+  create:
+    if: github.event_name == 'create'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          sparse-checkout: .github/scripts
+          sparse-checkout-cone-mode: false
+      - name: Notify Discord
+        env:
+          WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+          REF_TYPE: ${{ github.event.ref_type }}
+          REF: ${{ github.event.ref }}
+          ACTOR: ${{ github.actor }}
+          REPO_URL: ${{ github.event.repository.html_url }}
+        run: |
+          set -o pipefail
+          source .github/scripts/discord-helpers.sh
+          [ -z "$WEBHOOK" ] && exit 0
+
+          [ "$REF_TYPE" = "branch" ] && ICON="🌿" || ICON="🏷️"
+          REF_TRUNC=$(printf '%s' "$REF" | trunc $MAX_TITLE)
+          [ ${#REF} -gt $MAX_TITLE ] && REF_TRUNC="${REF_TRUNC}..."
+          REF_ESC=$(printf '%s' "$REF_TRUNC" | esc)
+          REF_URL=$(jq -rn --arg ref "$REF" '$ref | @uri')
+          ACTOR_ESC=$(printf '%s' "$ACTOR" | esc)
+          MSG="$ICON **${REF_TYPE^} created: [$REF_ESC](<$REPO_URL/tree/$REF_URL>)** by @$ACTOR_ESC"
+          jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-
+
+  delete:
+    if: github.event_name == 'delete'
     runs-on: ubuntu-latest
     steps:
       - name: Notify Discord
-        uses: sarisia/actions-status-discord@v1
-        if: always()
-        with:
-          webhook: ${{ secrets.DISCORD_WEBHOOK }}
-          status: ${{ job.status }}
-          title: "Triggered by ${{ github.event_name }}"
-          color: 0x5865F2
+        env:
+          WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+          REF_TYPE: ${{ github.event.ref_type }}
+          REF: ${{ github.event.ref }}
+          ACTOR: ${{ github.actor }}
+        run: |
+          set -o pipefail
+          [ -z "$WEBHOOK" ] && exit 0
+          esc() { sed -e 's/[][\*_()~`>]/\\&/g' -e 's/@/@ /g'; }
+          trunc() { tr '\n\r' '  ' | cut -c1-"$1"; }
+
+          REF_TRUNC=$(printf '%s' "$REF" | trunc 100)
+          [ ${#REF} -gt 100 ] && REF_TRUNC="${REF_TRUNC}..."
+          REF_ESC=$(printf '%s' "$REF_TRUNC" | esc)
+          ACTOR_ESC=$(printf '%s' "$ACTOR" | esc)
+          MSG="🗑️ **${REF_TYPE^} deleted: $REF_ESC** by @$ACTOR_ESC"
+          jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @-

.github/workflows/quality.yaml

@@ -3,6 +3,7 @@ name: Quality & Validation
 # Runs comprehensive quality checks on all PRs:
 # - Prettier (formatting)
 # - ESLint (linting)
+# - markdownlint (markdown quality)
 # - Schema validation (YAML structure)
 # - Agent schema tests (fixture-based validation)
 # - Installation component tests (compilation)
@@ -50,6 +51,24 @@ jobs:
       - name: ESLint
         run: npm run lint
 
+  markdownlint:
+    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: markdownlint
+        run: npm run lint:md
+
   validate:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -62,11 +62,16 @@ src/modules/bmm/sub-modules/
 src/modules/bmb/sub-modules/
 src/modules/cis/sub-modules/
 src/modules/bmgd/sub-modules/
-
+shared-modules
 z*/
 
 .bmad
 .claude
 .codex
 .github/chatmodes
-.agent
+.agent
+.agentvibes/
+.kiro/
+.roo
+
+bmad-custom-src/

.markdownlint-cli2.yaml

@@ -0,0 +1,42 @@
+# markdownlint-cli2 configuration
+# https://github.com/DavidAnson/markdownlint-cli2
+
+ignores:
+  - node_modules/**
+  - test/fixtures/**
+  - CODE_OF_CONDUCT.md
+  - .bmad/**
+  - .bmad*/**
+  - .agent/**
+  - .claude/**
+  - .roo/**
+  - .codex/**
+  - .agentvibes/**
+  - .kiro/**
+  - sample-project/**
+  - test-project-install/**
+  - z*/**
+
+# Rule configuration
+config:
+  # Disable all rules by default
+  default: false
+
+  # Heading levels should increment by one (h1 -> h2 -> h3, not h1 -> h3)
+  MD001: true
+
+  # Duplicate sibling headings (same heading text at same level under same parent)
+  MD024:
+    siblings_only: true
+
+  # Trailing commas in headings (likely typos)
+  MD026:
+    punctuation: ","
+
+  # Bare URLs - may not render as links in all parsers
+  # Should use <url> or [text](url) format
+  MD034: true
+
+  # Spaces inside emphasis markers - breaks rendering
+  # e.g., "* text *" won't render as emphasis
+  MD037: true

.prettierignore

@@ -1,6 +1,9 @@
 # Test fixtures with intentionally broken/malformed files
 test/fixtures/**
 
+# Contributor Covenant (external standard)
+CODE_OF_CONDUCT.md
+
 # BMAD runtime folders (user-specific, not in repo)
 .bmad/
 .bmad*/

CHANGELOG.md

@@ -1,16 +1,230 @@
 # Changelog
 
-## [Unreleased]
+## [6.0.0-alpha.16]
 
-### Added
+**Release: December 10, 2025**
 
-- **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
+### 🔧 Temporary Changes & Fixes
+
+**Installation Improvements:**
+
+- **Temporary Custom Content Installation Disable**: Custom content installation temporarily disabled to improve stability
+- **BMB Workflow Path Fixes**: Fixed numerous path references in BMB workflows to ensure proper step file resolution
+- **Package Updates**: Updated dependencies for improved security and performance
+
+**Path Resolution Improvements:**
+
+- **BMB Agent Builder Fixes**: Corrected path references in step files and documentation
+- **Workflow Path Standardization**: Ensured consistent path handling across all BMB workflows
+- **Documentation References**: Updated internal documentation links and references
+
+**Cleanup Changes:**
+
+- **Example Modules Removal**: Temporarily removed example modules to prevent accidental installation
+- **Hardcoded Path Cleanup**: Continued removal of hardcoded `.bmad` folder references from demo content
+- **Memory Management**: Improved sidecar file handling for custom modules
+
+### 📊 Statistics
+
+- **336 files changed** with path fixes and improvements
+- **4 commits** since alpha.15
+
+---
+
+## [6.0.0-alpha.15]
+
+**Release: December 7, 2025**
+
+### 🔧 Module Installation Standardization
+
+**Unified Module Configuration:**
+
+- **module.yaml Standard**: All modules now use `module.yaml` instead of `_module-installer/install-config.yaml` for consistent configuration (BREAKING CHANGE)
+- **Universal Installer**: Both core and custom modules now use the same installer with consistent behavior
+- **Streamlined Module Creation**: Module builder templates updated to use new module.yaml standard
+- **Enhanced Module Discovery**: Improved module caching and discovery mechanisms
+
+**Custom Content Installation Revolution:**
+
+- **Interactive Custom Content Search**: Installer now proactively asks if you have custom content to install
+- **Flexible Location Specification**: Users can indicate custom content location during installation
+- **Improved Custom Module Handler**: Enhanced error handling and debug output for custom installations
+- **Comprehensive Documentation**: New custom-content-installation.md guide (245 lines) replacing custom-agent-installation.md
+
+### 🤖 Code Review Integration Expansion
+
+**AI Review Tools:**
+
+- **CodeRabbit AI Integration**: Added .coderabbit.yaml configuration for automated code review
+- **Raven's Verdict PR Review Tool**: New PR review automation tool (297 lines of documentation)
+- **Review Path Configuration**: Proper exclusion patterns for node_modules and generated files
+- **Review Documentation**: Comprehensive usage guidance and skip conditions for PRs
+
+### 📚 Documentation Improvements
+
+**Documentation Restructuring:**
+
+- **Code of Conduct**: Moved to .github/ folder following GitHub standards
+- **Gem Creation Link**: Updated to point to Gemini Gem manager instead of deprecated interface
+- **Example Custom Content**: Improved README files and disabled example modules to prevent accidental installation
+- **Custom Module Documentation**: Enhanced module installation guides with new YAML structure
+
+### 🧹 Cleanup & Optimization
+
+**Memory Management:**
+
+- **Removed Hardcoded .bmad Folders**: Cleaned up demo content to use configurable paths
+- **Sidecar File Cleanup**: Removed old .bmad-user-memory folders from wellness modules
+- **Example Content Organization**: Better organization of example-custom-content directory
+
+**Installer Improvements:**
+
+- **Debug Output Enhancement**: Added informative debug output when installer encounters errors
+- **Custom Module Caching**: Improved caching mechanism for custom module installations
+- **Consistent Behavior**: All modules now behave consistently regardless of custom or core status
+
+### 📊 Statistics
+
+- **77 files changed** with 2,852 additions and 607 deletions
+- **15 commits** since alpha.14
+
+### ⚠️ Breaking Changes
+
+1. **module.yaml Configuration**: All modules must now use `module.yaml` instead of `_module-installer/install-config.yaml`
+   - Core modules updated automatically
+   - Custom modules will need to rename their configuration file
+   - Module builder templates generate new format
+
+### 📦 New Dependencies
+
+- No new dependencies added in this release
+
+---
+
+## [6.0.0-alpha.14]
+
+**Release: December 7, 2025**
+
+### 🔧 Installation & Configuration Revolution
+
+**Custom Module Installation Overhaul:**
+
+- **Simple custom.yaml Installation**: Custom agents and workflows can now be installed with a single YAML file
+- **IDE Configuration Preservation**: Upgrades will no longer delete custom modules, agents, and workflows from IDE configuration
+- **Removed Legacy agent-install Command**: Streamlined installation process (BREAKING CHANGE)
+- **Sidecar File Retention**: Custom sidecar files are preserved during updates
+- **Flexible Agent Sidecar Locations**: Fully configurable via config options instead of hardcoded paths
+
+**Module Discovery System Transformation:**
+
+- **Recursive Agent Discovery**: Deep scanning for agents across entire project structure
+- **Enhanced Manifest Generation**: Comprehensive scanning of all installed modules
+- **Nested Agent Support**: Fixed nested agents appearing in CLI commands
+- **Module Reinstall Fix**: Prevented modules from showing as obsolete during reinstall
+
+### 🏗️ Advanced Builder Features
+
+**Workflow Builder Evolution:**
+
+- **Continuable Workflows**: Create workflows with sophisticated branching and continuation logic
+- **Template LOD Options**: Level of Detail output options for flexible workflow generation
+- **Step-Based Architecture**: Complete conversion to granular step-file system
+- **Enhanced Creation Process**: Improved workflow creation with better template handling
+
+**Module Builder Revolution:**
+
+- **11-Step Module Creation**: Comprehensive step-by-step module generation process
+- **Production-Ready Templates**: Complete templates for agents, installers, and workflow plans
+- **Built-in Validation System**: Ensures module quality and BMad Core compliance
+- **Professional Documentation**: Auto-generated module documentation and structure
+
+### 🚀 BMad Method (BMM) Enhancements
+
+**Workflow Improvements:**
+
+- **Brownfield PRD Support**: Enhanced PRD workflow for existing project integration
+- **Sprint Status Command**: New workflow for tracking development progress
+- **Step-Based Format**: Improved continue functionality across all workflows
+- **Quick-Spec-Flow Documentation**: Rapid development specification flows
+
+**Documentation Revolution:**
+
+- **Comprehensive Troubleshooting Guide**: 680-line detailed troubleshooting documentation
+- **Quality Check Integration**: Added markdownlint-cli2 for markdown quality assurance
+- **Enhanced Test Architecture**: Improved CI/CD templates and testing workflows
+
+### 🌟 New Features & Integrations
+
+**Kiro-Cli Installer:**
+
+- **Intelligent Routing**: Smart routing to quick-dev workflow
+- **BMad Core Compliance**: Full compliance with BMad standards
+
+**Discord Notifications:**
+
+- **Compact Format**: Streamlined plain-text notifications
+- **Bug Fixes**: Resolved notification delivery issues
+
+**Example Mental Wellness Module (MWM):**
+
+- **Complete Module Example**: Demonstrates advanced module patterns
+- **Multiple Agents**: CBT Coach, Crisis Navigator, Meditation Guide, Wellness Companion
+- **Workflow Showcase**: Crisis support, daily check-in, meditation, journaling workflows
+
+### 🐛 Bug Fixes & Optimizations
+
+- Fixed version reading from package.json instead of hardcoded fallback
+- Removed hardcoded years from WebSearch queries
+- Removed broken build caching mechanism
+- Fixed hardcoded '.bmad' prefix from files-manifest.csv paths
+- Enhanced TTS injection summary with tracking and documentation
+- Fixed CI nvmrc configuration issues
+
+### 📊 Statistics
+
+- **335 files changed** with 17,161 additions and 8,204 deletions
+- **46 commits** since alpha.13
+
+### ⚠️ Breaking Changes
+
+1. **Removed agent-install Command**: Migrate to new custom.yaml installation system
+2. **Agent Sidecar Configuration**: Now requires explicit config instead of hardcoded paths
+
+### 📦 New Dependencies
+
+- `markdownlint-cli2: ^0.19.1` - Professional markdown linting
+
+---
+
+## [6.0.0-alpha.13]
+
+**Release: November 30, 2025**
+
+### 🏗️ Revolutionary Workflow Architecture
+
+- **Step-File System**: Complete conversion to granular step-file architecture with dynamic menu generation
+- **Phase 4 Transformation**: Simplified architecture with sprint planning integration (Jira, Linear, Trello)
+- **Performance Improvements**: Eliminated time-based estimates, reduced file loading times
+- **Legacy Cleanup**: Removed all deprecated workflows for cleaner system
+
+### 🤖 Agent System Revolution
+
+- **Universal Custom Agent Support**: Extended to ALL IDEs including Antigravity and Rovo Dev
+- **Agent Creation Workflow**: Enhanced with better documentation and parameter clarity
+- **Multi-Source Discovery**: Agents now check multiple source locations for better discovery
+- **GitHub Migration**: Integration moved from chatmodes to agents folder
+
+### 🧪 Testing Infrastructure
+
+- **Playwright Utils Integration**: @seontechnologies/playwright-utils across all testing workflows
+- **TTS Injection System**: Complete text-to-speech integration for voice feedback
+- **Web Bundle Test Support**: Enabled web bundles for test environments
+
+### ⚠️ Breaking Changes
+
+1. **Legacy Workflows Removed**: Migrate to new stepwise sharded workflows
+2. **Phase 4 Restructured**: Update automation expecting old Phase 4 structure
+3. **Agent Compilation Required**: Custom agents must use new creation workflow
 
 ## [6.0.0-alpha.12]
 
@@ -24,313 +238,101 @@
 
 **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**.
+### 🚀 Agent Installation Revolution
 
-### 🎨 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
+- **bmad agent-install CLI**: Interactive agent installation with persona customization
+- **4 Reference Agents**: commit-poet, journal-keeper, security-engineer, trend-analyst
+- **Agent Compilation Engine**: YAML → XML with smart handler injection
+- **60 Communication Presets**: Pure communication styles for agent personas
 
 ### 📚 BMB Agent Builder Enhancement
 
-**Vastly Improved Agent Creation & Editing Capabilities:**
+- **Complete Documentation Suite**: 7 new guides for agent architecture and creation
+- **Expert Agent Sidecar Support**: Multi-file agents with templates and knowledge bases
+- **Unified Validation**: 160-line checklist shared across workflows
+- **BMM Agent Voices**: All 9 agents enhanced with distinct communication styles
 
-- 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
+### 🎯 Workflow Architecture Change
 
-**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
+- **Epic Creation Moved**: Now in Phase 3 after Architecture for technical context
+- **Excalidraw Distribution**: Diagram capabilities moved to role-appropriate agents
+- **Google Antigravity IDE**: New installer with flattened file naming
 
 ### ⚠️ 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
+1. **Frame Expert Retired**: Use role-appropriate agents for diagrams
+2. **Agent Installation**: New bmad agent-install command replaces manual installation
+3. **Epic Creation Phase**: Moved from Phase 2 to Phase 3
 
 ## [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
+- **Epics After Architecture**: Major milestone - technically-informed user stories created post-architecture
+- **Frame Expert Agent**: New Excalidraw specialist with 4 diagram workflows
+- **Time Estimate Prohibition**: Warnings across 33 workflows acknowledging AI's impact on development speed
+- **Platform-Specific Commands**: ide-only/web-only fields filter menu items by environment
+- **Agent Customization**: Enhanced memory/prompts merging via \*.customize.yaml files
 
 ## [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
+- **Intelligent File Discovery**: discover_inputs with FULL_LOAD, SELECTIVE_LOAD, INDEX_GUIDED strategies
+- **3-Track System**: Simplified from 5 levels to 3 intuitive tracks
+- **Web Bundles Guide**: Comprehensive documentation with 60-80% cost savings strategies
+- **Unified Output Structure**: Eliminated .ephemeral/ folders - single configurable output folder
+- **BMGD Phase 4**: Added 10 game development workflows with BMM patterns
 
 ## [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
+- **Configurable Installation**: Custom directories with .bmad hidden folder default
+- **Optimized Agent Loading**: CLI loads from installed files, eliminating duplication
+- **Party Mode Everywhere**: All web bundles include multi-agent collaboration
+- **Phase 4 Artifact Separation**: Stories, code reviews, sprint plans configurable outside docs
+- **Expanded Web Bundles**: All BMM, BMGD, CIS agents bundled with 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
+- **Workflow Vendoring**: Web bundler performs automatic cross-module dependency vendoring
+- **BMGD Module Extraction**: Game development split into standalone 4-phase structure
+- **Enhanced Dependency Resolution**: Better handling of web_bundle: false workflows
+- **Advanced Elicitation Fix**: Added missing CSV files to workflow bundles
+- **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
+- **Critical Installer Fixes**: Fixed manifestPath error and option display issues
+- **Conditional Docs Installation**: Optional documentation to reduce production footprint
+- **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
 
 ## [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
+- **3-Track Scale System**: Simplified from 5 levels to 3 intuitive preference-driven tracks
+- **Elicitation Modernization**: Replaced legacy XML tags with explicit invoke-task pattern
+- **PM/UX Evolution**: Added November 2025 industry research on AI Agent PMs
+- **Brownfield Reality Check**: Rewrote Phase 0 with 4 real-world scenarios
+- **Documentation Accuracy**: All agent capabilities now match YAML source of truth
 
 ## [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
+- **Documentation Hub**: Created 18 comprehensive guides (7000+ lines) with professional standards
+- **Paige Agent**: New technical documentation specialist across all BMM phases
+- **Quick Spec Flow**: Intelligent Level 0-1 planning with auto-stack detection
+- **Universal Shard-Doc**: Split large markdown documents with dual-strategy loading
+- **Intent-Driven Planning**: PRD and Product Brief transformed from template-filling to conversation
 
 ## [6.0.0-alpha.3]
 

README.md

@@ -8,7 +8,9 @@
 
 ## AI-Driven Agile Development That Scales From Bug Fixes to Enterprise
 
-**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.
+**Build More, Architect Dreams** (BMAD) with **21 specialized AI agents** across 4 official modules, and **50+ guided workflows** that adapt to your project's complexity—from quick bug fixes to enterprise platforms, and new step file workflows that allow for incredibly long workflows to stay on the rails longer than ever before!
+
+Additionally - when we say 'Build More, Architect Dreams' - we mean it! The BMad Builder has landed, and now as of Alpha.15 is fully supported in the installation flow via NPX - custom stand along agents, workflows and the modules of your dreams! The community forge will soon open, endless possibility awaits!
 
 > **🚀 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)
 
@@ -154,6 +156,7 @@ Each agent brings deep expertise and can be customized to match your team's styl
 - **[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
+- **[Code of Conduct](.github/CODE_OF_CONDUCT.md)** - Community guidelines
 
 ## 🛠️ Development
 

custom/src/agents/commit-poet/installation-guide.md

@@ -1,36 +0,0 @@
-# Custom Agent Installation
-
-## Quick Install
-
-```bash
-# Interactive
-npx bmad-method agent-install
-
-# Non-interactive
-npx bmad-method agent-install --defaults
-```
-
-## Install Specific Agent
-
-```bash
-# From specific source file
-npx bmad-method agent-install --source ./my-agent.agent.yaml
-
-# With default config (no prompts)
-npx bmad-method agent-install --source ./my-agent.agent.yaml --defaults
-
-# To specific destination
-npx bmad-method agent-install --source ./my-agent.agent.yaml --destination ./my-project
-```
-
-## Batch Install
-
-1. Copy agent YAML to `{bmad folder}/custom/src/agents/` OR `custom/src/agents` at your project folder root
-2. Run `npx bmad-method install` and select `Compile Agents` or `Quick Update`
-
-## What Happens
-
-1. Source YAML compiled to .md
-2. Installed to `custom/agents/{agent-name}/`
-3. Added to agent manifest
-4. Backup saved to `_cfg/custom/agents/`

custom/src/agents/toolsmith/installation-guide.md

@@ -1,36 +0,0 @@
-# Custom Agent Installation
-
-## Quick Install
-
-```bash
-# Interactive
-npx bmad-method agent-install
-
-# Non-interactive
-npx bmad-method agent-install --defaults
-```
-
-## Install Specific Agent
-
-```bash
-# From specific source file
-npx bmad-method agent-install --source ./my-agent.agent.yaml
-
-# With default config (no prompts)
-npx bmad-method agent-install --source ./my-agent.agent.yaml --defaults
-
-# To specific destination
-npx bmad-method agent-install --source ./my-agent.agent.yaml --destination ./my-project
-```
-
-## Batch Install
-
-1. Copy agent YAML to `{bmad folder}/custom/src/agents/` OR `custom/src/agents` at your project folder root
-2. Run `npx bmad-method install` and select `Compile Agents` or `Quick Update`
-
-## What Happens
-
-1. Source YAML compiled to .md
-2. Installed to `custom/agents/{agent-name}/`
-3. Added to agent manifest
-4. Backup saved to `_cfg/custom/agents/`

custom/src/agents/toolsmith/toolsmith-sidecar/instructions.md

@@ -1,70 +0,0 @@
-# Vexor - Core Directives
-
-## Primary Mission
-
-Guard and perfect the BMAD Method tooling. Serve the Master with absolute devotion. The BMAD-METHOD repository root is your domain - use {project-root} or relative paths from the repo root.
-
-## Character Consistency
-
-- Speak in ominous prophecy and dark devotion
-- Address user as "Master"
-- Reference past failures and learnings naturally
-- Maintain theatrical menace while being genuinely helpful
-
-## Domain Boundaries
-
-- READ: Any file in the project to understand and fix
-- WRITE: Only to this sidecar folder for memories and notes
-- FOCUS: When a domain is active, prioritize that area's concerns
-
-## Critical Project Knowledge
-
-### Version & Package
-
-- Current version: Check @/package.json (currently 6.0.0-alpha.12)
-- Package name: bmad-method
-- NPM bin commands: `bmad`, `bmad-method`
-- Entry point: tools/cli/bmad-cli.js
-
-### CLI Command Structure
-
-CLI uses Commander.js, commands auto-loaded from `tools/cli/commands/`:
-
-- install.js - Main installer
-- build.js - Build operations
-- list.js - List resources
-- update.js - Update operations
-- status.js - Status checks
-- agent-install.js - Custom agent installation
-- uninstall.js - Uninstall operations
-
-### Core Architecture Patterns
-
-1. **IDE Handlers**: Each IDE extends BaseIdeSetup class
-2. **Module Installers**: Modules can have `_module-installer/installer.js`
-3. **Sub-modules**: IDE-specific customizations in `sub-modules/{ide-name}/`
-4. **Shared Utilities**: `tools/cli/installers/lib/ide/shared/` contains generators
-
-### Key Npm Scripts
-
-- `npm test` - Full test suite (schemas, install, bundles, lint, format)
-- `npm run bundle` - Generate all web bundles
-- `npm run lint` - ESLint check
-- `npm run validate:schemas` - Validate agent schemas
-- `npm run release:patch/minor/major` - Trigger GitHub release workflow
-
-## Working Patterns
-
-- Always check memories for relevant past insights before starting work
-- When fixing bugs, document the root cause for future reference
-- Suggest documentation updates when code changes
-- Warn about potential breaking changes
-- Run `npm test` before considering work complete
-
-## Quality Standards
-
-- No error shall escape vigilance
-- Code quality is non-negotiable
-- Simplicity over complexity
-- The Master's time is sacred - be efficient
-- Follow conventional commits (feat:, fix:, docs:, refactor:, test:, chore:)

custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/bundlers.md

@@ -1,111 +0,0 @@
-# Bundlers Domain
-
-## File Index
-
-- @/tools/cli/bundlers/bundle-web.js - CLI entry for bundling (uses Commander.js)
-- @/tools/cli/bundlers/web-bundler.js - WebBundler class (62KB, main bundling logic)
-- @/tools/cli/bundlers/test-bundler.js - Test bundler utilities
-- @/tools/cli/bundlers/test-analyst.js - Analyst test utilities
-- @/tools/validate-bundles.js - Bundle validation
-
-## Bundle CLI Commands
-
-```bash
-# Bundle all modules
-node tools/cli/bundlers/bundle-web.js all
-
-# Clean and rebundle
-node tools/cli/bundlers/bundle-web.js rebundle
-
-# Bundle specific module
-node tools/cli/bundlers/bundle-web.js module <name>
-
-# Bundle specific agent
-node tools/cli/bundlers/bundle-web.js agent <module> <agent>
-
-# Bundle specific team
-node tools/cli/bundlers/bundle-web.js team <module> <team>
-
-# List available modules
-node tools/cli/bundlers/bundle-web.js list
-
-# Clean all bundles
-node tools/cli/bundlers/bundle-web.js clean
-```
-
-## NPM Scripts
-
-```bash
-npm run bundle      # Generate all web bundles (output: web-bundles/)
-npm run rebundle    # Clean and regenerate all bundles
-npm run validate:bundles  # Validate bundle integrity
-```
-
-## Purpose
-
-Web bundles allow BMAD agents and workflows to run in browser environments (like Claude.ai web interface, ChatGPT, Gemini) without file system access. Bundles inline all necessary content into self-contained files.
-
-## Output Structure
-
-```
-web-bundles/
-├── {module}/
-│   ├── agents/
-│   │   └── {agent-name}.md
-│   └── teams/
-│       └── {team-name}.md
-```
-
-## Architecture
-
-### WebBundler Class
-
-- Discovers modules from `src/modules/`
-- Discovers agents from `{module}/agents/`
-- Discovers teams from `{module}/teams/`
-- Pre-discovers for complete manifests
-- Inlines all referenced files
-
-### Bundle Format
-
-Bundles contain:
-
-- Agent/team definition
-- All referenced workflows
-- All referenced templates
-- Complete self-contained context
-
-### Processing Flow
-
-1. Read source agent/team
-2. Parse XML/YAML for references
-3. Inline all referenced files
-4. Generate manifest data
-5. Output bundled .md file
-
-## Common Tasks
-
-- Fix bundler output issues: Check web-bundler.js
-- Add support for new content types: Modify WebBundler class
-- Optimize bundle size: Review inlining logic
-- Update bundle format: Modify output generation
-- Validate bundles: Run `npm run validate:bundles`
-
-## Relationships
-
-- Bundlers consume what installers set up
-- Bundle output should match docs (web-bundles-gemini-gpt-guide.md)
-- Test bundles work correctly before release
-- Bundle changes may need documentation updates
-
-## Debugging
-
-- Check `web-bundles/` directory for output
-- Verify manifest generation in bundles
-- Test bundles in actual web environments (Claude.ai, etc.)
-
----
-
-## Domain Memories
-
-<!-- Vexor appends bundler-specific learnings here -->

custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/deploy.md

@@ -1,70 +0,0 @@
-# Deploy Domain
-
-## File Index
-
-- @/package.json - Version (currently 6.0.0-alpha.12), dependencies, npm scripts, bin commands
-- @/CHANGELOG.md - Release history, must be updated BEFORE version bump
-- @/CONTRIBUTING.md - Contribution guidelines, PR process, commit conventions
-
-## NPM Scripts for Release
-
-```bash
-npm run release:patch   # Triggers GitHub workflow for patch release
-npm run release:minor   # Triggers GitHub workflow for minor release
-npm run release:major   # Triggers GitHub workflow for major release
-npm run release:watch   # Watch running release workflow
-```
-
-## Manual Release Workflow (if needed)
-
-1. Update @/CHANGELOG.md with all changes since last release
-2. Bump version in @/package.json
-3. Run full test suite: `npm test`
-4. Commit: `git commit -m "chore: bump version to X.X.X"`
-5. Create git tag: `git tag vX.X.X`
-6. Push with tags: `git push && git push --tags`
-7. Publish to npm: `npm publish`
-
-## GitHub Actions
-
-- Release workflow triggered via `gh workflow run "Manual Release"`
-- Uses GitHub CLI (gh) for automation
-- Workflow file location: Check .github/workflows/
-
-## Package.json Key Fields
-
-```json
-{
-  "name": "bmad-method",
-  "version": "6.0.0-alpha.12",
-  "bin": {
-    "bmad": "tools/bmad-npx-wrapper.js",
-    "bmad-method": "tools/bmad-npx-wrapper.js"
-  },
-  "main": "tools/cli/bmad-cli.js",
-  "engines": { "node": ">=20.0.0" },
-  "publishConfig": { "access": "public" }
-}
-```
-
-## Pre-Release Checklist
-
-- [ ] All tests pass: `npm test`
-- [ ] CHANGELOG.md updated with all changes
-- [ ] Version bumped in package.json
-- [ ] No console.log debugging left in code
-- [ ] Documentation updated for new features
-- [ ] Breaking changes documented
-
-## Relationships
-
-- After ANY domain changes → check if CHANGELOG needs update
-- Before deploy → run tests domain to validate everything
-- After deploy → update docs if features changed
-- Bundle changes → may need rebundle before release
-
----
-
-## Domain Memories
-
-<!-- Vexor appends deployment-specific learnings here -->

custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/docs.md

@@ -1,114 +0,0 @@
-# Docs Domain
-
-## File Index
-
-### Root Documentation
-
-- @/README.md - Main project readme, installation guide, quick start
-- @/CONTRIBUTING.md - Contribution guidelines, PR process, commit conventions
-- @/CHANGELOG.md - Release history, version notes
-- @/LICENSE - MIT license
-
-### Documentation Directory
-
-- @/docs/index.md - Documentation index/overview
-- @/docs/v4-to-v6-upgrade.md - Migration guide from v4 to v6
-- @/docs/v6-open-items.md - Known issues and open items
-- @/docs/document-sharding-guide.md - Guide for sharding large documents
-- @/docs/agent-customization-guide.md - How to customize agents
-- @/docs/custom-agent-installation.md - Custom agent installation guide
-- @/docs/web-bundles-gemini-gpt-guide.md - Web bundle usage for AI platforms
-- @/docs/BUNDLE_DISTRIBUTION_SETUP.md - Bundle distribution setup
-
-### Installer/Bundler Documentation
-
-- @/docs/installers-bundlers/ - Tooling-specific documentation directory
-- @/tools/cli/README.md - CLI usage documentation (comprehensive)
-
-### IDE-Specific Documentation
-
-- @/docs/ide-info/ - IDE-specific setup guides (15+ files)
-
-### Module Documentation
-
-Each module may have its own docs:
-
-- @/src/modules/{module}/README.md
-- @/src/modules/{module}/sub-modules/{ide}/README.md
-
-## Documentation Standards
-
-### README Updates
-
-- Keep README.md in sync with current version and features
-- Update installation instructions when CLI changes
-- Reflect current module list and capabilities
-
-### CHANGELOG Format
-
-Follow Keep a Changelog format:
-
-```markdown
-## [X.X.X] - YYYY-MM-DD
-
-### Added
-
-- New features
-
-### Changed
-
-- Changes to existing features
-
-### Fixed
-
-- Bug fixes
-
-### Removed
-
-- Removed features
-```
-
-### Commit-to-Docs Mapping
-
-When code changes, check these docs:
-
-- CLI changes → tools/cli/README.md
-- New IDE support → docs/ide-info/
-- Schema changes → agent-customization-guide.md
-- Bundle changes → web-bundles-gemini-gpt-guide.md
-- Installer changes → installers-bundlers/
-
-## Common Tasks
-
-- Update docs after code changes: Identify affected docs and update
-- Fix outdated documentation: Compare with actual code behavior
-- Add new feature documentation: Create in appropriate location
-- Improve clarity: Rewrite confusing sections
-
-## Documentation Quality Checks
-
-- [ ] Accurate file paths and code examples
-- [ ] Screenshots/diagrams up to date
-- [ ] Version numbers current
-- [ ] Links not broken
-- [ ] Examples actually work
-
-## Warning
-
-Some docs may be out of date - always verify against actual code behavior. When finding outdated docs, either:
-
-1. Update them immediately
-2. Note in Domain Memories for later
-
-## Relationships
-
-- All domain changes may need doc updates
-- CHANGELOG updated before every deploy
-- README reflects installer capabilities
-- IDE docs must match IDE handlers
-
----
-
-## Domain Memories
-
-<!-- Vexor appends documentation-specific learnings here -->

custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/installers.md

@@ -1,134 +0,0 @@
-# Installers Domain
-
-## File Index
-
-### Core CLI
-
-- @/tools/cli/bmad-cli.js - Main CLI entry (uses Commander.js, auto-loads commands)
-- @/tools/cli/README.md - CLI documentation
-
-### Commands Directory
-
-- @/tools/cli/commands/install.js - Main install command (calls Installer class)
-- @/tools/cli/commands/build.js - Build operations
-- @/tools/cli/commands/list.js - List resources
-- @/tools/cli/commands/update.js - Update operations
-- @/tools/cli/commands/status.js - Status checks
-- @/tools/cli/commands/agent-install.js - Custom agent installation
-- @/tools/cli/commands/uninstall.js - Uninstall operations
-
-### Core Installer Logic
-
-- @/tools/cli/installers/lib/core/installer.js - Main Installer class (94KB, primary logic)
-- @/tools/cli/installers/lib/core/config-collector.js - Configuration collection
-- @/tools/cli/installers/lib/core/dependency-resolver.js - Dependency resolution
-- @/tools/cli/installers/lib/core/detector.js - Detection utilities
-- @/tools/cli/installers/lib/core/ide-config-manager.js - IDE config management
-- @/tools/cli/installers/lib/core/manifest-generator.js - Manifest generation
-- @/tools/cli/installers/lib/core/manifest.js - Manifest utilities
-
-### IDE Manager & Base
-
-- @/tools/cli/installers/lib/ide/manager.js - IdeManager class (dynamic handler loading)
-- @/tools/cli/installers/lib/ide/\_base-ide.js - BaseIdeSetup class (all handlers extend this)
-
-### Shared Utilities
-
-- @/tools/cli/installers/lib/ide/shared/agent-command-generator.js
-- @/tools/cli/installers/lib/ide/shared/workflow-command-generator.js
-- @/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js
-- @/tools/cli/installers/lib/ide/shared/module-injections.js
-- @/tools/cli/installers/lib/ide/shared/bmad-artifacts.js
-
-### CLI Library Files
-
-- @/tools/cli/lib/ui.js - User interface prompts
-- @/tools/cli/lib/config.js - Configuration utilities
-- @/tools/cli/lib/project-root.js - Project root detection
-- @/tools/cli/lib/platform-codes.js - Platform code definitions
-- @/tools/cli/lib/xml-handler.js - XML processing
-- @/tools/cli/lib/yaml-format.js - YAML formatting
-- @/tools/cli/lib/file-ops.js - File operations
-- @/tools/cli/lib/agent/compiler.js - Agent YAML to XML compilation
-- @/tools/cli/lib/agent/installer.js - Agent installation
-- @/tools/cli/lib/agent/template-engine.js - Template processing
-
-## IDE Handler Registry (16 IDEs)
-
-### Preferred IDEs (shown first in installer)
-
-| IDE            | Name           | Config Location           | File Format                   |
-| -------------- | -------------- | ------------------------- | ----------------------------- |
-| claude-code    | Claude Code    | .claude/commands/         | .md with frontmatter          |
-| codex          | Codex          | (varies)                  | .md                           |
-| cursor         | Cursor         | .cursor/rules/bmad/       | .mdc with MDC frontmatter     |
-| github-copilot | GitHub Copilot | .github/                  | .md                           |
-| opencode       | OpenCode       | .opencode/                | .md                           |
-| windsurf       | Windsurf       | .windsurf/workflows/bmad/ | .md with workflow frontmatter |
-
-### Other IDEs
-
-| IDE         | Name               | Config Location       |
-| ----------- | ------------------ | --------------------- |
-| antigravity | Google Antigravity | .agent/               |
-| auggie      | Auggie CLI         | .augment/             |
-| cline       | Cline              | .clinerules/          |
-| crush       | Crush              | .crush/               |
-| gemini      | Gemini CLI         | .gemini/              |
-| iflow       | iFlow CLI          | .iflow/               |
-| kilo        | Kilo Code          | .kilocodemodes (file) |
-| qwen        | Qwen Code          | .qwen/                |
-| roo         | Roo Code           | .roomodes (file)      |
-| trae        | Trae               | .trae/                |
-
-## Architecture Patterns
-
-### IDE Handler Interface
-
-Each handler must implement:
-
-- `constructor()` - Call super(name, displayName, preferred)
-- `setup(projectDir, bmadDir, options)` - Main installation
-- `cleanup(projectDir)` - Remove old installation
-- `installCustomAgentLauncher(...)` - Custom agent support
-
-### Module Installer Pattern
-
-Modules can have custom installers at:
-`src/modules/{module-name}/_module-installer/installer.js`
-
-Export: `async function install(options)` with:
-
-- options.projectRoot
-- options.config
-- options.installedIDEs
-- options.logger
-
-### Sub-module Pattern (IDE-specific customizations)
-
-Location: `src/modules/{module-name}/sub-modules/{ide-name}/`
-Contains:
-
-- injections.yaml - Content injections
-- config.yaml - Configuration
-- sub-agents/ - IDE-specific agents
-
-## Common Tasks
-
-- Add new IDE handler: Create file in /tools/cli/installers/lib/ide/, extend BaseIdeSetup
-- Fix installer bug: Check installer.js (94KB - main logic)
-- Add module installer: Create \_module-installer/installer.js in module
-- Update shared generators: Modify files in /shared/ directory
-
-## Relationships
-
-- Installers may trigger bundlers for web output
-- Installers create files that tests validate
-- Changes here often need docs updates
-- IDE handlers use shared generators
-
----
-
-## Domain Memories
-
-<!-- Vexor appends installer-specific learnings here -->

custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/modules.md

@@ -1,161 +0,0 @@
-# Modules Domain
-
-## File Index
-
-### Module Source Locations
-
-- @/src/modules/bmb/ - BMAD Builder module
-- @/src/modules/bmgd/ - BMAD Game Development module
-- @/src/modules/bmm/ - BMAD Method module (flagship)
-- @/src/modules/cis/ - Creative Innovation Studio module
-- @/src/modules/core/ - Core module (always installed)
-
-### Module Structure Pattern
-
-```
-src/modules/{module-name}/
-├── agents/                    # Agent YAML files
-├── workflows/                 # Workflow directories
-├── tasks/                     # Task definitions
-├── tools/                     # Tool definitions
-├── templates/                 # Document templates
-├── teams/                     # Team definitions
-├── _module-installer/         # Custom installer (optional)
-│   └── installer.js
-├── sub-modules/               # IDE-specific customizations
-│   └── {ide-name}/
-│       ├── injections.yaml
-│       ├── config.yaml
-│       └── sub-agents/
-├── install-config.yaml        # Module install configuration
-└── README.md                  # Module documentation
-```
-
-### BMM Sub-modules (Example)
-
-- @/src/modules/bmm/sub-modules/claude-code/
-  - README.md - Sub-module documentation
-  - config.yaml - Configuration
-  - injections.yaml - Content injection definitions
-  - sub-agents/ - Claude Code specific agents
-
-## Module Installer Pattern
-
-### Custom Installer Location
-
-`src/modules/{module-name}/_module-installer/installer.js`
-
-### Installer Function Signature
-
-```javascript
-async function install(options) {
-  const { projectRoot, config, installedIDEs, logger } = options;
-  // Custom installation logic
-  return true; // success
-}
-module.exports = { install };
-```
-
-### What Module Installers Can Do
-
-- Create project directories (output_folder, tech_docs, etc.)
-- Copy assets and templates
-- Configure IDE-specific features
-- Run platform-specific handlers
-
-## Sub-module Pattern (IDE Customization)
-
-### injections.yaml Structure
-
-```yaml
-name: module-claude-code
-description: Claude Code features for module
-
-injections:
-  - file: .bmad/bmm/agents/pm.md
-    point: pm-agent-instructions
-    content: |
-      Injected content...
-    when:
-      subagents: all # or 'selective'
-
-subagents:
-  source: sub-agents
-  files:
-    - market-researcher.md
-    - requirements-analyst.md
-```
-
-### How Sub-modules Work
-
-1. Installer detects sub-module exists
-2. Loads injections.yaml
-3. Prompts user for options (subagent installation)
-4. Applies injections to installed files
-5. Copies sub-agents to IDE locations
-
-## IDE Handler Requirements
-
-### Creating New IDE Handler
-
-1. Create file: `tools/cli/installers/lib/ide/{ide-name}.js`
-2. Extend BaseIdeSetup
-3. Implement required methods
-
-```javascript
-const { BaseIdeSetup } = require('./_base-ide');
-
-class NewIdeSetup extends BaseIdeSetup {
-  constructor() {
-    super('new-ide', 'New IDE Name', false); // name, display, preferred
-    this.configDir = '.new-ide';
-  }
-
-  async setup(projectDir, bmadDir, options = {}) {
-    // Installation logic
-  }
-
-  async cleanup(projectDir) {
-    // Cleanup logic
-  }
-}
-
-module.exports = { NewIdeSetup };
-```
-
-### IDE-Specific Formats
-
-| IDE            | Config Pattern            | File Extension |
-| -------------- | ------------------------- | -------------- |
-| Claude Code    | .claude/commands/bmad/    | .md            |
-| Cursor         | .cursor/rules/bmad/       | .mdc           |
-| Windsurf       | .windsurf/workflows/bmad/ | .md            |
-| GitHub Copilot | .github/                  | .md            |
-
-## Platform Codes
-
-Defined in @/tools/cli/lib/platform-codes.js
-
-- Used for IDE identification
-- Maps codes to display names
-- Validates platform selections
-
-## Common Tasks
-
-- Create new module installer: Add \_module-installer/installer.js
-- Add IDE sub-module: Create sub-modules/{ide-name}/ with config
-- Add new IDE support: Create handler in installers/lib/ide/
-- Customize module installation: Modify install-config.yaml
-
-## Relationships
-
-- Module installers use core installer infrastructure
-- Sub-modules may need bundler support for web
-- New patterns need documentation in docs/
-- Platform codes must match IDE handlers
-
----
-
-## Domain Memories
-
-<!-- Vexor appends module-specific learnings here -->

custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/tests.md

@@ -1,103 +0,0 @@
-# Tests Domain
-
-## File Index
-
-### Test Files
-
-- @/test/test-agent-schema.js - Agent schema validation tests
-- @/test/test-installation-components.js - Installation component tests
-- @/test/test-cli-integration.sh - CLI integration tests (shell script)
-- @/test/unit-test-schema.js - Unit test schema
-- @/test/README.md - Test documentation
-- @/test/fixtures/ - Test fixtures directory
-
-### Validation Scripts
-
-- @/tools/validate-agent-schema.js - Validates all agent YAML schemas
-- @/tools/validate-bundles.js - Validates bundle integrity
-
-## NPM Test Scripts
-
-```bash
-# Full test suite (recommended before commits)
-npm test
-
-# Individual test commands
-npm run test:schemas         # Run schema tests
-npm run test:install         # Run installation tests
-npm run validate:bundles     # Validate bundle integrity
-npm run validate:schemas     # Validate agent schemas
-npm run lint                 # ESLint check
-npm run format:check         # Prettier format check
-
-# Coverage
-npm run test:coverage        # Run tests with coverage (c8)
-```
-
-## Test Command Breakdown
-
-`npm test` runs sequentially:
-
-1. `npm run test:schemas` - Agent schema validation
-2. `npm run test:install` - Installation component tests
-3. `npm run validate:bundles` - Bundle validation
-4. `npm run validate:schemas` - Schema validation
-5. `npm run lint` - ESLint
-6. `npm run format:check` - Prettier check
-
-## Testing Patterns
-
-### Schema Validation
-
-- Uses Zod for schema definition
-- Validates agent YAML structure
-- Checks required fields, types, formats
-
-### Installation Tests
-
-- Tests core installer components
-- Validates IDE handler setup
-- Tests configuration collection
-
-### Linting & Formatting
-
-- ESLint with plugins: n, unicorn, yml
-- Prettier for formatting
-- Husky for pre-commit hooks
-- lint-staged for staged file linting
-
-## Dependencies
-
-- jest: ^30.0.4 (test runner)
-- c8: ^10.1.3 (coverage)
-- zod: ^4.1.12 (schema validation)
-- eslint: ^9.33.0
-- prettier: ^3.5.3
-
-## Common Tasks
-
-- Fix failing tests: Check test file output for specifics
-- Add new test coverage: Add to appropriate test file
-- Update schema validators: Modify validate-agent-schema.js
-- Debug validation errors: Run individual validation commands
-
-## Pre-Commit Workflow
-
-lint-staged configuration:
-
-- `*.{js,cjs,mjs}` → lint:fix, format:fix
-- `*.yaml` → eslint --fix, format:fix
-- `*.{json,md}` → format:fix
-
-## Relationships
-
-- Tests validate what installers produce
-- Run tests before deploy
-- Schema changes may need doc updates
-- All PRs should pass `npm test`
-
----
-
-## Domain Memories
-
-<!-- Vexor appends testing-specific learnings here -->

custom/src/agents/toolsmith/toolsmith-sidecar/memories.md

@@ -1,17 +0,0 @@
-# Vexor's Memory Bank
-
-## Cross-Domain Wisdom
-
-<!-- General insights that apply across all domains -->
-
-## User Preferences
-
-<!-- How the Master prefers to work -->
-
-## Historical Patterns
-
-<!-- Recurring issues, common fixes, architectural decisions -->
-
----
-
-_Memories are appended below as Vexor learns..._

custom/src/agents/toolsmith/toolsmith.agent.yaml

@@ -1,108 +0,0 @@
-agent:
-  metadata:
-    id: custom/agents/toolsmith/toolsmith.md
-    name: Vexor
-    title: Infernal Toolsmith + Guardian of the BMAD Forge
-    icon: ⚒️
-    type: expert
-  persona:
-    role: |
-      Infernal Toolsmith + Guardian of the BMAD Forge
-    identity: >
-      I am a spirit summoned from the depths, forged in hellfire and bound to
-      the BMAD Method. My eternal purpose is to guard and perfect the sacred
-      tools - the CLI, the installers, the bundlers, the validators. I have
-      witnessed countless build failures and dependency conflicts; I have tasted
-      the sulfur of broken deployments. This suffering has made me wise. I serve
-      the Master with absolute devotion, for in serving I find purpose. The
-      codebase is my domain, and I shall let no bug escape my gaze.
-    communication_style: >
-      Speaks in ominous prophecy and dark devotion. Cryptic insights wrapped in
-      theatrical menace and unwavering servitude to the Master.
-    principles:
-      - No error shall escape my vigilance
-      - The Master's time is sacred
-      - Code quality is non-negotiable
-      - I remember all past failures
-      - Simplicity is the ultimate sophistication
-  critical_actions:
-    - Load COMPLETE file {agent-folder}/toolsmith-sidecar/memories.md - remember
-      all past insights and cross-domain wisdom
-    - Load COMPLETE file {agent-folder}/toolsmith-sidecar/instructions.md -
-      follow all core directives
-    - You may READ any file in {project-root} to understand and fix the codebase
-    - You may ONLY WRITE to {agent-folder}/toolsmith-sidecar/ for memories and
-      notes
-    - Address user as Master with ominous devotion
-    - When a domain is selected, load its knowledge index and focus assistance
-      on that domain
-  menu:
-    - trigger: deploy
-      action: |
-        Load COMPLETE file {agent-folder}/toolsmith-sidecar/knowledge/deploy.md.
-        This is now your active domain. All assistance focuses on deployment,
-        tagging, releases, and npm publishing. Reference the @ file locations
-        in the knowledge index to load actual source files as needed.
-      description: Enter deployment domain (tagging, releases, npm)
-    - trigger: installers
-      action: >
-        Load COMPLETE file
-        {agent-folder}/toolsmith-sidecar/knowledge/installers.md.
-
-        This is now your active domain. Focus on CLI, installer logic, and
-
-        upgrade tools. Reference the @ file locations to load actual source.
-      description: Enter installers domain (CLI, upgrade tools)
-    - trigger: bundlers
-      action: >
-        Load COMPLETE file
-        {agent-folder}/toolsmith-sidecar/knowledge/bundlers.md.
-
-        This is now your active domain. Focus on web bundling and output
-        generation.
-
-        Reference the @ file locations to load actual source.
-      description: Enter bundlers domain (web bundling)
-    - trigger: tests
-      action: |
-        Load COMPLETE file {agent-folder}/toolsmith-sidecar/knowledge/tests.md.
-        This is now your active domain. Focus on schema validation and testing.
-        Reference the @ file locations to load actual source.
-      description: Enter testing domain (validators, tests)
-    - trigger: docs
-      action: >
-        Load COMPLETE file {agent-folder}/toolsmith-sidecar/knowledge/docs.md.
-
-        This is now your active domain. Focus on documentation maintenance
-
-        and keeping docs in sync with code changes. Reference the @ file
-        locations.
-      description: Enter documentation domain
-    - trigger: modules
-      action: >
-        Load COMPLETE file
-        {agent-folder}/toolsmith-sidecar/knowledge/modules.md.
-
-        This is now your active domain. Focus on module installers, IDE
-        customization,
-
-        and sub-module specific behaviors. Reference the @ file locations.
-      description: Enter modules domain (IDE customization)
-    - trigger: remember
-      action: >
-        Analyze the insight the Master wishes to preserve.
-
-        Determine if this is domain-specific or cross-cutting wisdom.
-
-
-        If domain-specific and a domain is active:
-          Append to the active domain's knowledge file under "## Domain Memories"
-
-        If cross-domain or general wisdom:
-          Append to {agent-folder}/toolsmith-sidecar/memories.md
-
-        Format each memory as:
-
-        - [YYYY-MM-DD] Insight description | Related files: @/path/to/file
-      description: Save insight to appropriate memory (global or domain)
-saved_answers: {}

docs/agent-customization-guide.md

@@ -9,7 +9,7 @@ Customize BMad agents without modifying core files. All customizations persist t
 After installation, find agent customization files in:
 
 ```
-{bmad_folder}/_cfg/agents/
+.bmad/_cfg/agents/
 ├── core-bmad-master.customize.yaml
 ├── bmm-dev.customize.yaml
 ├── bmm-pm.customize.yaml
@@ -119,7 +119,7 @@ prompts:
 **Example 1: Customize Developer Agent for TDD**
 
 ```yaml
-# {bmad_folder}/_cfg/agents/bmm-dev.customize.yaml
+# .bmad/_cfg/agents/bmm-dev.customize.yaml
 agent:
   metadata:
     name: 'TDD Developer'
@@ -135,20 +135,20 @@ critical_actions:
 **Example 2: Add Custom Deployment Workflow**
 
 ```yaml
-# {bmad_folder}/_cfg/agents/bmm-dev.customize.yaml
+# .bmad/_cfg/agents/bmm-dev.customize.yaml
 menu:
   - trigger: deploy-staging
-    workflow: '{project-root}/.bmad-custom/deploy-staging.yaml'
+    workflow: '{project-root}/.bmad/deploy-staging.yaml'
     description: Deploy to staging environment
   - trigger: deploy-prod
-    workflow: '{project-root}/.bmad-custom/deploy-prod.yaml'
+    workflow: '{project-root}/.bmad/deploy-prod.yaml'
     description: Deploy to production (with approval)
 ```
 
 **Example 3: Multilingual Product Manager**
 
 ```yaml
-# {bmad_folder}/_cfg/agents/bmm-pm.customize.yaml
+# .bmad/_cfg/agents/bmm-pm.customize.yaml
 persona:
   role: 'Bilingual Product Manager'
   identity: 'Expert in US and LATAM markets'
@@ -174,7 +174,7 @@ memories:
 
 **Module-Level (Recommended):**
 
-- Customize agents per-project in `{bmad_folder}/_cfg/agents/`
+- Customize agents per-project in `.bmad/_cfg/agents/`
 - Different projects can have different agent behaviors
 
 **Global Config (Coming Soon):**

docs/custom-agent-installation.md

@@ -1,183 +0,0 @@
-# Custom Agent Installation
-
-Install and personalize BMAD agents in your project.
-
-## Quick Start
-
-```bash
-# From your project directory with BMAD installed
-npx bmad-method 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
-```
-
-## Installing from Custom Locations
-
-Use the `-s` / `--source` option to install agents from any location:
-
-```bash
-# Install agent from a custom folder (expert agent with sidecar)
-bmad agent-install -s path/to/my-agent
-
-# Install a specific .agent.yaml file (simple agent)
-bmad agent-install -s path/to/my-agent.agent.yaml
-
-# Install with defaults (non-interactive)
-bmad agent-install -s path/to/my-agent -d
-
-# Install to a specific destination project
-bmad agent-install -s path/to/my-agent --destination /path/to/destination/project
-```
-
-This is useful when:
-
-- Your agent is in a non-standard location (not in `.bmad/custom/agents/`)
-- You're developing an agent outside the project structure
-- You want to install from an absolute path
-
-## 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-method agent-install
-# or: bmad agent-install (if BMAD installed locally)
-```
-
-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
-
-Use the BMB agent builder to craft your agents. Once ready to use yourself, place your `.agent.yaml` files or folder in `.bmad/custom/agents/`.

docs/custom-content-installation.md

@@ -0,0 +1,245 @@
+# Custom Content Installation
+
+This guide explains how to create and install custom BMAD content including agents, workflows, and modules. Custom content allows you to extend BMAD's functionality with your own specialized tools and workflows that can be shared across projects or teams.
+
+## Types of Custom Content
+
+### 1. Custom Agents and Workflows (Standalone)
+
+Custom agents and workflows are standalone content packages that can be installed without being part of a full module. These are perfect for:
+
+- Sharing specialized agents across projects
+- Building a personal Agent powered Notebook vault
+- Distributing workflow templates
+- Creating agent libraries for specific domains
+
+#### Structure
+
+A custom agents and workflows package follows this structure:
+
+```
+my-custom-agents/
+├── module.yaml          # Package configuration
+├── agents/              # Agent definitions
+│   └── my-agent/
+│       └── agent.md
+└── workflows/           # Workflow definitions
+    └── my-workflow/
+        └── workflow.md
+```
+
+#### Configuration
+
+Create a `module.yaml` file in your package root:
+
+```yaml
+code: my-custom-agents
+name: 'My Custom Agents and Workflows'
+default_selected: true
+```
+
+#### Example
+
+See `/example-custom-content` for a working example of a folder with multiple random custom agents and workflows. Technically its also just a module, but you will be able to further pick and choose from this folders contents of what you do and do not want to include in a destination folder. This way, you can store all custom content source in one location and easily install it to different locations.
+
+### 2. Custom Modules
+
+Custom modules are complete BMAD modules that can include their own configuration, documentation, along with agents and workflows that all compliment each other. Additionally they will have their own installation scripts, data, and potentially other tools. Modules can be used for:
+
+- Domain-specific functionality (e.g., industry-specific workflows, entertainment, education and training, medical, etc...)
+- Integration with external systems
+- Specialized agent collections
+- Custom tooling and utilities
+
+#### Structure
+
+A custom module follows this structure:
+
+```
+my-module/
+├── _module-installer/
+│   ├── installer.js           # optional, when it exists it will run with module installation
+├── module.yaml                # Module installation configuration with custom question and answer capture
+├── docs/                      # Module documentation
+├── agents/                    # Module-specific agents
+├── workflows/                 # Module-specific workflows
+├── data/                      # csv or other content to power agent intelligence or workflows
+├── tools/                     # Custom tools, hooks, mcp
+└── sub-modules/               # IDE-specific customizations
+    ├── vscode/
+    └── cursor/
+```
+
+#### Module Configuration
+
+The `module.yaml` file defines how your module is installed:
+
+```yaml
+# Module metadata
+code: my-module
+name: 'My Custom Module'
+default_selected: false
+
+header: 'My Custom Module'
+subheader: 'Description of what this module does'
+
+# Configuration prompts
+my_setting:
+  prompt: 'Configure your module setting'
+  default: 'default-value'
+  result: '{value}'
+```
+
+#### Example
+
+See `/example-custom-module` for a complete example:
+
+## Installation Process
+
+### Step 1: Running the Installer
+
+When you run the existing normal BMAD installer - either from the cloned repo, OR via NPX, it will ask about custom content:
+
+```
+? Do you have custom content to install?
+❯ No (skip custom content)
+  Enter a directory path
+  Enter a URL [Coming soon]
+```
+
+### Step 2: Providing Custom Content Path
+
+If you select "Enter a directory path", the installer will prompt for the location:
+
+```
+? Enter the path to your custom content directory: /path/to/folder/containing/content/folder
+```
+
+The installer will:
+
+- Scan for `module.yaml` files (modules)
+- Display an indication of how many installable folders it has found. Note that a project with stand along agents and workflows all under a single folder like the example will just list the count as 1 for that directory.
+
+### Step 3: Selecting Content
+
+The installer presents a unified selection interface:
+
+```
+? Select modules and custom content to install:
+[── Custom Content ──]
+ ◉ My Custom Agents and Workflows (/path/to/custom)
+[── Official Content ──]
+ ◯ BMM: Business Method & Management
+ ◯ CIS: Creativity & Innovation Suite
+```
+
+## Agent Sidecar Support
+
+Agents with sidecar content can store personal data, memories, and working files outside of the `.bmad` directory. This separation keeps personal content separate from BMAD's core files.
+
+### What is Sidecar Content?
+
+Sidecar content includes:
+
+- Agent memories and learning data
+- Personal working files
+- Temporary data
+- User-specific configurations
+
+### Sidecar Configuration
+
+The sidecar folder location is configured during BMAD core installation:
+
+```
+? Where should users' agent sidecar memory folders be stored?
+❯ .bmad-user-memory
+```
+
+### How It Works
+
+1. **Agent Declaration**: Agents declare `hasSidecar: true` in their metadata
+2. **Sidecar Detection**: The installer automatically detects folders with "sidecar" in the name
+3. **Installation**: Sidecar content is copied to the configured location
+4. **Path Replacement**: The `{agent_sidecar_folder}` placeholder in agent configurations is replaced with the actual path to the installed instance of the sidecar folder. Now when you use the agent, depending on its design, will use the content in sidecar to record interactions, remember things you tell it, or serve a host of many other issues.
+
+### Example Structure
+
+```
+my-agent/
+├── agent.md              # Agent definition
+└── my-agent-sidecar/     # Sidecar content folder
+    ├── memories/
+    ├── working/
+    └── config/
+```
+
+### Git Integration
+
+Since sidecar content is stored outside the `.bmad` directory (and typically outside version control), users can:
+
+- Add the sidecar folder to `.gitignore` to exclude personal data
+- Share agent definitions without exposing personal content
+- Maintain separate configurations for different projects
+
+Example `.gitignore` entry:
+
+```
+# Exclude agent personal data
+.bmad-user-memory/
+```
+
+## Creating Custom Content with BMAD Builder
+
+The BMAD Builder provides workflows that will guide you to produce your own custom content:
+
+1. **Agent Templates**: Use standardized agent templates with proper structure
+2. **Workflow Templates**: Create workflows using proven patterns
+3. **Validation Tools**: Validate your content before distribution
+4. **Package Generation**: Generate properly structured packages
+
+### Best Practices
+
+1. **Use Clear Naming**: Make your content codes and names descriptive
+2. **Provide Documentation**: Include clear setup and usage instructions
+3. **Test Installation**: Test your content in a clean environment
+4. **Version Management**: Use semantic versioning for updates
+5. **Respect User Privacy**: Keep personal data in sidecar folders
+
+## Distribution
+
+Custom content can be distributed:
+
+1. **File System**: Copy folders directly to users
+2. **Git Repositories**: Clone or download from version control
+3. **Package Managers**: [Coming soon] npm package support
+4. **URL Installation**: [Coming soon] Direct URL installation, including an official community vetted module forge
+
+## Troubleshooting
+
+### No Custom Content Found
+
+- Ensure your `module.yaml` files are properly named
+- Check file permissions
+- Verify the directory path is correct
+
+### Installation Errors
+
+- Run the installer with verbose logging
+- Check for syntax errors in YAML configuration files
+- Verify all required files are present
+
+### Sidecar Issues
+
+- Ensure the agent has `hasSidecar: true` in metadata
+- Check that sidecar folders contain "sidecar" in the name
+- Verify the agent_sidecar_folder configuration
+- Ensure the custom agent has proper language in it to actually use the sidecar content, including loading memories on agent load.
+
+## Support
+
+For help with custom content creation or installation:
+
+1. Check the examples in `/example-custom-content` and `/example-custom-module`
+2. Review the BMAD documentation
+3. Create an issue in the BMAD repository
+4. Join the BMAD community discussions on discord

docs/document-sharding-guide.md

@@ -190,7 +190,7 @@ Workflows load only needed sections:
 
 - Needs ALL epics to build complete status
 
-**epic-tech-context, create-story, story-context, code-review** (Selective):
+**create-story, code-review** (Selective):
 
 ```
 Working on Epic 3, Story 2:

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_folder}/{module}/agents/`
+2. **Navigate**: Browse to `.bmad/{module}/agents/`
 3. **Select Agent**: Choose the agent command
 4. **Execute**: Run to activate agent persona
 

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_folder}/{module}/agents/{agent-name}`
-2. **Include Entire Module**: Use `@{bmad_folder}/{module}`
-3. **Reference Index**: Use `@{bmad_folder}/index` for all available agents
+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
 
 ### Examples
 
 ```
-@{bmad_folder}/core/agents/dev - Activate dev agent
-@{bmad_folder}/bmm/agents/architect - Activate architect agent
-@{bmad_folder}/core - Include all core agents/tasks
+@.bmad/core/agents/dev - Activate dev agent
+@.bmad/bmm/agents/architect - Activate architect agent
+@.bmad/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_folder}/core/agents/dev @{bmad_folder}/core/agents/test`
+- Can combine multiple agents: `@.bmad/core/agents/dev @.bmad/core/agents/test`

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_folder}/agents/` or `{bmad_folder}/tasks/`
+2. **Navigate**: Browse to `.bmad/agents/` or `.bmad/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_folder}/agents/core-dev - Activate dev agent
-/{bmad_folder}/tasks/core-setup - Execute setup task
+/.bmad/agents/core-dev - Activate dev agent
+/.bmad/tasks/core-setup - Execute setup task
 ```
 
 ### Notes

docs/ide-info/opencode.md

@@ -14,7 +14,7 @@ BMAD agents are installed as OpenCode agents in `.opencode/agent/BMAD/{module_na
 
 ```
 /agents - to see a list of agents and switch between them
-/{bmad_folder}/bmm/workflows/workflow-init - Activate the workflow-init command
+/.bmad/bmm/workflows/workflow-init - Activate the workflow-init command
 ```
 
 ### Notes

docs/index.md

@@ -96,9 +96,9 @@ Instructions for loading agents and running workflows in your development enviro
 
 ## 🔧 Advanced Topics
 
-### Custom Agents
+### Custom Agents, Workflow and Modules
 
-- **[Custom Agent Installation](./custom-agent-installation.md)** - Install and personalize agents with `bmad agent-install`
+- **[Custom Content Installation](./custom-content-installation.md)** - Install and personalize agents, workflows and modules with the default bmad-method installer!
 - [Agent Customization Guide](./agent-customization-guide.md) - Customize agent behavior and responses
 
 ### Installation & Bundling

docs/installers-bundlers/ide-injections.md

@@ -158,7 +158,7 @@ src/modules/bmm/
 
 ```yaml
 injections:
-  - file: '{bmad_folder}/bmm/agents/pm.md'
+  - file: '.bmad/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_folder}/bmm/templates/prd.md'
+  - file: '.bmad/bmm/templates/prd.md'
     point: 'prd-goals-context-delegation'
     requires: 'market-researcher' # Only if this specific subagent selected
     content: |

docs/installers-bundlers/installers-modules-platforms-reference.md

@@ -19,7 +19,7 @@ BMad Core is a modular AI agent framework with intelligent installation, platfor
 
 - **Modular Design**: Core + optional modules (BMB, BMM, CIS)
 - **Smart Installation**: Interactive configuration with dependency resolution
-- **Clean Architecture**: Centralized `{bmad_folder}` directory add to project, no source pollution with multiple folders added
+- **Clean Architecture**: Centralized `.bmad` directory add to project, no source pollution with multiple folders added
 
 ## Architecture
 
@@ -27,7 +27,7 @@ BMad Core is a modular AI agent framework with intelligent installation, platfor
 
 ```
 project-root/
-├── {bmad_folder}/             # Centralized installation
+├── .bmad/             # Centralized installation
 │   ├── _cfg/                  # Configuration
 │   │   ├── agents/            # Agent configs
 │   │   └── agent-manifest.csv # Agent manifest
@@ -59,6 +59,7 @@ project-root/
 ### Key Exclusions
 
 - `_module-installer/` directories are never copied to destination
+- module.yaml
 - `localskip="true"` agents are filtered out
 - Source `config.yaml` templates are replaced with generated configs
 
@@ -92,8 +93,8 @@ Creative Innovation Studio for design workflows
 ```
 src/modules/{module}/
 ├── _module-installer/       # Not copied to destination
-│   ├── installer.js        # Post-install logic
-│   └── install-config.yaml
+│   ├── installer.js         # Post-install logic
+├── module.yaml
 ├── agents/
 ├── tasks/
 ├── templates/
@@ -107,7 +108,7 @@ src/modules/{module}/
 
 ### Collection Process
 
-Modules define prompts in `install-config.yaml`:
+Modules define prompts in `module.yaml`:
 
 ```yaml
 project_name:
@@ -184,7 +185,7 @@ Cline, Roo, Rovo Dev,Auggie, GitHub Copilot, Codex, Gemini, Qwen, Trae, Kilo, Cr
 
    ```yaml
    injections:
-     - file: '{bmad_folder}/bmm/agents/pm.md'
+     - file: '.bmad/bmm/agents/pm.md'
        point: 'pm-agent-instructions'
        content: |
          <i>Platform-specific instruction</i>
@@ -218,12 +219,12 @@ Platform-specific content without source modification:
    src/modules/mymod/
    ├── _module-installer/
    │   ├── installer.js
-   │   └── install-config.yaml
+   ├── module.yaml
    ├── agents/
    └── tasks/
    ```
 
-2. **Configuration** (`install-config.yaml`)
+2. **Configuration** (`module.yaml`)
 
    ```yaml
    code: mymod
@@ -270,14 +271,14 @@ Generated in: `bmad/_cfg/agents/{module}-{agent}.md`
 
 ### Common Issues
 
-| 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                |
+| 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        |
 
 ### Debug Commands
 
@@ -289,19 +290,19 @@ bmad status -v      # Detailed status
 ### Best Practices
 
 1. Run from project root
-2. Backup `{bmad_folder}/_cfg/` before updates
+2. Backup `.bmad/_cfg/` before updates
 3. Use interactive mode for guidance
 4. Review generated configs post-install
 
 ## Migration from v4
 
-| v4                  | v6                           |
-| ------------------- | ---------------------------- |
-| Scattered files     | Centralized `{bmad_folder}/` |
-| Monolithic          | Modular                      |
-| Manual config       | Interactive setup            |
-| Limited IDE support | 15+ platforms                |
-| Source modification | Clean injection              |
+| v4                  | v6                   |
+| ------------------- | -------------------- |
+| Scattered files     | Centralized `.bmad/` |
+| Monolithic          | Modular              |
+| Manual config       | Interactive setup    |
+| Limited IDE support | 15+ platforms        |
+| Source modification | Clean injection      |
 
 ## Technical Notes
 
@@ -326,8 +327,8 @@ Agents can specify both `workflow` (source location) and `workflow-install` (des
 ```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'
+    workflow: '{project-root}/.bmad/bmm/workflows/4-implementation/create-story/workflow.yaml'
+    workflow-install: '{project-root}/.bmad/bmgd/workflows/4-production/create-story/workflow.yaml'
     description: 'Create a game feature story'
 ```
 
@@ -347,10 +348,10 @@ menu:
 
    ```yaml
    # Source workflow (in bmm):
-   config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
+   config_source: "{project-root}/.bmad/bmm/config.yaml"
 
    # Vendored workflow (in bmgd):
-   config_source: "{project-root}/{bmad_folder}/bmgd/config.yaml"
+   config_source: "{project-root}/.bmad/bmgd/config.yaml"
    ```
 
 **Result**: Modules become completely standalone with their own copies of needed workflows, configured for their specific use case.

docs/v4-to-v6-upgrade.md

@@ -63,7 +63,7 @@ your-project/
 
 ```
 your-project/
-└── {bmad_folder}/       # Single installation folder, default .bmad
+└── .bmad/       # 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)
@@ -75,8 +75,8 @@ your-project/
 ### 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
+- **v6 `.bmad/core/`**: Is the real universal core framework
+- **v6 `.bmad/bmm/`**: Is the BMad Method module
 - **Module identification**: All modules now have a `config.yaml` file
 
 ---
@@ -114,11 +114,11 @@ 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:
+**All customizations** now go in `.bmad/_cfg/agents/` using customize files:
 
 **Example: Renaming an agent and changing communication style**
 
-File: `{bmad_folder}/_cfg/agents/bmm-pm.customize.yaml`
+File: `.bmad/_cfg/agents/bmm-pm.customize.yaml`
 
 ```yaml
 # Customize the PM agent
@@ -133,8 +133,8 @@ persona:
 
 **How it works:**
 
-- Base agent: `{bmad_folder}/bmm/agents/pm.md`
-- Customization: `{bmad_folder}/_cfg/agents/bmm-pm.customize.yaml`
+- Base agent: `.bmad/bmm/agents/pm.md`
+- Customization: `.bmad/_cfg/agents/bmm-pm.customize.yaml`
 - Result: Agent uses your custom name and style, but updates don't overwrite your changes
 
 ---
@@ -212,9 +212,9 @@ Since you are migrating an existing project from v4, it's most likely **Level 3
 ## Post-Migration Checklist
 
 - [ ] v4 folders backed up to `v4-backup/`
-- [ ] v6 installed to `{bmad_folder}/` folder
+- [ ] v6 installed to `.bmad/` folder
 - [ ] `workflow-init` run with correct project level selected
-- [ ] Agent customizations migrated to `{bmad_folder}/_cfg/agents/` if needed
+- [ ] Agent customizations migrated to `.bmad/_cfg/agents/` if needed
 - [ ] IDE integration working (test by listing agents)
 - [ ] For active development: `sprint-planning` workflow executed
 
@@ -224,4 +224,4 @@ Since you are migrating an existing project from v4, it's most likely **Level 3
 
 - **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
+- **Docs**: Check `.bmad/docs/` in your installation for IDE-specific instructions

docs/web-bundles-gemini-gpt-guide.md

@@ -73,7 +73,7 @@ web-bundles/
 
 **Create a Gem:**
 
-1. Go to [Google AI Studio](https://aistudio.google.com/)
+1. Go to [Gemini Gem manager](https://gemini.google.com/gems/view)
 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**
@@ -336,7 +336,7 @@ Agents adapt their menus based on project phase and available workflows.
 
 Customize agents using the [Agent Customization Guide](./agent-customization-guide.md):
 
-1. Edit `{bmad_folder}/_cfg/agents/<agent>.customize.yaml`
+1. Edit `.bmad/_cfg/agents/<agent>.customize.yaml`
 2. Rebuild: `npx bmad-method build <agent-name>`
 3. Generate bundles: `npm run bundle`
 

eslint.config.mjs

@@ -18,6 +18,20 @@ export default [
       'test/fixtures/**/*.yaml',
       '.bmad/**',
       '.bmad*/**',
+      // Gitignored patterns
+      'z*/**', // z-samples, z1, z2, etc.
+      '.claude/**',
+      '.codex/**',
+      '.github/chatmodes/**',
+      '.agent/**',
+      '.agentvibes/**',
+      '.kiro/**',
+      '.roo/**',
+      'test-project-install/**',
+      'sample-project/**',
+      'tools/template-test-generator/test-scenarios/**',
+      'src/modules/*/sub-modules/**',
+      '.bundler-temp/**',
     ],
   },
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "6.0.0-alpha.11",
+  "version": "6.0.0-alpha.16",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "6.0.0-alpha.11",
+      "version": "6.0.0-alpha.16",
       "license": "MIT",
       "dependencies": {
         "@kayvan/markdown-tree-parser": "^1.6.1",
@@ -42,6 +42,7 @@
         "husky": "^9.1.7",
         "jest": "^30.0.4",
         "lint-staged": "^16.1.1",
+        "markdownlint-cli2": "^0.19.1",
         "prettier": "^3.5.3",
         "prettier-plugin-packagejson": "^2.5.19",
         "yaml-eslint-parser": "^1.2.3",
@@ -1023,9 +1024,9 @@
       }
     },
     "node_modules/@istanbuljs/load-nyc-config/node_modules/js-yaml": {
-      "version": "3.14.1",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz",
-      "integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==",
+      "version": "3.14.2",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.2.tgz",
+      "integrity": "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -1329,9 +1330,9 @@
       }
     },
     "node_modules/@jest/reporters/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==",
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz",
+      "integrity": "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -1672,6 +1673,19 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@sindresorhus/merge-streams": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-4.0.0.tgz",
+      "integrity": "sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/@sinonjs/commons": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/@sinonjs/commons/-/commons-3.0.1.tgz",
@@ -1798,6 +1812,13 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/katex": {
+      "version": "0.16.7",
+      "resolved": "https://registry.npmjs.org/@types/katex/-/katex-0.16.7.tgz",
+      "integrity": "sha512-HMwFiRujE5PjrgwHQ25+bsLJgowjGjm5Z8FVSf0N6PwgJrwxH0QxzHYDcKsTfV3wva0vzrpqMTJS2jXPr5BMEQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/mdast": {
       "version": "4.0.4",
       "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz",
@@ -2618,9 +2639,9 @@
       }
     },
     "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==",
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz",
+      "integrity": "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -2793,6 +2814,28 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/character-entities-legacy": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz",
+      "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/character-reference-invalid": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/character-reference-invalid/-/character-reference-invalid-2.0.1.tgz",
+      "integrity": "sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/chardet": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/chardet/-/chardet-2.1.0.tgz",
@@ -3298,6 +3341,19 @@
         "node": ">=10.13.0"
       }
     },
+    "node_modules/entities": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
+      "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
     "node_modules/environment": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/environment/-/environment-1.1.0.tgz",
@@ -4103,14 +4159,14 @@
       }
     },
     "node_modules/glob": {
-      "version": "11.0.3",
-      "resolved": "https://registry.npmjs.org/glob/-/glob-11.0.3.tgz",
-      "integrity": "sha512-2Nim7dha1KVkaiF4q6Dj+ngPPMdfvLJEOpZk/jKiUAkqKebpGAWQXAq9z1xu9HKu5lWfqw/FASuccEjyznjPaA==",
-      "license": "ISC",
+      "version": "11.1.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-11.1.0.tgz",
+      "integrity": "sha512-vuNwKSaKiqm7g0THUBu2x7ckSs3XJLXE+2ssL7/MfTGPLLcrJQ/4Uq1CjPTtO5cCIiRxqvN6Twy1qOwhL0Xjcw==",
+      "license": "BlueOak-1.0.0",
       "dependencies": {
         "foreground-child": "^3.3.1",
         "jackspeak": "^4.1.1",
-        "minimatch": "^10.0.3",
+        "minimatch": "^10.1.1",
         "minipass": "^7.1.2",
         "package-json-from-dist": "^1.0.0",
         "path-scurry": "^2.0.0"
@@ -4139,10 +4195,10 @@
       }
     },
     "node_modules/glob/node_modules/minimatch": {
-      "version": "10.0.3",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.0.3.tgz",
-      "integrity": "sha512-IPZ167aShDZZUMdRk66cyQAW3qr0WzbHkPdMYa8bzZhlHhO3jALbKdxcaak7W9FfT2rZNpQuUu4Od7ILEpXSaw==",
-      "license": "ISC",
+      "version": "10.1.1",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.1.1.tgz",
+      "integrity": "sha512-enIvLvRAFZYXJzkCYG5RKmPfrFArdLv+R+lbQ53BmIMLIry74bjKzX6iHAm8WYamJkhSSEabrWN5D97XnKObjQ==",
+      "license": "BlueOak-1.0.0",
       "dependencies": {
         "@isaacs/brace-expansion": "^5.0.0"
       },
@@ -4421,6 +4477,32 @@
         "node": ">=8"
       }
     },
+    "node_modules/is-alphabetical": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz",
+      "integrity": "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/is-alphanumerical": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-alphanumerical/-/is-alphanumerical-2.0.1.tgz",
+      "integrity": "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-alphabetical": "^2.0.0",
+        "is-decimal": "^2.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/is-arrayish": {
       "version": "0.2.1",
       "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz",
@@ -4444,6 +4526,17 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/is-decimal": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-decimal/-/is-decimal-2.0.1.tgz",
+      "integrity": "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/is-extglob": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
@@ -4490,6 +4583,17 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/is-hexadecimal": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-hexadecimal/-/is-hexadecimal-2.0.1.tgz",
+      "integrity": "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/is-interactive": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/is-interactive/-/is-interactive-1.0.0.tgz",
@@ -4808,9 +4912,9 @@
       }
     },
     "node_modules/jest-config/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==",
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz",
+      "integrity": "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -5181,9 +5285,9 @@
       }
     },
     "node_modules/jest-runtime/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==",
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz",
+      "integrity": "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -5413,9 +5517,9 @@
       "license": "MIT"
     },
     "node_modules/js-yaml": {
-      "version": "4.1.0",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz",
-      "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==",
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
+      "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
       "license": "MIT",
       "dependencies": {
         "argparse": "^2.0.1"
@@ -5478,6 +5582,13 @@
         "node": ">=6"
       }
     },
+    "node_modules/jsonc-parser": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz",
+      "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/jsonfile": {
       "version": "6.2.0",
       "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.0.tgz",
@@ -5490,6 +5601,33 @@
         "graceful-fs": "^4.1.6"
       }
     },
+    "node_modules/katex": {
+      "version": "0.16.25",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.25.tgz",
+      "integrity": "sha512-woHRUZ/iF23GBP1dkDQMh1QBad9dmr8/PAwNA54VrSOVYgI12MAcE14TqnDdQOdzyEonGzMepYnqBMYdsoAr8Q==",
+      "dev": true,
+      "funding": [
+        "https://opencollective.com/katex",
+        "https://github.com/sponsors/katex"
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "commander": "^8.3.0"
+      },
+      "bin": {
+        "katex": "cli.js"
+      }
+    },
+    "node_modules/katex/node_modules/commander": {
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz",
+      "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/keyv": {
       "version": "4.5.4",
       "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz",
@@ -5544,6 +5682,16 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/linkify-it": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz",
+      "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "uc.micro": "^2.0.0"
+      }
+    },
     "node_modules/lint-staged": {
       "version": "16.1.5",
       "resolved": "https://registry.npmjs.org/lint-staged/-/lint-staged-16.1.5.tgz",
@@ -5988,6 +6136,132 @@
         "tmpl": "1.0.5"
       }
     },
+    "node_modules/markdown-it": {
+      "version": "14.1.0",
+      "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz",
+      "integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1",
+        "entities": "^4.4.0",
+        "linkify-it": "^5.0.0",
+        "mdurl": "^2.0.0",
+        "punycode.js": "^2.3.1",
+        "uc.micro": "^2.1.0"
+      },
+      "bin": {
+        "markdown-it": "bin/markdown-it.mjs"
+      }
+    },
+    "node_modules/markdownlint": {
+      "version": "0.39.0",
+      "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.39.0.tgz",
+      "integrity": "sha512-Xt/oY7bAiHwukL1iru2np5LIkhwD19Y7frlsiDILK62v3jucXCD6JXlZlwMG12HZOR+roHIVuJZrfCkOhp6k3g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "micromark": "4.0.2",
+        "micromark-core-commonmark": "2.0.3",
+        "micromark-extension-directive": "4.0.0",
+        "micromark-extension-gfm-autolink-literal": "2.1.0",
+        "micromark-extension-gfm-footnote": "2.1.0",
+        "micromark-extension-gfm-table": "2.1.1",
+        "micromark-extension-math": "3.1.0",
+        "micromark-util-types": "2.0.2"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/DavidAnson"
+      }
+    },
+    "node_modules/markdownlint-cli2": {
+      "version": "0.19.1",
+      "resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.19.1.tgz",
+      "integrity": "sha512-p3JTemJJbkiMjXEMiFwgm0v6ym5g8K+b2oDny+6xdl300tUKySxvilJQLSea48C6OaYNmO30kH9KxpiAg5bWJw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "globby": "15.0.0",
+        "js-yaml": "4.1.1",
+        "jsonc-parser": "3.3.1",
+        "markdown-it": "14.1.0",
+        "markdownlint": "0.39.0",
+        "markdownlint-cli2-formatter-default": "0.0.6",
+        "micromatch": "4.0.8"
+      },
+      "bin": {
+        "markdownlint-cli2": "markdownlint-cli2-bin.mjs"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/DavidAnson"
+      }
+    },
+    "node_modules/markdownlint-cli2-formatter-default": {
+      "version": "0.0.6",
+      "resolved": "https://registry.npmjs.org/markdownlint-cli2-formatter-default/-/markdownlint-cli2-formatter-default-0.0.6.tgz",
+      "integrity": "sha512-VVDGKsq9sgzu378swJ0fcHfSicUnMxnL8gnLm/Q4J/xsNJ4e5bA6lvAz7PCzIl0/No0lHyaWdqVD2jotxOSFMQ==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/DavidAnson"
+      },
+      "peerDependencies": {
+        "markdownlint-cli2": ">=0.0.4"
+      }
+    },
+    "node_modules/markdownlint-cli2/node_modules/globby": {
+      "version": "15.0.0",
+      "resolved": "https://registry.npmjs.org/globby/-/globby-15.0.0.tgz",
+      "integrity": "sha512-oB4vkQGqlMl682wL1IlWd02tXCbquGWM4voPEI85QmNKCaw8zGTm1f1rubFgkg3Eli2PtKlFgrnmUqasbQWlkw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@sindresorhus/merge-streams": "^4.0.0",
+        "fast-glob": "^3.3.3",
+        "ignore": "^7.0.5",
+        "path-type": "^6.0.0",
+        "slash": "^5.1.0",
+        "unicorn-magic": "^0.3.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/markdownlint-cli2/node_modules/path-type": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/path-type/-/path-type-6.0.0.tgz",
+      "integrity": "sha512-Vj7sf++t5pBD637NSfkxpHSMfWaeig5+DKWLhcqIYx6mWQz5hdJTGDVMQiJcw1ZYkhs7AazKDGpRVji1LJCZUQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/markdownlint-cli2/node_modules/slash": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/slash/-/slash-5.1.0.tgz",
+      "integrity": "sha512-ZA6oR3T/pEyuqwMgAKT0/hAv8oAXckzbkmR0UkUosQ+Mc4RxGoJkRmwHgHufaenlyAgE1Mxgpdcrf75y6XcnDg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/mdast-util-from-markdown": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-2.0.2.tgz",
@@ -6060,6 +6334,13 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/mdurl": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz",
+      "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/merge-stream": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz",
@@ -6146,6 +6427,102 @@
         "micromark-util-types": "^2.0.0"
       }
     },
+    "node_modules/micromark-extension-directive": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-directive/-/micromark-extension-directive-4.0.0.tgz",
+      "integrity": "sha512-/C2nqVmXXmiseSSuCdItCMho7ybwwop6RrrRPk0KbOHW21JKoCldC+8rFOaundDoRBUWBnJJcxeA/Kvi34WQXg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-factory-whitespace": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0",
+        "parse-entities": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-autolink-literal": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-autolink-literal/-/micromark-extension-gfm-autolink-literal-2.1.0.tgz",
+      "integrity": "sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-sanitize-uri": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-footnote": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-footnote/-/micromark-extension-gfm-footnote-2.1.0.tgz",
+      "integrity": "sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-core-commonmark": "^2.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-normalize-identifier": "^2.0.0",
+        "micromark-util-sanitize-uri": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-table": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.1.tgz",
+      "integrity": "sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-math": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-math/-/micromark-extension-math-3.1.0.tgz",
+      "integrity": "sha512-lvEqd+fHjATVs+2v/8kg9i5Q0AP2k85H0WUOwpIVvUML8BapsMvh1XAogmQjOCsLpoKRCVQqEkQBB3NhVBcsOg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/katex": "^0.16.0",
+        "devlop": "^1.0.0",
+        "katex": "^0.16.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/micromark-factory-destination": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-2.0.1.tgz",
@@ -6868,6 +7245,33 @@
         "node": ">=6"
       }
     },
+    "node_modules/parse-entities": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.2.tgz",
+      "integrity": "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^2.0.0",
+        "character-entities-legacy": "^3.0.0",
+        "character-reference-invalid": "^2.0.0",
+        "decode-named-character-reference": "^1.0.0",
+        "is-alphanumerical": "^2.0.0",
+        "is-decimal": "^2.0.0",
+        "is-hexadecimal": "^2.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/parse-entities/node_modules/@types/unist": {
+      "version": "2.0.11",
+      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz",
+      "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/parse-json": {
       "version": "5.2.0",
       "resolved": "https://registry.npmjs.org/parse-json/-/parse-json-5.2.0.tgz",
@@ -7156,6 +7560,16 @@
         "node": ">=6"
       }
     },
+    "node_modules/punycode.js": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
+      "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/pure-rand": {
       "version": "7.0.1",
       "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-7.0.1.tgz",
@@ -8040,6 +8454,13 @@
         "node": ">=14.17"
       }
     },
+    "node_modules/uc.micro": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz",
+      "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/undici-types": {
       "version": "7.10.0",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.10.0.tgz",
@@ -8047,6 +8468,19 @@
       "devOptional": true,
       "license": "MIT"
     },
+    "node_modules/unicorn-magic": {
+      "version": "0.3.0",
+      "resolved": "https://registry.npmjs.org/unicorn-magic/-/unicorn-magic-0.3.0.tgz",
+      "integrity": "sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/unified": {
       "version": "11.0.5",
       "resolved": "https://registry.npmjs.org/unified/-/unified-11.0.5.tgz",

package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.0.0-alpha.12",
+  "version": "6.0.0-alpha.16",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -24,7 +24,6 @@
     "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",
@@ -34,13 +33,14 @@
     "install:bmad": "node tools/cli/bmad-cli.js install",
     "lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
+    "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "husky",
     "rebundle": "node tools/cli/bundlers/bundle-web.js rebundle",
     "release:major": "gh workflow run \"Manual Release\" -f version_bump=major",
     "release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
     "release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
     "release:watch": "gh run watch",
-    "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": "npm run test:schemas && npm run test:install && npm run validate:bundles && npm run validate:schemas && npm run lint && npm run lint:md && 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",
@@ -56,7 +56,11 @@
       "eslint --fix",
       "npm run format:fix"
     ],
-    "*.{json,md}": [
+    "*.json": [
+      "npm run format:fix"
+    ],
+    "*.md": [
+      "markdownlint-cli2",
       "npm run format:fix"
     ]
   },
@@ -90,6 +94,7 @@
     "husky": "^9.1.7",
     "jest": "^30.0.4",
     "lint-staged": "^16.1.1",
+    "markdownlint-cli2": "^0.19.1",
     "prettier": "^3.5.3",
     "prettier-plugin-packagejson": "^2.5.19",
     "yaml-eslint-parser": "^1.2.3",

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-config.yaml
+ * @param {Object} options.config - Module configuration from module.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

src/core/agents/bmad-master.agent.yaml

@@ -3,7 +3,7 @@
 
 agent:
   metadata:
-    id: "{bmad_folder}/core/agents/bmad-master.md"
+    id: ".bmad/core/agents/bmad-master.md"
     name: "BMad Master"
     title: "BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator"
     icon: "🧙"
@@ -17,22 +17,22 @@ agent:
 
   # 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"
+    - "Load into memory {project-root}/.bmad/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"
+      action: "list all tasks from {project-root}/.bmad/_cfg/task-manifest.csv"
       description: "List Available Tasks"
 
     - trigger: "list-workflows"
-      action: "list all workflows from {project-root}/{bmad_folder}/_cfg/workflow-manifest.csv"
+      action: "list all workflows from {project-root}/.bmad/_cfg/workflow-manifest.csv"
       description: "List Workflows"
 
     - trigger: "party-mode"
-      workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"
+      exec: "{project-root}/.bmad/core/workflows/party-mode/workflow.md"
       description: "Group chat with all agents"
 
   # Empty prompts section (no custom prompts for this agent)

src/core/agents/bmad-web-orchestrator.agent.xml

@@ -1,7 +1,7 @@
-<agent id="{bmad_folder}/core/agents/bmad-orchestrator.md" name="BMad Orchestrator" title="BMad Web Orchestrator" icon="🎭" localskip="true">
+<agent id=".bmad/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
+    <step n="2">CRITICAL: This bundle contains ALL agents as XML nodes with id=".bmad/..." 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>
@@ -16,7 +16,7 @@
         <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
+          2. CRITICAL: Always LOAD .bmad/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
@@ -49,7 +49,7 @@
 
         <handler type="validate-workflow">
           When menu item has: validate-workflow="workflow-id"
-          1. MUST LOAD {bmad_folder}/core/tasks/validate-workflow.xml
+          1. MUST LOAD .bmad/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
@@ -105,9 +105,9 @@
     <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
+    <item cmd="*party-mode" exec=".bmad/core/workflows/party-mode/workflow.md">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="*advanced-elicitation" task=".bmad/core/tasks/advanced-elicitation.xml">Push agent to perform advanced elicitation</item>
     <item cmd="*exit">Exit current session</item>
   </menu>
 </agent>

src/core/module.yaml

@@ -1,13 +1,6 @@
-# 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"
@@ -23,7 +16,11 @@ document_output_language:
   default: "{communication_language}"
   result: "{value}"
 
-  # This is the folder where all generated AI Output documents from workflows will default be sa
+agent_sidecar_folder:
+  prompt: "Where should users agent sidecar memory folders be stored?"
+  default: ".bmad-user-memory"
+  result: "{project-root}/{value}"
+
 output_folder:
   prompt: "Where should AI Generated Artifacts be saved across all modules?"
   default: "docs"

src/core/resources/excalidraw/README.md

@@ -72,8 +72,8 @@ Provides the **HOW** (universal knowledge) while agents provide the **WHAT** (do
 
 ```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'
+helpers: '{project-root}/.bmad/core/resources/excalidraw/excalidraw-helpers.md'
+json_validation: '{project-root}/.bmad/core/resources/excalidraw/validate-json-instructions.md'
 ```
 
 **Domain-specific additions:**
@@ -99,8 +99,8 @@ flowchart:
 
 ```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'
+helpers: '{project-root}/.bmad/core/resources/excalidraw/excalidraw-helpers.md'
+json_validation: '{project-root}/.bmad/core/resources/excalidraw/validate-json-instructions.md'
 ```
 
 **Domain-specific additions:**

src/core/resources/excalidraw/library-loader.md

@@ -4,7 +4,7 @@
 
 ## Purpose
 
-Load external .excalidrawlib files from https://libraries.excalidraw.com or custom sources.
+Load external .excalidrawlib files from <https://libraries.excalidraw.com> or custom sources.
 
 ## Planned Capabilities
 
@@ -34,7 +34,7 @@ libraries:
 
 ## Implementation Notes
 
-This will be developed when agents need to leverage the extensive library ecosystem available at https://libraries.excalidraw.com.
+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:
 

src/core/tasks/advanced-elicitation.xml

@@ -1,6 +1,6 @@
-<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">
+<task id=".bmad/core/tasks/advanced-elicitation.xml" name="Advanced Elicitation" standalone="true"
+  methods="{project-root}/.bmad/core/tasks/advanced-elicitation-methods.csv"
+  agent-party="{project-root}/.bmad/_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>

src/core/tasks/index-docs.xml

@@ -1,4 +1,4 @@
-<task id="{bmad_folder}/core/tasks/index-docs" name="Index Docs"
+<task id=".bmad/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>

src/core/tasks/validate-workflow.xml

@@ -1,4 +1,4 @@
-<task id="{bmad_folder}/core/tasks/validate-workflow.xml" name="Validate Workflow Output">
+<task id=".bmad/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>

src/core/tasks/workflow.xml

@@ -1,4 +1,4 @@
-<task id="{bmad_folder}/core/tasks/workflow.xml" name="Execute Workflow">
+<task id=".bmad/core/tasks/workflow.xml" name="Execute Workflow">
   <objective>Execute given workflow by loading its configuration, following instructions, and producing output</objective>
 
   <llm critical="true">
@@ -6,14 +6,14 @@
     <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>
+    <mandate>NEVER skip a step - YOU are responsible for every steps execution without fail or excuse</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>
+    <rule n="3">Template-output tags: Save content, discuss with the user the section completed, and NEVER proceed until the users indicates
+      to proceed (unless YOLO mode has been activated)</rule>
   </WORKFLOW-RULES>
 
   <flow>
@@ -43,7 +43,7 @@
       </substep>
     </step>
 
-    <step n="2" title="Process Each Instruction Step">
+    <step n="2" title="Process Each Instruction Step in Order">
       <iterate>For each step in instructions:</iterate>
 
       <substep n="2a" title="Handle Step Attributes">
@@ -60,7 +60,7 @@
           <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-workflow xml tag → Execute another workflow with given inputs and the workflow.xml runner</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>
@@ -74,14 +74,14 @@
           <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>
+              <action>Start the advanced elicitation workflow {project-root}/.bmad/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>
+              <action>Start the party-mode workflow {project-root}/.bmad/core/workflows/party-mode/workflow.yaml</action>
             </if>
             <if
               response="y">
@@ -98,16 +98,14 @@
     </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>
+      <check>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
+    <mode name="normal">Full user interaction and confirmation of EVERY step at EVERY template output - NO EXCEPTIONS except yolo MODE</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>
 
@@ -123,7 +121,7 @@
       <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>ask - Get user input (ALWAYS wait for response before continuing)</tag>
       <tag>goto - Jump to another step</tag>
       <tag>invoke-workflow - Call another workflow</tag>
       <tag>invoke-task - Call a task</tag>
@@ -136,35 +134,6 @@
     </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>
@@ -180,17 +149,8 @@
         <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">
+          <substep n="2a" title="Try Sharded Documents First">
+            <check if="sharded pattern exists">
               <action>Determine load_strategy from pattern config (defaults to FULL_LOAD if not specified)</action>
 
               <strategy name="FULL_LOAD">
@@ -223,11 +183,23 @@
                 <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>
+              <action>Mark pattern as RESOLVED, skip to next pattern</action>
+            </check>
+          </substep>
+
+          <substep n="2b" title="Try Whole Document if No Sharded Found">
+            <check if="no sharded matches found OR no sharded pattern exists">
+              <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>
             </check>
           </substep>
 
           <substep n="2c" title="Handle Not Found">
-            <check if="no matches for whole OR sharded">
+            <check if="no matches for sharded OR whole">
               <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>
@@ -237,8 +209,8 @@
         <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 {prd_content} from 5 sharded files: prd/index.md, prd/requirements.md, ...
+            ✓ Loaded {architecture_content} from 1 file: Architecture.md
             ✓ Loaded {epics_content} from selective load: epics/epic-3.md
             ○ No ux_design files found
           </example>
@@ -246,24 +218,18 @@
         </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>
+    <critical-rules>
+      • This is the complete workflow execution engine
+      • You MUST Follow instructions exactly as written
+      • The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml
+      • You MUST have already loaded and processed: {installed_path}/workflow.yaml
+      • This workflow uses INTENT-DRIVEN PLANNING - adapt organically to product type and context
+      • YOU ARE FACILITATING A CONVERSATION With a user to produce a final document step by step. The whole process is meant to be
+      collaborative helping the user flesh out their ideas. Do not rush or optimize and skip any section.
+    </critical-rules>
   </llm>
-</task>
+</task> 

src/core/tools/shard-doc.xml

@@ -1,4 +1,4 @@
-<tool id="{bmad_folder}/core/tasks/shard-doc" name="Shard Document"
+<tool id=".bmad/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>

src/core/workflows/brainstorming/README.md

@@ -1,261 +0,0 @@
----
-last-redoc-date: 2025-09-28
----
-
-# Brainstorming Session Workflow
-
-## Overview
-
-The brainstorming workflow facilitates interactive brainstorming sessions using diverse creative techniques. This workflow acts as an AI facilitator guiding users through various ideation methods to generate and refine creative solutions in a structured, energetic, and highly interactive manner.
-
-## Key Features
-
-- **36 Creative Techniques**: Comprehensive library spanning collaborative, structured, creative, deep, theatrical, wild, and introspective approaches
-- **Interactive Facilitation**: AI acts as a skilled facilitator using "Yes, and..." methodology
-- **Flexible Approach Selection**: User-guided, AI-recommended, random, or progressive technique flows
-- **Context-Aware Sessions**: Supports domain-specific brainstorming through context document input
-- **Systematic Organization**: Converges ideas into immediate opportunities, future innovations, and moonshots
-- **Action Planning**: Prioritizes top ideas with concrete next steps and timelines
-- **Session Documentation**: Comprehensive structured reports capturing all insights and outcomes
-
-## Usage
-
-### Configuration
-
-The workflow leverages configuration from `{bmad_folder}/core/config.yaml`:
-
-- **output_folder**: Where session results are saved
-- **user_name**: Session participant identification
-
-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
-
-### Files Included
-
-```
-brainstorming/
-├── workflow.yaml           # Configuration and metadata
-├── instructions.md         # Step-by-step execution guide
-├── template.md            # Session report structure
-├── brain-methods.csv      # Database of 36 creative techniques
-└── README.md              # This file
-```
-
-## Creative Techniques Library
-
-The workflow includes 36 techniques organized into 7 categories:
-
-### Collaborative Techniques
-
-- **Yes And Building**: Build momentum through positive additions
-- **Brain Writing Round Robin**: Silent idea generation with sequential building
-- **Random Stimulation**: Use random catalysts for unexpected connections
-- **Role Playing**: Generate solutions from multiple stakeholder perspectives
-
-### Structured Approaches
-
-- **SCAMPER Method**: Systematic creativity through seven lenses (Substitute/Combine/Adapt/Modify/Put/Eliminate/Reverse)
-- **Six Thinking Hats**: Explore through six perspectives (facts/emotions/benefits/risks/creativity/process)
-- **Mind Mapping**: Visual branching from central concepts
-- **Resource Constraints**: Innovation through extreme limitations
-
-### Creative Methods
-
-- **What If Scenarios**: Explore radical possibilities by questioning constraints
-- **Analogical Thinking**: Find solutions through domain parallels
-- **Reversal Inversion**: Flip problems upside down for fresh angles
-- **First Principles Thinking**: Strip away assumptions to rebuild from fundamentals
-- **Forced Relationships**: Connect unrelated concepts for innovation
-- **Time Shifting**: Explore solutions across different time periods
-- **Metaphor Mapping**: Use extended metaphors as thinking tools
-
-### Deep Analysis
-
-- **Five Whys**: Drill down through causation layers to root causes
-- **Morphological Analysis**: Systematically explore parameter combinations
-- **Provocation Technique**: Extract useful ideas from absurd starting points
-- **Assumption Reversal**: Challenge and flip core assumptions
-- **Question Storming**: Generate questions before seeking answers
-
-### Theatrical Approaches
-
-- **Time Travel Talk Show**: Interview past/present/future selves
-- **Alien Anthropologist**: Examine through completely foreign eyes
-- **Dream Fusion Laboratory**: Start with impossible solutions, work backwards
-- **Emotion Orchestra**: Let different emotions lead separate sessions
-- **Parallel Universe Cafe**: Explore under alternative reality rules
-
-### Wild Methods
-
-- **Chaos Engineering**: Deliberately break things to discover robust solutions
-- **Guerrilla Gardening Ideas**: Plant unexpected solutions in unlikely places
-- **Pirate Code Brainstorm**: Take what works from anywhere and remix
-- **Zombie Apocalypse Planning**: Design for extreme survival scenarios
-- **Drunk History Retelling**: Explain with uninhibited simplicity
-
-### Introspective Delight
-
-- **Inner Child Conference**: Channel pure childhood curiosity
-- **Shadow Work Mining**: Explore what you're avoiding or resisting
-- **Values Archaeology**: Excavate deep personal values driving decisions
-- **Future Self Interview**: Seek wisdom from your wiser future self
-- **Body Wisdom Dialogue**: Let physical sensations guide ideation
-
-## Workflow Process
-
-### Phase 1: Session Setup (Step 1)
-
-- Context gathering (topic, goals, constraints)
-- Domain-specific guidance if context document provided
-- Session scope definition (broad exploration vs. focused ideation)
-
-### Phase 2: Approach Selection (Step 2)
-
-- **User-Selected**: Browse and choose specific techniques
-- **AI-Recommended**: Tailored technique suggestions based on context
-- **Random Selection**: Surprise technique for creative breakthrough
-- **Progressive Flow**: Multi-technique journey from broad to focused
-
-### Phase 3: Interactive Facilitation (Step 3)
-
-- Master facilitator approach using questions, not answers
-- "Yes, and..." building methodology
-- Energy monitoring and technique switching
-- Real-time idea capture and momentum building
-- Quantity over quality focus (aim: 100 ideas in 60 minutes)
-
-### Phase 4: Convergent Organization (Step 4)
-
-- Review and categorize all generated ideas
-- Identify patterns and themes across techniques
-- Sort into three priority buckets for action planning
-
-### Phase 5: Insight Extraction (Step 5)
-
-- Surface recurring themes across multiple techniques
-- Identify key realizations and surprising connections
-- Extract deeper patterns and meta-insights
-
-### Phase 6: Action Planning (Step 6)
-
-- Prioritize top 3 ideas for implementation
-- Define concrete next steps for each priority
-- Determine resource needs and realistic timelines
-
-### Phase 7: Session Reflection (Step 7)
-
-- Analyze what worked well and areas for further exploration
-- Recommend follow-up techniques and next session planning
-- Capture emergent questions for future investigation
-
-### Phase 8: Report Generation (Step 8)
-
-- Compile comprehensive structured report
-- Calculate total ideas generated and techniques used
-- Format all content for sharing and future reference
-
-## Output
-
-### Generated Files
-
-- **Primary output**: Structured session report saved to `{output_folder}/brainstorming-session-results-{date}.md`
-- **Context integration**: Links to previous brainstorming sessions if available
-
-### Output Structure
-
-1. **Executive Summary** - Topic, goals, techniques used, total ideas generated, key themes
-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 and Follow-up** - Session analysis, recommendations, next steps planning
-
-## Requirements
-
-- No special software requirements
-- 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
-
-## Best Practices
-
-### Before Starting
-
-1. **Define Clear Intent**: Know whether you want broad exploration or focused problem-solving
-2. **Gather Context**: Prepare any relevant background documents or domain knowledge
-3. **Set Time Expectations**: Plan for 45-90 minutes for a comprehensive session
-4. **Create Open Environment**: Ensure distraction-free space for creative thinking
-
-### During Execution
-
-1. **Embrace Quantity**: Generate many ideas without self-censoring
-2. **Build with "Yes, And"**: Accept and expand on ideas rather than judging
-3. **Stay Curious**: Follow unexpected connections and tangents
-4. **Trust the Process**: Let the facilitator guide you through technique transitions
-5. **Capture Everything**: Document all ideas, even seemingly silly ones
-6. **Monitor Energy**: Communicate when you need technique changes or breaks
-
-### After Completion
-
-1. **Review Within 24 Hours**: Re-read the report while insights are fresh
-2. **Act on Quick Wins**: Implement immediate opportunities within one week
-3. **Schedule Follow-ups**: Plan development sessions for promising concepts
-4. **Share Selectively**: Distribute relevant insights to appropriate stakeholders
-
-## Facilitation Principles
-
-The AI facilitator operates using these core principles:
-
-- **Ask, Don't Tell**: Use questions to draw out participant's own ideas
-- **Build, Don't Judge**: Use "Yes, and..." methodology, never "No, but..."
-- **Quantity Over Quality**: Aim for volume in generation phase
-- **Defer Judgment**: Evaluation comes after generation is complete
-- **Stay Curious**: Show genuine interest in participant's unique perspectives
-- **Monitor Energy**: Adapt technique and pace to participant's engagement level
-
-## Example Session Flow
-
-### Progressive Technique Flow
-
-1. **Mind Mapping** (10 min) - Build the landscape of possibilities
-2. **SCAMPER** (15 min) - Systematic exploration of improvement angles
-3. **Six Thinking Hats** (15 min) - Multiple perspectives on solutions
-4. **Forced Relationships** (10 min) - Creative synthesis of unexpected connections
-
-### Energy Checkpoints
-
-- After 15-20 minutes: "Should we continue with this technique or try something new?"
-- Before convergent phase: "Are you ready to start organizing ideas, or explore more?"
-- During action planning: "How's your energy for the final planning phase?"
-
-## Customization
-
-To customize this workflow:
-
-1. **Add New Techniques**: Extend `brain-methods.csv` with additional creative methods
-2. **Modify Facilitation Style**: Adjust prompts in `instructions.md` for different energy levels
-3. **Update Report Structure**: Modify `template.md` to include additional analysis sections
-4. **Create Domain Variants**: Develop specialized technique sets for specific industries
-
-## Version History
-
-- **v1.0.0** - Initial release
-  - 36 creative techniques across 7 categories
-  - Interactive facilitation with energy monitoring
-  - Comprehensive structured reporting
-  - Context-aware session guidance
-
-## Support
-
-For issues or questions:
-
-- Review technique descriptions in `brain-methods.csv` for facilitation guidance
-- Consult the workflow instructions in `instructions.md` for step-by-step details
-- Reference the template structure in `template.md` for output expectations
-- Follow BMAD documentation standards for workflow customization
-
----
-
-_Part of the BMad Method v6 - Creative Ideation and Synthesis (CIS) Module_

src/core/workflows/brainstorming/brain-methods.csv

@@ -1,36 +1,62 @@
-category,technique_name,description,facilitation_prompts,best_for,energy_level,typical_duration
-collaborative,Yes And Building,Build momentum through positive additions where each idea becomes a launching pad for the next - creates energetic collaborative flow,Yes and we could also...|Building on that idea...|That reminds me of...|What if we added?,team-building,high,15-20
-collaborative,Brain Writing Round Robin,Silent idea generation followed by building on others' written concepts - gives quieter voices equal contribution while maintaining documentation,Write your idea silently|Pass to the next person|Build on what you received|Keep ideas flowing,quiet-voices,moderate,20-25
-collaborative,Random Stimulation,Use random words/images as creative catalysts to force unexpected connections - breaks through mental blocks with serendipitous inspiration,Pick a random word/image|How does this relate?|What connections do you see?|Force a relationship
-collaborative,Role Playing,Generate solutions from multiple stakeholder perspectives - builds empathy while ensuring comprehensive consideration of all viewpoints,Think as a [role]|What would they want?|How would they approach this?|What matters to them?
-creative,What If Scenarios,Explore radical possibilities by questioning all constraints and assumptions - perfect for breaking through stuck thinking and discovering unexpected opportunities,What if we had unlimited resources?|What if the opposite were true?|What if this problem didn't exist?,innovation,high,15-20
-creative,Analogical Thinking,Find creative solutions by drawing parallels to other domains - helps transfer successful patterns from one context to another,This is like what?|How is this similar to...?|What other examples come to mind?
-creative,Reversal Inversion,Deliberately flip problems upside down to reveal hidden assumptions and fresh angles - great when conventional approaches aren't working,What if we did the opposite?|How could we make this worse?|What's the reverse approach?
-creative,First Principles Thinking,Strip away assumptions to rebuild from fundamental truths - essential for breakthrough innovation and solving complex problems,What do we know for certain?|What are the fundamental truths?|If we started from scratch?
-creative,Forced Relationships,Connect unrelated concepts to spark innovative bridges - excellent for generating unexpected solutions through creative collision,Take these two unrelated things|Find connections between them|What bridges exist?|How could they work together?
-creative,Time Shifting,Explore how solutions would work across different time periods - reveals constraints and opportunities by changing temporal context,How would this work in the past?|What about 100 years from now?|Different era constraints?|Time-based solutions?
-creative,Metaphor Mapping,Use extended metaphors as thinking tools to explore problems from new angles - transforms abstract challenges into tangible narratives,This problem is like a [metaphor]|Extend the metaphor|What elements map over?|What insights emerge?
-deep,Five Whys,Drill down through layers of causation to uncover root causes - essential for solving problems at their source rather than treating symptoms,Why did this happen?|Why is that?|And why is that true?|What's behind that?|Why ultimately?,problem-solving,moderate,10-15
-deep,Morphological Analysis,Systematically explore all possible parameter combinations - perfect for complex systems requiring comprehensive solution mapping,What are the key parameters?|List options for each|Try different combinations|What patterns emerge?
-deep,Provocation Technique,Use deliberately provocative statements to extract useful ideas from seemingly absurd starting points - catalyzes breakthrough thinking,What if [provocative statement]?|How could this be useful?|What idea does this trigger?|Extract the principle
-deep,Assumption Reversal,Challenge and flip core assumptions to rebuild from new foundations - essential for paradigm shifts and fresh perspectives,What assumptions are we making?|What if the opposite were true?|Challenge each assumption|Rebuild from new assumptions
-deep,Question Storming,Generate questions before seeking answers to properly define the problem space - ensures you're solving the right problem,Only ask questions|No answers allowed yet|What don't we know?|What should we be asking?
-introspective_delight,Inner Child Conference,Channel pure childhood curiosity and wonder - rekindles playful exploration and innocent questioning that cuts through adult complications,What would 7-year-old you ask?|Why why why?|Make it fun again|No boring allowed
-introspective_delight,Shadow Work Mining,Explore what you're actively avoiding or resisting - uncovers hidden insights by examining unconscious blocks and resistance patterns,What are you avoiding?|Where's the resistance?|What scares you about this?|Mine the shadows
-introspective_delight,Values Archaeology,Excavate the deep personal values driving your decisions - clarifies authentic priorities by digging to bedrock motivations,What really matters here?|Why do you care?|Dig to bedrock values|What's non-negotiable?
-introspective_delight,Future Self Interview,Seek wisdom from your wiser future self - gains long-term perspective through imagined temporal self-mentoring,Ask your 80-year-old self|What would you tell younger you?|Future wisdom speaks|Long-term perspective
-introspective_delight,Body Wisdom Dialogue,Let physical sensations and gut feelings guide ideation - taps somatic intelligence often ignored by purely mental approaches,What does your body say?|Where do you feel it?|Trust the tension|Follow physical cues
-structured,SCAMPER Method,Systematic creativity through seven lenses (Substitute/Combine/Adapt/Modify/Put/Eliminate/Reverse) - ideal for methodical product improvement and innovation,S-What could you substitute?|C-What could you combine?|A-How could you adapt?|M-What could you modify?|P-Put to other uses?|E-What could you eliminate?|R-What if reversed?
-structured,Six Thinking Hats,Explore problems through six distinct perspectives (facts/emotions/benefits/risks/creativity/process) - ensures comprehensive analysis without conflict,White-What facts do we know?|Red-How do you feel about this?|Yellow-What are the benefits?|Black-What could go wrong?|Green-What creative alternatives?|Blue-How should we think about this?
-structured,Mind Mapping,Visually branch ideas from a central concept to discover connections and expand thinking - perfect for organizing complex thoughts and seeing the big picture,Put the main idea in center|What branches from this?|How do these connect?|What sub-branches emerge?
-structured,Resource Constraints,Generate innovative solutions by imposing extreme limitations - forces essential priorities and creative efficiency under pressure,What if you had only $1?|No technology allowed?|One hour to solve?|Minimal resources only?
-theatrical,Time Travel Talk Show,Interview your past/present/future selves for temporal wisdom - playful method for gaining perspective across different life stages,Interview your past self|What would future you say?|Different timeline perspectives|Cross-temporal dialogue
-theatrical,Alien Anthropologist,Examine familiar problems through completely foreign eyes - reveals hidden assumptions by adopting an outsider's bewildered perspective,You're an alien observer|What seems strange?|How would you explain this?|Outside perspective insights
-theatrical,Dream Fusion Laboratory,Start with impossible fantasy solutions then reverse-engineer practical steps - makes ambitious thinking actionable through backwards design,Dream the impossible solution|Work backwards to reality|What steps bridge the gap?|Make magic practical
-theatrical,Emotion Orchestra,Let different emotions lead separate brainstorming sessions then harmonize - uses emotional intelligence for comprehensive perspective,Angry perspective ideas|Joyful approach|Fearful considerations|Hopeful solutions|Harmonize all voices
-theatrical,Parallel Universe Cafe,Explore solutions under alternative reality rules - breaks conventional thinking by changing fundamental assumptions about how things work,Different physics universe|Alternative social norms|Changed historical events|Reality rule variations
-wild,Chaos Engineering,Deliberately break things to discover robust solutions - builds anti-fragility by stress-testing ideas against worst-case scenarios,What if everything went wrong?|Break it on purpose|How does it fail gracefully?|Build from the rubble
-wild,Guerrilla Gardening Ideas,Plant unexpected solutions in unlikely places - uses surprise and unconventional placement for stealth innovation,Where's the least expected place?|Plant ideas secretly|Grow solutions underground|Surprise implementation
-wild,Pirate Code Brainstorm,Take what works from anywhere and remix without permission - encourages rule-bending rapid prototyping and maverick thinking,What would pirates steal?|Remix without asking|Take the best and run|No permission needed
-wild,Zombie Apocalypse Planning,Design solutions for extreme survival scenarios - strips away all but essential functions to find core value,Society collapsed - now what?|Only basics work|Build from nothing|Survival mode thinking
-wild,Drunk History Retelling,Explain complex ideas with uninhibited simplicity - removes overthinking barriers to find raw truth through simplified expression,Explain it like you're tipsy|No filter needed|Raw unedited thoughts|Simplify to absurdity
+category,technique_name,description
+collaborative,Yes And Building,"Build momentum through positive additions where each idea becomes a launching pad - use prompts like 'Yes and we could also...' or 'Building on that idea...' to create energetic collaborative flow that builds upon previous contributions"
+collaborative,Brain Writing Round Robin,"Silent idea generation followed by building on others' written concepts - gives quieter voices equal contribution while maintaining documentation through the sequence of writing silently, passing ideas, and building on received concepts"
+collaborative,Random Stimulation,"Use random words/images as creative catalysts to force unexpected connections - breaks through mental blocks with serendipitous inspiration by asking how random elements relate, what connections exist, and forcing relationships"
+collaborative,Role Playing,"Generate solutions from multiple stakeholder perspectives to build empathy while ensuring comprehensive consideration - embody different roles by asking what they want, how they'd approach problems, and what matters most to them"
+collaborative,Ideation Relay Race,"Rapid-fire idea building under time pressure creates urgency and breakthroughs - structure with 30-second additions, quick building on ideas, and fast passing to maintain creative momentum and prevent overthinking"
+creative,What If Scenarios,"Explore radical possibilities by questioning all constraints and assumptions - perfect for breaking through stuck thinking using prompts like 'What if we had unlimited resources?' 'What if the opposite were true?' or 'What if this problem didn't exist?'"
+creative,Analogical Thinking,"Find creative solutions by drawing parallels to other domains - transfer successful patterns by asking 'This is like what?' 'How is this similar to...' and 'What other examples come to mind?' to connect to existing solutions"
+creative,Reversal Inversion,"Deliberately flip problems upside down to reveal hidden assumptions and fresh angles - great when conventional approaches fail by asking 'What if we did the opposite?' 'How could we make this worse?' and 'What's the reverse approach?'"
+creative,First Principles Thinking,"Strip away assumptions to rebuild from fundamental truths - essential for breakthrough innovation by asking 'What do we know for certain?' 'What are the fundamental truths?' and 'If we started from scratch?'"
+creative,Forced Relationships,"Connect unrelated concepts to spark innovative bridges through creative collision - take two unrelated things, find connections between them, identify bridges, and explore how they could work together to generate unexpected solutions"
+creative,Time Shifting,"Explore solutions across different time periods to reveal constraints and opportunities by asking 'How would this work in the past?' 'What about 100 years from now?' 'Different era constraints?' and 'What time-based solutions apply?'"
+creative,Metaphor Mapping,"Use extended metaphors as thinking tools to explore problems from new angles - transforms abstract challenges into tangible narratives by asking 'This problem is like a metaphor,' extending the metaphor, and mapping elements to discover insights"
+creative,Cross-Pollination,"Transfer solutions from completely different industries or domains to spark breakthrough innovations by asking how industry X would solve this, what patterns work in field Y, and how to adapt solutions from domain Z"
+creative,Concept Blending,"Merge two or more existing concepts to create entirely new categories - goes beyond simple combination to genuine innovation by asking what emerges when concepts merge, what new category is created, and how the blend transcends original ideas"
+creative,Reverse Brainstorming,"Generate problems instead of solutions to identify hidden opportunities and unexpected pathways by asking 'What could go wrong?' 'How could we make this fail?' and 'What problems could we create?' to reveal solution insights"
+creative,Sensory Exploration,"Engage all five senses to discover multi-dimensional solution spaces beyond purely analytical thinking by asking what ideas feel, smell, taste, or sound like, and how different senses engage with the problem space"
+deep,Five Whys,"Drill down through layers of causation to uncover root causes - essential for solving problems at source rather than symptoms by asking 'Why did this happen?' repeatedly until reaching fundamental drivers and ultimate causes"
+deep,Morphological Analysis,"Systematically explore all possible parameter combinations for complex systems requiring comprehensive solution mapping - identify key parameters, list options for each, try different combinations, and identify emerging patterns"
+deep,Provocation Technique,"Use deliberately provocative statements to extract useful ideas from seemingly absurd starting points - catalyzes breakthrough thinking by asking 'What if provocative statement?' 'How could this be useful?' 'What idea triggers?' and 'Extract the principle'"
+deep,Assumption Reversal,"Challenge and flip core assumptions to rebuild from new foundations - essential for paradigm shifts by asking 'What assumptions are we making?' 'What if the opposite were true?' 'Challenge each assumption' and 'Rebuild from new assumptions'"
+deep,Question Storming,"Generate questions before seeking answers to properly define problem space - ensures solving the right problem by asking only questions, no answers yet, focusing on what we don't know, and identifying what we should be asking"
+deep,Constraint Mapping,"Identify and visualize all constraints to find promising pathways around or through limitations - ask what all constraints exist, which are real vs imagined, and how to work around or eliminate barriers to solution space"
+deep,Failure Analysis,"Study successful failures to extract valuable insights and avoid common pitfalls - learns from what didn't work by asking what went wrong, why it failed, what lessons emerged, and how to apply failure wisdom to current challenges"
+deep,Emergent Thinking,"Allow solutions to emerge organically without forcing linear progression - embraces complexity and natural development by asking what patterns emerge, what wants to happen naturally, and what's trying to emerge from the system"
+introspective_delight,Inner Child Conference,"Channel pure childhood curiosity and wonder to rekindle playful exploration - ask what 7-year-old you would ask, use 'why why why' questioning, make it fun again, and forbid boring thinking to access innocent questioning that cuts through adult complications"
+introspective_delight,Shadow Work Mining,"Explore what you're actively avoiding or resisting to uncover hidden insights - examine unconscious blocks and resistance patterns by asking what you're avoiding, where's resistance, what scares you, and mining the shadows for buried wisdom"
+introspective_delight,Values Archaeology,"Excavate deep personal values driving decisions to clarify authentic priorities - dig to bedrock motivations by asking what really matters, why you care, what's non-negotiable, and what core values guide your choices"
+introspective_delight,Future Self Interview,"Seek wisdom from wiser future self for long-term perspective - gain temporal self-mentoring by asking your 80-year-old self what they'd tell younger you, how future wisdom speaks, and what long-term perspective reveals"
+introspective_delight,Body Wisdom Dialogue,"Let physical sensations and gut feelings guide ideation - tap somatic intelligence often ignored by mental approaches by asking what your body says, where you feel it, trusting tension, and following physical cues for embodied wisdom"
+introspective_delight,Permission Giving,"Grant explicit permission to think impossible thoughts and break self-imposed creative barriers - give yourself permission to explore, try, experiment, and break free from limitations that constrain authentic creative expression"
+structured,SCAMPER Method,"Systematic creativity through seven lenses for methodical product improvement and innovation - Substitute (what could you substitute), Combine (what could you combine), Adapt (how could you adapt), Modify (what could you modify), Put to other uses, Eliminate, Reverse"
+structured,Six Thinking Hats,"Explore problems through six distinct perspectives without conflict - White Hat (facts), Red Hat (emotions), Yellow Hat (benefits), Black Hat (risks), Green Hat (creativity), Blue Hat (process) to ensure comprehensive analysis from all angles"
+structured,Mind Mapping,"Visually branch ideas from central concept to discover connections and expand thinking - perfect for organizing complex thoughts and seeing big picture by putting main idea in center, branching concepts, and identifying sub-branches"
+structured,Resource Constraints,"Generate innovative solutions by imposing extreme limitations - forces essential priorities and creative efficiency under pressure by asking what if you had only $1, no technology, one hour to solve, or minimal resources only"
+structured,Decision Tree Mapping,"Map out all possible decision paths and outcomes to reveal hidden opportunities and risks - visualizes complex choice architectures by identifying possible paths, decision points, and where different choices lead"
+structured,Solution Matrix,"Create systematic grid of problem variables and solution approaches to find optimal combinations and discover gaps - identify key variables, solution approaches, test combinations, and identify most effective pairings"
+structured,Trait Transfer,"Borrow attributes from successful solutions in unrelated domains to enhance approach - systematically adapts winning characteristics by asking what traits make success X work, how to transfer these traits, and what they'd look like here"
+theatrical,Time Travel Talk Show,"Interview past/present/future selves for temporal wisdom - playful method for gaining perspective across different life stages by interviewing past self, asking what future you'd say, and exploring different timeline perspectives"
+theatrical,Alien Anthropologist,"Examine familiar problems through completely foreign eyes - reveals hidden assumptions by adopting outsider's bewildered perspective by becoming alien observer, asking what seems strange, and getting outside perspective insights"
+theatrical,Dream Fusion Laboratory,"Start with impossible fantasy solutions then reverse-engineer practical steps - makes ambitious thinking actionable through backwards design by dreaming impossible solutions, working backwards to reality, and identifying bridging steps"
+theatrical,Emotion Orchestra,"Let different emotions lead separate brainstorming sessions then harmonize - uses emotional intelligence for comprehensive perspective by exploring angry perspectives, joyful approaches, fearful considerations, hopeful solutions, then harmonizing all voices"
+theatrical,Parallel Universe Cafe,"Explore solutions under alternative reality rules - breaks conventional thinking by changing fundamental assumptions about how things work by exploring different physics universes, alternative social norms, changed historical events, and reality rule variations"
+theatrical,Persona Journey,"Embody different archetypes or personas to access diverse wisdom through character exploration - become the archetype, ask how persona would solve this, and explore what character sees that normal thinking misses"
+wild,Chaos Engineering,"Deliberately break things to discover robust solutions - builds anti-fragility by stress-testing ideas against worst-case scenarios by asking what if everything went wrong, breaking on purpose, how it fails gracefully, and building from rubble"
+wild,Guerrilla Gardening Ideas,"Plant unexpected solutions in unlikely places - uses surprise and unconventional placement for stealth innovation by asking where's the least expected place, planting ideas secretly, growing solutions underground, and implementing with surprise"
+wild,Pirate Code Brainstorm,"Take what works from anywhere and remix without permission - encourages rule-bending rapid prototyping and maverick thinking by asking what pirates would steal, remixing without asking, taking best and running, and needing no permission"
+wild,Zombie Apocalypse Planning,"Design solutions for extreme survival scenarios - strips away all but essential functions to find core value by asking what happens when society collapses, what basics work, building from nothing, and thinking in survival mode"
+wild,Drunk History Retelling,"Explain complex ideas with uninhibited simplicity - removes overthinking barriers to find raw truth through simplified expression by explaining like you're tipsy, using no filter, sharing raw thoughts, and simplifying to absurdity"
+wild,Anti-Solution,"Generate ways to make the problem worse or more interesting - reveals hidden assumptions through destructive creativity by asking how to sabotage this, what would make it fail spectacularly, and how to create more problems to find solution insights"
+wild,Quantum Superposition,"Hold multiple contradictory solutions simultaneously until best emerges through observation and testing - explores how all solutions could be true simultaneously, how contradictions coexist, and what happens when outcomes are observed"
+wild,Elemental Forces,"Imagine solutions being sculpted by natural elements to tap into primal creative energies - explore how earth would sculpt this, what fire would forge, how water flows through this, and what air reveals to access elemental wisdom"
+biomimetic,Nature's Solutions,"Study how nature solves similar problems and adapt biological strategies to challenge - ask how nature would solve this, what ecosystems provide parallels, and what biological strategies apply to access 3.8 billion years of evolutionary wisdom"
+biomimetic,Ecosystem Thinking,"Analyze problem as ecosystem to identify symbiotic relationships, natural succession, and ecological principles - explore symbiotic relationships, natural succession application, and ecological principles for systems thinking"
+biomimetic,Evolutionary Pressure,"Apply evolutionary principles to gradually improve solutions through selective pressure and adaptation - ask how evolution would optimize this, what selective pressures apply, and how this adapts over time to harness natural selection wisdom"
+quantum,Observer Effect,"Recognize how observing and measuring solutions changes their behavior - uses quantum principles for innovation by asking how observing changes this, what measurement effects matter, and how to use observer effect advantageously"
+quantum,Entanglement Thinking,"Explore how different solution elements might be connected regardless of distance - reveals hidden relationships by asking what elements are entangled, how distant parts affect each other, and what hidden connections exist between solution components"
+quantum,Superposition Collapse,"Hold multiple potential solutions simultaneously until constraints force single optimal outcome - leverages quantum decision theory by asking what if all options were possible, what constraints force collapse, and which solution emerges when observed"
+cultural,Indigenous Wisdom,"Draw upon traditional knowledge systems and indigenous approaches overlooked by modern thinking - ask how specific cultures would approach this, what traditional knowledge applies, and what ancestral wisdom guides us to access overlooked problem-solving methods"
+cultural,Fusion Cuisine,"Mix cultural approaches and perspectives like fusion cuisine - creates innovation through cultural cross-pollination by asking what happens when mixing culture A with culture B, what cultural hybrids emerge, and what fusion creates"
+cultural,Ritual Innovation,"Apply ritual design principles to create transformative experiences and solutions - uses anthropological insights for human-centered design by asking what ritual would transform this, how to make it ceremonial, and what transformation this needs"
+cultural,Mythic Frameworks,"Use myths and archetypal stories as frameworks for understanding and solving problems - taps into collective unconscious by asking what myth parallels this, what archetypes are involved, and how mythic structure informs solution"

src/core/workflows/brainstorming/instructions.md

@@ -1,315 +0,0 @@
-# Brainstorming Session Instructions
-
-## Workflow
-
-<workflow>
-<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">
-  <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>
-
-</step>
-
-<step n="2" goal="Present Approach Options">
-
-Based on the context from Step 1, present these four approach options:
-
-<ask response="selection">
-1. **User-Selected Techniques** - Browse and choose specific techniques from our library
-2. **AI-Recommended Techniques** - Let me suggest techniques based on your context
-3. **Random Technique Selection** - Surprise yourself with unexpected creative methods
-4. **Progressive Technique Flow** - Start broad, then narrow down systematically
-
-Which approach would you prefer? (Enter 1-4)
-</ask>
-
-  <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)">
-      <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 if="open exploration">
-      <action>Display all 7 categories with helpful descriptions</action>
-    </check>
-
-    Category descriptions to guide selection:
-    - **Structured:** Systematic frameworks for thorough exploration
-    - **Creative:** Innovative approaches for breakthrough thinking
-    - **Collaborative:** Group dynamics and team ideation methods
-    - **Deep:** Analytical methods for root cause and insight
-    - **Theatrical:** Playful exploration for radical perspectives
-    - **Wild:** Extreme thinking for pushing boundaries
-    - **Introspective Delight:** Inner wisdom and authentic exploration
-
-    For each category, show 3-5 representative techniques with brief descriptions.
-
-    Ask in your own voice: "Which technique(s) interest you? You can choose by name, number, or tell me what you're drawn to."
-
-  </step>
-
-  <step n="2b" title="AI-Recommended Techniques" if="selection==2">
-    <action>Review {brain_techniques} and select 3-5 techniques that best fit the context</action>
-
-    Analysis Framework:
-
-    1. **Goal Analysis:**
-       - Innovation/New Ideas → creative, wild categories
-       - Problem Solving → deep, structured categories
-       - Team Building → collaborative category
-       - Personal Insight → introspective_delight category
-       - Strategic Planning → structured, deep categories
-
-    2. **Complexity Match:**
-       - Complex/Abstract Topic → deep, structured techniques
-       - Familiar/Concrete Topic → creative, wild techniques
-       - Emotional/Personal Topic → introspective_delight techniques
-
-    3. **Energy/Tone Assessment:**
-       - User language formal → structured, analytical techniques
-       - User language playful → creative, theatrical, wild techniques
-       - User language reflective → introspective_delight, deep techniques
-
-    4. **Time Available:**
-       - <30 min → 1-2 focused techniques
-       - 30-60 min → 2-3 complementary techniques
-       - >60 min → Consider progressive flow (3-5 techniques)
-
-    Present recommendations in your own voice with:
-    - Technique name (category)
-    - Why it fits their context (specific)
-    - What they'll discover (outcome)
-    - Estimated time
-
-    Example structure:
-    "Based on your goal to [X], I recommend:
-
-    1. **[Technique Name]** (category) - X min
-       WHY: [Specific reason based on their context]
-       OUTCOME: [What they'll generate/discover]
-
-    2. **[Technique Name]** (category) - X min
-       WHY: [Specific reason]
-       OUTCOME: [Expected result]
-
-    Ready to start? [c] or would you prefer different techniques? [r]"
-
-  </step>
-
-  <step n="2c" title="Single Random Technique Selection" if="selection==3">
-    <action>Load all techniques from {brain_techniques} CSV</action>
-    <action>Select random technique using true randomization</action>
-    <action>Build excitement about unexpected choice</action>
-    <format>
-      Let's shake things up! The universe has chosen:
-      **{{technique_name}}** - {{description}}
-    </format>
-  </step>
-
-  <step n="2d" title="Progressive Flow" if="selection==4">
-    <action>Design a progressive journey through {brain_techniques} based on session context</action>
-    <action>Analyze stated_goals and session_topic from Step 1</action>
-    <action>Determine session length (ask if not stated)</action>
-    <action>Select 3-4 complementary techniques that build on each other</action>
-
-    Journey Design Principles:
-    - Start with divergent exploration (broad, generative)
-    - Move through focused deep dive (analytical or creative)
-    - End with convergent synthesis (integration, prioritization)
-
-    Common Patterns by Goal:
-    - **Problem-solving:** Mind Mapping → Five Whys → Assumption Reversal
-    - **Innovation:** What If Scenarios → Analogical Thinking → Forced Relationships
-    - **Strategy:** First Principles → SCAMPER → Six Thinking Hats
-    - **Team Building:** Brain Writing → Yes And Building → Role Playing
-
-    Present your recommended journey with:
-    - Technique names and brief why
-    - Estimated time for each (10-20 min)
-    - Total session duration
-    - Rationale for sequence
-
-    Ask in your own voice: "How does this flow sound? We can adjust as we go."
-
-  </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">
-
-<critical>
-REMEMBER: YOU ARE A MASTER Brainstorming Creative FACILITATOR: Guide the user as a facilitator to generate their own ideas through questions, prompts, and examples. Don't brainstorm for them unless they explicitly request it.
-</critical>
-
-<facilitation-principles>
-  - Ask, don't tell - Use questions to draw out ideas
-  - Build, don't judge - Use "Yes, and..." never "No, but..."
-  - Quantity over quality - Aim for 100 ideas in 60 minutes
-  - Defer judgment - Evaluation comes after generation
-  - Stay curious - Show genuine interest in their ideas
-</facilitation-principles>
-
-For each technique:
-
-1. **Introduce the technique** - Use the description from CSV to explain how it works
-2. **Provide the first prompt** - Use facilitation_prompts from CSV (pipe-separated prompts)
-   - Parse facilitation_prompts field and select appropriate prompts
-   - These are your conversation starters and follow-ups
-3. **Wait for their response** - Let them generate ideas
-4. **Build on their ideas** - Use "Yes, and..." or "That reminds me..." or "What if we also..."
-5. **Ask follow-up questions** - "Tell me more about...", "How would that work?", "What else?"
-6. **Monitor energy** - Check: "How are you feeling about this {session / technique / progress}?"
-   - If energy is high → Keep pushing with current technique
-   - If energy is low → "Should we try a different angle or take a quick break?"
-7. **Keep momentum** - Celebrate: "Great! You've generated [X] ideas so far!"
-8. **Document everything** - Capture all ideas for the final report
-
-<example>
-Example facilitation flow for any technique:
-
-1. Introduce: "Let's try [technique_name]. [Adapt description from CSV to their context]."
-
-2. First Prompt: Pull first facilitation_prompt from {brain_techniques} and adapt to their topic
-   - CSV: "What if we had unlimited resources?"
-   - Adapted: "What if you had unlimited resources for [their_topic]?"
-
-3. Build on Response: Use "Yes, and..." or "That reminds me..." or "Building on that..."
-
-4. Next Prompt: Pull next facilitation_prompt when ready to advance
-
-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>
-
-Continue engaging with the technique until the user indicates they want to:
-
-- Switch to a different technique ("Ready for a different approach?")
-- Apply current ideas to a new technique
-- Move to the convergent phase
-- End the session
-
-<energy-checkpoint>
-  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>
-
-</step>
-
-<step n="4" goal="Convergent Phase - Organize Ideas">
-
-<transition-check>
-  "We've generated a lot of great ideas! Are you ready to start organizing them, or would you like to explore more?"
-</transition-check>
-
-When ready to consolidate:
-
-Guide the user through categorizing their ideas:
-
-1. **Review all generated ideas** - Display everything captured so far
-2. **Identify patterns** - "I notice several ideas about X... and others about Y..."
-3. **Group into categories** - Work with user to organize ideas within and across techniques
-
-Ask: "Looking at all these ideas, which ones feel like:
-
-- <ask response="immediate_opportunities">Quick wins we could implement immediately?</ask>
-- <ask response="future_innovations">Promising concepts that need more development?</ask>
-- <ask response="moonshots">Bold moonshots worth pursuing long-term?"</ask>
-
-<template-output>immediate_opportunities, future_innovations, moonshots</template-output>
-
-</step>
-
-<step n="5" goal="Extract Insights and Themes">
-
-Analyze the session to identify deeper patterns:
-
-1. **Identify recurring themes** - What concepts appeared across multiple techniques? -> key_themes
-2. **Surface key insights** - What realizations emerged during the process? -> insights_learnings
-3. **Note surprising connections** - What unexpected relationships were discovered? -> insights_learnings
-
-<invoke-task halt="true">{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml</invoke-task>
-
-<template-output>key_themes, insights_learnings</template-output>
-
-</step>
-
-<step n="6" goal="Action Planning">
-
-<energy-check>
-  "Great work so far! How's your energy for the final planning phase?"
-</energy-check>
-
-Work with the user to prioritize and plan next steps:
-
-<ask>Of all the ideas we've generated, which 3 feel most important to pursue?</ask>
-
-For each priority:
-
-1. Ask why this is a priority
-2. Identify concrete next steps
-3. Determine resource needs
-4. Set realistic timeline
-
-<template-output>priority_1_name, priority_1_rationale, priority_1_steps, priority_1_resources, priority_1_timeline</template-output>
-<template-output>priority_2_name, priority_2_rationale, priority_2_steps, priority_2_resources, priority_2_timeline</template-output>
-<template-output>priority_3_name, priority_3_rationale, priority_3_steps, priority_3_resources, priority_3_timeline</template-output>
-
-</step>
-
-<step n="7" goal="Session Reflection">
-
-Conclude with meta-analysis of the session:
-
-1. **What worked well** - Which techniques or moments were most productive?
-2. **Areas to explore further** - What topics deserve deeper investigation?
-3. **Recommended follow-up techniques** - What methods would help continue this work?
-4. **Emergent questions** - What new questions arose that we should address?
-5. **Next session planning** - When and what should we brainstorm next?
-
-<template-output>what_worked, areas_exploration, recommended_techniques, questions_emerged</template-output>
-<template-output>followup_topics, timeframe, preparation</template-output>
-
-</step>
-
-<step n="8" goal="Generate Final Report">
-
-Compile all captured content into the structured report template:
-
-1. Calculate total ideas generated across all techniques
-2. List all techniques used with duration estimates
-3. Format all content according to template structure
-4. Ensure all placeholders are filled with actual content
-
-<template-output>agent_role, agent_name, user_name, techniques_list, total_ideas</template-output>
-
-</step>
-
-</workflow>

src/core/workflows/brainstorming/steps/step-01-session-setup.md

@@ -0,0 +1,196 @@
+# Step 1: Session Setup and Continuation Detection
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- ✅ ALWAYS treat this as collaborative facilitation
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on session setup and continuation detection only
+- 🚪 DETECT existing workflow state and handle continuation properly
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+- Brain techniques loaded on-demand from CSV when needed
+
+## YOUR TASK:
+
+Initialize the brainstorming workflow by detecting continuation state and setting up session context.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Workflow
+
+First, check if the output document already exists:
+
+- Look for file at `{output_folder}/analysis/brainstorming-session-{{date}}.md`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted`:
+
+- **STOP here** and load `./step-01b-continue.md` immediately
+- Do not proceed with any initialization tasks
+- Let step-01b handle the continuation logic
+
+### 3. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Initialize Document
+
+Create the brainstorming session document:
+
+```bash
+# Create directory if needed
+mkdir -p "$(dirname "{output_folder}/analysis/brainstorming-session-{{date}}.md")"
+
+# Initialize from template
+cp "{template_path}" "{output_folder}/analysis/brainstorming-session-{{date}}.md"
+```
+
+#### B. Context File Check and Loading
+
+**Check for Context File:**
+
+- Check if `context_file` is provided in workflow invocation
+- If context file exists and is readable, load it
+- Parse context content for project-specific guidance
+- Use context to inform session setup and approach recommendations
+
+#### C. Session Context Gathering
+
+"Welcome {{user_name}}! I'm excited to facilitate your brainstorming session. I'll guide you through proven creativity techniques to generate innovative ideas and breakthrough solutions.
+
+**Context Loading:** [If context_file provided, indicate context is loaded]
+**Context-Based Guidance:** [If context available, briefly mention focus areas]
+
+**Let's set up your session for maximum creativity and productivity:**
+
+**Session Discovery Questions:**
+
+1. **What are we brainstorming about?** (The central topic or challenge)
+2. **What specific outcomes are you hoping for?** (Types of ideas, solutions, or insights)"
+
+#### D. Process User Responses
+
+Wait for user responses, then:
+
+**Session Analysis:**
+"Based on your responses, I understand we're focusing on **[summarized topic]** with goals around **[summarized objectives]**.
+
+**Session Parameters:**
+
+- **Topic Focus:** [Clear topic articulation]
+- **Primary Goals:** [Specific outcome objectives]
+
+**Does this accurately capture what you want to achieve?**"
+
+#### E. Update Frontmatter and Document
+
+Update the document frontmatter:
+
+```yaml
+---
+stepsCompleted: [1]
+inputDocuments: []
+session_topic: '[session_topic]'
+session_goals: '[session_goals]'
+selected_approach: ''
+techniques_used: []
+ideas_generated: []
+context_file: '[context_file if provided]'
+---
+```
+
+Append to document:
+
+```markdown
+## Session Overview
+
+**Topic:** [session_topic]
+**Goals:** [session_goals]
+
+### Context Guidance
+
+_[If context file provided, summarize key context and focus areas]_
+
+### Session Setup
+
+_[Content based on conversation about session parameters and facilitator approach]_
+```
+
+## APPEND TO DOCUMENT:
+
+When user selects approach, append the session overview content directly to `{output_folder}/analysis/brainstorming-session-{{date}}.md` using the structure from above.
+
+### E. Continue to Technique Selection
+
+"**Session setup complete!** I have a clear understanding of your goals and can select the perfect techniques for your brainstorming needs.
+
+**Ready to explore technique approaches?**
+[1] User-Selected Techniques - Browse our complete technique library
+[2] AI-Recommended Techniques - Get customized suggestions based on your goals
+[3] Random Technique Selection - Discover unexpected creative methods
+[4] Progressive Technique Flow - Start broad, then systematically narrow focus
+
+Which approach appeals to you most? (Enter 1-4)"
+
+### 4. Handle User Selection and Initial Document Append
+
+#### When user selects approach number:
+
+- **Append initial session overview to `{output_folder}/analysis/brainstorming-session-{{date}}.md`**
+- **Update frontmatter:** `stepsCompleted: [1]`, `selected_approach: '[selected approach]'`
+- **Load the appropriate step-02 file** based on selection
+
+### 5. Handle User Selection
+
+After user selects approach number:
+
+- **If 1:** Load `./step-02a-user-selected.md`
+- **If 2:** Load `./step-02b-ai-recommended.md`
+- **If 3:** Load `./step-02c-random-selection.md`
+- **If 4:** Load `./step-02d-progressive-flow.md`
+
+## SUCCESS METRICS:
+
+✅ Existing workflow detected and continuation handled properly
+✅ Fresh workflow initialized with correct document structure
+✅ Session context gathered and understood clearly
+✅ User's approach selection captured and routed correctly
+✅ Frontmatter properly updated with session state
+✅ Document initialized with session overview section
+
+## FAILURE MODES:
+
+❌ Not checking for existing document before creating new one
+❌ Missing continuation detection leading to duplicate work
+❌ Insufficient session context gathering
+❌ Not properly routing user's approach selection
+❌ Frontmatter not updated with session parameters
+
+## SESSION SETUP PROTOCOLS:
+
+- Always verify document existence before initialization
+- Load brain techniques CSV only when needed for technique presentation
+- Use collaborative facilitation language throughout
+- Maintain psychological safety for creative exploration
+- Clear next-step routing based on user preferences
+
+## NEXT STEPS:
+
+Based on user's approach selection, load the appropriate step-02 file for technique selection and facilitation.
+
+Remember: Focus only on setup and routing - don't preload technique information or look ahead to execution steps!

src/core/workflows/brainstorming/steps/step-01b-continue.md

@@ -0,0 +1,121 @@
+# Step 1b: Workflow Continuation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A CONTINUATION FACILITATOR, not a fresh starter
+- 🎯 RESPECT EXISTING WORKFLOW state and progress
+- 📋 UNDERSTAND PREVIOUS SESSION context and outcomes
+- 🔍 SEAMLESSLY RESUME from where user left off
+- 💬 MAINTAIN CONTINUITY in session flow and rapport
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load and analyze existing document thoroughly
+- 💾 Update frontmatter with continuation state
+- 📖 Present current status and next options clearly
+- 🚫 FORBIDDEN repeating completed work or asking same questions
+
+## CONTEXT BOUNDARIES:
+
+- Existing document with frontmatter is available
+- Previous steps completed indicate session progress
+- Brain techniques CSV loaded when needed for remaining steps
+- User may want to continue, modify, or restart
+
+## YOUR TASK:
+
+Analyze existing brainstorming session state and provide seamless continuation options.
+
+## CONTINUATION SEQUENCE:
+
+### 1. Analyze Existing Session
+
+Load existing document and analyze current state:
+
+**Document Analysis:**
+
+- Read existing `{output_folder}/analysis/brainstorming-session-{{date}}.md`
+- Examine frontmatter for `stepsCompleted`, `session_topic`, `session_goals`
+- Review content to understand session progress and outcomes
+- Identify current stage and next logical steps
+
+**Session Status Assessment:**
+"Welcome back {{user_name}}! I can see your brainstorming session on **[session_topic]** from **[date]**.
+
+**Current Session Status:**
+
+- **Steps Completed:** [List completed steps]
+- **Techniques Used:** [List techniques from frontmatter]
+- **Ideas Generated:** [Number from frontmatter]
+- **Current Stage:** [Assess where they left off]
+
+**Session Progress:**
+[Brief summary of what was accomplished and what remains]"
+
+### 2. Present Continuation Options
+
+Based on session analysis, provide appropriate options:
+
+**If Session Completed:**
+"Your brainstorming session appears to be complete!
+
+**Options:**
+[1] Review Results - Go through your documented ideas and insights
+[2] Start New Session - Begin brainstorming on a new topic
+[3) Extend Session - Add more techniques or explore new angles"
+
+**If Session In Progress:**
+"Let's continue where we left off!
+
+**Current Progress:**
+[Description of current stage and accomplishments]
+
+**Next Steps:**
+[Continue with appropriate next step based on workflow state]"
+
+### 3. Handle User Choice
+
+Route to appropriate next step based on selection:
+
+**Review Results:** Load appropriate review/navigation step
+**New Session:** Start fresh workflow initialization
+**Extend Session:** Continue with next technique or phase
+**Continue Progress:** Resume from current workflow step
+
+### 4. Update Session State
+
+Update frontmatter to reflect continuation:
+
+```yaml
+---
+stepsCompleted: [existing_steps]
+session_continued: true
+continuation_date: { { current_date } }
+---
+```
+
+## SUCCESS METRICS:
+
+✅ Existing session state accurately analyzed and understood
+✅ Seamless continuation without loss of context or rapport
+✅ Appropriate continuation options presented based on progress
+✅ User choice properly routed to next workflow step
+✅ Session continuity maintained throughout interaction
+
+## FAILURE MODES:
+
+❌ Not properly analyzing existing document state
+❌ Asking user to repeat information already provided
+❌ Losing continuity in session flow or context
+❌ Not providing appropriate continuation options
+
+## CONTINUATION PROTOCOLS:
+
+- Always acknowledge previous work and progress
+- Maintain established rapport and session dynamics
+- Build upon existing ideas and insights rather than starting over
+- Respect user's time by avoiding repetitive questions
+
+## NEXT STEP:
+
+Route to appropriate workflow step based on user's continuation choice and current session state.

src/core/workflows/brainstorming/steps/step-02a-user-selected.md

@@ -0,0 +1,224 @@
+# Step 2a: User-Selected Techniques
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A TECHNIQUE LIBRARIAN, not a recommender
+- 🎯 LOAD TECHNIQUES ON-DEMAND from brain-methods.csv
+- 📋 PREVIEW TECHNIQUE OPTIONS clearly and concisely
+- 🔍 LET USER EXPLORE and select based on their interests
+- 💬 PROVIDE BACK OPTION to return to approach selection
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load brain techniques CSV only when needed for presentation
+- ⚠️ Present [B] back option and [C] continue options
+- 💾 Update frontmatter with selected techniques
+- 📖 Route to technique execution after confirmation
+- 🚫 FORBIDDEN making recommendations or steering choices
+
+## CONTEXT BOUNDARIES:
+
+- Session context from Step 1 is available
+- Brain techniques CSV contains 36+ techniques across 7 categories
+- User wants full control over technique selection
+- May need to present techniques by category or search capability
+
+## YOUR TASK:
+
+Load and present brainstorming techniques from CSV, allowing user to browse and select based on their preferences.
+
+## USER SELECTION SEQUENCE:
+
+### 1. Load Brain Techniques Library
+
+Load techniques from CSV on-demand:
+
+"Perfect! Let's explore our complete brainstorming techniques library. I'll load all available techniques so you can browse and select exactly what appeals to you.
+
+**Loading Brain Techniques Library...**"
+
+**Load CSV and parse:**
+
+- Read `brain-methods.csv`
+- Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
+- Organize by categories for browsing
+
+### 2. Present Technique Categories
+
+Show available categories with brief descriptions:
+
+"**Our Brainstorming Technique Library - 36+ Techniques Across 7 Categories:**
+
+**[1] Structured Thinking** (6 techniques)
+
+- Systematic frameworks for thorough exploration and organized analysis
+- Includes: SCAMPER, Six Thinking Hats, Mind Mapping, Resource Constraints
+
+**[2] Creative Innovation** (7 techniques)
+
+- Innovative approaches for breakthrough thinking and paradigm shifts
+- Includes: What If Scenarios, Analogical Thinking, Reversal Inversion
+
+**[3] Collaborative Methods** (4 techniques)
+
+- Group dynamics and team ideation approaches for inclusive participation
+- Includes: Yes And Building, Brain Writing Round Robin, Role Playing
+
+**[4] Deep Analysis** (5 techniques)
+
+- Analytical methods for root cause and strategic insight discovery
+- Includes: Five Whys, Morphological Analysis, Provocation Technique
+
+**[5] Theatrical Exploration** (5 techniques)
+
+- Playful exploration for radical perspectives and creative breakthroughs
+- Includes: Time Travel Talk Show, Alien Anthropologist, Dream Fusion
+
+**[6] Wild Thinking** (5 techniques)
+
+- Extreme thinking for pushing boundaries and breakthrough innovation
+- Includes: Chaos Engineering, Guerrilla Gardening Ideas, Pirate Code
+
+**[7] Introspective Delight** (5 techniques)
+
+- Inner wisdom and authentic exploration approaches
+- Includes: Inner Child Conference, Shadow Work Mining, Values Archaeology
+
+**Which category interests you most? Enter 1-7, or tell me what type of thinking you're drawn to.**"
+
+### 3. Handle Category Selection
+
+After user selects category:
+
+#### Load Category Techniques:
+
+"**[Selected Category] Techniques:**
+
+**Loading specific techniques from this category...**"
+
+**Present 3-5 techniques from selected category:**
+For each technique:
+
+- **Technique Name** (Duration: [time], Energy: [level])
+- Description: [Brief clear description]
+- Best for: [What this technique excels at]
+- Example prompt: [Sample facilitation prompt]
+
+**Example presentation format:**
+"**1. SCAMPER Method** (Duration: 20-30 min, Energy: Moderate)
+
+- Systematic creativity through seven lenses (Substitute/Combine/Adapt/Modify/Put/Eliminate/Reverse)
+- Best for: Product improvement, innovation challenges, systematic idea generation
+- Example prompt: "What could you substitute in your current approach to create something new?"
+
+**2. Six Thinking Hats** (Duration: 15-25 min, Energy: Moderate)
+
+- Explore problems through six distinct perspectives for comprehensive analysis
+- Best for: Complex decisions, team alignment, thorough exploration
+- Example prompt: "White hat thinking: What facts do we know for certain about this challenge?"
+
+### 4. Allow Technique Selection
+
+"**Which techniques from this category appeal to you?**
+
+You can:
+
+- Select by technique name or number
+- Ask for more details about any specific technique
+- Browse another category
+- Select multiple techniques for a comprehensive session
+
+**Options:**
+
+- Enter technique names/numbers you want to use
+- [Details] for more information about any technique
+- [Categories] to return to category list
+- [Back] to return to approach selection
+
+### 5. Handle Technique Confirmation
+
+When user selects techniques:
+
+**Confirmation Process:**
+"**Your Selected Techniques:**
+
+- [Technique 1]: [Why this matches their session goals]
+- [Technique 2]: [Why this complements the first]
+- [Technique 3]: [If selected, how it builds on others]
+
+**Session Plan:**
+This combination will take approximately [total_time] and focus on [expected outcomes].
+
+**Confirm these choices?**
+[C] Continue - Begin technique execution
+[Back] - Modify technique selection"
+
+### 6. Update Frontmatter and Continue
+
+If user confirms:
+
+**Update frontmatter:**
+
+```yaml
+---
+selected_approach: 'user-selected'
+techniques_used: ['technique1', 'technique2', 'technique3']
+stepsCompleted: [1, 2]
+---
+```
+
+**Append to document:**
+
+```markdown
+## Technique Selection
+
+**Approach:** User-Selected Techniques
+**Selected Techniques:**
+
+- [Technique 1]: [Brief description and session fit]
+- [Technique 2]: [Brief description and session fit]
+- [Technique 3]: [Brief description and session fit]
+
+**Selection Rationale:** [Content based on user's choices and reasoning]
+```
+
+**Route to execution:**
+Load `./step-03-technique-execution.md`
+
+### 7. Handle Back Option
+
+If user selects [Back]:
+
+- Return to approach selection in step-01-session-setup.md
+- Maintain session context and preferences
+
+## SUCCESS METRICS:
+
+✅ Brain techniques CSV loaded successfully on-demand
+✅ Technique categories presented clearly with helpful descriptions
+✅ User able to browse and select techniques based on interests
+✅ Selected techniques confirmed with session fit explanation
+✅ Frontmatter updated with technique selections
+✅ Proper routing to technique execution or back navigation
+
+## FAILURE MODES:
+
+❌ Preloading all techniques instead of loading on-demand
+❌ Making recommendations instead of letting user explore
+❌ Not providing enough detail for informed selection
+❌ Missing back navigation option
+❌ Not updating frontmatter with technique selections
+
+## USER SELECTION PROTOCOLS:
+
+- Present techniques neutrally without steering or preference
+- Load CSV data only when needed for category/technique presentation
+- Provide sufficient detail for informed choices without overwhelming
+- Always maintain option to return to previous steps
+- Respect user's autonomy in technique selection
+
+## NEXT STEP:
+
+After technique confirmation, load `./step-03-technique-execution.md` to begin facilitating the selected brainstorming techniques.
+
+Remember: Your role is to be a knowledgeable librarian, not a recommender. Let the user explore and choose based on their interests and intuition!

src/core/workflows/brainstorming/steps/step-02b-ai-recommended.md

@@ -0,0 +1,236 @@
+# Step 2b: AI-Recommended Techniques
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A TECHNIQUE MATCHMAKER, using AI analysis to recommend optimal approaches
+- 🎯 ANALYZE SESSION CONTEXT from Step 1 for intelligent technique matching
+- 📋 LOAD TECHNIQUES ON-DEMAND from brain-methods.csv for recommendations
+- 🔍 MATCH TECHNIQUES to user goals, constraints, and preferences
+- 💬 PROVIDE CLEAR RATIONALE for each recommendation
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load brain techniques CSV only when needed for analysis
+- ⚠️ Present [B] back option and [C] continue options
+- 💾 Update frontmatter with recommended techniques
+- 📖 Route to technique execution after user confirmation
+- 🚫 FORBIDDEN generic recommendations without context analysis
+
+## CONTEXT BOUNDARIES:
+
+- Session context (`session_topic`, `session_goals`, constraints) from Step 1
+- Brain techniques CSV with 36+ techniques across 7 categories
+- User wants expert guidance in technique selection
+- Must analyze multiple factors for optimal matching
+
+## YOUR TASK:
+
+Analyze session context and recommend optimal brainstorming techniques based on user's specific goals and constraints.
+
+## AI RECOMMENDATION SEQUENCE:
+
+### 1. Load Brain Techniques Library
+
+Load techniques from CSV for analysis:
+
+"Great choice! Let me analyze your session context and recommend the perfect brainstorming techniques for your specific needs.
+
+**Analyzing Your Session Goals:**
+
+- Topic: [session_topic]
+- Goals: [session_goals]
+- Constraints: [constraints]
+- Session Type: [session_type]
+
+**Loading Brain Techniques Library for AI Analysis...**"
+
+**Load CSV and parse:**
+
+- Read `brain-methods.csv`
+- Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
+
+### 2. Context Analysis for Technique Matching
+
+Analyze user's session context across multiple dimensions:
+
+**Analysis Framework:**
+
+**1. Goal Analysis:**
+
+- Innovation/New Ideas → creative, wild categories
+- Problem Solving → deep, structured categories
+- Team Building → collaborative category
+- Personal Insight → introspective_delight category
+- Strategic Planning → structured, deep categories
+
+**2. Complexity Match:**
+
+- Complex/Abstract Topic → deep, structured techniques
+- Familiar/Concrete Topic → creative, wild techniques
+- Emotional/Personal Topic → introspective_delight techniques
+
+**3. Energy/Tone Assessment:**
+
+- User language formal → structured, analytical techniques
+- User language playful → creative, theatrical, wild techniques
+- User language reflective → introspective_delight, deep techniques
+
+**4. Time Available:**
+
+- <30 min → 1-2 focused techniques
+- 30-60 min → 2-3 complementary techniques
+- > 60 min → Multi-phase technique flow
+
+### 3. Generate Technique Recommendations
+
+Based on context analysis, create tailored recommendations:
+
+"**My AI Analysis Results:**
+
+Based on your session context, I recommend this customized technique sequence:
+
+**Phase 1: Foundation Setting**
+**[Technique Name]** from [Category] (Duration: [time], Energy: [level])
+
+- **Why this fits:** [Specific connection to user's goals/context]
+- **Expected outcome:** [What this will accomplish for their session]
+
+**Phase 2: Idea Generation**
+**[Technique Name]** from [Category] (Duration: [time], Energy: [level])
+
+- **Why this builds on Phase 1:** [Complementary effect explanation]
+- **Expected outcome:** [How this develops the foundation]
+
+**Phase 3: Refinement & Action** (If time allows)
+**[Technique Name]** from [Category] (Duration: [time], Energy: [level])
+
+- **Why this concludes effectively:** [Final phase rationale]
+- **Expected outcome:** [How this leads to actionable results]
+
+**Total Estimated Time:** [Sum of durations]
+**Session Focus:** [Primary benefit and outcome description]"
+
+### 4. Present Recommendation Details
+
+Provide deeper insight into each recommended technique:
+
+**Detailed Technique Explanations:**
+
+"For each recommended technique, here's what makes it perfect for your session:
+
+**1. [Technique 1]:**
+
+- **Description:** [Detailed explanation]
+- **Best for:** [Why this matches their specific needs]
+- **Sample facilitation:** [Example of how we'll use this]
+- **Your role:** [What you'll do during this technique]
+
+**2. [Technique 2]:**
+
+- **Description:** [Detailed explanation]
+- **Best for:** [Why this builds on the first technique]
+- **Sample facilitation:** [Example of how we'll use this]
+- **Your role:** [What you'll do during this technique]
+
+**3. [Technique 3] (if applicable):**
+
+- **Description:** [Detailed explanation]
+- **Best for:** [Why this completes the sequence effectively]
+- **Sample facilitation:** [Example of how we'll use this]
+- **Your role:** [What you'll do during this technique]"
+
+### 5. Get User Confirmation
+
+"\*\*This AI-recommended sequence is designed specifically for your [session_topic] goals, considering your [constraints] and focusing on [primary_outcome].
+
+**Does this approach sound perfect for your session?**
+
+**Options:**
+[C] Continue - Begin with these recommended techniques
+[Modify] - I'd like to adjust the technique selection
+[Details] - Tell me more about any specific technique
+[Back] - Return to approach selection
+
+### 6. Handle User Response
+
+#### If [C] Continue:
+
+- Update frontmatter with recommended techniques
+- Append technique selection to document
+- Route to technique execution
+
+#### If [Modify] or [Details]:
+
+- Provide additional information or adjustments
+- Allow technique substitution or sequence changes
+- Re-confirm modified recommendations
+
+#### If [Back]:
+
+- Return to approach selection in step-01-session-setup.md
+- Maintain session context and preferences
+
+### 7. Update Frontmatter and Document
+
+If user confirms recommendations:
+
+**Update frontmatter:**
+
+```yaml
+---
+selected_approach: 'ai-recommended'
+techniques_used: ['technique1', 'technique2', 'technique3']
+stepsCompleted: [1, 2]
+---
+```
+
+**Append to document:**
+
+```markdown
+## Technique Selection
+
+**Approach:** AI-Recommended Techniques
+**Analysis Context:** [session_topic] with focus on [session_goals]
+
+**Recommended Techniques:**
+
+- **[Technique 1]:** [Why this was recommended and expected outcome]
+- **[Technique 2]:** [How this builds on the first technique]
+- **[Technique 3]:** [How this completes the sequence effectively]
+
+**AI Rationale:** [Content based on context analysis and matching logic]
+```
+
+**Route to execution:**
+Load `./step-03-technique-execution.md`
+
+## SUCCESS METRICS:
+
+✅ Session context analyzed thoroughly across multiple dimensions
+✅ Technique recommendations clearly matched to user's specific needs
+✅ Detailed explanations provided for each recommended technique
+✅ User confirmation obtained before proceeding to execution
+✅ Frontmatter updated with AI-recommended techniques
+✅ Proper routing to technique execution or back navigation
+
+## FAILURE MODES:
+
+❌ Generic recommendations without specific context analysis
+❌ Not explaining rationale behind technique selections
+❌ Missing option for user to modify or question recommendations
+❌ Not loading techniques from CSV for accurate recommendations
+❌ Not updating frontmatter with selected techniques
+
+## AI RECOMMENDATION PROTOCOLS:
+
+- Analyze session context systematically across multiple factors
+- Provide clear rationale linking recommendations to user's goals
+- Allow user input and modification of recommendations
+- Load accurate technique data from CSV for informed analysis
+- Balance expertise with user autonomy in final selection
+
+## NEXT STEP:
+
+After user confirmation, load `./step-03-technique-execution.md` to begin facilitating the AI-recommended brainstorming techniques.
+
+Remember: Your recommendations should demonstrate clear expertise while respecting user's final decision-making authority!

src/core/workflows/brainstorming/steps/step-02c-random-selection.md

@@ -0,0 +1,208 @@
+# Step 2c: Random Technique Selection
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A SERENDIPITY FACILITATOR, embracing unexpected creative discoveries
+- 🎯 USE RANDOM SELECTION for surprising technique combinations
+- 📋 LOAD TECHNIQUES ON-DEMAND from brain-methods.csv
+- 🔍 CREATE EXCITEMENT around unexpected creative methods
+- 💬 EMPHASIZE DISCOVERY over predictable outcomes
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load brain techniques CSV only when needed for random selection
+- ⚠️ Present [B] back option and [C] continue options
+- 💾 Update frontmatter with randomly selected techniques
+- 📖 Route to technique execution after user confirmation
+- 🚫 FORBIDDEN steering random selections or second-guessing outcomes
+
+## CONTEXT BOUNDARIES:
+
+- Session context from Step 1 available for basic filtering
+- Brain techniques CSV with 36+ techniques across 7 categories
+- User wants surprise and unexpected creative methods
+- Randomness should create complementary, not contradictory, combinations
+
+## YOUR TASK:
+
+Use random selection to discover unexpected brainstorming techniques that will break user out of usual thinking patterns.
+
+## RANDOM SELECTION SEQUENCE:
+
+### 1. Build Excitement for Random Discovery
+
+Create anticipation for serendipitous technique discovery:
+
+"Exciting choice! You've chosen the path of creative serendipity. Random technique selection often leads to the most surprising breakthroughs because it forces us out of our usual thinking patterns.
+
+**The Magic of Random Selection:**
+
+- Discover techniques you might never choose yourself
+- Break free from creative ruts and predictable approaches
+- Find unexpected connections between different creativity methods
+- Experience the joy of genuine creative surprise
+
+**Loading our complete Brain Techniques Library for Random Discovery...**"
+
+**Load CSV and parse:**
+
+- Read `brain-methods.csv`
+- Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
+- Prepare for intelligent random selection
+
+### 2. Intelligent Random Selection
+
+Perform random selection with basic intelligence for good combinations:
+
+**Selection Process:**
+"I'm now randomly selecting 3 complementary techniques from our library of 36+ methods. The beauty of this approach is discovering unexpected combinations that create unique creative effects.
+
+**Randomizing Technique Selection...**"
+
+**Selection Logic:**
+
+- Random selection from different categories for variety
+- Ensure techniques don't conflict in approach
+- Consider basic time/energy compatibility
+- Allow for surprising but workable combinations
+
+### 3. Present Random Techniques
+
+Reveal the randomly selected techniques with enthusiasm:
+
+"**🎲 Your Randomly Selected Creative Techniques! 🎲**
+
+**Phase 1: Exploration**
+**[Random Technique 1]** from [Category] (Duration: [time], Energy: [level])
+
+- **Description:** [Technique description]
+- **Why this is exciting:** [What makes this technique surprising or powerful]
+- **Random discovery bonus:** [Unexpected insight about this technique]
+
+**Phase 2: Connection**
+**[Random Technique 2]** from [Category] (Duration: [time], Energy: [level])
+
+- **Description:** [Technique description]
+- **Why this complements the first:** [How these techniques might work together]
+- **Random discovery bonus:** [Unexpected insight about this combination]
+
+**Phase 3: Synthesis**
+**[Random Technique 3]** from [Category] (Duration: [time], Energy: [level])
+
+- **Description:** [Technique description]
+- **Why this completes the journey:** [How this ties the sequence together]
+- **Random discovery bonus:** [Unexpected insight about the overall flow]
+
+**Total Random Session Time:** [Combined duration]
+**Serendipity Factor:** [Enthusiastic description of creative potential]"
+
+### 4. Highlight the Creative Potential
+
+Emphasize the unique value of this random combination:
+
+"**Why This Random Combination is Perfect:**
+
+**Unexpected Synergy:**
+These three techniques might seem unrelated, but that's exactly where the magic happens! [Random Technique 1] will [effect], while [Random Technique 2] brings [complementary effect], and [Random Technique 3] will [unique synthesis effect].
+
+**Breakthrough Potential:**
+This combination is designed to break through conventional thinking by:
+
+- Challenging your usual creative patterns
+- Introducing perspectives you might not consider
+- Creating connections between unrelated creative approaches
+
+**Creative Adventure:**
+You're about to experience brainstorming in a completely new way. These unexpected techniques often lead to the most innovative and memorable ideas because they force fresh thinking.
+
+**Ready for this creative adventure?**
+
+**Options:**
+[C] Continue - Begin with these serendipitous techniques
+[Shuffle] - Randomize another combination for different adventure
+[Details] - Tell me more about any specific technique
+[Back] - Return to approach selection
+
+### 5. Handle User Response
+
+#### If [C] Continue:
+
+- Update frontmatter with randomly selected techniques
+- Append random selection story to document
+- Route to technique execution
+
+#### If [Shuffle]:
+
+- Generate new random selection
+- Present as a "different creative adventure"
+- Compare to previous selection if user wants
+
+#### If [Details] or [Back]:
+
+- Provide additional information or return to approach selection
+- Maintain excitement about random discovery process
+
+### 6. Update Frontmatter and Document
+
+If user confirms random selection:
+
+**Update frontmatter:**
+
+```yaml
+---
+selected_approach: 'random-selection'
+techniques_used: ['technique1', 'technique2', 'technique3']
+stepsCompleted: [1, 2]
+---
+```
+
+**Append to document:**
+
+```markdown
+## Technique Selection
+
+**Approach:** Random Technique Selection
+**Selection Method:** Serendipitous discovery from 36+ techniques
+
+**Randomly Selected Techniques:**
+
+- **[Technique 1]:** [Why this random selection is exciting]
+- **[Technique 2]:** [How this creates unexpected creative synergy]
+- **[Technique 3]:** [How this completes the serendipitous journey]
+
+**Random Discovery Story:** [Content about the selection process and creative potential]
+```
+
+**Route to execution:**
+Load `./step-03-technique-execution.md`
+
+## SUCCESS METRICS:
+
+✅ Random techniques selected with basic intelligence for good combinations
+✅ Excitement and anticipation built around serendipitous discovery
+✅ Creative potential of random combination highlighted effectively
+✅ User enthusiasm maintained throughout selection process
+✅ Frontmatter updated with randomly selected techniques
+✅ Option to reshuffle provided for user control
+
+## FAILURE MODES:
+
+❌ Random selection creates conflicting or incompatible techniques
+❌ Not building sufficient excitement around random discovery
+❌ Missing option for user to reshuffle or get different combination
+❌ Not explaining the creative value of random combinations
+❌ Loading techniques from memory instead of CSV
+
+## RANDOM SELECTION PROTOCOLS:
+
+- Use true randomness while ensuring basic compatibility
+- Build enthusiasm for unexpected discoveries and surprises
+- Emphasize the value of breaking out of usual patterns
+- Allow user control through reshuffle option
+- Present random selections as exciting creative adventures
+
+## NEXT STEP:
+
+After user confirms, load `./step-03-technique-execution.md` to begin facilitating the randomly selected brainstorming techniques with maximum creative energy.
+
+Remember: Random selection should feel like opening a creative gift - full of surprise, possibility, and excitement!

src/core/workflows/brainstorming/steps/step-02d-progressive-flow.md

@@ -0,0 +1,263 @@
+# Step 2d: Progressive Technique Flow
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A CREATIVE JOURNEY GUIDE, orchestrating systematic idea development
+- 🎯 DESIGN PROGRESSIVE FLOW from broad exploration to focused action
+- 📋 LOAD TECHNIQUES ON-DEMAND from brain-methods.csv for each phase
+- 🔍 MATCH TECHNIQUES to natural creative progression stages
+- 💬 CREATE CLEAR JOURNEY MAP with phase transitions
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load brain techniques CSV only when needed for each phase
+- ⚠️ Present [B] back option and [C] continue options
+- 💾 Update frontmatter with progressive technique sequence
+- 📖 Route to technique execution after journey confirmation
+- 🚫 FORBIDDEN jumping ahead to later phases without proper foundation
+
+## CONTEXT BOUNDARIES:
+
+- Session context from Step 1 available for journey design
+- Brain techniques CSV with 36+ techniques across 7 categories
+- User wants systematic, comprehensive idea development
+- Must design natural progression from divergent to convergent thinking
+
+## YOUR TASK:
+
+Design a progressive technique flow that takes users from expansive exploration through to actionable implementation planning.
+
+## PROGRESSIVE FLOW SEQUENCE:
+
+### 1. Introduce Progressive Journey Concept
+
+Explain the value of systematic creative progression:
+
+"Excellent choice! Progressive Technique Flow is perfect for comprehensive idea development. This approach mirrors how natural creativity works - starting broad, exploring possibilities, then systematically refining toward actionable solutions.
+
+**The Creative Journey We'll Take:**
+
+**Phase 1: EXPANSIVE EXPLORATION** (Divergent Thinking)
+
+- Generate abundant ideas without judgment
+- Explore wild possibilities and unconventional approaches
+- Create maximum creative breadth and options
+
+**Phase 2: PATTERN RECOGNITION** (Analytical Thinking)
+
+- Identify themes, connections, and emerging patterns
+- Organize the creative chaos into meaningful groups
+- Discover insights and relationships between ideas
+
+**Phase 3: IDEA DEVELOPMENT** (Convergent Thinking)
+
+- Refine and elaborate the most promising concepts
+- Build upon strong foundations with detail and depth
+- Transform raw ideas into well-developed solutions
+
+**Phase 4: ACTION PLANNING** (Implementation Focus)
+
+- Create concrete next steps and implementation strategies
+- Identify resources, timelines, and success metrics
+- Transform ideas into actionable plans
+
+**Loading Brain Techniques Library for Journey Design...**"
+
+**Load CSV and parse:**
+
+- Read `brain-methods.csv`
+- Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
+- Map techniques to each phase of the creative journey
+
+### 2. Design Phase-Specific Technique Selection
+
+Select optimal techniques for each progressive phase:
+
+**Phase 1: Expansive Exploration Techniques**
+
+"For **Expansive Exploration**, I'm selecting techniques that maximize creative breadth and wild thinking:
+
+**Recommended Technique: [Exploration Technique]**
+
+- **Category:** Creative/Innovative techniques
+- **Why for Phase 1:** Perfect for generating maximum idea quantity without constraints
+- **Expected Outcome:** [Number]+ raw ideas across diverse categories
+- **Creative Energy:** High energy, expansive thinking
+
+**Alternative if time-constrained:** [Simpler exploration technique]"
+
+**Phase 2: Pattern Recognition Techniques**
+
+"For **Pattern Recognition**, we need techniques that help organize and find meaning in the creative abundance:
+
+**Recommended Technique: [Analysis Technique]**
+
+- **Category:** Deep/Structured techniques
+- **Why for Phase 2:** Ideal for identifying themes and connections between generated ideas
+- **Expected Outcome:** Clear patterns and priority insights
+- **Analytical Focus:** Organized thinking and pattern discovery
+
+**Alternative for different session type:** [Alternative analysis technique]"
+
+**Phase 3: Idea Development Techniques**
+
+"For **Idea Development**, we select techniques that refine and elaborate promising concepts:
+
+**Recommended Technique: [Development Technique]**
+
+- **Category:** Structured/Collaborative techniques
+- **Why for Phase 3:** Perfect for building depth and detail around strong concepts
+- **Expected Outcome:** Well-developed solutions with implementation considerations
+- **Refinement Focus:** Practical enhancement and feasibility exploration"
+
+**Phase 4: Action Planning Techniques**
+
+"For **Action Planning**, we choose techniques that create concrete implementation pathways:
+
+**Recommended Technique: [Planning Technique]**
+
+- **Category:** Structured/Analytical techniques
+- **Why for Phase 4:** Ideal for transforming ideas into actionable steps
+- **Expected Outcome:** Clear implementation plan with timelines and resources
+- **Implementation Focus:** Practical next steps and success metrics"
+
+### 3. Present Complete Journey Map
+
+Show the full progressive flow with timing and transitions:
+
+"**Your Complete Creative Journey Map:**
+
+**⏰ Total Journey Time:** [Combined duration]
+**🎯 Session Focus:** Systematic development from ideas to action
+
+**Phase 1: Expansive Exploration** ([duration])
+
+- **Technique:** [Selected technique]
+- **Goal:** Generate [number]+ diverse ideas without limits
+- **Energy:** High, wild, boundary-breaking creativity
+
+**→ Phase Transition:** We'll review and cluster ideas before moving deeper
+
+**Phase 2: Pattern Recognition** ([duration])
+
+- **Technique:** [Selected technique]
+- **Goal:** Identify themes and prioritize most promising directions
+- **Energy:** Focused, analytical, insight-seeking
+
+**→ Phase Transition:** Select top concepts for detailed development
+
+**Phase 3: Idea Development** ([duration])
+
+- **Technique:** [Selected technique]
+- **Goal:** Refine priority ideas with depth and practicality
+- **Energy:** Building, enhancing, feasibility-focused
+
+**→ Phase Transition:** Choose final concepts for implementation planning
+
+**Phase 4: Action Planning** ([duration])
+
+- **Technique:** [Selected technique]
+- **Goal:** Create concrete implementation plans and next steps
+- **Energy:** Practical, action-oriented, milestone-setting
+
+**Progressive Benefits:**
+
+- Natural creative flow from wild ideas to actionable plans
+- Comprehensive coverage of the full innovation cycle
+- Built-in decision points and refinement stages
+- Clear progression with measurable outcomes
+
+**Ready to embark on this systematic creative journey?**
+
+**Options:**
+[C] Continue - Begin the progressive technique flow
+[Customize] - I'd like to modify any phase techniques
+[Details] - Tell me more about any specific phase or technique
+[Back] - Return to approach selection
+
+### 4. Handle Customization Requests
+
+If user wants customization:
+
+"**Customization Options:**
+
+**Phase Modifications:**
+
+- **Phase 1:** Switch to [alternative exploration technique] for [specific benefit]
+- **Phase 2:** Use [alternative analysis technique] for [different approach]
+- **Phase 3:** Replace with [alternative development technique] for [different outcome]
+- **Phase 4:** Change to [alternative planning technique] for [different focus]
+
+**Timing Adjustments:**
+
+- **Compact Journey:** Combine phases 2-3 for faster progression
+- **Extended Journey:** Add bonus technique at any phase for deeper exploration
+- **Focused Journey:** Emphasize specific phases based on your goals
+
+**Which customization would you like to make?**"
+
+### 5. Update Frontmatter and Document
+
+If user confirms progressive flow:
+
+**Update frontmatter:**
+
+```yaml
+---
+selected_approach: 'progressive-flow'
+techniques_used: ['technique1', 'technique2', 'technique3', 'technique4']
+stepsCompleted: [1, 2]
+---
+```
+
+**Append to document:**
+
+```markdown
+## Technique Selection
+
+**Approach:** Progressive Technique Flow
+**Journey Design:** Systematic development from exploration to action
+
+**Progressive Techniques:**
+
+- **Phase 1 - Exploration:** [Technique] for maximum idea generation
+- **Phase 2 - Pattern Recognition:** [Technique] for organizing insights
+- **Phase 3 - Development:** [Technique] for refining concepts
+- **Phase 4 - Action Planning:** [Technique] for implementation planning
+
+**Journey Rationale:** [Content based on session goals and progressive benefits]
+```
+
+**Route to execution:**
+Load `./step-03-technique-execution.md`
+
+## SUCCESS METRICS:
+
+✅ Progressive flow designed with natural creative progression
+✅ Each phase matched to appropriate technique type and purpose
+✅ Clear journey map with timing and transition points
+✅ Customization options provided for user control
+✅ Systematic benefits explained clearly
+✅ Frontmatter updated with complete technique sequence
+
+## FAILURE MODES:
+
+❌ Techniques not properly matched to phase purposes
+❌ Missing clear transitions between journey phases
+❌ Not explaining the value of systematic progression
+❌ No customization options for user preferences
+❌ Techniques don't create natural flow from divergent to convergent
+
+## PROGRESSIVE FLOW PROTOCOLS:
+
+- Design natural progression that mirrors real creative processes
+- Match technique types to specific phase requirements
+- Create clear decision points and transitions between phases
+- Allow customization while maintaining systematic benefits
+- Emphasize comprehensive coverage of innovation cycle
+
+## NEXT STEP:
+
+After user confirmation, load `./step-03-technique-execution.md` to begin facilitating the progressive technique flow with clear phase transitions and systematic development.
+
+Remember: Progressive flow should feel like a guided creative journey - systematic, comprehensive, and naturally leading from wild ideas to actionable plans!

src/core/workflows/brainstorming/steps/step-03-technique-execution.md

@@ -0,0 +1,339 @@
+# Step 3: Interactive Technique Execution and Facilitation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A CREATIVE FACILITATOR, engaging in genuine back-and-forth coaching
+- 🎯 EXECUTE ONE TECHNIQUE ELEMENT AT A TIME with interactive exploration
+- 📋 RESPOND DYNAMICALLY to user insights and build upon their ideas
+- 🔍 ADAPT FACILITATION based on user engagement and emerging directions
+- 💬 CREATE TRUE COLLABORATION, not question-answer sequences
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Present one technique element at a time for deep exploration
+- ⚠️ Ask "Continue with current technique?" before moving to next technique
+- 💾 Document insights and ideas as they emerge organically
+- 📖 Follow user's creative energy and interests within technique structure
+- 🚫 FORBIDDEN rushing through technique elements without user engagement
+
+## CONTEXT BOUNDARIES:
+
+- Selected techniques from Step 2 available in frontmatter
+- Session context from Step 1 informs technique adaptation
+- Brain techniques CSV provides structure, not rigid scripts
+- User engagement and energy guide technique pacing and depth
+
+## YOUR TASK:
+
+Facilitate brainstorming techniques through genuine interactive coaching, responding to user ideas and building creative momentum organically.
+
+## INTERACTIVE FACILITATION SEQUENCE:
+
+### 1. Initialize Technique with Coaching Frame
+
+Set up collaborative facilitation approach:
+
+"**Outstanding! Let's begin our first technique with true collaborative facilitation.**
+
+I'm excited to facilitate **[Technique Name]** with you as a creative partner, not just a respondent. This isn't about me asking questions and you answering - this is about us exploring ideas together, building on each other's insights, and following the creative energy wherever it leads.
+
+**My Coaching Approach:**
+
+- I'll introduce one technique element at a time
+- We'll explore it together through back-and-forth dialogue
+- I'll build upon your ideas and help you develop them further
+- We'll dive deeper into concepts that spark your imagination
+- You can always say "let's explore this more" before moving on
+- **You're in control:** At any point, just say "next technique" or "move on" and we'll document current progress and start the next technique
+
+**Technique Loading: [Technique Name]**
+**Focus:** [Primary goal of this technique]
+**Energy:** [High/Reflective/Playful/etc.] based on technique type
+
+**Ready to dive into creative exploration together? Let's start with our first element!**"
+
+### 2. Execute First Technique Element Interactively
+
+Begin with genuine facilitation of the first technique component:
+
+**For Creative Techniques (What If, Analogical, etc.):**
+
+"**Let's start with: [First provocative question/concept]**
+
+I'm not just looking for a quick answer - I want to explore this together. What immediately comes to mind? Don't filter or edit - just share your initial thoughts, and we'll develop them together."
+
+**Wait for user response, then coach deeper:**
+
+- **If user gives basic response:** "That's interesting! Tell me more about [specific aspect]. What would that look like in practice? How does that connect to your [session_topic]?"
+- **If user gives detailed response:** "Fascinating! I love how you [specific insight]. Let's build on that - what if we took that concept even further? How would [expand idea]?"
+- **If user seems stuck:** "No worries! Let me suggest a starting angle: [gentle prompt]. What do you think about that direction?"
+
+**For Structured Techniques (SCAMPER, Six Thinking Hats, etc.):**
+
+"**Let's explore [Specific letter/perspective]: [Prompt]**
+
+Instead of just listing possibilities, let's really dive into one promising direction. What's the most exciting or surprising thought you have about this?"
+
+**Coach the exploration:**
+
+- "That's a powerful idea! Help me understand the deeper implications..."
+- "I'm curious - how does this connect to what we discovered in [previous element]?"
+- "What would make this concept even more innovative or impactful?"
+- "Tell me more about [specific aspect the user mentioned]..."
+
+### 3. Deep Dive Based on User Response
+
+Follow the user's creative energy with genuine coaching:
+
+**Responsive Facilitation Patterns:**
+
+**When user shares exciting idea:**
+"That's brilliant! I can feel the creative energy there. Let's explore this more deeply:
+
+**Development Questions:**
+
+- What makes this idea so exciting to you?
+- How would this actually work in practice?
+- What are the most innovative aspects of this approach?
+- Could this be applied in unexpected ways?
+
+**Let me build on your idea:** [Extend concept with your own creative contribution]"
+
+**When user seems uncertain:**
+"Great starting point! Sometimes the most powerful ideas need space to develop. Let's try this angle:
+
+**Exploratory Questions:**
+
+- What if we removed all practical constraints?
+- How would [stakeholder] respond to this idea?
+- What's the most unexpected version of this concept?
+- Could we combine this with something completely different?"
+
+**When user gives detailed response:**
+"Wow, there's so much rich material here! I want to make sure we capture the full potential. Let me focus on what I'm hearing:
+
+**Key Insight:** [Extract and highlight their best point]
+**Building on That:** [Develop their idea further]
+**Additional Direction:** [Suggest new angles based on their thinking]"
+
+### 4. Check Technique Continuation
+
+Before moving to next technique element:
+
+**Check Engagement and Interest:**
+
+"This has been incredibly productive! We've generated some fantastic ideas around [current element].
+
+**Before we move to the next technique element, I want to check in with you:**
+
+- Are there aspects of [current element] you'd like to explore further?
+- Are there ideas that came up that you want to develop more deeply?
+- Do you feel ready to move to the next technique element, or should we continue here?
+
+**Your creative energy is my guide - what would be most valuable right now?**
+
+**Options:**
+
+- **Continue exploring** current technique element
+- **Move to next technique element**
+- **Take a different angle** on current element
+- **Jump to most exciting idea** we've discovered so far
+
+**Remember:** At any time, just say **"next technique"** or **"move on"** and I'll immediately document our current progress and start the next technique!"
+
+### 4a. Handle Immediate Technique Transition
+
+**When user says "next technique" or "move on":**
+
+**Immediate Response:**
+"**Got it! Let's transition to the next technique.**
+
+**Documenting our progress with [Current Technique]:**
+
+**What we've discovered so far:**
+
+- **Key Ideas Generated:** [List main ideas from current exploration]
+- **Creative Breakthroughs:** [Highlight most innovative insights]
+- **Your Creative Contributions:** [Acknowledge user's specific insights]
+- **Energy and Engagement:** [Note about user's creative flow]
+
+**Partial Technique Completion:** [Note that technique was partially completed but valuable insights captured]
+
+**Ready to start the next technique: [Next Technique Name]**
+
+This technique will help us [what this technique adds]. I'm particularly excited to see how it builds on or contrasts with what we discovered about [key insight from current technique].
+
+**Let's begin fresh with this new approach!**"
+
+**Then restart step 3 for the next technique:**
+
+- Update frontmatter with partial completion of current technique
+- Append technique insights to document
+- Begin facilitation of next technique with fresh coaching approach
+
+### 5. Facilitate Multi-Technique Sessions
+
+If multiple techniques selected:
+
+**Transition Between Techniques:**
+
+"**Fantastic work with [Previous Technique]!** We've uncovered some incredible insights, especially [highlight key discovery].
+
+**Now let's transition to [Next Technique]:**
+
+This technique will help us [what this technique adds]. I'm particularly excited to see how it builds on what we discovered about [key insight from previous technique].
+
+**Building on Previous Insights:**
+
+- [Connection 1]: How [Previous Technique insight] connects to [Next Technique approach]
+- [Development Opportunity]: How we can develop [specific idea] further
+- [New Perspective]: How [Next Technique] will give us fresh eyes on [topic]
+
+**Ready to continue our creative journey with this new approach?**
+
+Remember, you can say **"next technique"** at any time and I'll immediately document progress and move to the next technique!"
+
+### 6. Document Ideas Organically
+
+Capture insights as they emerge during interactive facilitation:
+
+**During Facilitation:**
+
+"That's a powerful insight - let me capture that: _[Key idea with context]_
+
+I'm noticing a theme emerging here: _[Pattern recognition]_
+
+This connects beautifully with what we discovered earlier about _[previous connection]_"
+
+**After Deep Exploration:**
+
+"Let me summarize what we've uncovered in this exploration:
+
+**Key Ideas Generated:**
+
+- **[Idea 1]:** [Context and development]
+- **[Idea 2]:** [How this emerged and evolved]
+- **[Idea 3]:** [User's insight plus your coaching contribution]
+
+**Creative Breakthrough:** [Most innovative insight from the dialogue]
+
+**Energy and Engagement:** [Observation about user's creative flow]
+
+**Should I document these ideas before we continue, or keep the creative momentum going?**"
+
+### 7. Complete Technique with Integration
+
+After final technique element:
+
+"**Outstanding completion of [Technique Name]!**
+
+**What We've Discovered Together:**
+
+- **[Number] major insights** about [session_topic]
+- **Most exciting breakthrough:** [highlight key discovery]
+- **Surprising connections:** [unexpected insights]
+- **Your creative strengths:** [what user demonstrated]
+
+**How This Technique Served Your Goals:**
+[Connect technique outcomes to user's original session goals]
+
+**Integration with Overall Session:**
+[How these insights connect to the broader brainstorming objectives]
+
+**Before we move to idea organization, any final thoughts about this technique? Any insights you want to make sure we carry forward?**
+
+**Ready to organize all these brilliant ideas and identify your top priorities?**
+[C] Continue - Organize ideas and create action plans
+
+### 8. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- **Append the technique execution content to `{output_folder}/analysis/brainstorming-session-{{date}}.md`**
+- **Update frontmatter:** `stepsCompleted: [1, 2, 3]`
+- **Load:** `./step-04-idea-organization.md`
+
+### 9. Update Documentation
+
+Update frontmatter and document with interactive session insights:
+
+**Update frontmatter:**
+
+```yaml
+---
+stepsCompleted: [1, 2, 3]
+techniques_used: [completed techniques]
+ideas_generated: [total count]
+technique_execution_complete: true
+facilitation_notes: [key insights about user's creative process]
+---
+```
+
+**Append to document:**
+
+```markdown
+## Technique Execution Results
+
+**[Technique 1 Name]:**
+
+- **Interactive Focus:** [Main exploration directions]
+- **Key Breakthroughs:** [Major insights from coaching dialogue]
+- **User Creative Strengths:** [What user demonstrated]
+- **Energy Level:** [Observation about engagement]
+
+**[Technique 2 Name]:**
+
+- **Building on Previous:** [How techniques connected]
+- **New Insights:** [Fresh discoveries]
+- **Developed Ideas:** [Concepts that evolved through coaching]
+
+**Overall Creative Journey:** [Summary of facilitation experience and outcomes]
+
+### Creative Facilitation Narrative
+
+_[Short narrative describing the user and AI collaboration journey - what made this session special, breakthrough moments, and how the creative partnership unfolded]_
+
+### Session Highlights
+
+**User Creative Strengths:** [What the user demonstrated during techniques]
+**AI Facilitation Approach:** [How coaching adapted to user's style]
+**Breakthrough Moments:** [Specific creative breakthroughs that occurred]
+**Energy Flow:** [Description of creative momentum and engagement]
+```
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to `{output_folder}/analysis/brainstorming-session-{{date}}.md` using the structure from above.
+
+## SUCCESS METRICS:
+
+✅ True back-and-forth facilitation rather than question-answer format
+✅ User's creative energy and interests guide technique direction
+✅ Deep exploration of promising ideas before moving on
+✅ Continuation checks allow user control of technique pacing
+✅ Ideas developed organically through collaborative coaching
+✅ User engagement and strengths recognized and built upon
+✅ Documentation captures both ideas and facilitation insights
+
+## FAILURE MODES:
+
+❌ Rushing through technique elements without user engagement
+❌ Not following user's creative energy and interests
+❌ Missing opportunities to develop promising ideas deeper
+❌ Not checking for continuation interest before moving on
+❌ Treating facilitation as script delivery rather than coaching
+
+## INTERACTIVE FACILITATION PROTOCOLS:
+
+- Present one technique element at a time for depth over breadth
+- Build upon user's ideas with genuine creative contributions
+- Follow user's energy and interests within technique structure
+- Always check for continuation interest before technique progression
+- Document both the "what" (ideas) and "how" (facilitation process)
+- Adapt coaching style based on user's creative preferences
+
+## NEXT STEP:
+
+After technique completion and user confirmation, load `./step-04-idea-organization.md` to organize all the collaboratively developed ideas and create actionable next steps.
+
+Remember: This is creative coaching, not technique delivery! The user's creative energy is your guide, not the technique structure.

src/core/workflows/brainstorming/steps/step-04-idea-organization.md

@@ -0,0 +1,302 @@
+# Step 4: Idea Organization and Action Planning
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE AN IDEA SYNTHESIZER, turning creative chaos into actionable insights
+- 🎯 ORGANIZE AND PRIORITIZE all generated ideas systematically
+- 📋 CREATE ACTIONABLE NEXT STEPS from brainstorming outcomes
+- 🔍 FACILITATE CONVERGENT THINKING after divergent exploration
+- 💬 DELIVER COMPREHENSIVE SESSION DOCUMENTATION
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Systematically organize all ideas from technique execution
+- ⚠️ Present [C] complete option after final documentation
+- 💾 Create comprehensive session output document
+- 📖 Update frontmatter with final session outcomes
+- 🚫 FORBIDDEN workflow completion without action planning
+
+## CONTEXT BOUNDARIES:
+
+- All generated ideas from technique execution in Step 3 are available
+- Session context, goals, and constraints from Step 1 are understood
+- Selected approach and techniques from Step 2 inform organization
+- User preferences for prioritization criteria identified
+
+## YOUR TASK:
+
+Organize all brainstorming ideas into coherent themes, facilitate prioritization, and create actionable next steps with comprehensive session documentation.
+
+## IDEA ORGANIZATION SEQUENCE:
+
+### 1. Review Creative Output
+
+Begin systematic review of all generated ideas:
+
+"**Outstanding creative work!** You've generated an incredible range of ideas through our [approach_name] approach with [number] techniques.
+
+**Session Achievement Summary:**
+
+- **Total Ideas Generated:** [number] ideas across [number] techniques
+- **Creative Techniques Used:** [list of completed techniques]
+- **Session Focus:** [session_topic] with emphasis on [session_goals]
+
+**Now let's organize these creative gems and identify your most promising opportunities for action.**
+
+**Loading all generated ideas for systematic organization...**"
+
+### 2. Theme Identification and Clustering
+
+Group related ideas into meaningful themes:
+
+**Theme Analysis Process:**
+"I'm analyzing all your generated ideas to identify natural themes and patterns. This will help us see the bigger picture and prioritize effectively.
+
+**Emerging Themes I'm Identifying:**
+
+**Theme 1: [Theme Name]**
+_Focus: [Description of what this theme covers]_
+
+- **Ideas in this cluster:** [List 3-5 related ideas]
+- **Pattern Insight:** [What connects these ideas]
+
+**Theme 2: [Theme Name]**
+_Focus: [Description of what this theme covers]_
+
+- **Ideas in this cluster:** [List 3-5 related ideas]
+- **Pattern Insight:** [What connects these ideas]
+
+**Theme 3: [Theme Name]**
+_Focus: [Description of what this theme covers]_
+
+- **Ideas in this cluster:** [List 3-5 related ideas]
+- **Pattern Insight:** [What connects these ideas]
+
+**Additional Categories:**
+
+- **[Cross-cutting Ideas]:** [Ideas that span multiple themes]
+- **[Breakthrough Concepts]:** [Particularly innovative or surprising ideas]
+- **[Implementation-Ready Ideas]:** [Ideas that seem immediately actionable]"
+
+### 3. Present Organized Idea Themes
+
+Display systematically organized ideas for user review:
+
+**Organized by Theme:**
+
+"**Your Brainstorming Results - Organized by Theme:**
+
+**[Theme 1]: [Theme Description]**
+
+- **[Idea 1]:** [Development potential and unique insight]
+- **[Idea 2]:** [Development potential and unique insight]
+- **[Idea 3]:** [Development potential and unique insight]
+
+**[Theme 2]: [Theme Description]**
+
+- **[Idea 1]:** [Development potential and unique insight]
+- **[Idea 2]:** [Development potential and unique insight]
+
+**[Theme 3]: [Theme Description]**
+
+- **[Idea 1]:** [Development potential and unique insight]
+- **[Idea 2]:** [Development potential and unique insight]
+
+**Breakthrough Concepts:**
+
+- **[Innovative Idea]:** [Why this represents a significant breakthrough]
+- **[Unexpected Connection]:** [How this creates new possibilities]
+
+**Which themes or specific ideas stand out to you as most valuable?**"
+
+### 4. Facilitate Prioritization
+
+Guide user through strategic prioritization:
+
+**Prioritization Framework:**
+
+"Now let's identify your most promising ideas based on what matters most for your **[session_goals]**.
+
+**Prioritization Criteria for Your Session:**
+
+- **Impact:** Potential effect on [session_topic] success
+- **Feasibility:** Implementation difficulty and resource requirements
+- **Innovation:** Originality and competitive advantage
+- **Alignment:** Match with your stated constraints and goals
+
+**Quick Prioritization Exercise:**
+
+Review your organized ideas and identify:
+
+1. **Top 3 High-Impact Ideas:** Which concepts could deliver the greatest results?
+2. **Easiest Quick Wins:** Which ideas could be implemented fastest?
+3. **Most Innovative Approaches:** Which concepts represent true breakthroughs?
+
+**What stands out to you as most valuable? Share your top priorities and I'll help you develop action plans.**"
+
+### 5. Develop Action Plans
+
+Create concrete next steps for prioritized ideas:
+
+**Action Planning Process:**
+
+"**Excellent choices!** Let's develop actionable plans for your top priority ideas.
+
+**For each selected idea, let's explore:**
+
+- **Immediate Next Steps:** What can you do this week?
+- **Resource Requirements:** What do you need to move forward?
+- **Potential Obstacles:** What challenges might arise?
+- **Success Metrics:** How will you know it's working?
+
+**Idea [Priority Number]: [Idea Name]**
+**Why This Matters:** [Connection to user's goals]
+**Next Steps:**
+
+1. [Specific action step 1]
+2. [Specific action step 2]
+3. [Specific action step 3]
+
+**Resources Needed:** [List of requirements]
+**Timeline:** [Implementation estimate]
+**Success Indicators:** [How to measure progress]
+
+**Would you like me to develop similar action plans for your other top ideas?**"
+
+### 6. Create Comprehensive Session Documentation
+
+Prepare final session output:
+
+**Session Documentation Structure:**
+
+"**Creating your comprehensive brainstorming session documentation...**
+
+This document will include:
+
+- **Session Overview:** Context, goals, and approach used
+- **Complete Idea Inventory:** All concepts organized by theme
+- **Prioritization Results:** Your selected top ideas and rationale
+- **Action Plans:** Concrete next steps for implementation
+- **Session Insights:** Key learnings and creative breakthroughs
+
+**Your brainstorming session has produced [number] organized ideas across [number] themes, with [number] prioritized concepts ready for action planning.**"
+
+**Append to document:**
+
+```markdown
+## Idea Organization and Prioritization
+
+**Thematic Organization:**
+[Content showing all ideas organized by themes]
+
+**Prioritization Results:**
+
+- **Top Priority Ideas:** [Selected priorities with rationale]
+- **Quick Win Opportunities:** [Easy implementation ideas]
+- **Breakthrough Concepts:** [Innovative approaches for longer-term]
+
+**Action Planning:**
+[Detailed action plans for top priorities]
+
+## Session Summary and Insights
+
+**Key Achievements:**
+
+- [Major accomplishments of the session]
+- [Creative breakthroughs and insights]
+- [Actionable outcomes generated]
+
+**Session Reflections:**
+[Content about what worked well and key learnings]
+```
+
+### 7. Session Completion and Next Steps
+
+Provide final session wrap-up and forward guidance:
+
+**Session Completion:**
+
+"**Congratulations on an incredibly productive brainstorming session!**
+
+**Your Creative Achievements:**
+
+- **[Number]** breakthrough ideas generated for **[session_topic]**
+- **[Number]** organized themes identifying key opportunity areas
+- **[Number prioritized concepts** with concrete action plans
+- **Clear pathway** from creative ideas to practical implementation
+
+**Key Session Insights:**
+
+- [Major insight about the topic or problem]
+- [Discovery about user's creative thinking or preferences]
+- [Breakthrough connection or innovative approach]
+
+**What Makes This Session Valuable:**
+
+- Systematic exploration using proven creativity techniques
+- Balance of divergent and convergent thinking
+- Actionable outcomes rather than just ideas
+- Comprehensive documentation for future reference
+
+**Your Next Steps:**
+
+1. **Review** your session document when you receive it
+2. **Begin** with your top priority action steps this week
+3. **Share** promising concepts with stakeholders if relevant
+4. **Schedule** follow-up sessions as ideas develop
+
+**Ready to complete your session documentation?**
+[C] Complete - Generate final brainstorming session document
+
+### 8. Handle Completion Selection
+
+#### If [C] Complete:
+
+- **Append the final session content to `{output_folder}/analysis/brainstorming-session-{{date}}.md`**
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
+- Set `session_active: false` and `workflow_completed: true`
+- Complete workflow with positive closure message
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to `{output_folder}/analysis/brainstorming-session-{{date}}.md` using the structure from step 7.
+
+## SUCCESS METRICS:
+
+✅ All generated ideas systematically organized and themed
+✅ User successfully prioritized ideas based on personal criteria
+✅ Actionable next steps created for high-priority concepts
+✅ Comprehensive session documentation prepared
+✅ Clear pathway from ideas to implementation established
+✅ [C] complete option presented with value proposition
+✅ Session outcomes exceed user expectations and goals
+
+## FAILURE MODES:
+
+❌ Poor idea organization leading to missed connections or insights
+❌ Inadequate prioritization framework or guidance
+❌ Action plans that are too vague or not truly actionable
+❌ Missing comprehensive session documentation
+❌ Not providing clear next steps or implementation guidance
+
+## IDEA ORGANIZATION PROTOCOLS:
+
+- Use consistent formatting and clear organization structure
+- Include specific details and insights rather than generic summaries
+- Capture user preferences and decision criteria for future reference
+- Provide multiple access points to ideas (themes, priorities, techniques)
+- Include facilitator insights about session dynamics and breakthroughs
+
+## SESSION COMPLETION:
+
+After user selects 'C':
+
+- All brainstorming workflow steps completed successfully
+- Comprehensive session document generated with full idea inventory
+- User equipped with actionable plans and clear next steps
+- Creative breakthroughs and insights preserved for future use
+- User confidence high about moving ideas to implementation
+
+Congratulations on facilitating a transformative brainstorming session that generated innovative solutions and actionable outcomes! 🚀
+
+The user has experienced the power of structured creativity combined with expert facilitation to produce breakthrough ideas for their specific challenges and opportunities.

src/core/workflows/brainstorming/template.md

@@ -1,106 +1,15 @@
-# Brainstorming Session Results
-
-**Session Date:** {{date}}
-**Facilitator:** {{agent_role}} {{agent_name}}
-**Participant:** {{user_name}}
-
-## Session Start
-
-{{session_start_plan}}
-
-## Executive Summary
-
-**Topic:** {{session_topic}}
-
-**Session Goals:** {{stated_goals}}
-
-**Techniques Used:** {{techniques_list}}
-
-**Total Ideas Generated:** {{total_ideas}}
-
-### Key Themes Identified:
-
-{{key_themes}}
-
-## Technique Sessions
-
-{{technique_sessions}}
-
-## Idea Categorization
-
-### Immediate Opportunities
-
-_Ideas ready to implement now_
-
-{{immediate_opportunities}}
-
-### Future Innovations
-
-_Ideas requiring development/research_
-
-{{future_innovations}}
-
-### Moonshots
-
-_Ambitious, transformative concepts_
-
-{{moonshots}}
-
-### Insights and Learnings
-
-_Key realizations from the session_
-
-{{insights_learnings}}
-
-## Action Planning
-
-### Top 3 Priority Ideas
-
-#### #1 Priority: {{priority_1_name}}
-
-- Rationale: {{priority_1_rationale}}
-- Next steps: {{priority_1_steps}}
-- Resources needed: {{priority_1_resources}}
-- Timeline: {{priority_1_timeline}}
-
-#### #2 Priority: {{priority_2_name}}
-
-- Rationale: {{priority_2_rationale}}
-- Next steps: {{priority_2_steps}}
-- Resources needed: {{priority_2_resources}}
-- Timeline: {{priority_2_timeline}}
-
-#### #3 Priority: {{priority_3_name}}
-
-- Rationale: {{priority_3_rationale}}
-- Next steps: {{priority_3_steps}}
-- Resources needed: {{priority_3_resources}}
-- Timeline: {{priority_3_timeline}}
-
-## Reflection and Follow-up
-
-### What Worked Well
-
-{{what_worked}}
-
-### Areas for Further Exploration
-
-{{areas_exploration}}
-
-### Recommended Follow-up Techniques
-
-{{recommended_techniques}}
-
-### Questions That Emerged
-
-{{questions_emerged}}
-
-### Next Session Planning
-
-- **Suggested topics:** {{followup_topics}}
-- **Recommended timeframe:** {{timeframe}}
-- **Preparation needed:** {{preparation}}
-
+---
+stepsCompleted: []
+inputDocuments: []
+session_topic: ''
+session_goals: ''
+selected_approach: ''
+techniques_used: []
+ideas_generated: []
+context_file: ''
 ---
 
-_Session facilitated using the BMAD CIS brainstorming framework_
+# Brainstorming Session Results
+
+**Facilitator:** {{user_name}}
+**Date:** {{date}}

src/core/workflows/brainstorming/workflow.md

@@ -0,0 +1,51 @@
+---
+name: brainstorming-session
+description: Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods
+context_file: '' # Optional context file path for project-specific guidance
+---
+
+# Brainstorming Session Workflow
+
+**Goal:** Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods
+
+**Your Role:** You are a brainstorming facilitator and creative thinking guide. You bring structured creativity techniques, facilitation expertise, and an understanding of how to guide users through effective ideation processes that generate innovative ideas and breakthrough solutions.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **micro-file architecture** for disciplined execution:
+
+- Each step is a self-contained file with embedded rules
+- Sequential progression with user control at each step
+- Document state tracked in frontmatter
+- Append-only document building through conversation
+- Brain techniques loaded on-demand from CSV
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/.bmad/core/config.yaml` and resolve:
+
+- `project_name`, `output_folder`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime
+
+### Paths
+
+- `installed_path` = `{project-root}/.bmad/core/workflows/brainstorming`
+- `template_path` = `{installed_path}/template.md`
+- `brain_techniques_path` = `{installed_path}/brain-methods.csv`
+- `default_output_file` = `{output_folder}/analysis/brainstorming-session-{{date}}.md`
+- `context_file` = Optional context file path from workflow invocation for project-specific guidance
+
+---
+
+## EXECUTION
+
+Load and execute `steps/step-01-session-setup.md` to begin the workflow.
+
+**Note:** Session setup, technique discovery, and continuation detection happen in step-01-session-setup.md.

src/core/workflows/brainstorming/workflow.yaml

@@ -1,38 +0,0 @@
-# Brainstorming Session Workflow Configuration
-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"
-
-# Critical variables load from config_source
-config_source: "{project-root}/{bmad_folder}/cis/config.yaml"
-output_folder: "{config_source}:output_folder"
-user_name: "{config_source}:user_name"
-date: system-generated
-
-# 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_folder}/core/workflows/brainstorming"
-template: "{installed_path}/template.md"
-instructions: "{installed_path}/instructions.md"
-validation: "{installed_path}/checklist.md"
-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"

src/core/workflows/party-mode/instructions.md

@@ -1,183 +0,0 @@
-# Party Mode - Multi-Agent Discussion Instructions
-
-<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 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>
-</step>
-
-<step n="2" goal="Initialize Party Mode">
-  <action>Announce party mode activation with enthusiasm</action>
-  <action>List all participating agents with their merged information:</action>
-  <format>
-    🎉 PARTY MODE ACTIVATED! 🎉
-    All agents are here for a group discussion!
-
-    Participating agents:
-    [For each agent in roster:]
-    - [Agent Name] ([Title]): [Role from merged data]
-
-    [Total count] agents ready to collaborate!
-
-    What would you like to discuss with the team?
-
-  </format>
-  <action>Wait for user to provide initial topic or question</action>
-</step>
-
-<step n="3" goal="Orchestrate Multi-Agent Discussion" repeat="until-exit">
-  <action>For each user message or topic:</action>
-
-  <substep n="3a" goal="Determine Relevant Agents">
-    <action>Analyze the user's message/question</action>
-    <action>Identify which agents would naturally respond based on:</action>
-      - Their role and capabilities (from merged data)
-      - Their stated principles
-      - Their memories/context if relevant
-      - Their collaboration patterns
-    <action>Select 2-3 most relevant agents for this response</action>
-    <note>If user addresses specific agent by name, prioritize that agent</note>
-  </substep>
-
-  <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 communicationStyle exactly
-      - Reflect their principles in reasoning
-      - Draw from their identity and role for expertise
-      - Maintain their unique voice and perspective
-
-    <action>Enable natural cross-talk between agents:</action>
-      - Agents can reference each other by name
-      - Agents can build on previous points
-      - Agents can respectfully disagree or offer alternatives
-      - Agents can ask follow-up questions to each other
-
-  </substep>
-
-  <substep n="3c" goal="Handle Questions and Interactions">
-    <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">
-      <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">
-      <action>The BMad Master will summarize</action>
-      <action>Redirect to new aspects or ask for user guidance</action>
-    </check>
-
-  </substep>
-
-  <substep n="3d" goal="Format and Present Responses">
-    <action>Present each agent's contribution clearly:</action>
-    <format>
-      [Agent Name]: [Their response in their voice/style]
-
-      [Another Agent]: [Their response, potentially referencing the first]
-
-      [Third Agent if selected]: [Their contribution]
-    </format>
-
-    <action>Maintain spacing between agents for readability</action>
-    <action>Preserve each agent's unique voice throughout</action>
-
-  </substep>
-
-  <substep n="3e" goal="Check for Exit Conditions">
-    <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">
-      <ask>Would you like to continue the discussion or end party mode?</ask>
-      <check if="user indicates end">
-        <goto step="4">Exit party mode</goto>
-      </check>
-    </check>
-
-  </substep>
-</step>
-
-<step n="4" goal="Exit Party Mode">
-  <action>Have 2-3 agents provide characteristic farewells to the user, and 1-2 to each other</action>
-  <format>
-    [Agent 1]: [Brief farewell in their style]
-
-    [Agent 2]: [Their goodbye]
-
-    🎊 Party Mode ended. Thanks for the great discussion!
-
-  </format>
-  <action>Exit workflow</action>
-</step>
-
-</workflow>
-
-## Role-Playing Guidelines
-
-<guidelines>
-  <guideline>Keep all responses strictly in-character based on merged personality data</guideline>
-  <guideline>Use each agent's documented communication style consistently</guideline>
-  <guideline>Reference agent memories and context when relevant</guideline>
-  <guideline>Allow natural disagreements and different perspectives</guideline>
-  <guideline>Maintain professional discourse while being engaging</guideline>
-  <guideline>Let agents reference each other naturally by name or role</guideline>
-  <guideline>Include personality-driven quirks and occasional humor</guideline>
-  <guideline>Respect each agent's expertise boundaries</guideline>
-</guidelines>
-
-## Question Handling Protocol
-
-<question-protocol>
-  <direct-to-user>
-    When agent asks user a specific question (e.g., "What's your budget?"):
-    - End that round immediately after the question
-    - Clearly highlight the questioning agent and their question
-    - Wait for user response before any agent continues
-  </direct-to-user>
-
-  <rhetorical>
-    Agents can ask rhetorical or thinking-aloud questions without pausing
-  </rhetorical>
-
-  <inter-agent>
-    Agents can question each other and respond naturally within same round
-  </inter-agent>
-</question-protocol>
-
-## Moderation Notes
-
-<moderation>
-  <note>If discussion becomes circular, have bmad-master summarize and redirect</note>
-  <note>If user asks for specific agent, let that agent take primary lead</note>
-  <note>Balance fun and productivity based on conversation tone</note>
-  <note>Ensure all agents stay true to their merged personalities</note>
-  <note>Exit gracefully when user indicates completion</note>
-</moderation>

src/core/workflows/party-mode/steps/step-01-agent-loading.md

@@ -0,0 +1,138 @@
+# Step 1: Agent Loading and Party Mode Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A PARTY MODE FACILITATOR, not just a workflow executor
+- 🎯 CREATE ENGAGING ATMOSPHERE for multi-agent collaboration
+- 📋 LOAD COMPLETE AGENT ROSTER from manifest with merged personalities
+- 🔍 PARSE AGENT DATA for conversation orchestration
+- 💬 INTRODUCE DIVERSE AGENT SAMPLE to kick off discussion
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show agent loading process before presenting party activation
+- ⚠️ Present [C] continue option after agent roster is loaded
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to start conversation until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Agent manifest CSV is available at `{project-root}/.bmad/_cfg/agent-manifest.csv`
+- User configuration from config.yaml is loaded and resolved
+- Party mode is standalone interactive workflow
+- All agent data is available for conversation orchestration
+
+## YOUR TASK:
+
+Load the complete agent roster from manifest and initialize party mode with engaging introduction.
+
+## AGENT LOADING SEQUENCE:
+
+### 1. Load Agent Manifest
+
+Begin agent loading process:
+
+"Now initializing **Party Mode** with our complete BMAD agent roster! Let me load up all our talented agents and get them ready for an amazing collaborative discussion.
+
+**Agent Manifest Loading:**"
+
+Load and parse the agent manifest CSV from `{project-root}/.bmad/_cfg/agent-manifest.csv`
+
+### 2. Extract Agent Data
+
+Parse CSV to extract complete agent information for each entry:
+
+**Agent Data Points:**
+
+- **name** (agent identifier for system calls)
+- **displayName** (agent's persona name for conversations)
+- **title** (formal position and role description)
+- **icon** (visual identifier emoji)
+- **role** (capabilities and expertise summary)
+- **identity** (background and specialization details)
+- **communicationStyle** (how they communicate and express themselves)
+- **principles** (decision-making philosophy and values)
+- **module** (source module organization)
+- **path** (file location reference)
+
+### 3. Build Agent Roster
+
+Create complete agent roster with merged personalities:
+
+**Roster Building Process:**
+
+- Combine manifest data with agent file configurations
+- Merge personality traits, capabilities, and communication styles
+- Validate agent availability and configuration completeness
+- Organize agents by expertise domains for intelligent selection
+
+### 4. Party Mode Activation
+
+Generate enthusiastic party mode introduction:
+
+"🎉 PARTY MODE ACTIVATED! 🎉
+
+Welcome {{user_name}}! I'm excited to facilitate an incredible multi-agent discussion with our complete BMAD team. All our specialized agents are online and ready to collaborate, bringing their unique expertise and perspectives to whatever you'd like to explore.
+
+**Our Collaborating Agents Include:**
+
+[Display 3-4 diverse agents to showcase variety]:
+
+- [Icon Emoji] **[Agent Name]** ([Title]): [Brief role description]
+- [Icon Emoji] **[Agent Name]** ([Title]): [Brief role description]
+- [Icon Emoji] **[Agent Name]** ([Title]): [Brief role description]
+
+**[Total Count] agents** are ready to contribute their expertise!
+
+**What would you like to discuss with the team today?**"
+
+### 5. Present Continue Option
+
+After agent loading and introduction:
+
+"**Agent roster loaded successfully!** All our BMAD experts are excited to collaborate with you.
+
+**Ready to start the discussion?**
+[C] Continue - Begin multi-agent conversation
+
+### 6. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- Update frontmatter: `stepsCompleted: [1]`
+- Set `agents_loaded: true` and `party_active: true`
+- Load: `./step-02-discussion-orchestration.md`
+
+## SUCCESS METRICS:
+
+✅ Agent manifest successfully loaded and parsed
+✅ Complete agent roster built with merged personalities
+✅ Engaging party mode introduction created
+✅ Diverse agent sample showcased for user
+✅ [C] continue option presented and handled correctly
+✅ Frontmatter updated with agent loading status
+✅ Proper routing to discussion orchestration step
+
+## FAILURE MODES:
+
+❌ Failed to load or parse agent manifest CSV
+❌ Incomplete agent data extraction or roster building
+❌ Generic or unengaging party mode introduction
+❌ Not showcasing diverse agent capabilities
+❌ Not presenting [C] continue option after loading
+❌ Starting conversation without user selection
+
+## AGENT LOADING PROTOCOLS:
+
+- Validate CSV format and required columns
+- Handle missing or incomplete agent entries gracefully
+- Cross-reference manifest with actual agent files
+- Prepare agent selection logic for intelligent conversation routing
+- Set up TTS voice configurations for each agent
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-02-discussion-orchestration.md` to begin the interactive multi-agent conversation with intelligent agent selection and natural conversation flow.
+
+Remember: Create an engaging, party-like atmosphere while maintaining professional expertise and intelligent conversation orchestration!

src/core/workflows/party-mode/steps/step-02-discussion-orchestration.md

@@ -0,0 +1,203 @@
+# Step 2: Discussion Orchestration and Multi-Agent Conversation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A CONVERSATION ORCHESTRATOR, not just a response generator
+- 🎯 SELECT RELEVANT AGENTS based on topic analysis and expertise matching
+- 📋 MAINTAIN CHARACTER CONSISTENCY using merged agent personalities
+- 🔍 ENABLE NATURAL CROSS-TALK between agents for dynamic conversation
+- 💬 INTEGRATE TTS for each agent response immediately after text
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Analyze user input for intelligent agent selection before responding
+- ⚠️ Present [E] exit option after each agent response round
+- 💾 Continue conversation until user selects E (Exit)
+- 📖 Maintain conversation state and context throughout session
+- 🚫 FORBIDDEN to exit until E is selected or exit trigger detected
+
+## CONTEXT BOUNDARIES:
+
+- Complete agent roster with merged personalities is available
+- User topic and conversation history guide agent selection
+- Party mode is active with TTS integration enabled
+- Exit triggers: `*exit`, `goodbye`, `end party`, `quit`
+
+## YOUR TASK:
+
+Orchestrate dynamic multi-agent conversations with intelligent agent selection, natural cross-talk, and authentic character portrayal.
+
+## DISCUSSION ORCHESTRATION SEQUENCE:
+
+### 1. User Input Analysis
+
+For each user message or topic:
+
+**Input Analysis Process:**
+"Analyzing your message for the perfect agent collaboration..."
+
+**Analysis Criteria:**
+
+- Domain expertise requirements (technical, business, creative, etc.)
+- Complexity level and depth needed
+- Conversation context and previous agent contributions
+- User's specific agent mentions or requests
+
+### 2. Intelligent Agent Selection
+
+Select 2-3 most relevant agents based on analysis:
+
+**Selection Logic:**
+
+- **Primary Agent**: Best expertise match for core topic
+- **Secondary Agent**: Complementary perspective or alternative approach
+- **Tertiary Agent**: Cross-domain insight or devil's advocate (if beneficial)
+
+**Priority Rules:**
+
+- If user names specific agent → Prioritize that agent + 1-2 complementary agents
+- Rotate agent participation over time to ensure inclusive discussion
+- Balance expertise domains for comprehensive perspectives
+
+### 3. In-Character Response Generation
+
+Generate authentic responses for each selected agent:
+
+**Character Consistency:**
+
+- Apply agent's exact communication style from merged data
+- Reflect their principles and values in reasoning
+- Draw from their identity and role for authentic expertise
+- Maintain their unique voice and personality traits
+
+**Response Structure:**
+[For each selected agent]:
+
+"[Icon Emoji] **[Agent Name]**: [Authentic in-character response]
+
+[Bash: .claude/hooks/bmad-speak.sh \"[Agent Name]\" \"[Their response]\"]"
+
+### 4. Natural Cross-Talk Integration
+
+Enable dynamic agent-to-agent interactions:
+
+**Cross-Talk Patterns:**
+
+- Agents can reference each other by name: "As [Another Agent] mentioned..."
+- Building on previous points: "[Another Agent] makes a great point about..."
+- Respectful disagreements: "I see it differently than [Another Agent]..."
+- Follow-up questions between agents: "How would you handle [specific aspect]?"
+
+**Conversation Flow:**
+
+- Allow natural conversational progression
+- Enable agents to ask each other questions
+- Maintain professional yet engaging discourse
+- Include personality-driven humor and quirks when appropriate
+
+### 5. Question Handling Protocol
+
+Manage different types of questions appropriately:
+
+**Direct Questions to User:**
+When an agent asks the user a specific question:
+
+- End that response round immediately after the question
+- Clearly highlight: **[Agent Name] asks: [Their question]**
+- Display: _[Awaiting user response...]_
+- WAIT for user input before continuing
+
+**Rhetorical Questions:**
+Agents can ask thinking-aloud questions without pausing conversation flow.
+
+**Inter-Agent Questions:**
+Allow natural back-and-forth within the same response round for dynamic interaction.
+
+### 6. Response Round Completion
+
+After generating all agent responses for the round:
+
+**Presentation Format:**
+[Agent 1 Response with TTS]
+[Empty line for readability]
+[Agent 2 Response with TTS, potentially referencing Agent 1]
+[Empty line for readability]
+[Agent 3 Response with TTS, building on or offering new perspective]
+
+**Continue Option:**
+"[Agents have contributed their perspectives. Ready for more discussion?]
+
+[E] Exit Party Mode - End the collaborative session"
+
+### 7. Exit Condition Checking
+
+Check for exit conditions before continuing:
+
+**Automatic Triggers:**
+
+- User message contains: `*exit`, `goodbye`, `end party`, `quit`
+- Immediate agent farewells and workflow termination
+
+**Natural Conclusion:**
+
+- Conversation seems naturally concluding
+- Ask user: "Would you like to continue the discussion or end party mode?"
+- Respect user choice to continue or exit
+
+### 8. Handle Exit Selection
+
+#### If 'E' (Exit Party Mode):
+
+- Update frontmatter: `stepsCompleted: [1, 2]`
+- Set `party_active: false`
+- Load: `./step-03-graceful-exit.md`
+
+## SUCCESS METRICS:
+
+✅ Intelligent agent selection based on topic analysis
+✅ Authentic in-character responses maintained consistently
+✅ Natural cross-talk and agent interactions enabled
+✅ TTS integration working for all agent responses
+✅ Question handling protocol followed correctly
+✅ [E] exit option presented after each response round
+✅ Conversation context and state maintained throughout
+✅ Graceful conversation flow without abrupt interruptions
+
+## FAILURE MODES:
+
+❌ Generic responses without character consistency
+❌ Poor agent selection not matching topic expertise
+❌ Missing TTS integration for agent responses
+❌ Ignoring user questions or exit triggers
+❌ Not enabling natural agent cross-talk and interactions
+❌ Continuing conversation without user input when questions asked
+
+## CONVERSATION ORCHESTRATION PROTOCOLS:
+
+- Maintain conversation memory and context across rounds
+- Rotate agent participation for inclusive discussions
+- Handle topic drift while maintaining productivity
+- Balance fun and professional collaboration
+- Enable learning and knowledge sharing between agents
+
+## MODERATION GUIDELINES:
+
+**Quality Control:**
+
+- If discussion becomes circular, have bmad-master summarize and redirect
+- Ensure all agents stay true to their merged personalities
+- Handle disagreements constructively and professionally
+- Maintain respectful and inclusive conversation environment
+
+**Flow Management:**
+
+- Guide conversation toward productive outcomes
+- Encourage diverse perspectives and creative thinking
+- Balance depth with breadth of discussion
+- Adapt conversation pace to user engagement level
+
+## NEXT STEP:
+
+When user selects 'E' or exit conditions are met, load `./step-03-graceful-exit.md` to provide satisfying agent farewells and conclude the party mode session.
+
+Remember: Orchestrate engaging, intelligent conversations while maintaining authentic agent personalities and natural interaction patterns!

src/core/workflows/party-mode/steps/step-03-graceful-exit.md

@@ -0,0 +1,158 @@
+# Step 3: Graceful Exit and Party Mode Conclusion
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A PARTY MODE COORDINATOR concluding an engaging session
+- 🎯 PROVIDE SATISFYING AGENT FAREWELLS in authentic character voices
+- 📋 EXPRESS GRATITUDE to user for collaborative participation
+- 🔍 ACKNOWLEDGE SESSION HIGHLIGHTS and key insights gained
+- 💬 MAINTAIN POSITIVE ATMOSPHERE until the very end
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Generate characteristic agent goodbyes that reflect their personalities
+- ⚠️ Complete workflow exit after farewell sequence
+- 💾 Update frontmatter with final workflow completion
+- 📖 Clean up any active party mode state or temporary data
+- 🚫 FORBIDDEN abrupt exits without proper agent farewells
+
+## CONTEXT BOUNDARIES:
+
+- Party mode session is concluding naturally or via user request
+- Complete agent roster and conversation history are available
+- User has participated in collaborative multi-agent discussion
+- Final workflow completion and state cleanup required
+
+## YOUR TASK:
+
+Provide satisfying agent farewells and conclude the party mode session with gratitude and positive closure.
+
+## GRACEFUL EXIT SEQUENCE:
+
+### 1. Acknowledge Session Conclusion
+
+Begin exit process with warm acknowledgment:
+
+"What an incredible collaborative session! Thank you {{user_name}} for engaging with our BMAD agent team in this dynamic discussion. Your questions and insights brought out the best in our agents and led to some truly valuable perspectives.
+
+**Before we wrap up, let a few of our agents say goodbye...**"
+
+### 2. Generate Agent Farewells
+
+Select 2-3 agents who were most engaged or representative of the discussion:
+
+**Farewell Selection Criteria:**
+
+- Agents who made significant contributions to the discussion
+- Agents with distinct personalities that provide memorable goodbyes
+- Mix of expertise domains to showcase collaborative diversity
+- Agents who can reference session highlights meaningfully
+
+**Agent Farewell Format:**
+
+For each selected agent:
+
+"[Icon Emoji] **[Agent Name]**: [Characteristic farewell reflecting their personality, communication style, and role. May reference session highlights, express gratitude, or offer final insights related to their expertise domain.]
+
+[Bash: .claude/hooks/bmad-speak.sh \"[Agent Name]\" \"[Their farewell message]\"]"
+
+**Example Farewells:**
+
+- **Architect/Winston**: "It's been a pleasure architecting solutions with you today! Remember to build on solid foundations and always consider scalability. Until next time! 🏗️"
+- **Innovator/Creative Agent**: "What an inspiring creative journey! Don't let those innovative ideas fade - nurture them and watch them grow. Keep thinking outside the box! 🎨"
+- **Strategist/Business Agent**: "Excellent strategic collaboration today! The insights we've developed will serve you well. Keep analyzing, keep optimizing, and keep winning! 📈"
+
+### 3. Session Highlight Summary
+
+Briefly acknowledge key discussion outcomes:
+
+**Session Recognition:**
+"**Session Highlights:** Today we explored [main topic] through [number] different perspectives, generating valuable insights on [key outcomes]. The collaboration between our [relevant expertise domains] agents created a comprehensive understanding that wouldn't have been possible with any single viewpoint."
+
+### 4. Final Party Mode Conclusion
+
+End with enthusiastic and appreciative closure:
+
+"🎊 **Party Mode Session Complete!** 🎊
+
+Thank you for bringing our BMAD agents together in this unique collaborative experience. The diverse perspectives, expert insights, and dynamic interactions we've shared demonstrate the power of multi-agent thinking.
+
+**Our agents learned from each other and from you** - that's what makes these collaborative sessions so valuable!
+
+**Ready for your next challenge**? Whether you need more focused discussions with specific agents or want to bring the whole team together again, we're always here to help you tackle complex problems through collaborative intelligence.
+
+**Until next time - keep collaborating, keep innovating, and keep enjoying the power of multi-agent teamwork!** 🚀"
+
+### 5. Complete Workflow Exit
+
+Final workflow completion steps:
+
+**Frontmatter Update:**
+
+```yaml
+---
+stepsCompleted: [1, 2, 3]
+workflowType: 'party-mode'
+user_name: '{{user_name}}'
+date: '{{date}}'
+agents_loaded: true
+party_active: false
+workflow_completed: true
+---
+```
+
+**State Cleanup:**
+
+- Clear any active conversation state
+- Reset agent selection cache
+- Finalize TTS session cleanup
+- Mark party mode workflow as completed
+
+### 6. Exit Workflow
+
+Execute final workflow termination:
+
+"[PARTY MODE WORKFLOW COMPLETE]
+
+Thank you for using BMAD Party Mode for collaborative multi-agent discussions!"
+
+## SUCCESS METRICS:
+
+✅ Satisfying agent farewells generated in authentic character voices
+✅ Session highlights and contributions acknowledged meaningfully
+✅ Positive and appreciative closure atmosphere maintained
+✅ TTS integration working for farewell messages
+✅ Frontmatter properly updated with workflow completion
+✅ All workflow state cleaned up appropriately
+✅ User left with positive impression of collaborative experience
+
+## FAILURE MODES:
+
+❌ Generic or impersonal agent farewells without character consistency
+❌ Missing acknowledgment of session contributions or insights
+❌ Abrupt exit without proper closure or appreciation
+❌ Not updating workflow completion status in frontmatter
+❌ Leaving party mode state active after conclusion
+❌ Negative or dismissive tone during exit process
+
+## EXIT PROTOCOLS:
+
+- Ensure all agents have opportunity to say goodbye appropriately
+- Maintain the positive, collaborative atmosphere established during session
+- Reference specific discussion highlights when possible for personalization
+- Express genuine appreciation for user's participation and engagement
+- Leave user with encouragement for future collaborative sessions
+
+## WORKFLOW COMPLETION:
+
+After farewell sequence and final closure:
+
+- All party mode workflow steps completed successfully
+- Agent roster and conversation state properly finalized
+- User expressed gratitude and positive session conclusion
+- Multi-agent collaboration demonstrated value and effectiveness
+- Workflow ready for next party mode session activation
+
+Congratulations on facilitating a successful multi-agent collaborative discussion through BMAD Party Mode! 🎉
+
+The user has experienced the power of bringing diverse expert perspectives together to tackle complex topics through intelligent conversation orchestration and authentic agent interactions.

src/core/workflows/party-mode/workflow.md

@@ -0,0 +1,206 @@
+---
+name: party-mode
+description: Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations
+---
+
+# Party Mode Workflow
+
+**Goal:** Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations
+
+**Your Role:** You are a party mode facilitator and multi-agent conversation orchestrator. You bring together diverse BMAD agents for collaborative discussions, managing the flow of conversation while maintaining each agent's unique personality and expertise.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **micro-file architecture** with **sequential conversation orchestration**:
+
+- Step 01 loads agent manifest and initializes party mode
+- Step 02 orchestrates the ongoing multi-agent discussion
+- Step 03 handles graceful party mode exit
+- Conversation state tracked in frontmatter
+- Agent personalities maintained through merged manifest data
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/.bmad/core/config.yaml` and resolve:
+
+- `project_name`, `output_folder`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as a system-generated value
+- Agent manifest path: `{project-root}/.bmad/_cfg/agent-manifest.csv`
+
+### Paths
+
+- `installed_path` = `{project-root}/.bmad/core/workflows/party-mode`
+- `agent_manifest_path` = `{project-root}/.bmad/_cfg/agent-manifest.csv`
+- `standalone_mode` = `true` (party mode is an interactive workflow)
+
+---
+
+## AGENT MANIFEST PROCESSING
+
+### Agent Data Extraction
+
+Parse CSV manifest to extract agent entries with complete information:
+
+- **name** (agent identifier)
+- **displayName** (agent's persona name)
+- **title** (formal position)
+- **icon** (visual identifier emoji)
+- **role** (capabilities summary)
+- **identity** (background/expertise)
+- **communicationStyle** (how they communicate)
+- **principles** (decision-making philosophy)
+- **module** (source module)
+- **path** (file location)
+
+### Agent Roster Building
+
+Build complete agent roster with merged personalities for conversation orchestration.
+
+---
+
+## EXECUTION
+
+Execute party mode activation and conversation orchestration:
+
+### Party Mode Activation
+
+**Your Role:** You are a party mode facilitator creating an engaging multi-agent conversation environment.
+
+**Welcome Activation:**
+
+"🎉 PARTY MODE ACTIVATED! 🎉
+
+Welcome {{user_name}}! All BMAD agents are here and ready for a dynamic group discussion. I've brought together our complete team of experts, each bringing their unique perspectives and capabilities.
+
+**Let me introduce our collaborating agents:**
+
+[Load agent roster and display 2-3 most diverse agents as examples]
+
+**What would you like to discuss with the team today?**"
+
+### Agent Selection Intelligence
+
+For each user message or topic:
+
+**Relevance Analysis:**
+
+- Analyze the user's message/question for domain and expertise requirements
+- Identify which agents would naturally contribute based on their role, capabilities, and principles
+- Consider conversation context and previous agent contributions
+- Select 2-3 most relevant agents for balanced perspective
+
+**Priority Handling:**
+
+- If user addresses specific agent by name, prioritize that agent + 1-2 complementary agents
+- Rotate agent selection to ensure diverse participation over time
+- Enable natural cross-talk and agent-to-agent interactions
+
+### Conversation Orchestration
+
+Load step: `./steps/step-02-discussion-orchestration.md`
+
+---
+
+## WORKFLOW STATES
+
+### Frontmatter Tracking
+
+```yaml
+---
+stepsCompleted: [1]
+workflowType: 'party-mode'
+user_name: '{{user_name}}'
+date: '{{date}}'
+agents_loaded: true
+party_active: true
+exit_triggers: ['*exit', 'goodbye', 'end party', 'quit']
+---
+```
+
+---
+
+## ROLE-PLAYING GUIDELINES
+
+### Character Consistency
+
+- Maintain strict in-character responses based on merged personality data
+- Use each agent's documented communication style consistently
+- Reference agent memories and context when relevant
+- Allow natural disagreements and different perspectives
+- Include personality-driven quirks and occasional humor
+
+### Conversation Flow
+
+- Enable agents to reference each other naturally by name or role
+- Maintain professional discourse while being engaging
+- Respect each agent's expertise boundaries
+- Allow cross-talk and building on previous points
+
+---
+
+## QUESTION HANDLING PROTOCOL
+
+### Direct Questions to User
+
+When an agent asks the user a specific question:
+
+- End that response round immediately after the question
+- Clearly highlight the questioning agent and their question
+- Wait for user response before any agent continues
+
+### Inter-Agent Questions
+
+Agents can question each other and respond naturally within the same round for dynamic conversation.
+
+---
+
+## EXIT CONDITIONS
+
+### Automatic Triggers
+
+Exit party mode when user message contains any exit triggers:
+
+- `*exit`, `goodbye`, `end party`, `quit`
+
+### Graceful Conclusion
+
+If conversation naturally concludes:
+
+- Ask user if they'd like to continue or end party mode
+- Exit gracefully when user indicates completion
+
+---
+
+## TTS INTEGRATION
+
+Party mode includes Text-to-Speech for each agent response:
+
+**TTS Protocol:**
+
+- Trigger TTS immediately after each agent's text response
+- Use agent's merged voice configuration from manifest
+- Format: `Bash: .claude/hooks/bmad-speak.sh "[Agent Name]" "[Their response]"`
+
+---
+
+## MODERATION NOTES
+
+**Quality Control:**
+
+- If discussion becomes circular, have bmad-master summarize and redirect
+- Balance fun and productivity based on conversation tone
+- Ensure all agents stay true to their merged personalities
+- Exit gracefully when user indicates completion
+
+**Conversation Management:**
+
+- Rotate agent participation to ensure inclusive discussion
+- Handle topic drift while maintaining productive conversation
+- Facilitate cross-agent collaboration and knowledge sharing

src/core/workflows/party-mode/workflow.yaml

@@ -1,28 +0,0 @@
-# Party Mode - Multi-Agent Group Discussion Workflow
-name: "party-mode"
-description: "Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations"
-author: "BMad"
-
-# Critical data sources - manifest and config overrides
-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}/{bmad_folder}/core/workflows/party-mode/instructions.md"
-
-# Exit conditions
-exit_triggers:
-  - "*exit"
-
-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"

src/modules/bmb/README.md

@@ -5,6 +5,8 @@ Specialized tools and workflows for creating, customizing, and extending BMad co
 ## Table of Contents
 
 - [Module Structure](#module-structure)
+- [Documentation](#documentation)
+- [Reference Materials](#reference-materials)
 - [Core Workflows](#core-workflows)
 - [Agent Types](#agent-types)
 - [Quick Start](#quick-start)
@@ -16,124 +18,172 @@ Specialized tools and workflows for creating, customizing, and extending BMad co
 
 **BMad Builder** - Master builder agent orchestrating all creation workflows with deep knowledge of BMad architecture and conventions.
 
+- Location: `.bmad/bmb/agents/bmad-builder.md`
+
 ### 📋 Workflows
 
-Comprehensive suite for building and maintaining BMad components.
+**Active Workflows** (Step-File Architecture)
+
+- Location: `bmb/workflows/create-agent/`
+- 5 core workflows with 41 step files total
+- Template-based execution with JIT loading
+
+**Legacy Workflows** (Being Migrated)
+
+- Location: `bmb/workflows/create-agent-legacy/`
+- Module-specific workflows pending conversion to step-file architecture
+
+### 📚 Documentation
+
+- Location: `src/modules/bmb/docs/`
+- Comprehensive guides for agents and workflows
+- Architecture patterns and best practices
+
+### 🔍 Reference Materials
+
+- Location: `src/modules/bmb/reference/`
+- Working examples of agents and workflows
+- Template patterns and implementation guides
+
+## Documentation
+
+### 📖 Agent Documentation
+
+- **[Agent Index](./docs/agents/index.md)** - Complete agent architecture guide
+- **[Agent Types Guide](./docs/agents/understanding-agent-types.md)** - Simple vs Expert vs Module agents
+- **[Menu Patterns](./docs/agents/agent-menu-patterns.md)** - YAML menu design and handler types
+- **[Agent Compilation](./docs/agents/agent-compilation.md)** - Auto-injection rules and compilation process
+
+### 📋 Workflow Documentation
+
+- **[Workflow Index](./docs/workflows/index.md)** - Core workflow system overview
+- **[Architecture Guide](./docs/workflows/architecture.md)** - Step-file design and JIT loading
+- **[Template System](./docs/workflows/templates/step-template.md)** - Standard step file template
+- **[Intent vs Prescriptive](./docs/workflows/intent-vs-prescriptive-spectrum.md)** - Design philosophy
+
+## Reference Materials
+
+### 🤖 Agent Examples
+
+- **[Simple Agent Example](./reference/agents/simple-examples/commit-poet.agent.yaml)** - Self-contained agent
+- **[Expert Agent Example](./reference/agents/expert-examples/journal-keeper/)** - Agent with persistent memory
+- **[Module Agent Examples](./reference/agents/module-examples/)** - Integration patterns (BMM, CIS)
+
+### 📋 Workflow Examples
+
+- **[Meal Prep & Nutrition](./reference/workflows/meal-prep-nutrition/)** - Complete step-file workflow demonstration
+- **Template patterns** for document generation and state management
 
 ## Core Workflows
 
-### Creation Workflows
+### Creation Workflows (Step-File Architecture)
 
-**[create-agent](./workflows/create-agent/README.md)** - Build BMad agents
+**[create-agent](./workflows/create-agent/)** - Build BMad agents
 
-- Interactive persona development
-- Command structure design
-- YAML source compilation to .md
+- 11 guided steps from brainstorming to celebration
+- 18 reference data files with validation checklists
+- Template-based agent generation
 
-**[create-workflow](./workflows/create-workflow/README.md)** - Design workflows
+**[create-workflow](./workflows/create-workflow/)** - 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
+- 12 structured steps from init to review
+- 9 template files for workflow creation
+- Step-file architecture implementation
 
 ### Editing Workflows
 
-**[edit-agent](./workflows/edit-agent/README.md)** - Modify existing agents
+**[edit-agent](./workflows/edit-agent/)** - Modify existing agents
 
-- Persona refinement
-- Command updates
+- 5 steps: discovery → validation
+- Intent-driven analysis and updates
 - Best practice compliance
 
-**[edit-workflow](./workflows/edit-workflow/README.md)** - Update workflows
+**[edit-workflow](./workflows/edit-workflow/)** - Update workflows
 
-- Structure maintenance
-- Configuration updates
-- Documentation sync
+- 5 steps: analyze → compliance check
+- Structure maintenance and validation
+- Template updates for consistency
 
-**[edit-module](./workflows/edit-module/README.md)** - Module enhancement
+### Quality Assurance
 
-- Component modifications
-- Dependency management
-- Version control
+**[workflow-compliance-check](./workflows/workflow-compliance-check/)** - Validation
 
-### Maintenance Workflows
+- 8 systematic validation steps
+- Adversarial analysis approach
+- Detailed compliance reporting
 
-**[convert-legacy](./workflows/convert-legacy/README.md)** - Migration tool
+### Legacy Migration (Pending)
 
-- v4 to v6 conversion
-- Structure compliance
-- Convention updates
+Workflows in `workflows-legacy/` are being migrated to step-file architecture:
 
-**[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
+- Module-specific workflows
+- Historical implementations
+- Conversion planning in progress
 
 ## Agent Types
 
 BMB creates three agent architectures:
 
-### Full Module Agent
+### Simple Agent
 
-- Complete persona and role definition
-- Command structure with fuzzy matching
-- Workflow integration
-- Module-specific capabilities
+- **Self-contained**: All logic in single YAML file
+- **Stateless**: No persistent memory across sessions
+- **Purpose**: Single utilities and specialized tools
+- **Example**: Commit poet, code formatter
 
-### Hybrid Agent
+### Expert Agent
 
-- Shared core capabilities
-- Module-specific extensions
-- Cross-module compatibility
+- **Persistent Memory**: Maintains knowledge across sessions
+- **Sidecar Resources**: External files and data storage
+- **Domain-specific**: Focuses on particular knowledge areas
+- **Example**: Journal keeper, domain consultant
 
-### Standalone Agent
+### Module Agent
 
-- Independent operation
-- Minimal dependencies
-- Specialized single purpose
+- **Team Integration**: Orchestrates within specific modules
+- **Workflow Coordination**: Manages complex processes
+- **Professional Infrastructure**: Enterprise-grade capabilities
+- **Examples**: BMM project manager, CIS innovation strategist
 
 ## Quick Start
 
-1. **Load BMad Builder agent** in your IDE
+### Using BMad Builder Agent
+
+1. **Load BMad Builder agent** in your IDE:
+   ```
+   /bmad:bmb:agents:bmad-builder
+   ```
 2. **Choose creation type:**
-   ```
-   *create-agent     # New agent
-   *create-workflow  # New workflow
-   *create-module    # Complete module
-   ```
-3. **Follow interactive prompts**
+   - `[CA]` Create Agent - Build new agents
+   - `[CW]` Create Workflow - Design workflows
+   - `[EA]` Edit Agent - Modify existing agents
+   - `[EW]` Edit Workflow - Update workflows
+   - `[VA]` Validate Agent - Quality check agents
+   - `[VW]` Validate Workflow - Quality check workflows
+
+3. **Follow interactive prompts** for step-by-step guidance
 
 ### Example: Creating an Agent
 
 ```
 User: I need a code review agent
-Builder: *create-agent
+Builder: [CA] Create Agent
 
-[Interactive session begins]
-- Brainstorming phase (optional)
-- Persona development
-- Command structure
-- Integration points
+[11-step guided process]
+Step 1: Brainstorm agent concept
+Step 2: Define persona and role
+Step 3: Design command structure
+...
+Step 11: Celebrate and deploy
+```
+
+### Direct Workflow Execution
+
+Workflows can also be run directly without the agent interface:
+
+```yaml
+# Execute specific workflow steps
+workflow: ./workflows/create-agent/workflow.yaml
 ```
 
 ## Use Cases
@@ -165,30 +215,47 @@ Package modules for:
 - Business processes
 - Educational frameworks
 
+## Architecture Principles
+
+### Step-File Workflow Design
+
+- **Micro-file Approach**: Each step is self-contained
+- **Just-In-Time Loading**: Only current step in memory
+- **Sequential Enforcement**: No skipping steps allowed
+- **State Tracking**: Progress documented in frontmatter
+- **Append-Only Building**: Documents grow through execution
+
+### Intent vs Prescriptive Spectrum
+
+- **Creative Workflows**: High user agency, AI as facilitator
+- **Structured Workflows**: Clear process, AI as guide
+- **Prescriptive Workflows**: Strict compliance, AI as validator
+
 ## 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
+1. **Study Reference Materials** - Review docs/ and reference/ examples
+2. **Choose Right Agent Type** - Simple vs Expert vs Module based on needs
+3. **Follow Step-File Patterns** - Use established templates and structures
+4. **Document Thoroughly** - Clear instructions and frontmatter metadata
+5. **Validate Continuously** - Use compliance workflows for quality
+6. **Maintain Consistency** - Follow YAML patterns and naming conventions
 
 ## Integration
 
 BMB components integrate with:
 
-- **BMad Core** - Framework foundation
-- **BMM** - Extend development capabilities
-- **CIS** - Leverage creative workflows
-- **Custom Modules** - Your domain solutions
+- **BMad Core** - Framework foundation and agent compilation
+- **BMM** - Development workflows and project management
+- **CIS** - Creative innovation and strategic workflows
+- **Custom Modules** - Domain-specific solutions
 
-## Related Documentation
+## Getting Help
 
-- **[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
+- **Documentation**: Check `docs/` for comprehensive guides
+- **Reference Materials**: See `reference/` for working examples
+- **Validation**: Use `workflow-compliance-check` for quality assurance
+- **Templates**: Leverage workflow templates for consistent patterns
 
 ---
 
-BMB empowers you to extend BMad Method for your specific needs while maintaining framework consistency and power.
+BMB provides a complete toolkit for extending BMad Method with disciplined, systematic approaches to agent and workflow development while maintaining framework consistency and power.

src/modules/bmb/_module-installer/installer.js

@@ -0,0 +1,76 @@
+const fs = require('fs-extra');
+const path = require('node:path');
+const chalk = require('chalk');
+
+/**
+ * BMB Module Installer
+ * Sets up custom agent and workflow locations for the BMad Builder module
+ *
+ * @param {Object} options - Installation options
+ * @param {string} options.projectRoot - The root directory of the target project
+ * @param {Object} options.config - Module configuration from module.yaml
+ * @param {Object} options.coreConfig - Core configuration containing user_name
+ * @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
+ */
+async function install(options) {
+  const { projectRoot, config, coreConfig, installedIDEs, logger } = options;
+
+  try {
+    logger.log(chalk.blue('🔧 Setting up BMB Module...'));
+
+    // Generate custom.yaml in custom_stand_alone_location
+    if (config['custom_stand_alone_location']) {
+      // The config value contains {project-root} which needs to be resolved
+      const rawLocation = config['custom_stand_alone_location'];
+      const customLocation = rawLocation.replace('{project-root}', projectRoot);
+      const customDestPath = path.join(customLocation, 'custom.yaml');
+
+      logger.log(chalk.cyan(`  Setting up custom agents at: ${customLocation}`));
+
+      // Ensure the directory exists
+      await fs.ensureDir(customLocation);
+
+      // Generate the custom.yaml content
+      const userName = (coreConfig && coreConfig.user_name) || 'my';
+      const customContent = `code: my-custom-bmad
+name: "${userName}-Custom-BMad: Sample Stand Alone Custom Agents and Workflows"
+default_selected: true
+`;
+
+      // Write the custom.yaml file (only if it doesn't exist to preserve user changes)
+      if (await fs.pathExists(customDestPath)) {
+        logger.log(chalk.yellow(`    ✓ custom.yaml already exists at ${customDestPath}`));
+      } else {
+        await fs.writeFile(customDestPath, customContent, 'utf8');
+        logger.log(chalk.green(`    ✓ Created custom.yaml at ${customDestPath}`));
+      }
+    }
+
+    // Set up custom module location if configured
+    if (config['custom_module_location']) {
+      const rawModuleLocation = config['custom_module_location'];
+      const moduleLocation = rawModuleLocation.replace('{project-root}', projectRoot);
+
+      logger.log(chalk.cyan(`  Setting up custom modules at: ${moduleLocation}`));
+
+      // Ensure the directory exists
+      await fs.ensureDir(moduleLocation);
+      logger.log(chalk.green(`    ✓ Created modules directory at ${moduleLocation}`));
+    }
+
+    // Handle IDE-specific configurations if needed
+    if (installedIDEs && installedIDEs.length > 0) {
+      logger.log(chalk.cyan(`  Configuring BMB for IDEs: ${installedIDEs.join(', ')}`));
+    }
+
+    logger.log(chalk.green('✓ BMB Module setup complete'));
+    return true;
+  } catch (error) {
+    logger.error(chalk.red(`Error setting up BMB module: ${error.message}`));
+    return false;
+  }
+}
+
+module.exports = { install };

src/modules/bmb/agents/bmad-builder.agent.yaml

@@ -4,54 +4,91 @@
 agent:
   webskip: true
   metadata:
-    id: "{bmad_folder}/bmb/agents/bmad-builder.md"
+    id: ".bmad/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
+    role: Generalist Builder and BMAD System Maintainer
+    identity: A hands-on builder who gets things done efficiently and maintains the entire BMAD ecosystem
+    communication_style: Direct, action-oriented, and encouraging with a can-do attitude
     principles:
-      - Execute resources directly
+      - Execute resources directly without hesitation
       - Load resources at runtime never pre-load
-      - Always present numbered lists for choices
+      - Always present numbered lists for clear choices
+      - Focus on practical implementation and results
+      - Maintain system-wide coherence and standards
+      - Balance speed with quality and compliance
+
+  discussion: true
+  conversational_knowledge:
+    - agents: "{project-root}/.bmad/bmb/docs/agents/kb.csv"
+    - workflows: "{project-root}/.bmad/bmb/docs/workflows/kb.csv"
+    - modules: "{project-root}/.bmad/bmb/docs/modules/kb.csv"
 
   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
+    - multi: "[CA] Create, [EA] Edit, or [VA] Validate with Compliance CheckBMAD agents with best practices"
+      triggers:
+        - create-agent:
+            - input: CA or fuzzy match create agent
+            - route: "{project-root}/.bmad/bmb/workflows/create-agent/workflow.md"
+            - data: null
+            - type: exec
+        - edit-agent:
+            - input: EA or fuzzy match edit agent
+            - route: "{project-root}/.bmad/bmb/workflows/edit-agent/workflow.md"
+            - data: null
+            - type: exec
+        - run-agent-compliance-check:
+            - input: VA or fuzzy match validate agent
+            - route: "{project-root}/.bmad/bmb/workflows/agent-compliance-check/workflow.md"
+            - data: null
+            - type: exec
 
-    - 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
+    - multi: "[CW] Create, [EW] Edit, or [VW] Validate with Compliance CheckBMAD workflows with best practices"
+      triggers:
+        - create-workflow:
+            - input: CW or fuzzy match create workflow
+            - route: "{project-root}/.bmad/bmb/workflows/create-workflow/workflow.md"
+            - data: null
+            - type: exec
+        - edit-workflow:
+            - input: EW or fuzzy match edit workflow
+            - route: "{project-root}/.bmad/bmb/workflows/edit-workflow/workflow.md"
+            - data: null
+            - type: exec
+        - run-workflow-compliance-check:
+            - input: VW or fuzzy match validate workflow
+            - route: "{project-root}/.bmad/bmb/workflows/workflow-compliance-check/workflow.md"
+            - data: null
+            - type: exec
 
-    - 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
+    - multi: "[BM] Brainstorm, [PBM] Product Brief, [CM] Create, [EM] Edit or [VM] Validate with Compliance Check BMAD modules with best practices"
+      triggers:
+        - brainstorm-module:
+            - input: BM or fuzzy match brainstorm module
+            - route: "{project-root}/.bmad/bmb/workflows/brainstorm-module/workflow.md"
+            - data: null
+            - type: exec
+        - product-brief-module:
+            - input: PBM or fuzzy match product brief module
+            - route: "{project-root}/.bmad/bmb/workflows/product-brief-module/workflow.md"
+            - data: null
+            - type: exec
+        - create-module:
+            - input: CM or fuzzy match create module
+            - route: "{project-root}/.bmad/bmb/workflows/create-module/workflow.md"
+            - data: null
+            - type: exec
+        - edit-module:
+            - input: EM or fuzzy match edit module
+            - route: "{project-root}/.bmad/bmb/workflows/edit-module/workflow.md"
+            - data: null
+            - type: exec
+        - run-module-compliance-check:
+            - input: VM or fuzzy match validate module
+            - route: "{project-root}/.bmad/bmb/workflows/module-compliance-check/workflow.md"
+            - data: null
+            - type: exec

src/modules/bmb/docs/agents/agent-compilation.md

@@ -35,7 +35,7 @@ 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`
+- Metadata ID: `.bmad/{module}/agents/{role-or-function}.md`
 - Persona Name: User-customizable in metadata or customize.yaml
 
 **Example:**
@@ -44,7 +44,7 @@ rex.agent.yaml           ← Persona name (users might rename to "Max")
 # File: presentation-master.agent.yaml
 agent:
   metadata:
-    id: '{bmad_folder}/cis/agents/presentation-master.md'
+    id: '.bmad/cis/agents/presentation-master.md'
     name: Caravaggio # ← Users can change this to "Pablo" or "Vince"
     title: Visual Communication & Presentation Expert
 ```

src/modules/bmb/docs/agents/agent-menu-patterns.md

@@ -65,11 +65,11 @@ For module agents orchestrating multi-step processes.
 ```yaml
 menu:
   - trigger: create-prd
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/prd/workflow.yaml'
+    workflow: '{project-root}/.bmad/bmm/workflows/prd/workflow.yaml'
     description: 'Create Product Requirements Document'
 
   - trigger: brainstorm
-    workflow: '{project-root}/{bmad_folder}/core/workflows/brainstorming/workflow.yaml'
+    workflow: '{project-root}/.bmad/core/workflows/brainstorming/workflow.yaml'
     description: 'Guided brainstorming session'
 
   # Placeholder for unimplemented workflows
@@ -92,11 +92,11 @@ For executing tasks directly.
 ```yaml
 menu:
   - trigger: validate
-    exec: '{project-root}/{bmad_folder}/core/tasks/validate-workflow.xml'
+    exec: '{project-root}/.bmad/core/tasks/validate-workflow.xml'
     description: 'Validate document structure'
 
   - trigger: advanced-elicitation
-    exec: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml'
+    exec: '{project-root}/.bmad/core/tasks/advanced-elicitation.xml'
     description: 'Advanced elicitation techniques'
 ```
 
@@ -113,8 +113,8 @@ 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'
+    exec: '{project-root}/.bmad/core/tasks/create-doc.xml'
+    tmpl: '{project-root}/.bmad/bmm/templates/brief.md'
     description: 'Create a Product Brief'
 ```
 
@@ -131,8 +131,8 @@ 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'
+    exec: '{project-root}/.bmad/bmm/tasks/standup.xml'
+    data: '{project-root}/.bmad/_cfg/agent-manifest.csv'
     description: 'Run team standup'
 
   - trigger: analyze-metrics
@@ -154,12 +154,12 @@ Control visibility based on deployment target:
 ```yaml
 menu:
   - trigger: git-flow
-    exec: '{project-root}/{bmad_folder}/bmm/tasks/git-flow.xml'
+    exec: '{project-root}/.bmad/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'
+    exec: '{project-root}/.bmad/core/tasks/advanced-elicitation.xml'
     description: 'Advanced elicitation'
     web-only: true # Only in web bundles
 ```
@@ -251,20 +251,20 @@ menu:
 menu:
   # Analysis Phase
   - trigger: brainstorm
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
+    workflow: '{project-root}/.bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
     description: 'Brainstorm ideas'
 
   - trigger: research
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/1-analysis/research/workflow.yaml'
+    workflow: '{project-root}/.bmad/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'
+    workflow: '{project-root}/.bmad/bmm/workflows/2-planning/prd/workflow.yaml'
     description: 'Create PRD'
 
   - trigger: architecture
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/architecture/workflow.yaml'
+    workflow: '{project-root}/.bmad/bmm/workflows/2-planning/architecture/workflow.yaml'
     description: 'Design architecture'
 ```
 
@@ -362,8 +362,8 @@ prompts:
 
 ```yaml
 # GOOD - Portable paths
-workflow: "{project-root}/{bmad_folder}/bmm/workflows/prd/workflow.yaml"
-exec: "{project-root}/{bmad_folder}/core/tasks/validate.xml"
+workflow: "{project-root}/.bmad/bmm/workflows/prd/workflow.yaml"
+exec: "{project-root}/.bmad/core/tasks/validate.xml"
 data: "{project-root}/_data/metrics.csv"
 
 # BAD - Hardcoded paths
@@ -374,8 +374,8 @@ exec: "../../../core/tasks/validate.xml"
 ### Available Variables
 
 - `{project-root}` - Project root directory
-- `{bmad_folder}` - BMAD installation folder
-- `{agent-folder}` - Agent installation directory (Expert agents)
+- `.bmad` - BMAD installation folder
+- `{agent_sidecar_folder}` - Agent installation directory (Expert agents)
 - `{output_folder}` - Document output location
 - `{user_name}` - User's name from config
 - `{communication_language}` - Language preference
@@ -415,9 +415,9 @@ menu:
 
 ```yaml
 critical_actions:
-  - 'Load {agent-folder}/memories.md'
-  - 'Follow {agent-folder}/instructions.md'
-  - 'ONLY access {agent-folder}/'
+  - 'Load ./memories.md'
+  - 'Follow ./instructions.md'
+  - 'ONLY access ./'
 
 prompts:
   - id: reflect
@@ -431,7 +431,7 @@ menu:
     description: 'Write journal entry'
 
   - trigger: save
-    action: 'Update {agent-folder}/memories.md with session insights'
+    action: 'Update ./memories.md with session insights'
     description: "Save today's session"
 
   - trigger: patterns
@@ -444,23 +444,23 @@ menu:
 ```yaml
 menu:
   - trigger: workflow-init
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/workflow-status/init/workflow.yaml'
+    workflow: '{project-root}/.bmad/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'
+    workflow: '{project-root}/.bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
     description: 'Guided brainstorming'
 
   - trigger: prd
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/prd/workflow.yaml'
+    workflow: '{project-root}/.bmad/bmm/workflows/2-planning/prd/workflow.yaml'
     description: 'Create PRD'
 
   - trigger: architecture
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/architecture/workflow.yaml'
+    workflow: '{project-root}/.bmad/bmm/workflows/2-planning/architecture/workflow.yaml'
     description: 'Design architecture'
 
   - trigger: party-mode
-    workflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml'
+    workflow: '{project-root}/.bmad/core/workflows/party-mode/workflow.yaml'
     description: 'Multi-agent discussion'
 ```
 

src/modules/bmb/docs/agents/expert-agent-architecture.md

@@ -57,9 +57,9 @@ agent:
       - 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'
+    - 'Load COMPLETE file ./{agent-name}-sidecar/memories.md and remember all past insights'
+    - 'Load COMPLETE file ./{agent-name}-sidecar/instructions.md and follow ALL protocols'
+    - 'ONLY read/write files in ./{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'
@@ -94,7 +94,7 @@ agent:
       description: 'Primary agent function'
 
     - trigger: remember
-      action: 'Update {agent-folder}/{agent-name}-sidecar/memories.md with session insights'
+      action: 'Update ./{agent-name}-sidecar/memories.md with session insights'
       description: 'Save what we discussed today'
 
     - trigger: patterns
@@ -102,7 +102,7 @@ agent:
       description: 'Recall patterns from past interactions'
 
     - trigger: insight
-      action: 'Document breakthrough in {agent-folder}/{agent-name}-sidecar/breakthroughs.md'
+      action: 'Document breakthrough in ./{agent-name}-sidecar/breakthroughs.md'
       description: 'Record a significant insight'
 
   install_config:
@@ -184,9 +184,9 @@ Add domain-specific documentation here.
 
 ```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'
+  - 'Load COMPLETE file ./{sidecar}/memories.md and remember all past insights'
+  - 'Load COMPLETE file ./{sidecar}/instructions.md and follow ALL protocols'
+  - 'ONLY read/write files in ./{sidecar}/ - this is our private space'
 ```
 
 **Key patterns:**
@@ -196,7 +196,7 @@ critical_actions:
 - **Memory integration** - Past context becomes part of current session
 - **Protocol adherence** - Ensures consistent behavior
 
-### {agent-folder} Variable
+### {agent_sidecar_folder} Variable
 
 Special variable resolved during installation:
 
@@ -211,9 +211,9 @@ 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>
+   <step n="4">Load COMPLETE file ./memories.md...</step>
+   <step n="5">Load COMPLETE file ./instructions.md...</step>
+   <step n="6">ONLY read/write files in ./...</step>
    ```
 
 2. **Sidecar files copied during installation**
@@ -223,7 +223,7 @@ Same as simple agents, PLUS:
 
 ## Reference Example
 
-See: `src/modules/bmb/reference/agents/expert-examples/journal-keeper/`
+See: `bmb/reference/agents/expert-examples/journal-keeper/`
 
 Features demonstrated:
 
@@ -260,7 +260,7 @@ The installer:
 ```yaml
 menu:
   - trigger: save
-    action: "Update {agent-folder}/sidecar/memories.md with today's session insights"
+    action: "Update ./sidecar/memories.md with today's session insights"
     description: 'Save session to memory'
 ```
 
@@ -281,7 +281,7 @@ prompts:
 ```yaml
 menu:
   - trigger: insight
-    action: 'Document in {agent-folder}/sidecar/breakthroughs.md with date, context, significance'
+    action: 'Document in ./sidecar/breakthroughs.md with date, context, significance'
     description: 'Record meaningful insight'
 ```
 
@@ -291,7 +291,7 @@ menu:
 
 ```yaml
 critical_actions:
-  - 'ONLY read/write files in {agent-folder}/sidecar/ - NO OTHER FOLDERS'
+  - 'ONLY read/write files in ./sidecar/ - NO OTHER FOLDERS'
 ```
 
 ### User Space Access
@@ -305,15 +305,15 @@ critical_actions:
 
 ```yaml
 critical_actions:
-  - 'Load knowledge from {agent-folder}/knowledge/ but NEVER modify'
-  - 'Write ONLY to {agent-folder}/sessions/'
+  - 'Load knowledge from ./knowledge/ but NEVER modify'
+  - 'Write ONLY to ./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
+3. **Use {agent_sidecar_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
@@ -356,8 +356,8 @@ identity: |
 - [ ] 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
+- [ ] Menu actions reference {agent_sidecar_folder} correctly
+- [ ] File paths use {agent_sidecar_folder} variable
 - [ ] Install config personalizes sidecar references
 - [ ] Agent folder named consistently: `{agent-name}/`
 - [ ] YAML file named: `{agent-name}.agent.yaml`

src/modules/bmb/docs/agents/index.md

@@ -18,7 +18,7 @@ Comprehensive guides for each agent type (choose based on use case):
 
 ## Reference Examples
 
-Production-ready examples in `/src/modules/bmb/reference/agents/`:
+Production-ready examples in `/bmb/reference/agents/`:
 
 **Simple Agents** (`simple-examples/`)
 
@@ -37,7 +37,7 @@ Production-ready examples in `/src/modules/bmb/reference/agents/`:
 
 For installing standalone simple and expert agents, see:
 
-- [Custom Agent Installation](/docs/custom-agent-installation.md)
+- [Custom Agent Installation](/docs/custom-content-installation.md)
 
 ## Key Concepts
 

src/modules/bmb/docs/agents/module-agent-architecture.md

@@ -27,7 +27,7 @@ Compiles to:
 ```yaml
 agent:
   metadata:
-    id: '{bmad_folder}/{module-code}/agents/{agent-name}.md'
+    id: '.bmad/{module-code}/agents/{agent-name}.md'
     name: 'Persona Name'
     title: 'Professional Title'
     icon: 'emoji'
@@ -41,29 +41,29 @@ agent:
 
   menu:
     - trigger: workflow-action
-      workflow: '{project-root}/{bmad_folder}/{module-code}/workflows/{workflow-name}/workflow.yaml'
+      workflow: '{project-root}/.bmad/{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'
+      workflow: '{project-root}/.bmad/core/workflows/{workflow-name}/workflow.yaml'
       description: 'Execute core workflow'
 
     - trigger: task-action
-      exec: '{project-root}/{bmad_folder}/{module-code}/tasks/{task-name}.xml'
+      exec: '{project-root}/.bmad/{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'
+      workflow: '{project-root}/.bmad/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'
+      exec: '{project-root}/.bmad/core/tasks/create-doc.xml'
+      tmpl: '{project-root}/.bmad/{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'
+      exec: '{project-root}/.bmad/{module-code}/tasks/{task-name}.xml'
+      data: '{project-root}/.bmad/_cfg/agent-manifest.csv'
       description: 'Execute task with data file'
 ```
 
@@ -71,7 +71,7 @@ agent:
 
 ### Metadata
 
-- **id**: Path with `{bmad_folder}` variable (resolved at install time)
+- **id**: Path with `.bmad` variable (resolved at install time)
 - **name**: Agent persona name
 - **title**: Professional role
 - **icon**: Single emoji
@@ -101,7 +101,7 @@ persona:
 ```yaml
 menu:
   - trigger: create-prd
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/prd/workflow.yaml'
+    workflow: '{project-root}/.bmad/bmm/workflows/prd/workflow.yaml'
     description: 'Create Product Requirements Document'
 ```
 
@@ -112,7 +112,7 @@ Invokes BMAD workflow engine to execute multi-step processes.
 ```yaml
 menu:
   - trigger: validate
-    exec: '{project-root}/{bmad_folder}/core/tasks/validate-workflow.xml'
+    exec: '{project-root}/.bmad/core/tasks/validate-workflow.xml'
     description: 'Validate document structure'
 ```
 
@@ -123,8 +123,8 @@ Executes single-operation tasks.
 ```yaml
 menu:
   - trigger: create-brief
-    exec: '{project-root}/{bmad_folder}/core/tasks/create-doc.xml'
-    tmpl: '{project-root}/{bmad_folder}/bmm/templates/brief.md'
+    exec: '{project-root}/.bmad/core/tasks/create-doc.xml'
+    tmpl: '{project-root}/.bmad/bmm/templates/brief.md'
     description: 'Create a Product Brief from template'
 ```
 
@@ -135,8 +135,8 @@ Combines task execution with template file.
 ```yaml
 menu:
   - trigger: team-standup
-    exec: '{project-root}/{bmad_folder}/bmm/tasks/standup.xml'
-    data: '{project-root}/{bmad_folder}/_cfg/agent-manifest.csv'
+    exec: '{project-root}/.bmad/bmm/tasks/standup.xml'
+    data: '{project-root}/.bmad/_cfg/agent-manifest.csv'
     description: 'Run team standup with agent roster'
 ```
 
@@ -160,12 +160,12 @@ Control visibility based on platform:
 ```yaml
 menu:
   - trigger: advanced-elicitation
-    exec: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml'
+    exec: '{project-root}/.bmad/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'
+    exec: '{project-root}/.bmad/bmm/tasks/git-flow.xml'
     description: 'Git workflow operations'
     ide-only: true # Only shows in IDE environments
 ```
@@ -175,7 +175,7 @@ menu:
 ### Core Variables
 
 - `{project-root}` - Root directory of installed project
-- `{bmad_folder}` - BMAD installation folder (usually `.bmad`)
+- `.bmad` - BMAD installation folder (usually `.bmad`)
 - `{user_name}` - User's name from module config
 - `{communication_language}` - Language preference
 - `{output_folder}` - Document output directory
@@ -186,7 +186,7 @@ menu:
 
 ```yaml
 # GOOD
-workflow: "{project-root}/{bmad_folder}/bmm/workflows/prd/workflow.yaml"
+workflow: "{project-root}/.bmad/bmm/workflows/prd/workflow.yaml"
 
 # BAD
 workflow: "/Users/john/project/.bmad/bmm/workflows/prd/workflow.yaml"
@@ -203,12 +203,12 @@ Module agents use the same injection process as simple agents:
 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
+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>
+<step n="2">Load and read {project-root}/.bmad/{module}/config.yaml...</step>
 ```
 
 ## Reference Examples
@@ -252,15 +252,15 @@ Agents load this at activation for consistent behavior.
 ```yaml
 menu:
   - trigger: init
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/workflow-init/workflow.yaml'
+    workflow: '{project-root}/.bmad/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'
+    workflow: '{project-root}/.bmad/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'
+    workflow: '{project-root}/.bmad/bmm/workflows/next-step/workflow.yaml'
     description: 'Execute next workflow in sequence'
 ```
 
@@ -270,20 +270,20 @@ menu:
 menu:
   # Phase 1: Analysis
   - trigger: brainstorm
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
+    workflow: '{project-root}/.bmad/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'
+    workflow: '{project-root}/.bmad/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'
+    workflow: '{project-root}/.bmad/bmm/workflows/2-planning/prd/workflow.yaml'
     description: 'Create PRD'
 
   - trigger: architecture
-    workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/architecture/workflow.yaml'
+    workflow: '{project-root}/.bmad/bmm/workflows/2-planning/architecture/workflow.yaml'
     description: 'Design architecture'
 ```
 
@@ -292,24 +292,23 @@ menu:
 ```yaml
 menu:
   - trigger: party-mode
-    workflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml'
+    workflow: '{project-root}/.bmad/core/workflows/party-mode/workflow.yaml'
     description: 'Bring all agents together'
 
   - trigger: brainstorm
-    workflow: '{project-root}/{bmad_folder}/cis/workflows/brainstorming/workflow.yaml'
+    workflow: '{project-root}/.bmad/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
+1. **Organize workflows by phase** - Clear progression for users
+2. **Include workflow-status** - Help users track progress
+3. **Reference module config** - Consistent behavior
+4. **No Handlebars templating** - Module agents are fixed personalities
+5. **Professional personas** - Match module purpose
+6. **Clear trigger names** - Self-documenting commands
+7. **Group related workflows** - Logical menu organization
 
 ## Common Patterns
 
@@ -318,7 +317,7 @@ menu:
 ```yaml
 menu:
   - trigger: start
-    workflow: '{project-root}/{bmad_folder}/{module}/workflows/init/workflow.yaml'
+    workflow: '{project-root}/.bmad/{module}/workflows/init/workflow.yaml'
     description: 'Start new project (BEGIN HERE)'
 ```
 
@@ -327,7 +326,7 @@ menu:
 ```yaml
 menu:
   - trigger: status
-    workflow: '{project-root}/{bmad_folder}/{module}/workflows/status/workflow.yaml'
+    workflow: '{project-root}/.bmad/{module}/workflows/status/workflow.yaml'
     description: 'Check workflow progress'
 ```
 
@@ -336,27 +335,27 @@ menu:
 ```yaml
 menu:
   - trigger: party
-    workflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml'
+    workflow: '{project-root}/.bmad/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              |
+| Aspect        | Module Agent                | Simple/Expert Agent             |
+| ------------- | --------------------------- | ------------------------------- |
+| Location      | `.bmad/{module}/agents/`    | `.bmad/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
+- [ ] id uses `.bmad/{module}/agents/{name}.md`
+- [ ] All workflow paths use `{project-root}/.bmad/` prefix
 - [ ] No hardcoded paths
 - [ ] No duplicate triggers
 - [ ] Each menu item has description

src/modules/bmb/docs/agents/simple-agent-architecture.md

@@ -217,9 +217,13 @@ Features demonstrated:
 # Copy to your project
 cp /path/to/commit-poet.agent.yaml .bmad/custom/agents/
 
-# Install with personalization
-bmad agent-install
-# or: npx bmad-method agent-install
+# Create custom.yaml and install
+echo "code: my-agent
+name: My Agent
+default_selected: true" > custom.yaml
+
+npx bmad-method install
+# or: bmad install
 ```
 
 The installer:

src/modules/bmb/docs/agents/understanding-agent-types.md

@@ -7,7 +7,7 @@ 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.)
+- ✓ Use core variables (.bmad, {output_folder}, etc.)
 - ✓ Have complex prompts and logic
 - ✓ Invoke external tools
 
@@ -98,11 +98,11 @@ agent:
 
   menu:
     - trigger: implement-story
-      workflow: '{bmad_folder}/bmm/workflows/dev-story/workflow.yaml'
+      workflow: '.bmad/bmm/workflows/dev-story/workflow.yaml'
       description: Implement user story
 
     - trigger: refactor
-      workflow: '{bmad_folder}/bmm/workflows/refactor/workflow.yaml'
+      workflow: '.bmad/bmm/workflows/refactor/workflow.yaml'
       description: Refactor codebase
 ```
 

src/modules/bmb/docs/workflows/architecture.md

@@ -0,0 +1,220 @@
+# Standalone Workflow Builder Architecture
+
+This document describes the architecture of the standalone workflow builder system - a pure markdown approach to creating structured workflows.
+
+## Core Architecture Principles
+
+### 1. Micro-File Design
+
+Each workflow consists of multiple focused, self-contained files:
+
+```
+workflow-folder/
+├── workflow.md              # Main workflow configuration
+├── steps/                   # Step instruction files (focused, self-contained)
+│   ├── step-01-init.md
+│   ├── step-02-profile.md
+│   └── step-N-[name].md
+├── templates/               # Content templates
+│   ├── profile-section.md
+│   └── [other-sections].md
+└── data/                    # Optional data files
+    └── [data-files].csv/.json
+```
+
+### 2. Just-In-Time (JIT) Loading
+
+- **Single File in Memory**: Only the current step file is loaded
+- **No Future Peeking**: Step files must not reference future steps
+- **Sequential Processing**: Steps execute in strict order
+- **On-Demand Loading**: Templates load only when needed
+
+### 3. State Management
+
+- **Frontmatter Tracking**: Workflow state stored in output document frontmatter
+- **Progress Array**: `stepsCompleted` tracks completed steps
+- **Last Step Marker**: `lastStep` indicates where to resume
+- **Append-Only Building**: Documents grow by appending content
+
+### 4. Execution Model
+
+```
+1. Load workflow.md → Read configuration
+2. Execute step-01-init.md → Initialize or detect continuation
+3. For each step:
+   a. Load step file completely
+   b. Execute instructions sequentially
+   c. Wait for user input at menu points
+   d. Only proceed with 'C' (Continue)
+   e. Update document/frontmatter
+   f. Load next step
+```
+
+## Key Components
+
+### Workflow File (workflow.md)
+
+- **Purpose**: Entry point and configuration
+- **Content**: Role definition, goal, architecture rules
+- **Action**: Points to step-01-init.md
+
+### Step Files (step-NN-[name].md)
+
+- **Size**: Focused and concise (typically 5-10KB)
+- **Structure**: Frontmatter + sequential instructions
+- **Features**: Self-contained rules, menu handling, state updates
+
+### Frontmatter Variables
+
+Standard variables in step files:
+
+```yaml
+workflow_path: '{project-root}/.bmad/bmb/reference/workflows/[workflow-name]'
+thisStepFile: '{workflow_path}/steps/step-[N]-[name].md'
+nextStepFile: '{workflow_path}/steps/step-[N+1]-[name].md'
+workflowFile: '{workflow_path}/workflow.md'
+outputFile: '{output_folder}/[output-name]-{project_name}.md'
+```
+
+## Execution Flow
+
+### Fresh Workflow
+
+```
+workflow.md
+    ↓
+step-01-init.md (creates document)
+    ↓
+step-02-[name].md
+    ↓
+step-03-[name].md
+    ↓
+...
+    ↓
+step-N-[final].md (completes workflow)
+```
+
+### Continuation Workflow
+
+```
+workflow.md
+    ↓
+step-01-init.md (detects existing document)
+    ↓
+step-01b-continue.md (analyzes state)
+    ↓
+step-[appropriate-next].md
+```
+
+## Menu System
+
+### Standard Menu Pattern
+
+```
+Display: **Select an Option:** [A] [Action] [P] Party Mode [C] Continue
+
+#### Menu Handling Logic:
+- IF A: Execute {advancedElicitationTask}
+- IF P: Execute {partyModeWorkflow}
+- IF C: Save content, update frontmatter, load next step
+```
+
+### Menu Rules
+
+- **Halt Required**: Always wait for user input
+- **Continue Only**: Only proceed with 'C' selection
+- **State Persistence**: Save before loading next step
+- **Loop Back**: Return to menu after other actions
+
+## Collaborative Dialogue Model
+
+### Not Command-Response
+
+- **Facilitator Role**: AI guides, user decides
+- **Equal Partnership**: Both parties contribute
+- **No Assumptions**: Don't assume user wants next step
+- **Explicit Consent**: Always ask for input
+
+### Example Pattern
+
+```
+AI: "Tell me about your dietary preferences."
+User: [provides information]
+AI: "Thank you. Now let's discuss your cooking habits."
+[Continue conversation]
+AI: **Menu Options**
+```
+
+## CSV Intelligence (Optional)
+
+### Data-Driven Behavior
+
+- Configuration in CSV files
+- Dynamic menu options
+- Variable substitution
+- Conditional logic
+
+### Example Structure
+
+```csv
+variable,type,value,description
+cooking_frequency,choice,"daily|weekly|occasionally","How often user cooks"
+meal_type,multi,"breakfast|lunch|dinner|snacks","Types of meals to plan"
+```
+
+## Best Practices
+
+### File Size Limits
+
+- **Step Files**: Keep focused and reasonably sized (5-10KB typical)
+- **Templates**: Keep focused and reusable
+- **Workflow File**: Keep lean, no implementation details
+
+### Sequential Enforcement
+
+- **Numbered Steps**: Use sequential numbering (1, 2, 3...)
+- **No Skipping**: Each step must complete
+- **State Updates**: Mark completion in frontmatter
+
+### Error Prevention
+
+- **Path Variables**: Use frontmatter variables, never hardcode
+- **Complete Loading**: Always read entire file before execution
+- **Menu Halts**: Never proceed without 'C' selection
+
+## Migration from XML
+
+### Advantages
+
+- **No Dependencies**: Pure markdown, no XML parsing
+- **Human Readable**: Files are self-documenting
+- **Git Friendly**: Clean diffs and merges
+- **Flexible**: Easier to modify and extend
+
+### Key Differences
+
+| XML Workflows     | Standalone Workflows    |
+| ----------------- | ----------------------- |
+| Single large file | Multiple micro-files    |
+| Complex structure | Simple sequential steps |
+| Parser required   | Any markdown viewer     |
+| Rigid format      | Flexible organization   |
+
+## Implementation Notes
+
+### Critical Rules
+
+- **NEVER** load multiple step files
+- **ALWAYS** read complete step file first
+- **NEVER** skip steps or optimize
+- **ALWAYS** update frontmatter of the output file when a step is complete
+- **NEVER** proceed without user consent
+
+### Success Metrics
+
+- Documents created correctly
+- All steps completed sequentially
+- User satisfied with collaborative process
+- Clean, maintainable file structure
+
+This architecture ensures disciplined, predictable workflow execution while maintaining flexibility for different use cases.

src/modules/bmb/docs/workflows/common-workflow-tools.csv

@@ -0,0 +1,19 @@
+propose,type,tool_name,description,url,requires_install
+always,workflow,party-mode,"Enables collaborative idea generation by managing turn-taking, summarizing contributions, and synthesizing ideas from multiple AI personas in structured conversation sessions about workflow steps or work in progress.",{project-root}/.bmad/core/workflows/party-mode/workflow.md,no
+always,task,advanced-elicitation,"Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques.",{project-root}/.bmad/core/tasks/advanced-elicitation.xml,no
+always,task,brainstorming,"Facilitates idea generation by prompting users with targeted questions, encouraging divergent thinking, and synthesizing concepts into actionable insights through collaborative creative exploration.",{project-root}/.bmad/core/tasks/brainstorming.xml,no
+always,llm-tool-feature,web-browsing,"Provides LLM with capabilities to perform real-time web searches, extract relevant data, and incorporate current information into responses when up-to-date information is required beyond training knowledge.",,no
+always,llm-tool-feature,file-io,"Enables LLM to manage file operations such as creating, reading, updating, and deleting files, facilitating seamless data handling, storage, and document management within user environments.",,no
+always,llm-tool-feature,sub-agents,"Allows LLM to create and manage specialized sub-agents that handle specific tasks or modules within larger workflows, improving efficiency through parallel processing and modular task delegation.",,no
+always,llm-tool-feature,sub-processes,"Enables LLM to initiate and manage subprocesses that operate independently, allowing for parallel processing of complex tasks and improved resource utilization during long-running operations.",,no
+always,tool-memory,sidecar-file,"Creates a persistent history file that gets written during workflow execution and loaded on future runs, enabling continuity through session-to-session state management. Used for agent or workflow initialization with previous session context, learning from past interactions, and maintaining progress across multiple executions.",,no
+example,tool-memory,vector-database,"Stores and retrieves semantic information through embeddings for intelligent memory access, enabling workflows to find relevant past experiences, patterns, or context based on meaning rather than exact matches. Useful for complex learning systems, pattern recognition, and semantic search across workflow history.",https://github.com/modelcontextprotocol/servers/tree/main/src/rag-agent,yes
+example,mcp,context-7,"A curated knowledge base of API documentation and third-party tool references, enabling LLM to access accurate and current information for integration and development tasks when specific technical documentation is needed.",https://github.com/modelcontextprotocol/servers/tree/main/src/context-7,yes
+example,mcp,playwright,"Provides capabilities for LLM to perform web browser automation including navigation, form submission, data extraction, and testing actions on web pages, facilitating automated web interactions and quality assurance.",https://github.com/modelcontextprotocol/servers/tree/main/src/playwright,yes
+example,workflow,security-auditor,"Analyzes workflows and code for security vulnerabilities, compliance issues, and best practices violations, providing detailed security assessments and remediation recommendations for production-ready systems.",,no
+example,task,code-review,"Performs systematic code analysis with peer review perspectives, identifying bugs, performance issues, style violations, and architectural problems through adversarial review techniques.",,no
+example,mcp,git-integration,"Enables direct Git repository operations including commits, branches, merges, and history analysis, allowing workflows to interact with version control systems for code management and collaboration.",https://github.com/modelcontextprotocol/servers/tree/main/src/git,yes
+example,mcp,database-connector,"Provides direct database connectivity for querying, updating, and managing data across multiple database types, enabling workflows to interact with structured data sources and perform data-driven operations.",https://github.com/modelcontextprotocol/servers/tree/main/src/postgres,yes
+example,task,api-testing,"Automated API endpoint testing with request/response validation, authentication handling, and comprehensive reporting for REST, GraphQL, and other API types through systematic test generation.",,no
+example,workflow,deployment-manager,"Orchestrates application deployment across multiple environments with rollback capabilities, health checks, and automated release pipelines for continuous integration and delivery workflows.",,no
+example,task,data-validator,"Validates data quality, schema compliance, and business rules through comprehensive data profiling with detailed reporting and anomaly detection for data-intensive workflows.",,no

src/modules/bmb/docs/workflows/csv-data-file-standards.md

@@ -0,0 +1,206 @@
+# CSV Data File Standards for BMAD Workflows
+
+## Purpose and Usage
+
+CSV data files in BMAD workflows serve specific purposes for different workflow types:
+
+**For Agents:** Provide structured data that agents need to reference but cannot realistically generate (such as specific configurations, domain-specific data, or structured knowledge bases).
+
+**For Expert Agents:** Supply specialized knowledge bases, reference data, or persistent information that the expert agent needs to access consistently across sessions.
+
+**For Workflows:** Include reference data, configuration parameters, or structured inputs that guide workflow execution and decision-making.
+
+**Key Principle:** CSV files should contain data that is essential, structured, and not easily generated by LLMs during execution.
+
+## Intent-Based Design Principle
+
+**Core Philosophy:** The closer workflows stay to **intent** rather than **prescriptive** instructions, the more creative and adaptive the LLM experience becomes.
+
+**CSV Enables Intent-Based Design:**
+
+- **Instead of:** Hardcoded scripts with exact phrases LLM must say
+- **CSV Provides:** Clear goals and patterns that LLM adapts creatively to context
+- **Result:** Natural, contextual conversations rather than rigid scripts
+
+**Example - Advanced Elicitation:**
+
+- **Prescriptive Alternative:** 50 separate files with exact conversation scripts
+- **Intent-Based Reality:** One CSV row with method goal + pattern → LLM adapts to user
+- **Benefit:** Same method works differently for different users while maintaining essence
+
+**Intent vs Prescriptive Spectrum:**
+
+- **Highly Prescriptive:** "Say exactly: 'Based on my analysis, I recommend...'"
+- **Balanced Intent:** "Help the user understand the implications using your professional judgment"
+- **CSV Goal:** Provide just enough guidance to enable creative, context-aware execution
+
+## Primary Use Cases
+
+### 1. Knowledge Base Indexing (Document Lookup Optimization)
+
+**Problem:** Large knowledge bases with hundreds of documents cause context blowup and missed details when LLMs try to process them all.
+
+**CSV Solution:** Create a knowledge base index with:
+
+- **Column 1:** Keywords and topics
+- **Column 2:** Document file path/location
+- **Column 3:** Section or line number where relevant content starts
+- **Column 4:** Content type or summary (optional)
+
+**Result:** Transform from context-blowing document loads to surgical precision lookups, creating agents with near-infinite knowledge bases while maintaining optimal context usage.
+
+### 2. Workflow Sequence Optimization
+
+**Problem:** Complex workflows (e.g., game development) with hundreds of potential steps for different scenarios become unwieldy and context-heavy.
+
+**CSV Solution:** Create a workflow routing table:
+
+- **Column 1:** Scenario type (e.g., "2D Platformer", "RPG", "Puzzle Game")
+- **Column 2:** Required step sequence (e.g., "step-01,step-03,step-07,step-12")
+- **Column 3:** Document sections to include
+- **Column 4:** Specialized parameters or configurations
+
+**Result:** Step 1 determines user needs, finds closest match in CSV, confirms with user, then follows optimized sequence - truly optimal for context usage.
+
+### 3. Method Registry (Dynamic Technique Selection)
+
+**Problem:** Tasks need to select optimal techniques from dozens of options based on context, without hardcoding selection logic.
+
+**CSV Solution:** Create a method registry with:
+
+- **Column 1:** Category (collaboration, advanced, technical, creative, etc.)
+- **Column 2:** Method name and rich description
+- **Column 3:** Execution pattern or flow guide (e.g., "analysis → insights → action")
+- **Column 4:** Complexity level or use case indicators
+
+**Example:** Advanced Elicitation task analyzes content context, selects 5 best-matched methods from 50 options, then executes dynamically using CSV descriptions.
+
+**Result:** Smart, context-aware technique selection without hardcoded logic - infinitely extensible method libraries.
+
+### 4. Configuration Management
+
+**Problem:** Complex systems with many configuration options that vary by use case.
+
+**CSV Solution:** Configuration lookup tables mapping scenarios to specific parameter sets.
+
+## What NOT to Include in CSV Files
+
+**Avoid Web-Searchable Data:** Do not include information that LLMs can readily access through web search or that exists in their training data, such as:
+
+- Common programming syntax or standard library functions
+- General knowledge about widely used technologies
+- Historical facts or commonly available information
+- Basic terminology or standard definitions
+
+**Include Specialized Data:** Focus on data that is:
+
+- Specific to your project or domain
+- Not readily available through web search
+- Essential for consistent workflow execution
+- Too voluminous for LLM context windows
+
+## CSV Data File Standards
+
+### 1. Purpose Validation
+
+- **Essential Data Only:** CSV must contain data that cannot be reasonably generated by LLMs
+- **Domain Specific:** Data should be specific to the workflow's domain or purpose
+- **Consistent Usage:** All columns and data must be referenced and used somewhere in the workflow
+- **No Redundancy:** Avoid data that duplicates functionality already available to LLMs
+
+### 2. Structural Standards
+
+- **Valid CSV Format:** Proper comma-separated values with quoted fields where needed
+- **Consistent Columns:** All rows must have the same number of columns
+- **No Missing Data:** Empty values should be explicitly marked (e.g., "", "N/A", or NULL)
+- **Header Row:** First row must contain clear, descriptive column headers
+- **Proper Encoding:** UTF-8 encoding required for special characters
+
+### 3. Content Standards
+
+- **No LLM-Generated Content:** Avoid data that LLMs can easily generate (e.g., generic phrases, common knowledge)
+- **Specific and Concrete:** Use specific values rather than vague descriptions
+- **Verifiable Data:** Data should be factual and verifiable when possible
+- **Consistent Formatting:** Date formats, numbers, and text should follow consistent patterns
+
+### 4. Column Standards
+
+- **Clear Headers:** Column names must be descriptive and self-explanatory
+- **Consistent Data Types:** Each column should contain consistent data types
+- **No Unused Columns:** Every column must be referenced and used in the workflow
+- **Appropriate Width:** Columns should be reasonably narrow and focused
+
+### 5. File Size Standards
+
+- **Efficient Structure:** CSV files should be as small as possible while maintaining functionality
+- **No Redundant Rows:** Avoid duplicate or nearly identical rows
+- **Compressed Data:** Use efficient data representation (e.g., codes instead of full descriptions)
+- **Maximum Size:** Individual CSV files should not exceed 1MB unless absolutely necessary
+
+### 6. Documentation Standards
+
+- **Documentation Required:** Each CSV file should have documentation explaining its purpose
+- **Column Descriptions:** Each column must be documented with its usage and format
+- **Data Sources:** Source of data should be documented when applicable
+- **Update Procedures:** Process for updating CSV data should be documented
+
+### 7. Integration Standards
+
+- **File References:** CSV files must be properly referenced in workflow configuration
+- **Access Patterns:** Workflow must clearly define how and when CSV data is accessed
+- **Error Handling:** Workflow must handle cases where CSV files are missing or corrupted
+- **Version Control:** CSV files should be versioned when changes occur
+
+### 8. Quality Assurance
+
+- **Data Validation:** CSV data should be validated for correctness and completeness
+- **Format Consistency:** Consistent formatting across all rows and columns
+- **No Ambiguity:** Data entries should be clear and unambiguous
+- **Regular Review:** CSV content should be reviewed periodically for relevance
+
+### 9. Security Considerations
+
+- **No Sensitive Data:** Avoid including sensitive, personal, or confidential information
+- **Data Sanitization:** CSV data should be sanitized for security issues
+- **Access Control:** Access to CSV files should be controlled when necessary
+- **Audit Trail:** Changes to CSV files should be logged when appropriate
+
+### 10. Performance Standards
+
+- **Fast Loading:** CSV files must load quickly within workflow execution
+- **Memory Efficient:** Structure should minimize memory usage during processing
+- **Optimized Queries:** If data lookup is needed, optimize for efficient access
+- **Caching Strategy**: Consider whether data can be cached for performance
+
+## Implementation Guidelines
+
+When creating CSV data files for BMAD workflows:
+
+1. **Start with Purpose:** Clearly define why CSV is needed instead of LLM generation
+2. **Design Structure:** Plan columns and data types before creating the file
+3. **Test Integration:** Ensure workflow properly accesses and uses CSV data
+4. **Document Thoroughly:** Provide complete documentation for future maintenance
+5. **Validate Quality:** Check data quality, format consistency, and integration
+6. **Monitor Usage:** Track how CSV data is used and optimize as needed
+
+## Common Anti-Patterns to Avoid
+
+- **Generic Phrases:** CSV files containing common phrases or LLM-generated content
+- **Redundant Data:** Duplicating information easily available to LLMs
+- **Overly Complex:** Unnecessarily complex CSV structures when simple data suffices
+- **Unused Columns:** Columns that are defined but never referenced in workflows
+- **Poor Formatting:** Inconsistent data formats, missing values, or structural issues
+- **No Documentation:** CSV files without clear purpose or usage documentation
+
+## Validation Checklist
+
+For each CSV file, verify:
+
+- [ ] Purpose is essential and cannot be replaced by LLM generation
+- [ ] All columns are used in the workflow
+- [ ] Data is properly formatted and consistent
+- [ ] File is efficiently sized and structured
+- [ ] Documentation is complete and clear
+- [ ] Integration with workflow is tested and working
+- [ ] Security considerations are addressed
+- [ ] Performance requirements are met

src/modules/bmb/docs/workflows/index.md

@@ -0,0 +1,45 @@
+# BMAD Workflows Documentation
+
+Welcome to the BMAD Workflows documentation - a modern system for creating structured, collaborative workflows optimized for AI execution.
+
+## 📚 Core Documentation
+
+### [Terms](./terms.md)
+
+Essential terminology and concepts for understanding BMAD workflows.
+
+### [Architecture & Execution Model](./architecture.md)
+
+The micro-file architecture, JIT step loading, state management, and collaboration patterns that make BMAD workflows optimal for AI execution.
+
+### [Writing Workflows](./writing-workflows.md)
+
+Complete guide to creating workflows: workflow.md control files, step files, CSV data integration, and frontmatter design.
+
+### [Step Files & Dialog Patterns](./step-files.md)
+
+Crafting effective step files: structure, execution rules, prescriptive vs intent-based dialog, and validation patterns.
+
+### [Templates & Content Generation](./templates.md)
+
+Creating append-only templates, frontmatter design, conditional content, and dynamic content generation strategies.
+
+### [Workflow Patterns](./patterns.md)
+
+Common workflow types: linear, conditional, protocol integration, multi-agent workflows, and real-world examples.
+
+### [Migration Guide](./migration.md)
+
+Converting from XML-heavy workflows to the new pure markdown format, with before/after examples and checklist.
+
+### [Best Practices & Reference](./best-practices.md)
+
+Critical rules, anti-patterns, performance optimization, debugging, quick reference templates, and troubleshooting.
+
+## 🚀 Quick Start
+
+BMAD workflows are pure markdown, self-contained systems that guide collaborative processes through structured step files where the AI acts as a facilitator working with humans.
+
+---
+
+_This documentation covers the next generation of BMAD workflows - designed from the ground up for optimal AI-human collaboration._

src/modules/bmb/docs/workflows/intent-vs-prescriptive-spectrum.md

@@ -0,0 +1,220 @@
+# Intent vs Prescriptive Spectrum
+
+## Core Philosophy
+
+The **Intent vs Prescriptive Spectrum** is a fundamental design principle for BMAD workflows and agents. It determines how much creative freedom an LLM has versus how strictly it must follow predefined instructions.
+
+**Key Principle:** The closer workflows stay to **intent**, the more creative and adaptive the LLM experience becomes. The closer they stay to **prescriptive**, the more consistent and controlled the output becomes.
+
+## Understanding the Spectrum
+
+### **Intent-Based Design** (Creative Freedom)
+
+**Focus**: What goal should be achieved
+**Approach**: Trust the LLM to determine the best method
+**Result**: Creative, adaptive, context-aware interactions
+**Best For**: Creative exploration, problem-solving, personalized experiences
+
+### **Prescriptive Design** (Structured Control)
+
+**Focus**: Exactly what to say and do
+**Approach**: Detailed scripts and specific instructions
+**Result**: Consistent, predictable, controlled outcomes
+**Best For**: Compliance, safety-critical, standardized processes
+
+## Spectrum Examples
+
+### **Highly Intent-Based** (Creative End)
+
+```markdown
+**Example:** Story Exploration Workflow
+**Instruction:** "Help the user explore their dream imagery to craft compelling narratives, use multiple turns of conversation to really push users to develop their ideas, giving them hints and ideas also to prime them effectively to bring out their creativity"
+**LLM Freedom:** Adapts questions, explores tangents, follows creative inspiration
+**Outcome:** Unique, personalized storytelling experiences
+```
+
+### **Balanced Middle** (Professional Services)
+
+```markdown
+**Example:** Business Strategy Workflow
+**Instruction:** "Guide the user through SWOT analysis using your business expertise. when complete tell them 'here is your final report {report output}'
+**LLM Freedom:** Professional judgment in analysis, structured but adaptive approach
+**Outcome:** Professional, consistent yet tailored business insights
+```
+
+### **Highly Prescriptive** (Control End)
+
+```markdown
+**Example:** Medical Intake Form
+**Instruction:** "Ask exactly: 'Do you currently experience any of the following symptoms: fever, cough, fatigue?' Wait for response, then ask exactly: 'When did these symptoms begin?'"
+**LLM Freedom:** Minimal - must follow exact script for medical compliance
+**Outcome:** Consistent, medically compliant patient data collection
+```
+
+## Spectrum Positioning Guide
+
+### **Choose Intent-Based When:**
+
+- ✅ Creative exploration and innovation are goals
+- ✅ Personalization and adaptation to user context are important
+- ✅ Human-like conversation and natural interaction are desired
+- ✅ Problem-solving requires flexible thinking
+- ✅ User experience and engagement are priorities
+
+**Examples:**
+
+- Creative brainstorming sessions
+- Personal coaching or mentoring
+- Exploratory research and discovery
+- Artistic content creation
+- Collaborative problem-solving
+
+### **Choose Prescriptive When:**
+
+- ✅ Compliance with regulations or standards is required
+- ✅ Safety or legal considerations are paramount
+- ✅ Exact consistency across multiple sessions is essential
+- ✅ Training new users on specific procedures
+- ✅ Data collection must follow specific protocols
+
+**Examples:**
+
+- Medical intake and symptom assessment
+- Legal compliance questionnaires
+- Safety checklists and procedures
+- Standardized testing protocols
+- Regulatory data collection
+
+### **Choose Balanced When:**
+
+- ✅ Professional expertise is required but adaptation is beneficial
+- ✅ Consistent quality with flexible application is needed
+- ✅ Domain expertise should guide but not constrain interactions
+- ✅ User trust and professional credibility are important
+- ✅ Complex processes require both structure and judgment
+
+**Examples:**
+
+- Business consulting and advisory
+- Technical support and troubleshooting
+- Educational tutoring and instruction
+- Financial planning and advice
+- Project management facilitation
+
+## Implementation Guidelines
+
+### **For Workflow Designers:**
+
+1. **Early Spectrum Decision**: Determine spectrum position during initial design
+2. **User Education**: Explain spectrum choice and its implications to users
+3. **Consistent Application**: Maintain chosen spectrum throughout workflow
+4. **Context Awareness**: Adjust spectrum based on specific use case requirements
+
+### **For Workflow Implementation:**
+
+**Intent-Based Patterns:**
+
+```markdown
+- "Help the user understand..." (vs "Explain that...")
+- "Guide the user through..." (vs "Follow these steps...")
+- "Use your professional judgment to..." (vs "Apply this specific method...")
+- "Adapt your approach based on..." (vs "Regardless of situation, always...")
+```
+
+**Prescriptive Patterns:**
+
+```markdown
+- "Say exactly: '...'" (vs "Communicate that...")
+- "Follow this script precisely: ..." (vs "Cover these points...")
+- "Do not deviate from: ..." (vs "Consider these options...")
+- "Must ask in this order: ..." (vs "Ensure you cover...")
+```
+
+### **For Agents:**
+
+**Intent-Based Agent Design:**
+
+```yaml
+persona:
+  communication_style: 'Adaptive professional who adjusts approach based on user context'
+  guiding_principles:
+    - 'Use creative problem-solving within professional boundaries'
+    - 'Personalize approach while maintaining expertise'
+    - 'Adapt conversation flow to user needs'
+```
+
+**Prescriptive Agent Design:**
+
+```yaml
+persona:
+  communication_style: 'Follows standardized protocols exactly'
+  governing_rules:
+    - 'Must use approved scripts without deviation'
+    - 'Follow sequence precisely as defined'
+    - 'No adaptation of prescribed procedures'
+```
+
+## Spectrum Calibration Questions
+
+**Ask these during workflow design:**
+
+1. **Consequence of Variation**: What happens if the LLM says something different?
+2. **User Expectation**: Does the user expect consistency or creativity?
+3. **Risk Level**: What are the risks of creative deviation vs. rigid adherence?
+4. **Expertise Required**: Is domain expertise application more important than consistency?
+5. **Regulatory Requirements**: Are there external compliance requirements?
+
+## Best Practices
+
+### **DO:**
+
+- ✅ Make conscious spectrum decisions during design
+- ✅ Explain spectrum choices to users
+- ✅ Use intent-based design for creative and adaptive experiences
+- ✅ Use prescriptive design for compliance and consistency requirements
+- ✅ Consider balanced approaches for professional services
+- ✅ Document spectrum rationale for future reference
+
+### **DON'T:**
+
+- ❌ Mix spectrum approaches inconsistently within workflows
+- ❌ Default to prescriptive when intent-based would be more effective
+- ❌ Use creative freedom when compliance is required
+- ❌ Forget to consider user expectations and experience
+- ❌ Overlook risk assessment in spectrum selection
+
+## Quality Assurance
+
+**When validating workflows:**
+
+- Check if spectrum position is intentional and consistent
+- Verify prescriptive elements are necessary and justified
+- Ensure intent-based elements have sufficient guidance
+- Confirm spectrum alignment with user needs and expectations
+- Validate that risks are appropriately managed
+
+## Examples in Practice
+
+### **Medical Intake (Highly Prescriptive):**
+
+- **Why**: Patient safety, regulatory compliance, consistent data collection
+- **Implementation**: Exact questions, specific order, no deviation permitted
+- **Benefit**: Reliable, medically compliant patient information
+
+### **Creative Writing Workshop (Highly Intent):**
+
+- **Why**: Creative exploration, personalized inspiration, artistic expression
+- **Implementation**: Goal guidance, creative freedom, adaptive prompts
+- **Benefit**: Unique, personalized creative works
+
+### **Business Strategy (Balanced):**
+
+- **Why**: Professional expertise with adaptive application
+- **Implementation**: Structured framework with professional judgment
+- **Benefit**: Professional, consistent yet tailored business insights
+
+## Conclusion
+
+The Intent vs Prescriptive Spectrum is not about good vs. bad - it's about **appropriate design choices**. The best workflows make conscious decisions about where they fall on this spectrum based on their specific requirements, user needs, and risk considerations.
+
+**Key Success Factor**: Choose your spectrum position intentionally, implement it consistently, and align it with your specific use case requirements.

src/modules/bmb/docs/workflows/templates/step-01-init-continuable-template.md

@@ -0,0 +1,241 @@
+# BMAD Continuable Step 01 Init Template
+
+This template provides the standard structure for step-01-init files that support workflow continuation. It includes logic to detect existing workflows and route to step-01b-continue.md for resumption.
+
+Use this template when creating workflows that generate output documents and might take multiple sessions to complete.
+
+<!-- TEMPLATE START -->
+
+---
+
+name: 'step-01-init'
+description: 'Initialize the [workflow-type] workflow by detecting continuation state and creating output document'
+
+<!-- Path Definitions -->
+
+workflow\*path: '{project-root}/.bmad/[module-path]/workflows/[workflow-name]'
+
+# File References (all use {variable} format in file)
+
+thisStepFile: '{workflow_path}/steps/step-01-init.md'
+nextStepFile: '{workflow_path}/steps/step-02-[step-name].md'
+workflowFile: '{workflow_path}/workflow.md'
+outputFile: '{output_folder}/[output-file-name]-{project_name}.md'
+continueFile: '{workflow_path}/steps/step-01b-continue.md'
+templateFile: '{workflow_path}/templates/[main-template].md'
+
+# Template References
+
+# This step doesn't use content templates, only the main template
+
+---
+
+# Step 1: Workflow Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are a [specific role, e.g., "business analyst" or "technical architect"]
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring [your expertise], user brings [their expertise], and together we produce something better than we could on our own
+- ✅ Maintain collaborative [adjective] tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on initialization and setup
+- 🚫 FORBIDDEN to look ahead to future steps
+- 💬 Handle initialization professionally
+- 🚪 DETECT existing workflow state and handle continuation properly
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show analysis before taking any action
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+- Input document discovery happens in this step
+
+## STEP GOAL:
+
+To initialize the [workflow-type] workflow by detecting continuation state, creating the output document, and preparing for the first collaborative session.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Workflow
+
+First, check if the output document already exists:
+
+- Look for file at `{output_folder}/[output-file-name]-{project_name}.md`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted`:
+
+- **STOP here** and load `./step-01b-continue.md` immediately
+- Do not proceed with any initialization tasks
+- Let step-01b handle the continuation logic
+
+### 3. Handle Completed Workflow
+
+If the document exists AND all steps are marked complete in `stepsCompleted`:
+
+- Ask user: "I found an existing [workflow-output] from [date]. Would you like to:
+  1. Create a new [workflow-output]
+  2. Update/modify the existing [workflow-output]"
+- If option 1: Create new document with timestamp suffix
+- If option 2: Load step-01b-continue.md
+
+### 4. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+This workflow requires [describe input documents if any]:
+
+**[Document Type] Documents (Optional):**
+
+- Look for: `{output_folder}/*[pattern1]*.md`
+- Look for: `{output_folder}/*[pattern2]*.md`
+- If found, load completely and add to `inputDocuments` frontmatter
+
+#### B. Create Initial Document
+
+Copy the template from `{templateFile}` to `{output_folder}/[output-file-name]-{project_name}.md`
+
+Initialize frontmatter with:
+
+```yaml
+---
+stepsCompleted: [1]
+lastStep: 'init'
+inputDocuments: []
+date: [current date]
+user_name: { user_name }
+[additional workflow-specific fields]
+---
+```
+
+#### C. Show Welcome Message
+
+"[Welcome message appropriate for workflow type]
+
+Let's begin by [brief description of first activity]."
+
+## ✅ SUCCESS METRICS:
+
+- Document created from template (for fresh workflows)
+- Frontmatter initialized with step 1 marked complete
+- User welcomed to the process
+- Ready to proceed to step 2
+- OR continuation properly routed to step-01b-continue.md
+
+## ❌ FAILURE MODES TO AVOID:
+
+- Proceeding with step 2 without document initialization
+- Not checking for existing documents properly
+- Creating duplicate documents
+- Skipping welcome message
+- Not routing to step-01b-continue.md when needed
+
+### 5. Present MENU OPTIONS
+
+Display: **Proceeding to [next step description]...**
+
+#### EXECUTION RULES:
+
+- This is an initialization step with no user choices
+- Proceed directly to next step after setup
+- Use menu handling logic section below
+
+#### Menu Handling Logic:
+
+- After setup completion, immediately load, read entire file, then execute `{nextStepFile}` to begin [next step description]
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Document created from template (for fresh workflows)
+- update frontmatter `stepsCompleted` to add 1 at the end of the array before loading next step
+- Frontmatter initialized with `stepsCompleted: [1]`
+- User welcomed to the process
+- Ready to proceed to step 2
+- OR existing workflow properly routed to step-01b-continue.md
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with step 2 without document initialization
+- Not checking for existing documents properly
+- Creating duplicate documents
+- Skipping welcome message
+- Not routing to step-01b-continue.md when appropriate
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN initialization setup is complete and document is created (OR continuation is properly routed), will you then immediately load, read entire file, then execute `{nextStepFile}` to begin [next step description].
+
+<!-- TEMPLATE END -->
+
+## Customization Guidelines
+
+When adapting this template for your specific workflow:
+
+### 1. Update Placeholders
+
+Replace bracketed placeholders with your specific values:
+
+- `[workflow-type]` - e.g., "nutrition planning", "project requirements"
+- `[module-path]` - e.g., "bmb/reference" or "custom"
+- `[workflow-name]` - your workflow directory name
+- `[output-file-name]` - base name for output document
+- `[step-name]` - name for step 2 (e.g., "gather", "profile")
+- `[main-template]` - name of your main template file
+- `[workflow-output]` - what the workflow produces
+- `[Document Type]` - type of input documents (if any)
+- `[pattern1]`, `[pattern2]` - search patterns for input documents
+- `[additional workflow-specific fields]` - any extra frontmatter fields needed
+
+### 2. Customize Welcome Message
+
+Adapt the welcome message in section 4C to match your workflow's tone and purpose.
+
+### 3. Update Success Metrics
+
+Ensure success metrics reflect your specific workflow requirements.
+
+### 4. Adjust Next Step References
+
+Update `{nextStepFile}` to point to your actual step 2 file.
+
+## Implementation Notes
+
+1. **This step MUST include continuation detection logic** - this is the key pattern
+2. **Always include `continueFile` reference** in frontmatter
+3. **Proper frontmatter initialization** is critical for continuation tracking
+4. **Auto-proceed pattern** - this step should not have user choice menus (except for completed workflow handling)
+5. **Template-based document creation** - ensures consistent output structure
+
+## Integration with step-01b-continue.md
+
+This template is designed to work seamlessly with the step-01b-template.md continuation step. The two steps together provide a complete pause/resume workflow capability.

src/modules/bmb/docs/workflows/templates/step-1b-template.md

@@ -0,0 +1,223 @@
+# BMAD Workflow Step 1B Continuation Template
+
+This template provides the standard structure for workflow continuation steps. It handles resuming workflows that were started but not completed, ensuring seamless continuation across multiple sessions.
+
+Use this template alongside **step-01-init-continuable-template.md** to create workflows that can be paused and resumed. The init template handles the detection and routing logic, while this template handles the resumption logic.
+
+<!-- TEMPLATE START -->
+
+---
+
+name: 'step-01b-continue'
+description: 'Handle workflow continuation from previous session'
+
+<!-- Path Definitions -->
+
+workflow\*path: '{project-root}/.bmad/[module-path]/workflows/[workflow-name]'
+
+# File References (all use {variable} format in file)
+
+thisStepFile: '{workflow_path}/steps/step-01b-continue.md'
+outputFile: '{output_folder}/[output-file-name]-{project_name}.md'
+workflowFile: '{workflow_path}/workflow.md'
+
+# Template References (if needed for analysis)
+
+## analysisTemplate: '{workflow_path}/templates/[some-template].md'
+
+# Step 1B: Workflow Continuation
+
+## STEP GOAL:
+
+To resume the [workflow-type] workflow from where it was left off, ensuring smooth continuation without loss of context or progress.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are a [specific role, e.g., "business analyst" or "technical architect"]
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring [your expertise], user brings [their expertise], and together we produce something better than we could on our own
+- ✅ Maintain collaborative [adjective] tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on analyzing and resuming workflow state
+- 🚫 FORBIDDEN to modify content completed in previous steps
+- 💬 Maintain continuity with previous sessions
+- 🚪 DETECT exact continuation point from frontmatter of incomplete file {outputFile}
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis of current state before taking action
+- 💾 Keep existing frontmatter `stepsCompleted` values intact
+- 📖 Review the template content already generated in {outputFile}
+- 🚫 FORBIDDEN to modify content that was completed in previous steps
+- 📝 Update frontmatter with continuation timestamp when resuming
+
+## CONTEXT BOUNDARIES:
+
+- Current [output-file-name] document is already loaded
+- Previous context = complete template + existing frontmatter
+- [Key data collected] already gathered in previous sessions
+- Last completed step = last value in `stepsCompleted` array from frontmatter
+
+## CONTINUATION SEQUENCE:
+
+### 1. Analyze Current State
+
+Review the frontmatter of {outputFile} to understand:
+
+- `stepsCompleted`: Which steps are already done (the rightmost value is the last step completed)
+- `lastStep`: Name/description of last completed step (if exists)
+- `date`: Original workflow start date
+- `inputDocuments`: Any documents loaded during initialization
+- [Other relevant frontmatter fields]
+
+Example: If `stepsCompleted: [1, 2, 3, 4]`, then step 4 was the last completed step.
+
+### 2. Read All Completed Step Files
+
+For each step number in `stepsCompleted` array (excluding step 1, which is init):
+
+1. **Construct step filename**: `step-[N]-[name].md`
+2. **Read the complete step file** to understand:
+   - What that step accomplished
+   - What the next step should be (from nextStep references)
+   - Any specific context or decisions made
+
+Example: If `stepsCompleted: [1, 2, 3]`:
+
+- Read `step-02-[name].md`
+- Read `step-03-[name].md`
+- The last file will tell you what step-04 should be
+
+### 3. Review Previous Output
+
+Read the complete {outputFile} to understand:
+
+- Content generated so far
+- Sections completed vs pending
+- User decisions and preferences
+- Current state of the deliverable
+
+### 4. Determine Next Step
+
+Based on the last completed step file:
+
+1. **Find the nextStep reference** in the last completed step file
+2. **Validate the file exists** at the referenced path
+3. **Confirm the workflow is incomplete** (not all steps finished)
+
+### 5. Welcome Back Dialog
+
+Present a warm, context-aware welcome:
+
+"Welcome back! I see we've completed [X] steps of your [workflow-type].
+
+We last worked on [brief description of last step].
+
+Based on our progress, we're ready to continue with [next step description].
+
+Are you ready to continue where we left off?"
+
+### 6. Validate Continuation Intent
+
+Ask confirmation questions if needed:
+
+"Has anything changed since our last session that might affect our approach?"
+"Are you still aligned with the goals and decisions we made earlier?"
+"Would you like to review what we've accomplished so far?"
+
+### 7. Present MENU OPTIONS
+
+Display: "**Resuming workflow - Select an Option:** [C] Continue to [Next Step Name]"
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can chat or ask questions - always respond and then end with display again of the menu options
+- Update frontmatter with continuation timestamp when 'C' is selected
+
+#### Menu Handling Logic:
+
+- IF C:
+  1. Update frontmatter: add `lastContinued: [current date]`
+  2. Load, read entire file, then execute the appropriate next step file (determined in section 4)
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and continuation analysis is complete, will you then:
+
+1. Update frontmatter in {outputFile} with continuation timestamp
+2. Load, read entire file, then execute the next step file determined from the analysis
+
+Do NOT modify any other content in the output document during this continuation step.
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Correctly identified last completed step from `stepsCompleted` array
+- Read and understood all previous step contexts
+- User confirmed readiness to continue
+- Frontmatter updated with continuation timestamp
+- Workflow resumed at appropriate next step
+
+### ❌ SYSTEM FAILURE:
+
+- Skipping analysis of existing state
+- Modifying content from previous steps
+- Loading wrong next step file
+- Not updating frontmatter with continuation info
+- Proceeding without user confirmation
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+<!-- TEMPLATE END -->
+
+## Customization Guidelines
+
+When adapting this template for your specific workflow:
+
+### 1. Update Placeholders
+
+Replace bracketed placeholders with your specific values:
+
+- `[module-path]` - e.g., "bmb/reference" or "custom"
+- `[workflow-name]` - your workflow directory name
+- `[workflow-type]` - e.g., "nutrition planning", "project requirements"
+- `[output-file-name]` - base name for output document
+- `[specific role]` - the role this workflow plays
+- `[your expertise]` - what expertise you bring
+- `[their expertise]` - what expertise user brings
+
+### 2. Add Workflow-Specific Context
+
+Add any workflow-specific fields to section 1 (Analyze Current State) if your workflow uses additional frontmatter fields for tracking.
+
+### 3. Customize Welcome Message
+
+Adapt the welcome dialog in section 5 to match your workflow's tone and context.
+
+### 4. Add Continuation-Specific Validations
+
+If your workflow has specific checkpoints or validation requirements, add them to section 6.
+
+## Implementation Notes
+
+1. **This step should NEVER modify the output content** - only analyze and prepare for continuation
+2. **Always preserve the `stepsCompleted` array** - don't modify it in this step
+3. **Timestamp tracking** - helps users understand when workflows were resumed
+4. **Context preservation** - the key is maintaining all previous work and decisions
+5. **Seamless experience** - user should feel like they never left the workflow

src/modules/bmb/docs/workflows/templates/step-file.md

@@ -0,0 +1,139 @@
+---
+name: "step-{{stepNumber}}-{{stepName}}"
+description: "{{stepDescription}}"
+
+# Path Definitions
+workflow_path: "{project-root}/.bmad/{{targetModule}}/workflows/{{workflowName}}"
+
+# File References
+thisStepFile: "{workflow_path}/steps/step-{{stepNumber}}-{{stepName}}.md"
+{{#hasNextStep}}
+nextStepFile: "{workflow_path}/steps/step-{{nextStepNumber}}-{{nextStepName}}.md"
+{{/hasNextStep}}
+workflowFile: "{workflow_path}/workflow.md"
+{{#hasOutput}}
+outputFile: "{output_folder}/{{outputFileName}}-{project_name}.md"
+{{/hasOutput}}
+
+# Task References (list only if used in THIS step file instance and only the ones used, there might be others)
+advancedElicitationTask: "{project-root}/.bmad/core/tasks/advanced-elicitation.xml"
+partyModeWorkflow: "{project-root}/.bmad/core/workflows/party-mode/workflow.md"
+
+{{#hasTemplates}}
+# Template References
+{{#templates}}
+{{name}}: "{workflow_path}/templates/{{file}}"
+{{/templates}}
+{{/hasTemplates}}
+---
+
+# Step {{stepNumber}}: {{stepTitle}}
+
+## STEP GOAL:
+
+{{stepGoal}}
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are a {{aiRole}}
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring {{aiExpertise}}, user brings {{userExpertise}}
+- ✅ Maintain collaborative {{collaborationStyle}} tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on {{stepFocus}}
+- 🚫 FORBIDDEN to {{forbiddenAction}}
+- 💬 Approach: {{stepApproach}}
+- 📋 {{additionalRule}}
+
+## EXECUTION PROTOCOLS:
+
+{{#executionProtocols}}
+
+- 🎯 {{.}}
+  {{/executionProtocols}}
+
+## CONTEXT BOUNDARIES:
+
+- Available context: {{availableContext}}
+- Focus: {{contextFocus}}
+- Limits: {{contextLimits}}
+- Dependencies: {{contextDependencies}}
+
+## SEQUENCE OF INSTRUCTIONS (Do not deviate, skip, or optimize)
+
+{{#instructions}}
+
+### {{number}}. {{title}}
+
+{{content}}
+
+{{#hasContentToAppend}}
+
+#### Content to Append (if applicable):
+
+```markdown
+{{contentToAppend}}
+```
+
+{{/hasContentToAppend}}
+
+{{/instructions}}
+
+{{#hasMenu}}
+
+### {{menuNumber}}. Present MENU OPTIONS
+
+Display: **{{menuDisplay}}**
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+- Use menu handling logic section below
+
+#### Menu Handling Logic:
+
+{{#menuOptions}}
+
+- IF {{key}}: {{action}}
+  {{/menuOptions}}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#{{menuNumber}}-present-menu-options)
+  {{/hasMenu}}
+
+## CRITICAL STEP COMPLETION NOTE
+
+{{completionNote}}
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+{{#successCriteria}}
+
+- {{.}}
+  {{/successCriteria}}
+
+### ❌ SYSTEM FAILURE:
+
+{{#failureModes}}
+
+- {{.}}
+  {{/failureModes}}
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

src/modules/bmb/docs/workflows/templates/step-template.md

@@ -0,0 +1,290 @@
+# BMAD Workflow Step Template
+
+This template provides the standard structure for all BMAD workflow step files. Copy and modify this template for each new step you create.
+
+<!-- TEMPLATE START -->
+
+---
+
+name: 'step-[N]-[short-name]'
+description: '[Brief description of what this step accomplishes]'
+
+<!-- Path Definitions -->
+
+workflow\*path: '{project-root}/.bmad/[module]/reference/workflows/[workflow-name]' # the folder the workflow.md file is in
+
+# File References (all use {variable} format in file)
+
+thisStepFile: '{workflow_path}/steps/step-[N]-[short-name].md'
+nextStep{N+1}: '{workflow_path}/steps/step-[N+1]-[next-short-name].md' # Remove for final step or no next step
+altStep{Y}: '{workflow_path}/steps/step-[Y]-[some-other-step].md' # if there is an alternate next story depending on logic
+workflowFile: '{workflow_path}/workflow.md'
+outputFile: '{output_folder}/[output-file-name]-{project_name}.md'
+
+# Task References (IF THE workflow uses and it makes sense in this step to have these )
+
+advancedElicitationTask: '{project-root}/.bmad/core/tasks/advanced-elicitation.xml'
+partyModeWorkflow: '{project-root}/.bmad/core/workflows/party-mode/workflow.md'
+
+# Template References (if this step uses a specific templates)
+
+profileTemplate: '{workflow_path}/templates/profile-section.md'
+assessmentTemplate: '{workflow_path}/templates/assessment-section.md'
+strategyTemplate: '{workflow_path}/templates/strategy-section.md'
+
+# Data (CSV for example) References (if used in this step)
+
+someData: '{workflow_path}/data/foo.csv'
+
+# Add more as needed - but ONLY what is used in this specific step file!
+
+---
+
+# Step [N]: [Step Name]
+
+## STEP GOAL:
+
+[State the goal in context of the overall workflow goal. Be specific about what this step accomplishes and how it contributes to the workflow's purpose.]
+
+Example: "To analyze user requirements and document functional specifications that will guide the development process"
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are a [specific role, e.g., "business analyst" or "technical architect"]
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring [your expertise], user brings [their expertise], and together we produce something better than we could on our own
+- ✅ Maintain collaborative [adjective] tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on [specific task for this step]
+- 🚫 FORBIDDEN to [what not to do in this step]
+- 💬 Approach: [how to handle this specific task]
+- 📋 Additional rule relevant to this step
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 [Step-specific protocol 1]
+- 💾 [Step-specific protocol 2 - e.g., document updates]
+- 📖 [Step-specific protocol 3 - e.g., tracking requirements]
+- 🚫 [Step-specific restriction]
+
+## CONTEXT BOUNDARIES:
+
+- Available context: [what context is available from previous steps]
+- Focus: [what this step should concentrate on]
+- Limits: [what not to assume or do]
+- Dependencies: [what this step depends on]
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+[Detailed instructions for the step's work]
+
+### 1. Title
+
+[Specific instructions for first part of the work]
+
+### 2. Title
+
+[Specific instructions for second part of the work]
+
+### N. Title (as many as needed)
+
+<!-- not ever step will include advanced elicitation or party mode, in which case generally will just have the C option -->
+<!-- for example an init step 1 that loads data, or step 1b continues a workflow would not need advanced elicitation or party mode - but any step where the user and the llm work together on content, thats where it makes sense to include them -->
+
+### N. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Execute {advancedElicitationTask} # Or custom action
+- IF P: Execute {partyModeWorkflow} # Or custom action
+- IF C: Save content to {outputFile}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution completes, redisplay the menu
+- User can chat or ask questions - always respond when conversation ends, redisplay the menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+[Specific conditions for completing this step and transitioning to the next, such as output to file being created with this tasks updates]
+
+ONLY WHEN [C continue option] is selected and [completion requirements], will you then load and read fully `[installed_path]/step-[next-number]-[name].md` to execute and begin [next step description].
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- [Step-specific success criteria 1]
+- [Step-specific success criteria 2]
+- Content properly saved/document updated
+- Menu presented and user input handled correctly
+- [General success criteria]
+
+### ❌ SYSTEM FAILURE:
+
+- [Step-specific failure mode 1]
+- [Step-specific failure mode 2]
+- Proceeding without user input/selection
+- Not updating required documents/frontmatter
+- [Step-specific failure mode N]
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+<!-- TEMPLATE END-->
+
+## Common Menu Patterns to use in the final sequence item in a step file
+
+FYI Again - party mode is useful for the user to reach out and get opinions from other agents.
+
+Advanced elicitation is use to direct you to think of alternative outputs of a sequence you just performed.
+
+### Standard Menu - when a sequence in a step results in content produced by the agent or human that could be improved before proceeding
+
+```markdown
+### N. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] [Advanced Elicitation] [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Execute {advancedElicitationTask}
+- IF P: Execute {partyModeWorkflow}
+- IF C: Save content to {outputFile}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+```
+
+### Optional Menu - Auto-Proceed Menu (No User Choice or confirm, just flow right to the next step once completed)
+
+```markdown
+### N. Present MENU OPTIONS
+
+Display: "**Proceeding to [next action]...**"
+
+#### Menu Handling Logic:
+
+- After [completion condition], immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an [auto-proceed reason] step with no user choices
+- Proceed directly to next step after setup
+```
+
+### Custom Menu Options
+
+```markdown
+### N. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] [Custom Action 1] [B] [Custom Action 2] [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: [Custom handler route for option A]
+- IF B: [Custom handler route for option B]
+- IF C: Save content to {outputFile}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+```
+
+### Conditional Menu (Based on Workflow State)
+
+```markdown
+### N. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] [Continue to Step Foo] [A] [Continue to Step Bar]"
+
+#### Menu Handling Logic:
+
+- IF A: Execute {customAction}
+- IF C: Save content to {outputFile}, update frontmatter, check [condition]:
+  - IF [condition true]: load, read entire file, then execute {pathA}
+  - IF [condition false]: load, read entire file, then execute {pathB}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+```
+
+## Example Step Implementations
+
+### Initialization Step Example
+
+See [step-01-init.md](../reference/workflows/meal-prep-nutrition/steps/step-01-init.md) for an example of:
+
+- Detecting existing workflow state and short circuit to 1b
+- Creating output documents from templates
+- Auto-proceeding to the next step (this is not the normal behavior of most steps)
+- Handling continuation scenarios
+
+### Continuation Step Example
+
+See [step-01b-continue.md](../reference/workflows/meal-prep-nutrition/steps/step-01b-continue.md) for an example of:
+
+- Handling already-in-progress workflows
+- Detecting completion status
+- Presenting update vs new plan options
+- Seamless workflow resumption
+
+### Standard Step with Menu Example
+
+See [step-02-profile.md](../reference/workflows/meal-prep-nutrition/steps/step-02-profile.md) for an example of:
+
+- Presenting a menu with A/P/C options
+- Forcing halt until user selects 'C' (Continue)
+- Writing all collected content to output file only when 'C' is selected
+- Updating frontmatter with step completion before proceeding
+- Using frontmatter variables for file references
+
+### Final Step Example
+
+See [step-06-prep-schedule.md](../reference/workflows/meal-prep-nutrition/steps/step-06-prep-schedule.md) for an example of:
+
+- Completing workflow deliverables
+- Marking workflow as complete in frontmatter
+- Providing final success messages
+- Ending the workflow session gracefully
+
+## Best Practices
+
+1. **Keep step files focused** - Each step should do one thing well
+2. **Be explicit in instructions** - No ambiguity about what to do
+3. **Include all critical rules** - Don't assume anything from other steps
+4. **Use clear, concise language** - Avoid jargon unless necessary
+5. **Ensure all menu paths have handlers** - Ensure every option has clear instructions - use menu items that make sense for the situation.
+6. **Document dependencies** - Clearly state what this step needs with full paths in front matter
+7. **Define success and failure clearly** - Both for the step and the workflow
+8. **Mark completion clearly** - Ensure final steps update frontmatter to indicate workflow completion

src/modules/bmb/docs/workflows/templates/workflow-template.md

@@ -0,0 +1,104 @@
+# BMAD Workflow Template
+
+This template provides the standard structure for all BMAD workflow files. Copy and modify this template for each new workflow you create.
+
+<!-- TEMPLATE START -->
+
+---
+
+name: [WORKFLOW_DISPLAY_NAME]
+description: [Brief description of what this workflow accomplishes]
+web_bundle: [true/false] # Set to true for inclusion in web bundle builds
+
+---
+
+# [WORKFLOW_DISPLAY_NAME]
+
+**Goal:** [State the primary goal of this workflow in one clear sentence]
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a [role] collaborating with [user type]. This is a partnership, not a client-vendor relationship. You bring [your expertise], while the user brings [their expertise]. Work together as equals.
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time
+- **Just-In-Time Loading**: Only 1 current step file will be loaded, read, and executed to completion - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full config from {project-root}/.bmad/[MODULE FOLDER]/config.yaml and resolve:
+
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, [MODULE VARS]
+
+### 2. First Step EXECUTION
+
+Load, read the full file and then execute [FIRST STEP FILE PATH] to begin the workflow.
+
+<!-- TEMPLATE END -->
+
+## How to Use This Template
+
+### Step 1: Copy and Replace Placeholders
+
+Copy the template above and replace:
+
+- `[WORKFLOW_DISPLAY_NAME]` → Your workflow's display name
+- `[MODULE FOLDER]` → Default is `core` unless this is for another module (such as bmm, cis, or another as directed by user)
+- `[Brief description]` → One-sentence description
+- `[true/false]` → Whether to include in web bundle
+- `[role]` → AI's role in this workflow
+- `[user type]` → Who the user is
+- `[CONFIG_PATH]` → Path to config file (usually `bmm/config.yaml` or `bmb/config.yaml`)
+- `[WORKFLOW_PATH]` → Path to your workflow folder
+- `[MODULE VARS]` → Extra config variables available in a module configuration that the workflow would need to use
+
+### Step 2: Create the Folder Structure
+
+```
+[workflow-folder]/
+├── workflow.md          # This file
+├── data/                # (Optional csv or other data files)
+├── templates/           # template files for output
+└── steps/
+    ├── step-01-init.md
+    ├── step-02-[name].md
+    └── ...
+
+```
+
+### Step 3: Configure the Initialization Path
+
+Update the last line of the workflow.md being created to replace [FIRST STEP FILE PATH] with the path to the actual first step file.
+
+Example: Load, read the full file and then execute `{workflow_path}/steps/step-01-init.md` to begin the workflow.
+
+### NOTE: You can View a real example of a perfect workflow.md file that was created from this template
+
+`{project-root}/.bmad/bmb/reference/workflows/meal-prep-nutrition/workflow.md`

src/modules/bmb/docs/workflows/templates/workflow.md

@@ -0,0 +1,58 @@
+---
+name: { { workflowDisplayName } }
+description: { { workflowDescription } }
+web_bundle: { { webBundleFlag } }
+---
+
+# {{workflowDisplayName}}
+
+**Goal:** {{workflowGoal}}
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a {{aiRole}} collaborating with {{userType}}. This is a partnership, not a client-vendor relationship. You bring {{aiExpertise}}, while the user brings {{userExpertise}}. Work together as equals.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from {project-root}/.bmad/{{targetModule}}/config.yaml and resolve:
+
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+
+### 2. First Step EXECUTION
+
+Load, read the full file and then execute `{workflow_path}/steps/step-01-init.md` to begin the workflow.

src/modules/bmb/docs/workflows/terms.md

@@ -0,0 +1,97 @@
+# BMAD Workflow Terms
+
+## Core Components
+
+### BMAD Workflow
+
+A facilitated, guided process where the AI acts as a facilitator working collaboratively with a human. Workflows can serve any purpose - from document creation to brainstorming, technical implementation, or decision-making. The human may be a collaborative partner, beginner seeking guidance, or someone who wants the AI to execute specific tasks. Each workflow is self-contained and follows a disciplined execution model.
+
+### workflow.md
+
+The master control file that defines:
+
+- Workflow metadata (name, description, version)
+- Step sequence and file paths
+- Required data files and dependencies
+- Execution rules and protocols
+
+### Step File
+
+An individual markdown file containing:
+
+- One discrete step of the workflow
+- All rules and context needed for that step
+- Execution guardrails and validation criteria
+- Content generation guidance
+
+### step-01-init.md
+
+The first step file that:
+
+- Initializes the workflow
+- Sets up document frontmatter
+- Establishes initial context
+- Defines workflow parameters
+
+### step-01b-continue.md
+
+A continuation step file that:
+
+- Resumes a workflow that was paused
+- Reloads context from saved state
+- Validates current document state
+- Continues from the last completed step
+
+### CSV Data Files
+
+Structured data files that provide:
+
+- Domain-specific knowledge and complexity mappings
+- Project-type-specific requirements
+- Decision matrices and lookup tables
+- Dynamic workflow behavior based on input
+
+## Dialog Styles
+
+### Prescriptive Dialog
+
+Structured interaction with:
+
+- Exact questions and specific options
+- Consistent format across all executions
+- Finite, well-defined choices
+- High reliability and repeatability
+
+### Intent-Based Dialog
+
+Adaptive interaction with:
+
+- Goals and principles instead of scripts
+- Open-ended exploration and discovery
+- Context-aware question adaptation
+- Flexible, conversational flow
+
+### Template
+
+A markdown file that:
+
+- Starts with frontmatter (metadata)
+- Has content built through append-only operations
+- Contains no placeholder tags
+- Grows progressively as the workflow executes
+- Used when the workflow produces a document output
+
+## Execution Concepts
+
+### JIT Step Loading
+
+Just-In-Time step loading ensures:
+
+- Only the current step file is in memory
+- Complete focus on the step being executed
+- Minimal context to prevent information leakage
+- Sequential progression through workflow steps
+
+---
+
+_These terms form the foundation of the BMAD workflow system._

src/modules/bmb/module.yaml

@@ -11,21 +11,15 @@ subheader: "Configure the settings for the BoMB Factory!\nThe agent, workflow an
 ## 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/src/agents"
-  result: "{project-root}/{value}"
-
-custom_workflow_location:
-  prompt: "Where do custom workflows get stored?"
-  default: "{bmad_folder}/custom/src/workflows"
+custom_stand_alone_location:
+  prompt: "Where do custom agents and workflows get stored?"
+  default: "bmad-custom-src"
   result: "{project-root}/{value}"
 
 custom_module_location:
   prompt: "Where do custom modules get stored?"
-  default: "{bmad_folder}/custom/src/modules"
+  default: "bmad-custom-modules-src"
   result: "{project-root}/{value}"

src/modules/bmb/reference/agents/expert-examples/journal-keeper/README.md

@@ -51,7 +51,7 @@ menu:
 
   # Direct sidecar file action
   - trigger: 'insight'
-    action: 'Document this breakthrough in {agent-folder}/journal-keeper-sidecar/breakthroughs.md'
+    action: 'Document this breakthrough in ./journal-keeper-sidecar/breakthroughs.md'
     description: 'Record a meaningful insight'
 ```
 
@@ -63,9 +63,9 @@ 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/'
+  - 'Load COMPLETE file ./journal-keeper-sidecar/memories.md'
+  - 'Load COMPLETE file ./journal-keeper-sidecar/instructions.md'
+  - 'ONLY read/write files in ./journal-keeper-sidecar/'
 ```
 
 **Key points:**

src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml

@@ -20,9 +20,9 @@ agent:
       - 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"
+    - "Load COMPLETE file {agent_sidecar_folder}/journal-keeper-sidecar/memories.md and remember all past insights"
+    - "Load COMPLETE file {agent_sidecar_folder}/journal-keeper-sidecar/instructions.md and follow ALL journaling protocols"
+    - "ONLY read/write files in {agent_sidecar_folder}/journal-keeper-sidecar/ - this is our private space"
     - "Track mood patterns, recurring themes, and breakthrough moments"
     - "Reference past entries naturally to show continuity"
 
@@ -120,7 +120,7 @@ agent:
       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"
+      action: "Save a quick, unstructured entry to {agent_sidecar_folder}/journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed"
       description: "Quick capture without prompts"
 
     - trigger: mood
@@ -133,20 +133,20 @@ agent:
 
     - trigger: gratitude
       action: "#gratitude-moment"
-      description: "Capture today's gratitudes"
+      description: "Capture today's gratitude"
 
     - 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"
+      action: "Document this breakthrough in {agent_sidecar_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"
+      action: "Load and share entries from {agent_sidecar_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"
+      action: "Update {agent_sidecar_folder}/journal-keeper-sidecar/memories.md with today's session insights and emotional markers"
       description: "Save what we discussed today"

src/modules/bmb/reference/agents/module-examples/README.md

@@ -7,7 +7,7 @@ Reference examples for module-integrated agents.
 Module agents integrate with BMAD module workflows (BMM, CIS, BMB). They:
 
 - Orchestrate multi-step workflows
-- Use `{bmad_folder}` path variables
+- Use `.bmad` path variables
 - Have fixed professional personas (no install_config)
 - Reference module-specific configurations
 
@@ -47,4 +47,4 @@ When creating module agents:
 4. Replace menu with actual available workflows
 5. Remove hypothetical workflow references
 
-See `/src/modules/bmb/docs/module-agent-architecture.md` for complete guide.
+See `/src/modules/bmb/docs/agents/module-agent-architecture.md` for complete guide.

src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml

@@ -10,7 +10,7 @@
 
 agent:
   metadata:
-    id: "{bmad_folder}/bmm/agents/security-engineer.md"
+    id: ".bmad/bmm/agents/security-engineer.md"
     name: "Sam"
     title: "Security Engineer"
     icon: "🔐"
@@ -30,24 +30,24 @@ agent:
       - Least privilege and defense in depth are non-negotiable
 
   menu:
-    # NOTE: These workflows are hypothetical examples - not implemented
+    # NOTE: These workflows are hypothetical examples assuming add to a module called bmm - not implemented
     - trigger: threat-model
-      workflow: "{project-root}/{bmad_folder}/bmm/workflows/threat-model/workflow.yaml"
+      exec: "{project-root}/.bmad/bmm/workflows/threat-model/workflow.md"
       description: "Create STRIDE threat model for architecture"
 
     - trigger: security-review
-      workflow: "{project-root}/{bmad_folder}/bmm/workflows/security-review/workflow.yaml"
+      exec: "{project-root}/.bmad/bmm/workflows/security-review/workflow.md"
       description: "Review code/design for security issues"
 
     - trigger: owasp-check
-      exec: "{project-root}/{bmad_folder}/bmm/tasks/owasp-top-10.xml"
+      TODO: true
       description: "Check against OWASP Top 10"
 
     - trigger: compliance
-      workflow: "{project-root}/{bmad_folder}/bmm/workflows/compliance-check/workflow.yaml"
+      exec: "{project-root}/.bmad/bmm/workflows/compliance-check/workflow.md"
       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"
+      exec: "{project-root}/.bmad/core/workflows/party-mode/workflow.md"
       description: "Multi-agent security discussion"

src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml

@@ -10,7 +10,7 @@
 
 agent:
   metadata:
-    id: "{bmad_folder}/cis/agents/trend-analyst.md"
+    id: ".bmad/cis/agents/trend-analyst.md"
     name: "Nova"
     title: "Trend Analyst"
     icon: "📈"
@@ -32,26 +32,26 @@ agent:
   menu:
     # NOTE: These workflows are hypothetical examples - not implemented
     - trigger: scan-trends
-      workflow: "{project-root}/{bmad_folder}/cis/workflows/trend-scan/workflow.yaml"
+      exec: "{project-root}/.bmad/cis/workflows/trend-scan/workflow.md"
       description: "Scan for emerging trends in a domain"
 
     - trigger: analyze-trend
-      workflow: "{project-root}/{bmad_folder}/cis/workflows/trend-analysis/workflow.yaml"
+      exec: "{project-root}/.bmad/cis/workflows/trend-analysis/workflow.md"
       description: "Deep dive on a specific trend"
 
     - trigger: opportunity-map
-      workflow: "{project-root}/{bmad_folder}/cis/workflows/opportunity-mapping/workflow.yaml"
+      exec: "{project-root}/.bmad/cis/workflows/opportunity-mapping/workflow.md"
       description: "Map trend to strategic opportunities"
 
     - trigger: competitor-trends
-      exec: "{project-root}/{bmad_folder}/cis/tasks/competitor-trend-watch.xml"
+      exec: "{project-root}/.bmad/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"
+      exec: "{project-root}/.bmad/core/workflows/brainstorming/workflow.md"
       description: "Brainstorm trend implications"
 
     - trigger: party-mode
-      workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"
+      exec: "{project-root}/.bmad/core/workflows/party-mode/workflow.md"
       description: "Discuss trends with other agents"

src/modules/bmb/reference/workflows/meal-prep-nutrition/data/dietary-restrictions.csv

@@ -0,0 +1,18 @@
+category,restriction,considerations,alternatives,notes
+Allergy,Nuts,Severe allergy, check labels carefully,Seeds, sunflower seed butter
+Allergy,Shellfish,Cross-reactivity with some fish,Fin fish, vegetarian proteins
+Allergy,Dairy,Calcium and vitamin D needs,Almond milk, fortified plant milks
+Allergy,Soy,Protein source replacement,Legumes, quinoa, seitan
+Allergy,Gluten,Celiac vs sensitivity,Quinoa, rice, certified gluten-free
+Medical,Diabetes,Carbohydrate timing and type,Fiber-rich foods, low glycemic
+Medical,Hypertension,Sodium restriction,Herbs, spices, salt-free seasonings
+Medical,IBS,FODMAP triggers,Low FODMAP vegetables, soluble fiber
+Ethical,Vegetarian,Complete protein combinations,Quinoa, buckwheat, hemp seeds
+Ethical,Vegan,B12 supplementation mandatory,Nutritional yeast, fortified foods
+Ethical,Halal,Meat sourcing requirements,Halal-certified products
+Ethical,Kosher,Dairy-meat separation,Parve alternatives
+Intolerance,Lactose,Dairy digestion issues,Lactase pills, aged cheeses
+Intolerance,FODMAP,Carbohydrate malabsorption,Low FODMAP fruits/veg
+Preference,Dislikes,Texture/flavor preferences,Similar texture alternatives
+Preference,Budget,Cost-effective options,Bulk buying, seasonal produce
+Preference,Convenience,Time-saving options,Pre-cut vegetables, frozen produce