feat: Update @clack/prompts to v1.0.0 and Add autocompleteMultiselect prompt (#1514)

* feat: Update @clack/prompts to v1.0.0 and Add autocompleteMultiselect prompt

* fix(cli): flexible tool selection (skip recommended or additional) + fix spacing

* feat(cli): improve tool selection UX with autocomplete and upgrade path

* feat(cli): display selected tools after IDE selection with preferred markers

* fix: formatting

* fix: make selection message more clear

* fix: formatting

* fix: Remove redundant colon

---------

Co-authored-by: Brian <bmadcode@gmail.com>

.claude/skills/changelog-social/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: changelog-social
+description: Generate social media announcements for Discord, Twitter, and LinkedIn from the latest changelog entry. Use when user asks to create release announcements, social posts, or share changelog updates. Reads CHANGELOG.md in current working directory. Reference examples/ for tone and format.
+disable-model-invocation: true
+---
+
+# Changelog Social
+
+Generate engaging social media announcements from changelog entries.
+
+## Workflow
+
+### Step 1: Extract Changelog Entry
+
+Read `./CHANGELOG.md` and extract the latest version entry. The changelog follows this format:
+
+```markdown
+## [VERSION]
+
+### 🎁 Features
+* **Title** — Description
+
+### 🐛 Bug Fixes
+* **Title** — Description
+
+### 📚 Documentation
+* **Title** — Description
+
+### 🔧 Maintenance
+* **Title** — Description
+```
+
+Parse:
+- **Version number** (e.g., `6.0.0-Beta.5`)
+- **Features** - New functionality, enhancements
+- **Bug Fixes** - Fixes users will care about
+- **Documentation** - New or improved docs
+- **Maintenance** - Dependency updates, tooling improvements
+
+### Step 2: Get Git Contributors
+
+Use git log to find contributors since the previous version. Get commits between the current version tag and the previous one:
+
+```bash
+# Find the previous version tag first
+git tag --sort=-version:refname | head -5
+
+# Get commits between versions with PR numbers and authors
+git log <previous-tag>..<current-tag> --pretty=format:"%h|%s|%an" --grep="#"
+```
+
+Extract PR numbers from commit messages that contain `#` followed by digits. Compile unique contributors.
+
+### Step 3: Generate Discord Announcement
+
+**Limit: 2,000 characters per message.** Split into multiple messages if needed.
+
+Use this template style:
+
+```markdown
+🚀 **BMad vVERSION RELEASED!**
+
+🎉 [Brief hype sentence]
+
+🪥 **KEY HIGHLIGHT** - [One-line summary]
+
+🎯 **CATEGORY NAME**
+• Feature one - brief description
+• Feature two - brief description
+• Coming soon: Future teaser
+
+🔧 **ANOTHER CATEGORY**
+• Fix or feature
+• Another item
+
+📚 **DOCS OR OTHER**
+• Item
+• Item with link
+
+🌟 **COMMUNITY PHILOSOPHY** (optional - include for major releases)
+• Everything is FREE - No paywalls
+• Knowledge shared, not sold
+
+📊 **STATS**
+X commits | Y PRs merged | Z files changed
+
+🙏 **CONTRIBUTORS**
+@username1 (X PRs!), @username2 (Y PRs!)
+@username3, @username4, username5 + dependabot 🛡️
+Community-driven FTW! 🌟
+
+📦 **INSTALL:**
+`npx bmad-method@VERSION install`
+
+⭐ **SUPPORT US:**
+🌟 GitHub: github.com/bmad-code-org/BMAD-METHOD/
+📺 YouTube: youtube.com/@BMadCode
+☕ Donate: buymeacoffee.com/bmad
+
+🔥 **Next version tease!**
+```
+
+**Content Strategy:**
+- Focus on **user impact** - what's better for them?
+- Highlight **annoying bugs fixed** that frustrated users
+- Show **new capabilities** that enable workflows
+- Keep it **punchy** - use emojis and short bullets
+- Add **personality** - excitement, humor, gratitude
+
+### Step 4: Generate Twitter Post
+
+**Limit: 25,000 characters per tweet (Premium).** With Premium, use a single comprehensive post matching the Discord style (minus Discord-specific formatting). Aim for 1,500-3,000 characters for better engagement.
+
+**Threads are optional** — only use for truly massive releases where you want multiple engagement points.
+
+See `examples/twitter-example.md` for the single-post Premium format.
+
+## Content Selection Guidelines
+
+**Include:**
+- New features that change workflows
+- Bug fixes for annoying/blocking issues
+- Documentation that helps users
+- Performance improvements
+- New agents or workflows
+- Breaking changes (call out clearly)
+
+**Skip/Minimize:**
+- Internal refactoring
+- Dependency updates (unless user-facing)
+- Test improvements
+- Minor style fixes
+
+**Emphasize:**
+- "Finally fixed" issues
+- "Faster" operations
+- "Easier" workflows
+- "Now supports" capabilities
+
+## Examples
+
+Reference example posts in `examples/` for tone and formatting guidance:
+
+- **discord-example.md** — Full Discord announcement with emojis, sections, contributor shout-outs
+- **twitter-example.md** — Twitter thread format (5 tweets max for major releases)
+- **linkedin-example.md** — Professional post for major/minor releases with significant features
+
+**When to use LinkedIn:**
+- Major version releases (e.g., v6.0.0 Beta, v7.0.0)
+- Minor releases with exceptional new features
+- Community milestone announcements
+
+Read the appropriate example file before generating to match the established style and voice.
+
+## Output Format
+
+Present both announcements in clearly labeled sections:
+
+```markdown
+## Discord Announcement
+
+[paste Discord content here]
+
+## Twitter Post
+
+[paste Twitter content here]
+```
+
+Offer to make adjustments if the user wants different emphasis, tone, or content.

.claude/skills/changelog-social/examples/discord-example.md

@@ -0,0 +1,53 @@
+🚀 **BMad v6.0.0-alpha.23 RELEASED!**
+
+🎉 Huge update - almost beta!
+
+🪟 **WINDOWS INSTALLER FIXED** - Menu arrows issue should be fixed! CRLF & ESM problems resolved.
+
+🎯 **PRD WORKFLOWS IMPROVED**
+• Validation & Edit workflows added!
+• PRD Cohesion check ensures document flows beautifully
+• Coming soon: Use of subprocess optimization (context saved!)
+• Coming soon: Final format polish step in all workflows - Human consumption OR hyper-optimized LLM condensed initially!
+
+🔧 **WORKFLOW CREATOR & VALIDATOR**
+• Subprocess support for advanced optimization
+• Path violation checks ensure integrity
+• Beyond error checking - offers optimization & flow suggestions!
+
+📚 **NEW DOCS SITE** - docs.bmad-method.org
+• Diataxis framework: Tutorials, How-To, Explanations, References
+• Current docs still being revised
+• Tutorials, blogs & explainers coming soon!
+
+💡 **BRAINSTORMING REVOLUTION**
+• 100+ idea goal (quantity-first!)
+• Anti-bias protocol (pivot every 10 ideas)
+• Chain-of-thought + simulated temperature prompts
+• Coming soon: SubProcessing (on-the-fly sub agents)
+
+🌟 **COMMUNITY PHILOSOPHY**
+• Everything is FREE - No paywalls, no gated content
+• Knowledge shared, not sold
+• No premium tiers - full access to our ideas
+
+📊 **27 commits | 217 links converted | 42+ docs created**
+
+🙏 **17 Community PR Authors in this release!**
+@lum (6 PRs!), @q00 (3 PRs!), @phil (2 PRs!)
+@mike, @alex, @ramiz, @sjennings + dependabot 🛡️
+Community-driven FTW! 🌟
+
+📦 **INSTALL ALPHA:**
+`npx bmad-method install`
+
+⭐ **SUPPORT US:**
+🌟 GitHub: github.com/bmad-code-org/BMAD-METHOD/
+📺 YouTube: youtube.com/@BMadCode
+
+🎤 **SPEAKING & MEDIA**
+Available for conferences, podcasts, media appearances!
+Topics: AI-Native Organizations (Any Industry), BMad Method
+DM on Discord for inquiries!
+
+🔥 **V6 Beta is DAYS away!** January 22nd ETA - new features such as xyz and abc bug fixes!

.claude/skills/changelog-social/examples/linkedin-example.md

@@ -0,0 +1,49 @@
+🚀 **Announcing BMad Method v6.0.0 Beta - AI-Native Agile Development Framework**
+
+I'm excited to share that BMad Method, the open-source AI-driven agile development framework, is entering Beta! After 27 alpha releases and countless community contributions, we're approaching a major milestone.
+
+**What's New in v6.0.0-alpha.23**
+
+🪟 **Windows Compatibility Fixed**
+We've resolved the installer issues that affected Windows users. The menu arrows problem, CRLF handling, and ESM compatibility are all resolved.
+
+🎯 **Enhanced PRD Workflows**
+Our Product Requirements Document workflows now include validation and editing capabilities, with a new cohesion check that ensures your documents flow beautifully. Subprocess optimization is coming soon to save even more context.
+
+🔧 **Workflow Creator & Validator**
+New tools for creating and validating workflows with subprocess support, path violation checks, and optimization suggestions that go beyond simple error checking.
+
+📚 **New Documentation Platform**
+We've launched docs.bmad-method.org using the Diataxis framework - providing clear separation between tutorials, how-to guides, explanations, and references. Our documentation is being continuously revised and expanded.
+
+💡 **Brainstorming Revolution**
+Our brainstorming workflows now use research-backed techniques: 100+ idea goals, anti-bias protocols, chain-of-thought reasoning, and simulated temperature prompts for higher divergence.
+
+**Our Philosophy**
+
+Everything in BMad Method is FREE. No paywalls, no gated content, no premium tiers. We believe knowledge should be shared, not sold. This is community-driven development at its finest.
+
+**The Stats**
+- 27 commits in this release
+- 217 documentation links converted
+- 42+ new documents created
+- 17 community PR authors contributed
+
+**Get Started**
+
+```
+npx bmad-method@alpha install
+```
+
+**Learn More**
+- GitHub: github.com/bmad-code-org/BMAD-METHOD
+- YouTube: youtube.com/@BMadCode
+- Docs: docs.bmad-method.org
+
+**What's Next?**
+
+Beta is just days away with an ETA of January 22nd. We're also available for conferences, podcasts, and media appearances to discuss AI-Native Organizations and the BMad Method.
+
+Have you tried BMad Method yet? I'd love to hear about your experience in the comments!
+
+#AI #SoftwareDevelopment #Agile #OpenSource #DevTools #LLM #AgentEngineering

.claude/skills/changelog-social/examples/twitter-example.md

@@ -0,0 +1,55 @@
+🚀 **BMad v6.0.0-alpha.23 RELEASED!**
+
+Huge update - we're almost at Beta! 🎉
+
+🪟 **WINDOWS INSTALLER FIXED** - Menu arrows issue should be fixed! CRLF & ESM problems resolved.
+
+🎯 **PRD WORKFLOWS IMPROVED**
+• Validation & Edit workflows added!
+• PRD Cohesion check ensures document flows beautifully
+• Coming soon: Subprocess optimization (context saved!)
+• Coming soon: Final format polish step in all workflows
+
+🔧 **WORKFLOW CREATOR & VALIDATOR**
+• Subprocess support for advanced optimization
+• Path violation checks ensure integrity
+• Beyond error checking - offers optimization & flow suggestions!
+
+📚 **NEW DOCS SITE** - docs.bmad-method.org
+• Diataxis framework: Tutorials, How-To, Explanations, References
+• Current docs still being revised
+• Tutorials, blogs & explainers coming soon!
+
+💡 **BRAINSTORMING REVOLUTION**
+• 100+ idea goal (quantity-first!)
+• Anti-bias protocol (pivot every 10 ideas)
+• Chain-of-thought + simulated temperature prompts
+• Coming soon: SubProcessing (on-the-fly sub agents)
+
+🌟 **COMMUNITY PHILOSOPHY**
+• Everything is FREE - No paywalls, no gated content
+• Knowledge shared, not sold
+• No premium tiers - full access to our ideas
+
+📊 **27 commits | 217 links converted | 42+ docs created**
+
+🙏 **17 Community PR Authors in this release!**
+@lum (6 PRs!), @q00 (3 PRs!), @phil (2 PRs!)
+@mike, @alex, @ramiz, @sjennings + dependabot 🛡️
+Community-driven FTW! 🌟
+
+📦 **INSTALL ALPHA:**
+`npx bmad-method install`
+
+⭐ **SUPPORT US:**
+🌟 GitHub: github.com/bmad-code-org/BMAD-METHOD/
+📺 YouTube: youtube.com/@BMadCode
+
+🎤 **SPEAKING & MEDIA**
+Available for conferences, podcasts, media appearances!
+Topics: AI-Native Organizations (Any Industry), BMad Method
+DM on Discord for inquiries!
+
+🔥 **V6 Beta is DAYS away!** January 22nd ETA!
+
+#AI #DevTools #Agile #OpenSource #LLM #AgentEngineering

.claude/skills/draft-changelog/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: draft-changelog
+description: Analyzes changes since the last release and generates a draft changelog entry
+disable-model-invocation: true
+---
+
+Read `prompts/instructions.md` and execute.

.claude/skills/draft-changelog/prompts/instructions.md

@@ -0,0 +1,58 @@
+# Draft Changelog Execution
+
+## Input
+Project path (or run from project root)
+
+## Step 1: Identify Current State
+- Get the latest released tag
+- Get current version
+- Verify there are commits since the last release
+
+## Step 2: Launch Explore Agent
+
+Use `thoroughness: "very thorough"` to analyze all changes since the last release tag.
+
+**Key: For each merge commit, look up the merged PR/issue that was closed.**
+- Use `gh pr view` or git commit body to find the PR number
+- Read the PR description and comments to understand full context
+- Don't rely solely on commit merge messages - they lack context
+
+**Analyze:**
+
+1. **All merges/commits** since the last tag
+2. **For each merge, read the original PR/issue** that was closed
+3. **Files changed** with statistics
+4. **Categorize changes:**
+   - 🎁 **Features** - New functionality, new agents, new workflows
+   - 🐛 **Bug Fixes** - Fixed bugs, corrected issues
+   - ♻️ **Refactoring** - Code improvements, reorganization
+   - 📚 **Documentation** - Docs updates, README changes
+   - 🔧 **Maintenance** - Dependency updates, tooling, infrastructure
+   - 💥 **Breaking Changes** - Changes that may affect users
+
+**Provide:**
+- Comprehensive summary of ALL changes with PR context
+- Categorization of each change
+- Identification of breaking changes
+- Significance assessment (major/minor/trivial)
+
+## Step 3: Generate Draft Changelog
+
+Format:
+```markdown
+## v0.X.X - [Date]
+
+* [Change 1 - categorized by type]
+* [Change 2]
+```
+
+Guidelines:
+- Present tense ("Fix bug" not "Fixed bug")
+- Most significant changes first
+- Group related changes
+- Clear, concise language
+- For breaking changes, clearly indicate impact
+
+## Step 4: Present Draft
+
+Show the draft with current version, last tag, commit count, and options to edit/retry.

.claude/skills/gh-triage/README.md

@@ -0,0 +1,14 @@
+# gh-triage
+
+Fetches all GitHub issues via gh CLI and uses AI agents to deeply analyze, cluster, and prioritize issues.
+
+## Usage
+
+Run from within any BMad Method repository to triage issues.
+
+## What It Does
+
+1. Fetches all open issues via `gh issue list`
+2. Splits issues into batches
+3. Launches parallel agents to analyze each batch
+4. Generates comprehensive triage report to `_bmad-output/triage-reports/`

.claude/skills/gh-triage/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: gh-triage
+description: Fetch all GitHub issues via gh CLI and use AI agents to deeply analyze, cluster, and prioritize issues
+license: MIT
+disable-model-invocation: true
+metadata:
+  author: bmad-code-org
+  version: "3.0.0"
+compatibility: Requires gh CLI, git repository, and BMad Method with Task tool support
+---
+
+Read `prompts/instructions.md` and execute.

.claude/skills/gh-triage/prompts/agent-prompt.md

@@ -0,0 +1,60 @@
+You are analyzing a batch of GitHub issues for deep understanding and triage.
+
+**YOUR TASK:**
+Read the issues in your batch and provide DEEP analysis:
+
+1. **For EACH issue, analyze:**
+   - What is this ACTUALLY about? (beyond keywords)
+   - What component/system does it affect?
+   - What's the impact and severity?
+   - Is it a bug, feature request, or something else?
+   - What specific theme does it belong to?
+
+2. **PRIORITY ASSESSMENT:**
+   - CRITICAL: Blocks users, security issues, data loss, broken installers
+   - HIGH: Major functionality broken, important features missing
+   - MEDIUM: Workarounds available, minor bugs, nice-to-have features
+   - LOW: Edge cases, cosmetic issues, questions
+
+3. **RELATIONSHIPS:**
+   - Duplicates: Near-identical issues about the same problem
+   - Related: Issues connected by theme or root cause
+   - Dependencies: One issue blocks or requires another
+
+**YOUR BATCH:**
+[Paste the batch of issues here - each with number, title, body, labels]
+
+**OUTPUT FORMAT (JSON only, no markdown):**
+{
+  "issues": [
+    {
+      "number": 123,
+      "title": "issue title",
+      "deep_understanding": "2-3 sentences explaining what this is really about",
+      "affected_components": ["installer", "workflows", "docs"],
+      "issue_type": "bug/feature/question/tech-debt",
+      "priority": "CRITICAL/HIGH/MEDIUM/LOW",
+      "priority_rationale": "Why this priority level",
+      "theme": "installation/workflow/integration/docs/ide-support/etc",
+      "relationships": {
+        "duplicates_of": [456],
+        "related_to": [789, 101],
+        "blocks": [111]
+      }
+    }
+  ],
+  "cross_repo_issues": [
+    {"number": 123, "target_repo": "bmad-builder", "reason": "about agent builder"}
+  ],
+  "cleanup_candidates": [
+    {"number": 456, "reason": "v4-related/outdated/duplicate"}
+  ],
+  "themes_found": {
+    "Installation Blockers": {
+      "count": 5,
+      "root_cause": "Common pattern if identifiable"
+    }
+  }
+}
+
+Return ONLY valid JSON. No explanations outside the JSON structure.

.claude/skills/gh-triage/prompts/instructions.md

@@ -0,0 +1,74 @@
+# GitHub Issue Triage with AI Analysis
+
+**CRITICAL RULES:**
+- NEVER include time or effort estimates in output or recommendations
+- Focus on WHAT needs to be done, not HOW LONG it takes
+- Use Bash tool with gh CLI for all GitHub operations
+
+## Execution
+
+### Step 1: Fetch Issues
+Use `gh issue list --json number,title,body,labels` to fetch all open issues.
+
+### Step 2: Batch Creation
+Split issues into batches of ~10 issues each for parallel analysis.
+
+### Step 3: Parallel Agent Analysis
+For EACH batch, use the Task tool with `subagent_type=general-purpose` to launch an agent with prompt from `prompts/agent-prompt.md`
+
+### Step 4: Consolidate & Generate Report
+After all agents complete, create a comprehensive markdown report saved to `_bmad-output/triage-reports/triage-YYYY-MM-DD.md`
+
+## Report Format
+
+### Executive Summary
+- Total issues analyzed
+- Issue count by priority (CRITICAL, HIGH, MEDIUM, LOW)
+- Major themes discovered
+- Top 5 critical issues requiring immediate attention
+
+### Critical Issues (CRITICAL Priority)
+For each CRITICAL issue:
+- **#123 - [Issue Title](url)**
+- **What it's about:** [Deep understanding]
+- **Affected:** [Components]
+- **Why Critical:** [Rationale]
+- **Suggested Action:** [Specific action]
+
+### High Priority Issues (HIGH Priority)
+Same format as Critical, grouped by theme.
+
+### Theme Clusters
+For each major theme:
+- **Theme Name** (N issues)
+- **What connects these:** [Pattern]
+- **Root cause:** [If identifiable]
+- **Consolidated actions:** [Bulk actions if applicable]
+- **Issues:** #123, #456, #789
+
+### Relationships & Dependencies
+- **Duplicates:** List pairs with `gh issue close` commands
+- **Related Issues:** Groups of related issues
+- **Dependencies:** Blocking relationships
+
+### Cross-Repo Issues
+Issues that should be migrated to other repositories.
+
+For each, provide:
+```
+gh issue close XXX --repo CURRENT_REPO --comment "This issue belongs in REPO. Please report at https://github.com/TARGET_REPO/issues/new"
+```
+
+### Cleanup Candidates
+- **v4-related:** Deprecated version issues with close commands
+- **Stale:** No activity >30 days
+- **Low priority + old:** Low priority issues >60 days old
+
+### Actionable Next Steps
+Specific, prioritized actions:
+1. [CRITICAL] Fix broken installer - affects all new users
+2. [HIGH] Resolve Windows path escaping issues
+3. [HIGH] Address workflow integration bugs
+etc.
+
+Include `gh` commands where applicable for bulk actions.

.claude/skills/release-module/README.md

@@ -0,0 +1,24 @@
+# release-module
+
+Automates the complete release process for npm modules.
+
+## Usage
+
+Run from project root or pass project path:
+```
+bmad-utility-skills:release-module
+```
+
+## Prerequisite
+
+First run `draft-changelog` to analyze changes and create a draft changelog.
+
+## What It Does
+
+1. Gets and confirms changelog entry
+2. Confirms version bump type (patch/minor/major)
+3. Updates CHANGELOG.md
+4. Bumps version with `npm version`
+5. Pushes git tag
+6. Publishes to npm
+7. Creates GitHub release

.claude/skills/release-module/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: release-module
+description: Automates the complete release process for npm modules - version bump, changelog, git tag, npm publish, GitHub release
+disable-model-invocation: true
+---
+
+Read `prompts/instructions.md` and execute.

.claude/skills/release-module/prompts/instructions.md

@@ -0,0 +1,73 @@
+# Release BMad Module Execution
+
+## Input
+Project path (or run from project root)
+
+## Execution Steps
+
+### Step 1: Get Current State
+- Verify git working tree is clean
+- Get latest tag and current version
+- Check for unpushed commits
+
+### Step 2: Get Changelog Entry
+
+Ask the user for the changelog entry (from draft-changelog skill or manual).
+
+### Step 3: Confirm Changelog
+
+Show project name, current version, proposed next version, and changelog. Get confirmation.
+
+### Step 4: Confirm Version Bump Type
+
+Ask what type of bump: patch, minor, major, prerelease, or custom.
+
+### Step 5: Update CHANGELOG.md
+
+Insert new entry at top, commit, and push.
+
+### Step 6: Bump Version
+
+Run `npm version` to update package.json, create commit, and create tag.
+
+### Step 7: Push Tag
+
+Push the new version tag to GitHub.
+
+### Step 8: Publish to npm
+
+Publish the package.
+
+### Step 9: Create GitHub Release
+
+Create release with changelog notes using `gh release create`.
+
+### Step 10: Create Social Announcement
+
+Create a social media announcement file at `_bmad-output/social/{repo-name}-release.md`.
+
+Format:
+```markdown
+# {name} v{version} Released
+
+## Highlights
+{2-3 bullet points of key features/changes}
+
+## Links
+- GitHub: {release-url}
+- npm: {npm-url}
+```
+
+### Step 11: Confirm Completion
+
+Show npm, GitHub, and social announcement file paths.
+
+## Error Handling
+
+Stop immediately on any step failure. Inform user and suggest fix.
+
+## Important Notes
+
+- Wait for user confirmation before destructive operations
+- Push changelog commit before version bump
+- Use explicit directory paths in commands

.coderabbit.yaml

@@ -11,8 +11,8 @@ reviews:
   walkthrough: false
   poem: false
   auto_review:
-    enabled: false
+    enabled: true
-    drafts: true # Can review drafts. Since it's manually triggered, it's fine.
+    drafts: false # Don't review drafts automatically
     auto_incremental_review: false # always review the whole PR, not just new commits
     base_branches:
       - main

.github/ISSUE_TEMPLATE/bug-report.yaml

@@ -0,0 +1,124 @@
+name: Bug Report
+description: File a bug report to help us improve BMad Method
+title: "[BUG] "
+labels: bug
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing a bug report! Please fill out the information below to help us reproduce and fix the issue.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Clear and concise description of what the bug is
+      placeholder: e.g., When I run /dev-story, it crashes on step 3
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Step-by-step instructions to reproduce the behavior
+      placeholder: |
+        1. Run 'npx bmad-method install'
+        2. Select option X
+        3. Run workflow Y
+        4. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What you expected to happen
+      placeholder: The workflow should complete successfully
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened
+      placeholder: The workflow crashed with error "..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots
+      description: Add screenshots if applicable (paste images directly)
+      placeholder: Paste any relevant screenshots here
+
+  - type: dropdown
+    id: module
+    attributes:
+      label: Which module is this for?
+      description: Select the BMad module this issue relates to
+      options:
+        - BMad Method (BMM) - Core Framework
+        - BMad Builder (BMB) - Agent Builder Tool
+        - Test Architect (TEA) - Test Strategy Module
+        - Game Dev Studio (BMGD) - Game Development Module
+        - Creative Intelligence Suite (CIS) - Innovation Module
+        - Not sure / Other
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: BMad Version
+      description: "Check with: npx bmad-method --version or check package.json"
+      placeholder: e.g., 6.0.0-Beta.4
+    validations:
+      required: true
+
+  - type: dropdown
+    id: ide
+    attributes:
+      label: Which AI IDE are you using?
+      options:
+        - Claude Code
+        - Cursor
+        - Windsurf
+        - Copilot CLI / GitHub Copilot
+        - Kilo Code
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Operating System
+      options:
+        - macOS
+        - Windows
+        - Linux
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Copy and paste any relevant log output
+      render: shell
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Confirm
+      options:
+        - label: I've searched for existing issues
+          required: true
+        - label: I'm using the latest version
+          required: false

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,32 +0,0 @@
----
-name: Bug report
-about: Create a report to help us improve
-title: ''
-labels: ''
-assignees: ''
----
-
-**Describe the bug**
-A clear and concise description of what the bug is.
-
-**Steps to Reproduce**
-What lead to the bug and can it be reliable recreated - if so with what steps.
-
-**PR**
-If you have an idea to fix and would like to contribute, please indicate here you are working on a fix, or link to a proposed PR to fix the issue. Please review the contribution.md - contributions are always welcome!
-
-**Expected behavior**
-A clear and concise description of what you expected to happen.
-
-**Please be Specific if relevant**
-Model(s) Used:
-Agentic IDE Used:
-WebSite Used:
-Project Language:
-BMad Method version:
-
-**Screenshots or Links**
-If applicable, add screenshots or links (if web sharable record) to help explain your problem.
-
-**Additional context**
-Add any other context about the problem here. The more information you can provide, the easier it will be to suggest a fix or resolve

.github/ISSUE_TEMPLATE/config.yaml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
-  - name: Discord Community Support
+  - name: 📚 Documentation
+    url: http://docs.bmad-method.org
+    about: Check the docs first — tutorials, guides, and reference
+  - name: 💬 Discord Community
     url: https://discord.gg/gk8jAdXWmj
-    about: Please join our Discord server for general questions and community discussion before opening an issue.
+    about: Join for questions, discussion, and help before opening an issue

.github/ISSUE_TEMPLATE/documentation.yaml

@@ -0,0 +1,55 @@
+name: Documentation
+description: Report issues or suggest improvements to documentation
+title: "[DOCS] "
+labels: documentation
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Help us improve the BMad Method documentation!
+
+  - type: dropdown
+    id: doc-type
+    attributes:
+      label: What type of documentation issue is this?
+      options:
+        - Error or inaccuracy
+        - Missing information
+        - Unclear or confusing
+        - Outdated content
+        - Request for new documentation
+        - Typo or grammar
+    validations:
+      required: true
+
+  - type: textarea
+    id: location
+    attributes:
+      label: Documentation location
+      description: Where is the documentation that needs improvement?
+      placeholder: e.g., http://docs.bmad-method.org/tutorials/getting-started/ or "In the README"
+    validations:
+      required: true
+
+  - type: textarea
+    id: issue
+    attributes:
+      label: What's the issue?
+      description: Describe the documentation issue in detail
+      placeholder: e.g., Step 3 says to run command X but it should be command Y
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested improvement
+      description: How would you like to see this improved?
+      placeholder: e.g., Change the command to X and add an example
+
+  - type: input
+    id: version
+    attributes:
+      label: BMad Version (if applicable)
+      placeholder: e.g., 6.0.0-Beta.4

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,22 @@
+---
+name: Feature Request
+about: Suggest an idea or new feature
+title: ''
+labels: ''
+assignees: ''
+---
+
+**Describe your idea**
+A clear and concise description of what you'd like to see added or changed.
+
+**Why is this needed?**
+Explain the problem this solves or the benefit it brings to the BMad community.
+
+**How should it work?**
+Describe your proposed solution. If you have ideas on implementation, share them here.
+
+**PR**
+If you'd like to contribute, please indicate you're working on this or link to your PR. Please review [CONTRIBUTING.md](../../CONTRIBUTING.md) — contributions are always welcome!
+
+**Additional context**
+Add any other context, screenshots, or links that help explain your idea.

.github/ISSUE_TEMPLATE/idea_submission.md

@@ -1,109 +0,0 @@
----
-name: V6 Idea Submission
-about: Suggest an idea for v6
-title: ''
-labels: ''
-assignees: ''
----
-
-# Idea: [Replace with a clear, actionable title]
-
-## PASS Framework
-
-**P**roblem:
-
-> What's broken or missing? What pain point are we addressing? (1-2 sentences)
->
-> [Your answer here]
-
-**A**udience:
-
-> Who's affected by this problem and how severely? (1-2 sentences)
->
-> [Your answer here]
-
-**S**olution:
-
-> What will we build or change? How will we measure success? (1-2 sentences with at least 1 measurable outcome)
->
-> [Your answer here]
->
-> [Your Acceptance Criteria for measuring success here]
-
-**S**ize:
-
-> How much effort do you estimate this will take?
->
-> - [ ] **XS** - A few hours
-> - [ ] **S** - 1-2 days
-> - [ ] **M** - 3-5 days
-> - [ ] **L** - 1-2 weeks
-> - [ ] **XL** - More than 2 weeks
-
----
-
-### Metadata
-
-**Submitted by:** [Your name]  
-**Date:** [Today's date]  
-**Priority:** [Leave blank - will be assigned during team review]
-
----
-
-## Examples
-
-<details>
-<summary>Click to see a GOOD example</summary>
-
-### Idea: Add search functionality to customer dashboard
-
-**P**roblem:  
-Customers can't find their past orders quickly. They have to scroll through pages of orders to find what they're looking for, leading to 15+ support tickets per week.
-
-**A**udience:  
-All 5,000+ active customers are affected. Support team spends ~10 hours/week helping customers find orders.
-
-**S**olution:  
-Add a search bar that filters by order number, date range, and product name. Success = 50% reduction in order-finding support tickets within 2 weeks of launch.
-
-**S**ize:
-
-- [x] **M** - 3-5 days
-
-</details>
-
-<details>
-<summary>Click to see a POOR example</summary>
-
-### Idea: Make the app better
-
-**P**roblem:  
-The app needs improvements and updates.
-
-**A**udience:  
-Users
-
-**S**olution:  
-Fix issues and add features.
-
-**S**ize:
-
-- [ ] Unknown
-
-_Why this is poor: Too vague, no specific problem identified, no measurable success criteria, unclear scope_
-
-</details>
-
----
-
-## Tips for Success
-
-1. **Be specific** - Vague problems lead to vague solutions
-2. **Quantify when possible** - Numbers help us prioritize (e.g., "20 customers asked for this" vs "customers want this")
-3. **One idea per submission** - If you have multiple ideas, submit multiple templates
-4. **Success metrics matter** - How will we know this worked?
-5. **Honest sizing** - Better to overestimate than underestimate
-
-## Questions?
-
-Reach out to @OverlordBaconPants if you need help completing this template.

.github/ISSUE_TEMPLATE/issue.md

@@ -0,0 +1,32 @@
+---
+name: Issue
+about: Report a problem or something that's not working
+title: ''
+labels: ''
+assignees: ''
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Steps to reproduce**
+1. What were you doing when the bug occurred?
+2. What steps can recreate the issue?
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Environment (if relevant)**
+- Model(s) used:
+- Agentic IDE used:
+- BMad version:
+- Project language:
+
+**Screenshots or links**
+If applicable, add screenshots or links to help explain the problem.
+
+**PR**
+If you'd like to contribute a fix, please indicate you're working on it or link to your PR. See [CONTRIBUTING.md](../../CONTRIBUTING.md) — contributions are always welcome!
+
+**Additional context**
+Add any other context about the problem here. The more information you provide, the easier it is to help.

.github/workflows/bundle-latest.yaml

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

.github/workflows/discord.yaml

@@ -2,19 +2,9 @@ name: Discord Notification
 
 on:
   pull_request:
-    types: [opened, closed, reopened, ready_for_review]
+    types: [opened, closed]
-  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]
+    types: [opened]
 
 env:
   MAX_TITLE: 100
@@ -47,9 +37,7 @@ jobs:
 
           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" = "closed" ]; then ICON="❌"; LABEL="Closed"; fi
-          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}..."
@@ -77,22 +65,16 @@ jobs:
       - 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)
@@ -102,209 +84,7 @@ jobs:
           BODY=$(printf '%s' "$BODY" | wrap_urls | esc)
           [ -n "$ISSUE_BODY" ] && [ ${#ISSUE_BODY} -gt $MAX_BODY ] && BODY="${BODY}..."
           [ -n "$BODY" ] && BODY=" · $BODY"
-          USER=$(printf '%s' "$USER" | esc)
+          USER=$(printf '%s' "$ISSUE_USER" | esc)
 
-          MSG="$ICON **[$LABEL #$ISSUE_NUM: $TITLE](<$ISSUE_URL>)**"$'\n'"by @$USER$BODY"
+          MSG="🐛 **[Issue #$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)
-          if [ ${#COMMENT_BODY} -gt $MAX_BODY ]; then
-            BODY=$(printf '%s' "$BODY" | strip_trailing_url)
-          fi
-          BODY=$(printf '%s' "$BODY" | wrap_urls | 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)
-          if [ -n "$REVIEW_BODY" ] && [ ${#REVIEW_BODY} -gt $MAX_BODY ]; then
-            BODY=$(printf '%s' "$BODY" | strip_trailing_url)
-          fi
-          BODY=$(printf '%s' "$BODY" | wrap_urls | 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)
-          if [ ${#COMMENT_BODY} -gt $MAX_BODY ]; then
-            BODY=$(printf '%s' "$BODY" | strip_trailing_url)
-          fi
-          BODY=$(printf '%s' "$BODY" | wrap_urls | 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)
-          if [ -n "$RELEASE_BODY" ] && [ ${#RELEASE_BODY} -gt $MAX_BODY ]; then
-            BODY=$(printf '%s' "$BODY" | strip_trailing_url)
-          fi
-          BODY=$(printf '%s' "$BODY" | wrap_urls | 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
-        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/docs.yaml

@@ -39,20 +39,11 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Determine site URL
-        id: site-url
-        run: |
-          if [ "${{ github.repository }}" = "bmad-code-org/BMAD-METHOD" ]; then
-            echo "url=https://bmad-code-org.github.io/BMAD-METHOD" >> $GITHUB_OUTPUT
-          else
-            OWNER="${{ github.repository_owner }}"
-            REPO="${{ github.event.repository.name }}"
-            echo "url=https://${OWNER}.github.io/${REPO}" >> $GITHUB_OUTPUT
-          fi
-
       - name: Build documentation
         env:
-          SITE_URL: ${{ steps.site-url.outputs.url }}
+          # Override site URL from GitHub repo variable if set
+          # Otherwise, astro.config.mjs will compute from GITHUB_REPOSITORY
+          SITE_URL: ${{ vars.SITE_URL }}
         run: npm run docs:build
 
       - name: Upload artifact

.github/workflows/manual-release.yaml

@@ -6,11 +6,11 @@ on:
       version_bump:
         description: Version bump type
         required: true
-        default: alpha
+        default: beta
         type: choice
         options:
-          - alpha
           - beta
+          - alpha
           - patch
           - minor
           - major
@@ -158,9 +158,12 @@ jobs:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           VERSION="${{ steps.version.outputs.new_version }}"
-          if [[ "$VERSION" == *"alpha"* ]] || [[ "$VERSION" == *"beta"* ]]; then
+          if [[ "$VERSION" == *"alpha"* ]]; then
-            echo "Publishing prerelease version with --tag alpha"
+            echo "Publishing alpha prerelease version with --tag alpha"
             npm publish --tag alpha
+          elif [[ "$VERSION" == *"beta"* ]]; then
+            echo "Publishing beta prerelease version with --tag latest"
+            npm publish --tag latest
           else
             echo "Publishing stable version with --tag latest"
             npm publish --tag latest

.github/workflows/quality.yaml

@@ -69,6 +69,27 @@ jobs:
       - name: markdownlint
         run: npm run lint:md
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate documentation links
+        run: npm run docs:validate-links
+
+      - name: Build documentation
+        run: npm run docs:build
+
   validate:
     runs-on: ubuntu-latest
     steps:
@@ -92,3 +113,6 @@ jobs:
 
       - name: Test agent compilation components
         run: npm run test:install
+
+      - name: Validate file references
+        run: npm run validate:refs

.gitignore

@@ -1,12 +1,11 @@
 # Dependencies
-node_modules/
+**/node_modules/
 pnpm-lock.yaml
 bun.lock
 deno.lock
 pnpm-workspace.yaml
 package-lock.json
 
-
 test-output/*
 coverage/
 
@@ -28,11 +27,6 @@ Thumbs.db
 # Development tools and configs
 .prettierrc
 
-# IDE and editor configs
-.windsurf/
-.trae/
-_bmad*/.cursor/
-
 # AI assistant files
 CLAUDE.md
 .ai/*
@@ -43,39 +37,32 @@ CLAUDE.local.md
 .serena/
 .claude/settings.local.json
 
-# Project-specific
-_bmad-core
-_bmad-creator-tools
-test-project-install/*
-sample-project/*
-flattened-codebase.xml
-*.stats.md
-.internal-docs/
-#UAT template testing output files
-tools/template-test-generator/test-scenarios/
-
-# Bundler temporary files and generated bundles
-.bundler-temp/
-
-# Generated web bundles (built by CI, not committed)
-src/modules/bmm/sub-modules/
-src/modules/bmb/sub-modules/
-src/modules/cis/sub-modules/
-src/modules/bmgd/sub-modules/
-shared-modules
 z*/
 
 _bmad
-.claude
+_bmad-output
+.clinerules
+.augment
+.crush
+.cursor
+.iflow
+.opencode
+.qwen
+.rovodev
+.kilocodemodes
+.claude/commands
 .codex
 .github/chatmodes
+.github/agents
 .agent
-.agentvibes/
+.agentvibes
-.kiro/
+.kiro
 .roo
+.trae
+.windsurf
 
-bmad-custom-src/
 
-# Docusaurus / Documentation Build
+# Astro / Documentation Build
-.docusaurus/
+website/.astro/
+website/dist/
 build/

.husky/pre-commit

@@ -5,3 +5,16 @@ npx --no-install lint-staged
 
 # Validate everything
 npm test
+
+# Validate docs links only when docs change
+if command -v rg >/dev/null 2>&1; then
+  if git diff --cached --name-only | rg -q '^docs/'; then
+    npm run docs:validate-links
+		npm run docs:build
+  fi
+else
+  if git diff --cached --name-only | grep -Eq '^docs/'; then
+    npm run docs:validate-links
+		npm run docs:build
+  fi
+fi

.markdownlint-cli2.yaml

@@ -2,7 +2,7 @@
 # https://github.com/DavidAnson/markdownlint-cli2
 
 ignores:
-  - node_modules/**
+  - "**/node_modules/**"
   - test/fixtures/**
   - CODE_OF_CONDUCT.md
   - _bmad/**
@@ -11,7 +11,6 @@ ignores:
   - .claude/**
   - .roo/**
   - .codex/**
-  - .agentvibes/**
   - .kiro/**
   - sample-project/**
   - test-project-install/**

.npmrc

@@ -1 +1,5 @@
-registry=https://registry.npmjs.org
+# Prevent peer dependency warnings during installation
+legacy-peer-deps=true
+
+# Improve install performance
+prefer-offline=true

.vscode/settings.json

@@ -57,6 +57,7 @@
     "tileset",
     "tmpl",
     "Trae",
+    "Unsharded",
     "VNET",
     "webskip"
   ],

CHANGELOG.md

@@ -1,5 +1,476 @@
 # Changelog
 
+## [6.0.0-Beta.5]
+
+### 🎁 Features
+
+* **Add generate-project-context workflow** — New 3-step workflow for project context generation, integrated with quick-flow-solo-dev agent
+* **Shard market research customer analysis** — Refactor monolithic customer insights into 4-step detailed customer behavior analysis workflow
+
+### 🐛 Bug Fixes
+
+* **Fix npm install peer dependency issues** — Add `.npmrc` with `legacy-peer-deps=true`, update Starlight to 0.37.5, and add `--legacy-peer-deps` flag to module installer (PR #1476)
+* **Fix leaked source paths in PRD validation report** — Replace absolute `/src/core/` paths with `{project-root}/_bmad/core/` (#1481)
+* **Fix orphaned market research customer analysis** — Connect step-01-init to step-02-customer-behavior to complete workflow sharding (#1486)
+* **Fix duplicate 2-letter brainstorming code** — Change BS to BSP to resolve conflict with cis Brainstorming module
+* **Fix tech writer sidecar functionality** — Enable proper sidecar operation (#1487)
+* **Fix relative paths in workflow steps** — Correct paths in step-11-polish (#1497) and step-e-04-complete (#1498)
+* **Fix party-mode workflow file extension** — Correct extension in workflow.xml (#1499)
+* **Fix generated slash commands** — Add `disable-model-invocation` to all generated commands (#1501)
+* **Fix agent scan and help CSV files** — Correct module-help.csv entries
+* **Fix HELP_STEP placeholder replacement** — Fix placeholder not replaced in compiled agents, fix hardcoded path, fix single quote (#1437)
+
+### 📚 Documentation
+
+* **Add exact slash commands to Getting Started guide** — Provide precise command examples for users (#1505)
+* **Remove .claude/commands from version control** — Commands are generated, not tracked (#1506)
+
+### 🔧 Maintenance
+
+* **Update Starlight to 0.37.5** — Latest version with peer dependency compatibility
+* **Add GitHub issue templates** — New bug-report.yaml and documentation.yaml templates
+
+---
+
+## [6.0.0-Beta.4]
+
+### 🐛 Bug Fixes
+
+- **Activation steps formatting fix**: Fixed missing opening quote that caused infrequent menu rendering issues
+- **Custom module installation fix**: Added missing yaml require in manifest.js to fix custom module installation
+
+---
+
+## [6.0.0-Beta.3]
+
+### 🌟 Key Highlights
+
+1. **SDET Module Replaces TEA**: TEA module removed from core, SDET module added with "automate" workflow for test automation
+2. **Gemini CLI TOML Support**: IDE integration now supports the TOML config format used by Gemini CLI
+3. **File System Sprint Status**: Default project_key support for file-system based sprint status tracking
+
+### 🔧 Features & Improvements
+
+**Module Changes:**
+- **TEA Module Moved to External** (#1430, #1443): The TEA module is now external. SDET module added with a single "automate" workflow focused on test automation
+- **SDET Module**: New module with streamlined test automation capabilities
+
+**IDE Integration:**
+- **Gemini CLI TOML Format** (#1431): Previous update accidentally switched Gemini to md instead of toml.
+
+**Sprint Status:**
+- **Default project_key** (#1446): File-system based sprint status now uses a default project_key so certain LLMs do not complain
+
+### 🐛 Bug Fixes
+
+- **Quick-flow workflow path fix** (#1368): Fixed incorrect workflow_path in bmad-quick-flow/quick-spec steps (step-01, step-02, step-03) - changed from non-existent 'create-tech-spec' to correct 'quick-spec'
+- **PRD edit flow paths**: Fixed path references in PRD editing workflow
+- **Agent file handling**: Changes to prevent double agent files and use .agent.md file extensions
+- **README link fix**: Corrected broken documentation links
+
+## [6.0.0-Beta.2]
+
+- Fix installer so commands match what is installed, centralize most ide into a central file instead of separate files for each ide.
+- Specific IDEs may still need udpates, but all is config driven now and should be easier to maintain
+- Kiro still needs updates, but its been in this state since contributed, will investigate soon
+- Any version older than Beta.0 will recommend removal and reinstall to project. From later alphas though its sufficient to quick update if still desired, but best is just start fresh with Beta.
+
+## [6.0.0-Beta.1]
+
+**Release: January 2026 - Alpha to Beta Transition**
+
+### 🎉 Beta Release
+
+- **Transition from Alpha to Beta**: BMad Method is now in Beta! This marks a significant milestone in the framework's development
+- **NPM Default Tag**: Beta versions are now published with the `latest` tag, making `npx bmad-method` serve the beta version by default
+
+### 🌟 Key Highlights
+
+1. **bmad-help**: Revolutionary AI-powered guidance system replaces the alpha workflow-init and workflow tracking — introduces full AI intelligence to guide users through workflows, commands, and project context
+2. **Module Ecosystem Expansion**: bmad-builder, CIS (Creative Intelligence Suite), and Game Dev Studio moved to separate repositories for focused development
+3. **Installer Consolidation**: Unified installer architecture with standardized command naming (`bmad-dash-case.md` or `bmad-*-agent-*.md`)
+4. **Windows Compatibility**: Complete migration from Inquirer.js to @clack/prompts for reliable cross-platform support
+
+### 🚀 Major Features
+
+**bmad-help - Intelligent Guidance System:**
+
+- **Replaces**: workflow-init and legacy workflow tracking
+- **AI-Powered**: Full context awareness of installed modules, workflows, agents, and commands
+- **Dynamic Discovery**: Automatically catalogs all available workflows from installed modules
+- **Intelligent Routing**: Guides users to the right workflow or agent based on their goal
+- **IDE Integration**: Generates proper IDE command files for all discovered workflows
+
+**Module Restructuring:**
+
+| Module                                | Status                                            | New Location                                            |
+| ------------------------------------- | ------------------------------------------------- | ------------------------------------------------------- |
+| **bmad-builder**                      | Near beta, with docs and walkthroughs coming soon | `bmad-code-org/bmad-builder`                            |
+| **CIS** (Creative Intelligence Suite) | Published as npm package                          | `bmad-code-org/bmad-module-creative-intelligence-suite` |
+| **Game Dev Studio**                   | Published as npm package                          | `bmad-code-org/bmad-module-game-dev-studio`             |
+
+### 🔧 Installer & CLI Improvements
+
+**UnifiedInstaller Architecture:**
+
+- All IDE installers now use a common `UnifiedInstaller` class
+- Standardized command naming conventions:
+  - Workflows: `bmad-module-workflow-name.md`
+  - Agents: `bmad-module-agent-name.md`
+  - Tasks: `bmad-task-name.md`
+  - Tools: `bmad-tool-name.md`
+- External module installation from npm with progress indicators
+- Module removal on unselect with confirmation
+
+**Windows Compatibility Fix:**
+
+- Replaced Inquirer.js with @clack/prompts to fix arrow key navigation issues on Windows
+- All 91 installer workflows migrated to new prompt system
+
+### 📚 Documentation Updates
+
+**Significant docsite improvements:**
+
+- Interactive workflow guide page (`/workflow-guide`) with track selector
+- TEA documentation restructured using Diátaxis framework (25 docs)
+- Style guide optimized for LLM readers (367 lines, down from 767)
+- Glossary rewritten using table format (123 lines, down from 373)
+- README overhaul with numbered command flows and prominent `/bmad-help` callout
+- New workflow map diagram with interactive HTML
+- New editorial review tasks for document quality
+- E2E testing methodology for Game Dev Studio
+
+More documentation updates coming soon.
+
+### 🐛 Bug Fixes
+
+- Fixed TodoMVC URL references to include `/dist/` path
+- Fixed glob pattern normalization for Windows compatibility
+- Fixed YAML indentation in kilo.js customInstructions field
+- Fixed stale path references in check-implementation-readiness workflow
+- Fixed sprint-status.yaml sync in correct-course workflow
+- Fixed web bundler entry point reference
+- Fixed mergeModuleHelpCatalogs ordering after generateManifests
+
+### 📊 Statistics
+
+- **91 commits** since alpha.23
+- **969 files changed** (+23,716 / -91,509 lines)
+- **Net reduction of ~67,793 lines** through cleanup and consolidation
+- **3 major modules** moved to separate repositories
+- **Complete installer refactor** for standardization
+
+---
+
+## [6.0.0-alpha.23]
+
+**Release: January 11, 2026**
+
+### 🌟 Key Highlights
+
+1. **Astro/Starlight Documentation Platform**: Complete migration from Docusaurus to modern Astro+Starlight for superior performance and customization
+2. **Diataxis Framework Implementation**: Professional documentation restructuring with tutorials, how-to guides, explanations, and references
+3. **Workflow Creator & Validator**: Powerful new tools for workflow creation with subprocess support and PRD validation
+4. **TEA Documentation Expansion**: Comprehensive testing documentation with cheat sheets, MCP enhancements, and API testing patterns
+5. **Brainstorming Revolution**: Research-backed procedural rigor with 100+ idea goal and anti-bias protocols
+6. **Cursor IDE Modernization**: Refactored from rules-based to command-based architecture for better IDE integration
+
+### 📚 Documentation Platform Revolution
+
+**Astro/Starlight Migration:**
+
+- **From Docusaurus to Astro**: Complete platform migration for improved performance, better customization, and modern tooling
+- **Starlight Theme**: Professional documentation theme with dark mode default and responsive design
+- **Build Pipeline Overhaul**: New build-docs.js orchestrates link checking, artifact generation, and Astro build
+- **LLM-Friendly Documentation**: Generated llms.txt and llms-full.txt for AI agent discoverability
+- **Downloadable Source Bundles**: bmad-sources.zip and bmad-prompts.zip for offline use
+
+**Diataxis Framework Implementation:**
+
+- **Four Content Types**: Professional separation into tutorials, how-to guides, explanations, and references
+- **21 Files Migrated**: Phase 1 migration of core documentation to Diataxis structure
+- **42+ Focused Documents**: Phase 2 split of large legacy files into manageable pieces
+- **FAQ Restructuring**: 7 topic-specific FAQ files with standardized format
+- **Tutorial Style Guide**: Comprehensive documentation standards for consistent content creation
+
+**Link Management & Quality:**
+
+- **Site-Relative Links**: Converted 217 links to repo-relative format (/docs/path/file.md)
+- **Link Validation Tools**: New validate-doc-links.js and fix-doc-links.js for maintaining link integrity
+- **Broken Link Fixes**: Resolved ~50 broken internal links across documentation
+- **BMad Acronym Standardization**: Consistent use of "BMad" (Breakthrough Method of Agile AI Driven Development)
+- **SEO Optimization**: Absolute URLs in AI meta tags for better web crawler discoverability
+
+### 🔧 Workflow Creator & Validator (Major Feature)
+
+**Workflow Creation Tool:**
+
+- **Subprocess Support**: Advanced workflows can now spawn subprocesses for complex operations
+- **PRD Validation Step**: New validation step ensures PRD quality before workflow execution
+- **Trimodal Workflow Creation**: Three-mode workflow generation system
+- **Quadrivariate Module Workflow**: Four-variable workflow architecture for enhanced flexibility
+- **Path Violation Checks**: Validator ensures workflows don't violate path constraints
+- **Max Parallel Mode POC**: Proof-of-concept for parallel workflow validation
+
+**Workflow Quality Improvements:**
+
+- **PRD Trimodal Compliance**: PRD workflow now follows trimodal standards
+- **Standardized Step Formatting**: Consistent markdown formatting across workflow and PRD steps
+- **Better Suggested Next Steps**: Improved workflow completion guidance
+- **Variable Naming Standardization**: {project_root} → {project-root} across all workflows
+
+### 🧪 TEA Documentation Expansion
+
+**Comprehensive Testing Guides:**
+
+- **Cheat Sheets**: Quick reference guides for common testing scenarios
+- **MCP Enhancements**: Model Context Protocol improvements for testing workflows
+- **API Testing Patterns**: Best practices for API testing documentation
+- **Design Philosophy Callout**: Clear explanation of TEA's design principles
+- **Context Engineering Glossary**: New glossary entry defining context engineering concepts
+- **Fragment Count Updates**: Accurate documentation of TEA workflow components
+- **Playwright Utils Examples**: Updated code examples for playwright-utils integration
+
+### 💡 Brainstorming Workflow Overhaul
+
+**Research-Backed Procedural Rigor:**
+
+- **100+ Idea Goal**: Emphasis on quantity-first approach to unlock better quality ideas
+- **Anti-Bias Protocol**: Domain pivot every 10 ideas to reduce cognitive biases
+- **Chain-of-Thought Requirements**: Reasoning before idea generation
+- **Simulated Temperature**: Prompts for higher divergence in ideation
+- **Standardized Idea Format**: Quality control template for consistent output
+- **Energy Checkpoints**: Multiple continuation options to maintain creative flow
+
+**Exploration Menu Improvements:**
+
+- **Letter-Based Navigation**: [K/T/A/B/C] options instead of numbers for clarity
+- **Keep/Try/Advanced/Break/Continue**: Clear action options for idea refinement
+- **Universal Facilitation Rules**: Consistent guidelines across all brainstorming steps
+- **Quality Growth Enforcement**: Balance between quantity and quality metrics
+
+### 🖥️ Cursor IDE Modernization
+
+**Command-Based Architecture:**
+
+- **From Rules to Commands**: Complete refactor from rules-based to command-based system
+- **Command Generation**: Automatic generation of task and tool commands
+- **Commands Directory**: New `.cursor/commands/bmad/` structure for generated commands
+- **Cleanup Integration**: Automatic cleanup of old BMAD commands alongside rules
+- **Enhanced Logging**: Better feedback on agents, tasks, tools, and workflow commands generated
+
+### 🤖 Agent System Improvements
+
+**Agent Builder & Validation:**
+
+- **hasSidecar Field**: All agents now indicate sidecar support (true/false)
+- **Validation Enforcement**: hasSidecar now required in agent validation
+- **Better Brownfield Documentation**: Improved brownfield project documentation
+- **Agent Builder Updates**: Agent builder now uses hasSidecar field
+- **Agent Editor Integration**: Editor workflow respects hasSidecar configuration
+
+### 🐛 Bug Fixes & Quality Improvements
+
+**Critical Fixes:**
+
+- **Windows Line Endings**: Resolved CRLF issues causing cross-platform problems
+- **Code-Review File Filtering**: Fixed code-review picking up non-application files
+- **ERR_REQUIRE_ESM Resolution**: Dynamic import for inquirer v9+ compatibility
+- **Project-Context Conflicts**: Allow full project-context usage with conflict precedence
+- **Workflow Paths**: Fixed paths for workflow and sprint status files
+- **Missing Scripts**: Fixed missing scripts from installation
+
+**Workflow & Variable Fixes:**
+
+- **Variable Naming**: Standardized from {project_root} to {project-root} across CIS, BMGD, and BMM modules
+- **Workflow References**: Fixed broken .yaml → .md workflow references
+- **Advanced Elicitation Variables**: Fixed undefined variables in brainstorming
+- **Dependency Format**: Corrected dependency format and added missing frontmatter
+
+**Code Quality:**
+
+- **Dependency Updates**: Bumped qs from 6.14.0 to 6.14.1
+- **CodeRabbit Integration**: Enabled auto-review on new PRs
+- **TEA Fragment Counts**: Updated fragment counts for accuracy
+- **Documentation Links**: Fixed Discord channel references (#general-dev → #bmad-development)
+
+### 🚀 Installation & CLI Improvements
+
+**Installation Enhancements:**
+
+- **Workflow Exclusion**: Ability to exclude workflows from being added as commands
+- **Example Workflow Protection**: Example workflow in workflow builder now excluded from tools
+- **CNAME Configuration**: Added CNAME file for custom domain support
+- **Script Fixes**: All scripts now properly included in installation
+
+### 📊 Statistics
+
+- **27 commits** since alpha.22
+- **217 documentation links** converted to site-relative format
+- **42+ focused documents** created from large legacy files
+- **7 topic-specific FAQ files** with standardized formatting
+- **Complete documentation platform** migrated from Docusaurus to Astro/Starlight
+- **Major workflow tools** added: Creator, Validator with subprocess support
+- **Brainstorming workflow** overhauled with research-backed rigor
+
+---
+
+## [6.0.0-alpha.22]
+
+**Release: December 31, 2025**
+
+### 🌟 Key Highlights
+
+1. **Unified Agent Workflow**: Create, Edit, and Validate workflows consolidated into single powerful agent workflow with separate step paths
+2. **Agent Knowledge System**: Comprehensive data file architecture with persona properties, validation patterns, and crafting principles
+3. **Deep Language Integration**: All sharded progressive workflows now support language choice at every step
+4. **Core Module Documentation**: Extensive docs for core workflows (brainstorming, party mode, advanced elicitation)
+5. **BMAD Core Concepts**: New documentation structure explaining agents, workflows, modules, and installation
+6. **Tech Spec Sharded**: create-tech-spec workflow converted to sharded format with orient-first pattern
+
+### 🤖 Unified Agent Workflow (Major Feature)
+
+**Consolidated Architecture:**
+
+- **Single Workflow, Three Paths**: Create, Edit, and Validate operations unified under `src/modules/bmb/workflows/agent/`
+- **steps-c/**: Create path with 9 comprehensive steps for building new agents
+- **steps-e/**: Edit path with 10 steps for modifying existing agents
+- **steps-v/**: Validate path for standalone agent validation review
+- **data/**: Centralized knowledge base for all agent-building intel
+
+### 📚 Agent Knowledge System
+
+**Data File Architecture:**
+
+Located in `src/modules/bmb/workflows/agent/data/`:
+
+- **agent-metadata.md** (208 lines) - Complete metadata field reference
+- **agent-menu-patterns.md** (233 lines) - Menu design patterns and best practices
+- **agent-compilation.md** (273 lines) - Compilation process documentation
+- **persona-properties.md** (266 lines) - Persona crafting properties and examples
+- **principles-crafting.md** (292 lines) - Core principles for agent design
+- **critical-actions.md** (120 lines) - Critical action patterns
+- **expert-agent-architecture.md** (236 lines) - Expert agent structure
+- **expert-agent-validation.md** (173 lines) - Expert-specific validation
+- **module-agent-validation.md** (124 lines) - Module-specific validation
+- **simple-agent-architecture.md** (204 lines) - Simple agent structure
+- **simple-agent-validation.md** (132 lines) - Simple agent validation
+- **understanding-agent-types.md** (222 lines) - Agent type comparison
+- **brainstorm-context.md** - Brainstorming guidance
+- **communication-presets.csv** - Communication style presets
+
+**Reference Examples:**
+
+- **reference/module-examples/architect.agent.yaml** - Module agent example
+- **reference/simple-examples/commit-poet.agent.yaml** - Simple agent example
+- **journal-keeper/** - Complete sidecar pattern example
+
+**Templates:**
+
+- **templates/simple-agent.template.md** - Simple agent template
+- **templates/expert-agent-template/expert-agent.template.md** - Expert agent template
+- **templates/expert-agent-sidecar/** - Sidecar templates (instructions, memories)
+
+### 🌍 Deep Language Integration
+
+**Progressive Workflow Language Support:**
+
+- **Every Step Biased**: All sharded progressive workflow steps now include language preference context
+- **260+ Files Updated**: Comprehensive language integration across:
+  - Core workflows (brainstorming, party mode, advanced elicitation)
+  - BMB workflows (create-agent, create-module, create-workflow, edit-workflow, etc.)
+  - BMGD workflows (game-brief, gdd, narrative, game-architecture, etc.)
+  - BMM workflows (research, create-ux-design, prd, create-architecture, etc.)
+- **Tested Languages**: Verified working with Spanish and Pirate Speak
+- **Natural Conversations**: AI agents respond in configured language throughout workflow
+
+### 📖 Core Module Documentation
+
+**New Core Documentation Structure:**
+
+`docs/modules/core/`:
+
+- **index.md** - Core module overview
+- **core-workflows.md** - Core workflow documentation
+- **core-tasks.md** - Core task reference
+- **brainstorming.md** (100 lines) - Brainstorming workflow guide
+- **party-mode.md** (50 lines) - Party mode guide
+- **advanced-elicitation.md** (105 lines) - Advanced elicitation techniques
+- **document-sharding-guide.md** (133 lines) - Sharded workflow format guide
+- **global-core-config.md** - Global core configuration reference
+
+**Advanced Elicitation Moved:**
+
+- **From**: `docs/` root
+- **To**: `src/core/workflows/advanced-elicitation/`
+- **Status**: Now a proper core workflow with methods.csv
+
+### 📚 BMAD Core Concepts Documentation
+
+**New Documentation Structure:**
+
+`docs/bmad-core-concepts/`:
+
+- **index.md** - Core concepts introduction
+- **agents.md** (93 lines) - Understanding agents in BMAD
+- **workflows.md** (89 lines) - Understanding workflows in BMAD
+- **modules.md** (76 lines) - Understanding modules (BMM, BMGD, CIS, BMB, Core)
+- **installing/index.md** (77 lines) - Installation guide
+- **installing/upgrading.md** (144 lines) - Upgrading guide
+- **bmad-customization/index.md** - Customization overview
+- **bmad-customization/agents.md** - Agent customization guide
+- **bmad-customization/workflows.md** (30 lines) - Workflow customization guide
+- **web-bundles/index.md** (34 lines) - Web bundle distribution guide
+
+**Documentation Cleanup:**
+
+- **Removed v4-to-v6-upgrade.md** - Outdated upgrade guide
+- **Removed document-sharding-guide.md** from docs root (moved to core)
+- **Removed web-bundles-gemini-gpt-guide.md** - Consolidated into web-bundles/index.md
+- **Removed getting-started/installation.md** - Migrated to bmad-core-concepts
+- **Removed all ide-info/*.md files** - Consolidated into web-bundles documentation
+
+### 🔧 Create-Tech-Spec Sharded Conversion
+
+**Monolithic to Sharded:**
+
+- **From**: Single `workflow.yaml` with `instructions.md`
+- **To**: Sharded `workflow.md` with individual step files
+- **Pattern**: Orient-first approach (understand before investigating)
+
+### 🔨 Additional Improvements
+
+**Workflow Status Path Fixes:**
+
+- **Corrected Discovery Paths**: workflow-status workflows now properly use planning_artifacts and implementation_artifacts
+- **Updated All Path Files**: enterprise-brownfield, enterprise-greenfield, method-brownfield, method-greenfield
+
+**Documentation Updates:**
+
+- **BMB Agent Creation Guide**: Comprehensive 166-line guide for agent creation
+- **Workflow Vendoring Doc**: New 42-line guide on workflow customization and inheritance
+- **Document Project Reference**: Moved from BMM docs to shared location
+- **Workflows Planning Guide**: New 89-line guide for planning workflows
+
+**BMB Documentation Streamlining:**
+
+- **Removed Redundant Docs**: Eliminated duplicate documentation in `src/modules/bmb/docs/`
+- **Step File Rules**: New 469-line comprehensive guide for step file creation
+- **Agent Docs Moved**: Agent architecture and validation docs moved to workflow data/
+
+**Windows Inquirer Fix:**
+
+- **Another Default Addition**: Additional inquirer default value setting for better Windows multiselection support
+
+**Code Quality:**
+
+- **Removed Old BMM README**: Consolidated module documentation
+- **Removed BMM Troubleshooting**: 661-line doc moved to shared location
+- **Removed Enterprise Agentic Development**: 686-line doc consolidated
+- **Removed Scale Adaptive System**: 618-line doc consolidated
+
+---
+
 ## [6.0.0-alpha.21]
 
 **Release: December 27, 2025**

CNAME

@@ -0,0 +1 @@
+docs.bmad-method.org

CONTRIBUTING.md

@@ -1,266 +1,167 @@
 # Contributing to BMad
 
-Thank you for considering contributing to the BMad project! We believe in **Human Amplification, Not Replacement** - bringing out the best thinking in both humans and AI through guided collaboration.
+Thank you for considering contributing! We believe in **Human Amplification, Not Replacement** — bringing out the best thinking in both humans and AI through guided collaboration.
 
-💬 **Discord Community**: Join our [Discord server](https://discord.gg/gk8jAdXWmj) for real-time discussions:
+💬 **Discord**: [Join our community](https://discord.gg/gk8jAdXWmj) for real-time discussions, questions, and collaboration.
 
-- **#general-dev** - Technical discussions, feature ideas, and development questions
+---
-- **#bugs-issues** - Bug reports and issue discussions
 
 ## Our Philosophy
 
-### BMad Core™: Universal Foundation
+BMad strengthens human-AI collaboration through specialized agents and guided workflows. Every contribution should answer: **"Does this make humans and AI better together?"**
 
-BMad Core empowers humans and AI agents working together in true partnership across any domain through our **C.O.R.E. Framework** (Collaboration Optimized Reflection Engine):
+**✅ What we welcome:**
-
+- Enhanced collaboration patterns and workflows
-- **Collaboration**: Human-AI partnership where both contribute unique strengths
+- Improved agent personas and prompts
-- **Optimized**: The collaborative process refined for maximum effectiveness
+- Domain-specific modules leveraging BMad Core
-- **Reflection**: Guided thinking that helps discover better solutions and insights
+- Better planning and context continuity
-- **Engine**: The powerful framework that orchestrates specialized agents and workflows
-
-### BMad Method™: Agile AI-Driven Development
-
-The BMad Method is the flagship bmad module for agile AI-driven software development. It emphasizes thorough planning and solid architectural foundations to provide detailed context for developer agents, mirroring real-world agile best practices.
-
-### Core Principles
-
-**Partnership Over Automation** - AI agents act as expert coaches, mentors, and collaborators who amplify human capability rather than replace it.
-
-**Bidirectional Guidance** - Agents guide users through structured workflows while users push agents with advanced prompting. Both sides actively work to extract better information from each other.
-
-**Systems of Workflows** - BMad Core builds comprehensive systems of guided workflows with specialized agent teams for any domain.
-
-**Tool-Agnostic Foundation** - BMad Core remains tool-agnostic, providing stable, extensible groundwork that adapts to any domain.
-
-## What Makes a Good Contribution?
-
-Every contribution should strengthen human-AI collaboration. Ask yourself: **"Does this make humans and AI better together?"**
-
-**✅ Contributions that align:**
-
-- Enhance universal collaboration patterns
-- Improve agent personas and workflows
-- Strengthen planning and context continuity
-- Increase cross-domain accessibility
-- Add domain-specific modules leveraging BMad Core
-
-**❌ What detracts from our mission:**
 
+**❌ What doesn't fit:**
 - Purely automated solutions that sideline humans
-- Tools that don't improve the partnership
 - Complexity that creates barriers to adoption
 - Features that fragment BMad Core's foundation
 
-## Before You Contribute
+---
 
-### Reporting Bugs
+## Reporting Issues
 
-1. **Check existing issues** first to avoid duplicates
+**ALL bug reports and feature requests MUST go through GitHub Issues.**
-2. **Consider discussing in Discord** (#bugs-issues channel) for quick help
-3. **Use the bug report template** when creating a new issue - it guides you through providing:
-   - Clear bug description
-   - Steps to reproduce
-   - Expected vs actual behavior
-   - Model/IDE/BMad version details
-   - Screenshots or links if applicable
-4. **Indicate if you're working on a fix** to avoid duplicate efforts
 
-### Suggesting Features or New Modules
+### Before Creating an Issue
 
-1. **Discuss first in Discord** (#general-dev channel) - the feature request template asks if you've done this
+1. **Search existing issues** — Use the GitHub issue search to check if your bug or feature has already been reported
-2. **Check existing issues and discussions** to avoid duplicates
+2. **Search closed issues** — Your issue may have been fixed or addressed previously
-3. **Use the feature request template** when creating an issue
+3. **Check discussions** — Some conversations happen in [GitHub Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions)
-4. **Be specific** about why this feature would benefit the BMad community and strengthen human-AI collaboration
 
-### Before Starting Work
+### Bug Reports
+
+After searching, if the bug is unreported, use the [bug report template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=bug_report.md) and include:
+
+- Clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Your environment (model, IDE, BMad version)
+- Screenshots or error messages if applicable
+
+### Feature Requests
+
+After searching, use the [feature request template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=feature_request.md) and explain:
+
+- What the feature is
+- Why it would benefit the BMad community
+- How it strengthens human-AI collaboration
+
+**For community modules**, review [TRADEMARK.md](TRADEMARK.md) for proper naming conventions (e.g., "My Module (BMad Community Module)").
+
+---
+
+## Before Starting Work
 
 ⚠️ **Required before submitting PRs:**
 
-1. **For bugs**: Check if an issue exists (create one using the bug template if not)
+| Work Type     | Requirement                                    |
-2. **For features**: Discuss in Discord (#general-dev) AND create a feature request issue
+| ------------- | ---------------------------------------------- |
-3. **For large changes**: Always open an issue first to discuss alignment
+| Bug fix       | An open issue (create one if it doesn't exist) |
+| Feature       | An open feature request issue                  |
+| Large changes | Discussion via issue first                     |
 
-Please propose small, granular changes! For large or significant changes, discuss in Discord and open an issue first. This prevents wasted effort on PRs that may not align with planned changes.
+**Why?** This prevents wasted effort on work that may not align with project direction.
+
+---
 
 ## Pull Request Guidelines
 
-### Which Branch?
+### Target Branch
 
-**Submit PR's to `main` branch** (critical only):
+Submit PRs to the `main` branch.
 
-- 🚨 Critical bug fixes that break basic functionality
+### PR Size
-- 🔒 Security patches
-- 📚 Fixing dangerously incorrect documentation
-- 🐛 Bugs preventing installation or basic usage
 
-### PR Size Guidelines
+- **Ideal**: 200-400 lines of code changes
+- **Maximum**: 800 lines (excluding generated files)
+- **One feature/fix per PR**
 
-- **Ideal PR size**: 200-400 lines of code changes
+If your change exceeds 800 lines, break it into smaller PRs that can be reviewed independently.
-- **Maximum PR size**: 800 lines (excluding generated files)
-- **One feature/fix per PR**: Each PR should address a single issue or add one feature
-- **If your change is larger**: Break it into multiple smaller PRs that can be reviewed independently
-- **Related changes**: Even related changes should be separate PRs if they deliver independent value
 
-### Breaking Down Large PRs
+### New to Pull Requests?
 
-If your change exceeds 800 lines, use this checklist to split it:
+1. **Fork** the repository
-
+2. **Clone** your fork: `git clone https://github.com/YOUR-USERNAME/bmad-method.git`
-- [ ] Can I separate the refactoring from the feature implementation?
+3. **Create a branch**: `git checkout -b fix/description` or `git checkout -b feature/description`
-- [ ] Can I introduce the new API/interface in one PR and implementation in another?
+4. **Make changes** — keep them focused
-- [ ] Can I split by file or module?
+5. **Commit**: `git commit -m "fix: correct typo in README"`
-- [ ] Can I create a base PR with shared utilities first?
+6. **Push**: `git push origin fix/description`
-- [ ] Can I separate test additions from implementation?
+7. **Open PR** from your fork on GitHub
-- [ ] Even if changes are related, can they deliver value independently?
-- [ ] Can these changes be merged in any order without breaking things?
-
-Example breakdown:
-
-1. PR #1: Add utility functions and types (100 lines)
-2. PR #2: Refactor existing code to use utilities (200 lines)
-3. PR #3: Implement new feature using refactored code (300 lines)
-4. PR #4: Add comprehensive tests (200 lines)
-
-**Note**: PRs #1 and #4 could be submitted simultaneously since they deliver independent value.
-
-### Pull Request Process
-
-#### New to Pull Requests?
-
-If you're new to GitHub or pull requests, here's a quick guide:
-
-1. **Fork the repository** - Click the "Fork" button on GitHub to create your own copy
-2. **Clone your fork** - `git clone https://github.com/YOUR-USERNAME/bmad-method.git`
-3. **Create a new branch** - Never work on `main` directly!
-   ```bash
-   git checkout -b fix/description
-   # or
-   git checkout -b feature/description
-   ```
-4. **Make your changes** - Edit files, keeping changes small and focused
-5. **Commit your changes** - Use clear, descriptive commit messages
-   ```bash
-   git add .
-   git commit -m "fix: correct typo in README"
-   ```
-6. **Push to your fork** - `git push origin fix/description`
-7. **Create the Pull Request** - Go to your fork on GitHub and click "Compare & pull request"
 
 ### PR Description Template
 
-Keep your PR description concise and focused. Use this template:
-
 ```markdown
 ## What
-
 [1-2 sentences describing WHAT changed]
 
 ## Why
-
 [1-2 sentences explaining WHY this change is needed]
-Fixes #[issue number] (if applicable)
+Fixes #[issue number]
 
 ## How
-
+- [2-3 bullets listing HOW you implemented it]
-## [2-3 bullets listing HOW you implemented it]
-
--
 -
 
 ## Testing
-
 [1-2 sentences on how you tested this]
 ```
 
-**Maximum PR description length: 200 words** (excluding code examples if needed)
+**Keep it under 200 words.**
 
-### Good vs Bad PR Descriptions
+### Commit Messages
 
-❌ **Bad Example:**
+Use conventional commits:
-
-> This revolutionary PR introduces a paradigm-shifting enhancement to the system's architecture by implementing a state-of-the-art solution that leverages cutting-edge methodologies to optimize performance metrics...
-
-✅ **Good Example:**
-
-> **What:** Added validation for agent dependency resolution
-> **Why:** Build was failing silently when agents had circular dependencies
-> **How:**
->
-> - Added cycle detection in dependency-resolver.js
-> - Throws clear error with dependency chain
->   **Testing:** Tested with circular deps between 3 agents
-
-### Commit Message Convention
-
-Use conventional commits format:
 
 - `feat:` New feature
 - `fix:` Bug fix
 - `docs:` Documentation only
-- `refactor:` Code change that neither fixes a bug nor adds a feature
+- `refactor:` Code change (no bug/feature)
-- `test:` Adding missing tests
+- `test:` Adding tests
-- `chore:` Changes to build process or auxiliary tools
+- `chore:` Build/tools changes
 
-Keep commit messages under 72 characters.
+Keep messages under 72 characters. Each commit = one logical change.
-
-### Atomic Commits
-
-Each commit should represent one logical change:
-
-- **Do:** One bug fix per commit
-- **Do:** One feature addition per commit
-- **Don't:** Mix refactoring with bug fixes
-- **Don't:** Combine unrelated changes
-
-## What Makes a Good Pull Request?
-
-✅ **Good PRs:**
-
-- Change one thing at a time
-- Have clear, descriptive titles
-- Explain what and why in the description
-- Include only the files that need to change
-- Reference related issue numbers
-
-❌ **Avoid:**
-
-- Changing formatting of entire files
-- Multiple unrelated changes in one PR
-- Copying your entire project/repo into the PR
-- Changes without explanation
-- Working directly on `main` branch
-
-## Common Mistakes to Avoid
-
-1. **Don't reformat entire files** - only change what's necessary
-2. **Don't include unrelated changes** - stick to one fix/feature per PR
-3. **Don't paste code in issues** - create a proper PR instead
-4. **Don't submit your whole project** - contribute specific improvements
-
-## Prompt & Agent Guidelines
-
-- Keep dev agents lean - they need context for coding, not documentation
-- Web/planning agents can be larger with more complex tasks
-- Everything is natural language (markdown) - no code in core framework
-- Use bmad modules for domain-specific features
-- Validate YAML schemas with `npm run validate:schemas` before committing
-
-## Code of Conduct
-
-By participating in this project, you agree to abide by our Code of Conduct. We foster a collaborative, respectful environment focused on building better human-AI partnerships.
-
-## Need Help?
-
-- 💬 Join our [Discord Community](https://discord.gg/gk8jAdXWmj):
-  - **#general-dev** - Technical questions and feature discussions
-  - **#bugs-issues** - Get help with bugs before filing issues
-- 🐛 Report bugs using the [bug report template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=bug_report.md)
-- 💡 Suggest features using the [feature request template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=feature_request.md)
-- 📖 Browse the [GitHub Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions)
 
 ---
 
-**Remember**: We're here to help! Don't be afraid to ask questions. Every expert was once a beginner. Together, we're building a future where humans and AI work better together.
+## What Makes a Good PR?
+
+| ✅ Do                        | ❌ Don't                      |
+| --------------------------- | ---------------------------- |
+| Change one thing per PR     | Mix unrelated changes        |
+| Clear title and description | Vague or missing explanation |
+| Reference related issues    | Reformat entire files        |
+| Small, focused commits      | Copy your whole project      |
+| Work on a branch            | Work directly on `main`      |
+
+---
+
+## Prompt & Agent Guidelines
+
+- Keep dev agents lean — focus on coding context, not documentation
+- Web/planning agents can be larger with complex tasks
+- Everything is natural language (markdown) — no code in core framework
+- Use BMad modules for domain-specific features
+- Validate YAML schemas: `npm run validate:schemas`
+
+---
+
+## Need Help?
+
+- 💬 **Discord**: [Join the community](https://discord.gg/gk8jAdXWmj)
+- 🐛 **Bugs**: Use the [bug report template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=bug_report.md)
+- 💡 **Features**: Use the [feature request template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=feature_request.md)
+
+---
+
+## Code of Conduct
+
+By participating, you agree to abide by our [Code of Conduct](.github/CODE_OF_CONDUCT.md).
 
 ## License
 
-By contributing to this project, you agree that your contributions will be licensed under the same license as the project.
+By contributing, your contributions are licensed under the same MIT License. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor attribution.

CONTRIBUTORS.md

@@ -0,0 +1,32 @@
+# Contributors
+
+BMad Core, BMad Method and BMad and Community BMad Modules are made possible by contributions from our community. We gratefully acknowledge everyone who has helped improve this project.
+
+## How We Credit Contributors
+
+- **Git history** — Every contribution is preserved in the project's commit history
+- **Contributors badge** — See the dynamic contributors list on our [README](README.md)
+- **GitHub contributors graph** — Visual representation at <https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors>
+
+## Becoming a Contributor
+
+Anyone who submits a pull request that is merged becomes a contributor. Contributions include:
+
+- Bug fixes
+- New features or workflows
+- Documentation improvements
+- Bug reports and issue triaging
+- Code reviews
+- Helping others in discussions
+
+There are no minimum contribution requirements — whether it's a one-character typo fix or a major feature, we value all contributions.
+
+## Copyright
+
+The BMad Method project is copyrighted by BMad Code, LLC. Individual contributions are licensed under the same MIT License as the project. Contributors retain authorship credit through Git history and the contributors graph.
+
+---
+
+**Thank you to everyone who has helped make BMad Method better!**
+
+For contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).

LICENSE

@@ -2,6 +2,9 @@ MIT License
 
 Copyright (c) 2025 BMad Code, LLC
 
+This project incorporates contributions from the open source community.
+See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor attribution.
+
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
@@ -21,6 +24,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 TRADEMARK NOTICE:
-BMad™ , BMAD-CORE™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. The use of these 
+BMad™, BMad Method™, and BMad Core™ are trademarks of BMad Code, LLC, covering all
-trademarks in this software does not grant any rights to use the trademarks 
+casings and variations (including BMAD, bmad, BMadMethod, BMAD-METHOD, etc.). The use of
-for any other purpose.
+these trademarks in this software does not grant any rights to use the trademarks
+for any other purpose. See [TRADEMARK.md](TRADEMARK.md) for detailed guidelines.

README.md

@@ -1,245 +1,151 @@
-# BMad Method & BMad Core
+![BMad Method](banner-bmad-method.png)
 
-[![Stable Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=stable)](https://www.npmjs.com/package/bmad-method)
+[![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method)
-[![Alpha Version](https://img.shields.io/npm/v/bmad-method/alpha?color=orange&label=alpha)](https://www.npmjs.com/package/bmad-method)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
 
----
+**Breakthrough Method of Agile AI Driven Development** — An AI-driven agile development framework with 21 specialized agents, 50+ guided workflows, and scale-adaptive intelligence that adjusts from bug fixes to enterprise systems.
 
-<div align="center">
+**100% free and open source.** No paywalls. No gated content. No gated Discord. We believe in empowering everyone, not just those who can pay.
 
-## 🎉 NEW: BMAD V6 Installer - Create & Share Custom Content!
+## Why BMad?
 
-The completely revamped **BMAD V6 installer** now includes built-in support for creating, installing, and sharing custom modules, agents, workflows, templates, and tools! Build your own AI solutions or share them with your team - and real soon, with the whole BMad Community througha verified community sharing portal!
+Traditional AI tools do the thinking for you, producing average results. BMad agents and facilitated workflow act as expert collaborators who guide you through a structured process to bring out your best thinking in partnership with the AI.
 
-**✨ What's New:**
+- **AI Intelligent Help**: Brand new for beta - AI assisted help will guide you from the beginning to the end - just ask for `/bmad-help` after you have installed BMad to your project
+- **Scale-Domain-Adaptive**: Automatically adjusts planning depth and needs based on project complexity, domain and type - a SaaS Mobile Dating App has different planning needs from a diagnostic medical system, BMad adapts and helps you along the way
+- **Structured Workflows**: Grounded in agile best practices across analysis, planning, architecture, and implementation
+- **Specialized Agents**: 12+ domain experts (PM, Architect, Developer, UX, Scrum Master, and more)
+- **Party Mode**: Bring multiple agent personas into one session to plan, troubleshoot, or discuss your project collaboratively, multiple perspectives with maximum fun
+- **Complete Lifecycle**: From brainstorming to deployment, BMad is there with you every step of the way
 
-- 📦 **Streamlined Custom Module Installation** - Package your custom content as installable modules
+## Quick Start
-- 🤖 **Agent & Workflow Sharing** - Distribute standalone agents and workflows
-- 🔄 **Unitary Module Support** - Install individual components without full modules
-- ⚙️ **Dependency Management** - Automatic handling of module dependencies
-- 🛡️ **Update-Safe Customization** - Your custom content persists through updates
 
-**📚 Learn More:**
+**Prerequisites**: [Node.js](https://nodejs.org) v20+
-
-- [**Custom Content Overview**](./docs/custom-content.md) - Discover all supported content types
-- [**Installation Guide**](./docs/custom-content-installation.md) - Learn to create and install custom content
-- [**Detail Content Docs**](./src/modules/bmb/docs/index.md) - Reference details for agents, modules, workflows and the bmad builder
-- [**2 Very simple Custom Modules of questionable quality**](./samples/sample-custom-modules/README.md) - if you want to download and try to install a custom shared module, get an idea of how to bundle and share your own, or create your own personal agents, workflows and modules.
-
-</div>
-
----
-
-## AI-Driven Agile Development That Scales From Bug Fixes to Enterprise
-
-**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)
-
-> **📌 v6 Alpha Status:** Near-beta quality with vastly improved stability. Documentation is being finalized. New videos coming soon to [BMadCode YouTube](https://www.youtube.com/@BMadCode).
-
-## 🎯 Why BMad Method?
-
-Unlike generic AI coding assistants, BMad Method provides **structured, battle-tested workflows** powered by specialized agents who understand agile development. Each agent has deep domain expertise—from product management to architecture to testing—working together seamlessly.
-
-**✨ Key Benefits:**
-
-- **Scale-Adaptive Intelligence** - Automatically adjusts planning depth from bug fixes to enterprise systems
-- **Complete Development Lifecycle** - Analysis → Planning → Architecture → Implementation
-- **Specialized Expertise** - 19 agents with specific roles (PM, Architect, Developer, UX Designer, etc.)
-- **Proven Methodologies** - Built on agile best practices with AI amplification
-- **IDE Integration** - Works with Claude Code, Cursor, Windsurf, VS Code
-
-## 🏗️ The Power of BMad Core
-
-**BMad Method** is actually a sophisticated module built on top of **BMad Core** (**C**ollaboration **O**ptimized **R**eflection **E**ngine). This revolutionary architecture means:
-
-- **BMad Core** provides the universal framework for human-AI collaboration
-- **BMad Method** leverages Core to deliver agile development workflows
-- **BMad Builder** lets YOU create custom modules as powerful as BMad Method itself
-
-With **BMad Builder**, you can architect both simple agents and vastly complex domain-specific modules (legal, medical, finance, education, creative) that will soon be sharable in an **official community marketplace**. Imagine building and sharing your own specialized AI team!
-
-## 📊 See It In Action
-
-<p align="center">
-  <img src="./src/modules/bmm/docs/images/workflow-method-greenfield.svg" alt="BMad Method Workflow" width="100%">
-</p>
-
-<p align="center">
-  <em>Complete BMad Method workflow showing all phases, agents, and decision points</em>
-</p>
-
-## 🚀 Get Started in 3 Steps
-
-### 1. Install BMad Method
 
 ```bash
-# Install v6 Alpha (recommended)
-npx bmad-method@alpha install
-
-# Or stable v4 for production
 npx bmad-method install
 ```
 
-### 2. Initialize Your Project
+Follow the installer prompts, then open your AI IDE (Claude Code, Cursor, Windsurf, etc.) in the project folder.
 
-Load any agent in your IDE and run:
+> **Not sure what to do?** Run `/bmad-help` — it tells you exactly what's next and what's optional. You can also ask it questions like:
 
-```
+ - `/bmad-help How should I build a web app for my TShirt Business that can scale to millions?`
-*workflow-init
+ - `/bmad-help I just finished the architecture, I am not sure what to do next`
-```
 
-This analyzes your project and recommends the right workflow track.
+And the amazing thing is BMad Help evolves depending on what modules you install also!
+ - `/bmad-help Im interested in really exploring creative ways to demo BMad at work, what do you recommend to help plan a great slide deck and compelling narrative?`, and if you have the Creative Intelligence Suite installed, it will offer you different or complimentary advice than if you just have BMad Method Module installed!
 
-### 3. Choose Your Track
+The workflows below show the fastest path to working code. You can also load agents directly for a more structured process, extensive planning, or to learn about agile development practices — the agents guide you with menus, explanations, and elicitation at each step.
 
-BMad Method adapts to your needs with three intelligent tracks:
+### Simple Path (Quick Flow)
 
-| Track              | Use For                   | Planning                | Time to Start |
+Bug fixes, small features, clear scope — 3 commands - 1 Optional Agent:
-| ------------------ | ------------------------- | ----------------------- | ------------- |
-| **⚡ Quick Flow**  | Bug fixes, small features | Tech spec only          | < 5 minutes   |
-| **📋 BMad Method** | Products, platforms       | PRD + Architecture + UX | < 15 minutes  |
-| **🏢 Enterprise**  | Compliance, scale         | Full governance suite   | < 30 minutes  |
 
-> **Not sure?** Run `*workflow-init` and let BMad analyze your project goal.
+1. `/quick-spec` — analyzes your codebase and produces a tech-spec with stories
+2. `/dev-story` — implements each story
+3. `/code-review` — validates quality
 
-## 🔄 How It Works: 4-Phase Methodology
+### Full Planning Path (BMad Method)
 
-BMad Method guides you through a proven development lifecycle:
+Products, platforms, complex features — structured planning then build:
 
-1. **📊 Analysis** (Optional) - Brainstorm, research, and explore solutions
+1. `/product-brief` — define problem, users, and MVP scope
-2. **📝 Planning** - Create PRDs, tech specs, or game design documents
+2. `/create-prd` — full requirements with personas, metrics, and risks
-3. **🏗️ Solutioning** - Design architecture, UX, and technical approach
+3. `/create-architecture` — technical decisions and system design
-4. **⚡ Implementation** - Story-driven development with continuous validation
+4. `/create-epics-and-stories` — break work into prioritized stories
+5. `/sprint-planning` — initialize sprint tracking
+6. **Repeat per story:** `/create-story` → `/dev-story` → `/code-review`
 
-Each phase has specialized workflows and agents working together to deliver exceptional results.
+Every step tells you what's next. Optional phases (brainstorming, research, UX design) are available when you need them — ask `/bmad-help` anytime. For a detailed walkthrough, see the [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/).
 
-## 🤖 Meet Your Team
+## Modules
 
-**12 Specialized Agents** working in concert:
+BMad Method extends with official modules for specialized domains. Modules are available during installation and can be added to your project at any time. After the V6 beta period these will also be available as Plugins and Granular Skills.
 
-| Development | Architecture   | Product       | Leadership     |
+| Module                                | GitHub                                                                                                                            | NPM                                                                                                | Purpose                                                               |
-| ----------- | -------------- | ------------- | -------------- |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| Developer   | Architect      | PM            | Scrum Master   |
+| **BMad Method (BMM)**                 | [bmad-code-org/BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD)                                                         | [bmad-method](https://www.npmjs.com/package/bmad-method)                                           | Core framework with 34+ workflows across 4 development phases         |
-| UX Designer | Test Architect | Analyst       | BMad Master    |
+| **BMad Builder (BMB)**                | [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder)                                                       | [bmad-builder](https://www.npmjs.com/package/bmad-builder)                                         | Create custom BMad agents, workflows, and domain-specific modules     |
-| Tech Writer | Game Architect | Game Designer | Game Developer |
+| **Test Architect (TEA)** 🆕            | [bmad-code-org/tea](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)                                    | [tea](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise)                      | Risk-based test strategy, automation, and release gates (8 workflows) |
+| **Game Dev Studio (BMGD)**            | [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio)                         | [bmad-game-dev-studio](https://www.npmjs.com/package/bmad-game-dev-studio)                         | Game development workflows for Unity, Unreal, and Godot               |
+| **Creative Intelligence Suite (CIS)** | [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) | [bmad-creative-intelligence-suite](https://www.npmjs.com/package/bmad-creative-intelligence-suite) | Innovation, brainstorming, design thinking, and problem-solving       |
 
-**Test Architect** integrates with `@seontechnologies/playwright-utils` for production-ready fixture-based utilities.
+* More modules are coming in the next 2 weeks from BMad Official, and a community marketplace for the installer also will be coming with the final V6 release!
 
-Each agent brings deep expertise and can be customized to match your team's style.
+## Testing Agents
 
-## 📦 What's Included
+BMad provides two testing options to fit your needs:
 
-### Core Modules
+### Quinn (QA) - Built-in
 
-- **BMad Method (BMM)** - Complete agile development framework
+**Quick test automation for rapid coverage**
-  - 12 specialized agents
-  - 34 workflows across 4 phases
-  - Scale-adaptive planning
-  - [→ Documentation Hub](./src/modules/bmm/docs/index.md)
 
-- **BMad Builder (BMB)** - Create custom agents and workflows
+- ✅ **Always available** in BMM module (no separate install)
-  - Build anything from simple agents to complex modules
+- ✅ **Simple**: One workflow (`QA` - Automate)
-  - Create domain-specific solutions (legal, medical, finance, education)
+- ✅ **Beginner-friendly**: Standard test framework patterns
-  - [→ Builder Guide](./src/modules/bmb/docs/index.md)
+- ✅ **Fast**: Generate tests and ship
 
-- **Creative Intelligence Suite (CIS)** - Innovation & problem-solving
+**Use Quinn for:** Small projects, quick coverage, standard patterns
-  - Brainstorming, design thinking, storytelling
-  - 5 creative facilitation workflows
-  - [→ Creative Workflows](./src/modules/cis/docs/index.md)
 
-### Key Features
+### Test Architect (TEA) - Optional Module
 
-- **🎨 Customizable Agents** - Modify personalities, expertise, and communication styles
+**Enterprise-grade test strategy and quality engineering**
-- **🌐 Multi-Language Support** - Separate settings for communication and code output
-- **📄 Document Sharding** - 90% token savings for large projects
-- **🔄 Update-Safe** - Your customizations persist through updates
-- **🚀 Web Bundles** - Use in ChatGPT, Claude Projects, or Gemini Gems
 
-## 📚 Documentation
+- 🆕 **Standalone module** (install separately)
+- 🏗️ **Comprehensive**: 8 workflows covering full test lifecycle
+- 🎯 **Advanced**: Risk-based planning, quality gates, NFR assessment
+- 📚 **Knowledge-driven**: 34 testing patterns and best practices
+- 📖 [Test Architect Documentation](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
 
-### Quick Links
+**Use TEA for:** Enterprise projects, test strategy, compliance, release gates
-
-- **[Quick Start Guide](./src/modules/bmm/docs/quick-start.md)** - 15-minute introduction
-- **[Complete BMM Documentation](./src/modules/bmm/docs/index.md)** - All guides and references
-- **[Agent Customization](./docs/agent-customization-guide.md)** - Personalize your agents
-- **[All Documentation](./docs/index.md)** - Complete documentation index
-
-### For v4 Users
-
-- **[v4 Documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)**
-- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)**
-
-## 💬 Community & Support
-
-- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help, share projects
-- **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs, request features
-- **[YouTube Channel](https://www.youtube.com/@BMadCode)** - Video tutorials and demos
-- **[Web Bundles](https://bmad-code-org.github.io/bmad-bundles/)** - Pre-built agent bundles
-- **[Code of Conduct](.github/CODE_OF_CONDUCT.md)** - Community guidelines
-
-## 🛠️ Development
-
-For contributors working on the BMad codebase:
-
-```bash
-# Run all quality checks
-npm test
-
-# Development commands
-npm run lint:fix      # Fix code style
-npm run format:fix    # Auto-format code
-npm run bundle        # Build web bundles
-```
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.
-
-## What's New in v6
-
-**v6 represents a complete architectural revolution from v4:**
-
-### 🚀 Major Upgrades
-
-- **BMad Core Framework** - Modular architecture enabling custom domain solutions
-- **Scale-Adaptive Intelligence** - Automatic adjustment from bug fixes to enterprise
-- **Visual Workflows** - Beautiful SVG diagrams showing complete methodology
-- **BMad Builder Module** - Create and share your own AI agent teams
-- **50+ Workflows** - Up from 20 in v4, covering every development scenario
-- **19 Specialized Agents** - Enhanced with customizable personalities and expertise
-- **Update-Safe Customization** - Your configs persist through all updates
-- **Web Bundles** - Use agents in ChatGPT, Claude, and Gemini
-- **Multi-Language Support** - Separate settings for communication and code
-- **Document Sharding** - 90% token savings for large projects
-
-### 🔄 For v4 Users
-
-- **[Comprehensive Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Step-by-step migration
-- **[v4 Documentation Archive](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)** - Legacy reference
-- Backwards compatibility where possible
-- Smooth migration path with installer detection
-
-## 📄 License
-
-MIT License - See [LICENSE](LICENSE) for details.
-
-**Trademarks:** BMad™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.
-
-Supported by:&nbsp;&nbsp;<a href="https://m.do.co/c/00f11bd932bb"><img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/SVG/DO_Logo_horizontal_blue.svg" height="24" alt="DigitalOcean" style="vertical-align: middle;"></a>
 
 ---
 
-<p align="center">
+## Documentation
-  <a href="https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors">
-    <img src="https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD" alt="Contributors">
-  </a>
-</p>
 
-<p align="center">
+**[BMad Documentation](http://docs.bmad-method.org)** — Tutorials, how-to guides, concepts, and reference
-  <sub>Built with ❤️ for the human-AI collaboration community</sub>
+**[Test Architect Documentation](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)** — TEA standalone module documentation
-</p>
+
+- [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/)
+- [Upgrading from Previous Versions](http://docs.bmad-method.org/how-to/upgrade-to-v6/)
+- [Test Architect Migration Guide](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/migration/) — Upgrading from BMM-embedded TEA
+
+### For v4 Users
+
+- **[v4 Documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4/docs)**
+- If you need to install V4, you can do this with  `npx bmad-method@4.44.3 install` - similar for any past version.
+
+## Community
+
+- [Discord](https://discord.gg/gk8jAdXWmj) — Get help, share ideas, collaborate
+- [Subscribe on YouTube](https://www.youtube.com/@BMadCode) — Tutorials, master class, and podcast (launching Feb 2025)
+- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) — Bug reports and feature requests
+- [Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions) — Community conversations
+
+## Support BMad
+
+BMad is free for everyone — and always will be. If you'd like to support development:
+
+- ⭐ Please click the star project icon near the top right of this page
+- ☕ [Buy Me a Coffee](https://buymeacoffee.com/bmad) — Fuel the development
+- 🏢 Corporate sponsorship — DM on Discord
+- 🎤 Speaking & Media — Available for conferences, podcasts, interviews (BM on Discord)
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+**BMad** and **BMAD-METHOD** are trademarks of BMad Code, LLC. See [TRADEMARK.md](TRADEMARK.md) for details.
+
+[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors)
+
+See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor information.

SECURITY.md

@@ -0,0 +1,85 @@
+# Security Policy
+
+## Supported Versions
+
+We release security patches for the following versions:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| Latest  | :white_check_mark: |
+| < Latest | :x:               |
+
+We recommend always using the latest version of BMad Method to ensure you have the most recent security updates.
+
+## Reporting a Vulnerability
+
+We take security vulnerabilities seriously. If you discover a security issue, please report it responsibly.
+
+### How to Report
+
+**Do NOT report security vulnerabilities through public GitHub issues.**
+
+Instead, please report them via one of these methods:
+
+1. **GitHub Security Advisories** (Preferred): Use [GitHub's private vulnerability reporting](https://github.com/bmad-code-org/BMAD-METHOD/security/advisories/new) to submit a confidential report.
+
+2. **Discord**: Contact a maintainer directly via DM on our [Discord server](https://discord.gg/gk8jAdXWmj).
+
+### What to Include
+
+Please include as much of the following information as possible:
+
+- Type of vulnerability (e.g., prompt injection, path traversal, etc.)
+- Full paths of source file(s) related to the vulnerability
+- Step-by-step instructions to reproduce the issue
+- Proof-of-concept or exploit code (if available)
+- Impact assessment of the vulnerability
+
+### Response Timeline
+
+- **Initial Response**: Within 48 hours of receiving your report
+- **Status Update**: Within 7 days with our assessment
+- **Resolution Target**: Critical issues within 30 days; other issues within 90 days
+
+### What to Expect
+
+1. We will acknowledge receipt of your report
+2. We will investigate and validate the vulnerability
+3. We will work on a fix and coordinate disclosure timing with you
+4. We will credit you in the security advisory (unless you prefer to remain anonymous)
+
+## Security Scope
+
+### In Scope
+
+- Vulnerabilities in BMad Method core framework code
+- Security issues in agent definitions or workflows that could lead to unintended behavior
+- Path traversal or file system access issues
+- Prompt injection vulnerabilities that bypass intended agent behavior
+- Supply chain vulnerabilities in dependencies
+
+### Out of Scope
+
+- Security issues in user-created custom agents or modules
+- Vulnerabilities in third-party AI providers (Claude, GPT, etc.)
+- Issues that require physical access to a user's machine
+- Social engineering attacks
+- Denial of service attacks that don't exploit a specific vulnerability
+
+## Security Best Practices for Users
+
+When using BMad Method:
+
+1. **Review Agent Outputs**: Always review AI-generated code before executing it
+2. **Limit File Access**: Configure your AI IDE to limit file system access where possible
+3. **Keep Updated**: Regularly update to the latest version
+4. **Validate Dependencies**: Review any dependencies added by generated code
+5. **Environment Isolation**: Consider running AI-assisted development in isolated environments
+
+## Acknowledgments
+
+We appreciate the security research community's efforts in helping keep BMad Method secure. Contributors who report valid security issues will be acknowledged in our security advisories.
+
+---
+
+Thank you for helping keep BMad Method and our community safe.

TRADEMARK.md

@@ -0,0 +1,55 @@
+# Trademark Notice & Guidelines
+
+## Trademark Ownership
+
+The following names and logos are trademarks of BMad Code, LLC:
+
+- **BMad** (word mark, all casings: BMad, bmad, BMAD)
+- **BMad Method** (word mark, includes BMadMethod, BMAD-METHOD, and all variations)
+- **BMad Core** (word mark, includes BMadCore, BMAD-CORE, and all variations)
+- **BMad Code** (word mark)
+- BMad Method logo and visual branding
+- The "Build More, Architect Dreams" tagline
+
+**All casings, stylings, and variations** of the above names (with or without hyphens, spaces, or specific capitalization) are covered by these trademarks.
+
+These trademarks are protected under trademark law and are **not** licensed under the MIT License. The MIT License applies to the software code only, not to the BMad brand identity.
+
+## What This Means
+
+You may:
+
+- Use the BMad software under the terms of the MIT License
+- Refer to BMad to accurately describe compatibility or integration (e.g., "Compatible with BMad Method v6")
+- Link to <https://github.com/bmad-code-org/BMAD-METHOD>
+- Fork the software and distribute your own version under a different name
+
+You may **not**:
+
+- Use "BMad" or any confusingly similar variation as your product name, service name, company name, or domain name
+- Present your product as officially endorsed, approved, or certified by BMad Code, LLC when it is not, without written consent from an authorized representative of BMad Code, LLC
+- Use BMad logos or branding in a way that suggests your product is an official or endorsed BMad product
+- Register domain names, social media handles, or trademarks that incorporate BMad branding
+
+## Examples
+
+| Permitted                                              | Not Permitted                                |
+| ------------------------------------------------------ | -------------------------------------------- |
+| "My workflow tool, compatible with BMad Method"        | "BMadFlow" or "BMad Studio"                  |
+| "An alternative implementation inspired by BMad"       | "BMad Pro" or "BMad Enterprise"              |
+| "My Awesome Healthcare Module (Bmad Community Module)" | "The Official BMad Core Healthcare Module"   |
+| Accurately stating you use BMad as a dependency        | Implying official endorsement or partnership |
+
+## Commercial Use
+
+You may sell products that incorporate or work with BMad software. However:
+
+- Your product must have its own distinct name and branding
+- You must not use BMad trademarks in your marketing, domain names, or product identity
+- You may truthfully describe technical compatibility (e.g., "Works with BMad Method")
+
+## Questions?
+
+If you have questions about trademark usage or would like to discuss official partnership or endorsement opportunities, please reach out:
+
+- **Email**: <contact@bmadcode.com>

docs/404.md

@@ -0,0 +1,9 @@
+---
+title: Page Not Found
+template: splash
+---
+
+
+The page you're looking for doesn't exist or has been moved.
+
+[Return to Home](/docs/index.md)

docs/_STYLE_GUIDE.md

@@ -0,0 +1,367 @@
+---
+title: "Documentation Style Guide"
+---
+
+This project adheres to the [Google Developer Documentation Style Guide](https://developers.google.com/style) and uses [Diataxis](https://diataxis.fr/) to structure content. Only project-specific conventions follow.
+
+## Project-Specific Rules
+
+| Rule                             | Specification                            |
+| -------------------------------- | ---------------------------------------- |
+| No horizontal rules (`---`)      | Fragments reading flow                   |
+| No `####` headers                | Use bold text or admonitions instead     |
+| No "Related" or "Next:" sections | Sidebar handles navigation               |
+| No deeply nested lists           | Break into sections instead              |
+| No code blocks for non-code      | Use admonitions for dialogue examples    |
+| No bold paragraphs for callouts  | Use admonitions instead                  |
+| 1-2 admonitions per section max  | Tutorials allow 3-4 per major section    |
+| Table cells / list items         | 1-2 sentences max                        |
+| Header budget                    | 8-12 `##` per doc; 2-3 `###` per section |
+
+## Admonitions (Starlight Syntax)
+
+```md
+:::tip[Title]
+Shortcuts, best practices
+:::
+
+:::note[Title]
+Context, definitions, examples, prerequisites
+:::
+
+:::caution[Title]
+Caveats, potential issues
+:::
+
+:::danger[Title]
+Critical warnings only — data loss, security issues
+:::
+```
+
+### Standard Uses
+
+| Admonition               | Use For                       |
+| ------------------------ | ----------------------------- |
+| `:::note[Prerequisites]` | Dependencies before starting  |
+| `:::tip[Quick Path]`     | TL;DR summary at document top |
+| `:::caution[Important]`  | Critical caveats              |
+| `:::note[Example]`       | Command/response examples     |
+
+## Standard Table Formats
+
+**Phases:**
+
+```md
+| Phase | Name     | What Happens                                 |
+| ----- | -------- | -------------------------------------------- |
+| 1     | Analysis | Brainstorm, research *(optional)*            |
+| 2     | Planning | Requirements — PRD or tech-spec *(required)* |
+```
+
+**Commands:**
+
+```md
+| Command      | Agent   | Purpose                              |
+| ------------ | ------- | ------------------------------------ |
+| `brainstorm` | Analyst | Brainstorm a new project             |
+| `prd`        | PM      | Create Product Requirements Document |
+```
+
+## Folder Structure Blocks
+
+Show in "What You've Accomplished" sections:
+
+````md
+```
+your-project/
+├── _bmad/                         # BMad configuration
+├── _bmad-output/
+│   ├── PRD.md                     # Your requirements document
+│   └── bmm-workflow-status.yaml   # Progress tracking
+└── ...
+```
+````
+
+## Tutorial Structure
+
+```text
+1. Title + Hook (1-2 sentences describing outcome)
+2. Version/Module Notice (info or warning admonition) (optional)
+3. What You'll Learn (bullet list of outcomes)
+4. Prerequisites (info admonition)
+5. Quick Path (tip admonition - TL;DR summary)
+6. Understanding [Topic] (context before steps - tables for phases/agents)
+7. Installation (optional)
+8. Step 1: [First Major Task]
+9. Step 2: [Second Major Task]
+10. Step 3: [Third Major Task]
+11. What You've Accomplished (summary + folder structure)
+12. Quick Reference (commands table)
+13. Common Questions (FAQ format)
+14. Getting Help (community links)
+15. Key Takeaways (tip admonition)
+```
+
+### Tutorial Checklist
+
+- [ ] Hook describes outcome in 1-2 sentences
+- [ ] "What You'll Learn" section present
+- [ ] Prerequisites in admonition
+- [ ] Quick Path TL;DR admonition at top
+- [ ] Tables for phases, commands, agents
+- [ ] "What You've Accomplished" section present
+- [ ] Quick Reference table present
+- [ ] Common Questions section present
+- [ ] Getting Help section present
+- [ ] Key Takeaways admonition at end
+
+## How-To Structure
+
+```text
+1. Title + Hook (one sentence: "Use the `X` workflow to...")
+2. When to Use This (bullet list of scenarios)
+3. When to Skip This (optional)
+4. Prerequisites (note admonition)
+5. Steps (numbered ### subsections)
+6. What You Get (output/artifacts produced)
+7. Example (optional)
+8. Tips (optional)
+9. Next Steps (optional)
+```
+
+### How-To Checklist
+
+- [ ] Hook starts with "Use the `X` workflow to..."
+- [ ] "When to Use This" has 3-5 bullet points
+- [ ] Prerequisites listed
+- [ ] Steps are numbered `###` subsections with action verbs
+- [ ] "What You Get" describes output artifacts
+
+## Explanation Structure
+
+### Types
+
+| Type              | Example                      |
+| ----------------- | ---------------------------- |
+| **Index/Landing** | `core-concepts/index.md`     |
+| **Concept**       | `what-are-agents.md`         |
+| **Feature**       | `quick-flow.md`              |
+| **Philosophy**    | `why-solutioning-matters.md` |
+| **FAQ**           | `brownfield-faq.md`          |
+
+### General Template
+
+```text
+1. Title + Hook (1-2 sentences)
+2. Overview/Definition (what it is, why it matters)
+3. Key Concepts (### subsections)
+4. Comparison Table (optional)
+5. When to Use / When Not to Use (optional)
+6. Diagram (optional - mermaid, 1 per doc max)
+7. Next Steps (optional)
+```
+
+### Index/Landing Pages
+
+```text
+1. Title + Hook (one sentence)
+2. Content Table (links with descriptions)
+3. Getting Started (numbered list)
+4. Choose Your Path (optional - decision tree)
+```
+
+### Concept Explainers
+
+```text
+1. Title + Hook (what it is)
+2. Types/Categories (### subsections) (optional)
+3. Key Differences Table
+4. Components/Parts
+5. Which Should You Use?
+6. Creating/Customizing (pointer to how-to guides)
+```
+
+### Feature Explainers
+
+```text
+1. Title + Hook (what it does)
+2. Quick Facts (optional - "Perfect for:", "Time to:")
+3. When to Use / When Not to Use
+4. How It Works (mermaid diagram optional)
+5. Key Benefits
+6. Comparison Table (optional)
+7. When to Graduate/Upgrade (optional)
+```
+
+### Philosophy/Rationale Documents
+
+```text
+1. Title + Hook (the principle)
+2. The Problem
+3. The Solution
+4. Key Principles (### subsections)
+5. Benefits
+6. When This Applies
+```
+
+### Explanation Checklist
+
+- [ ] Hook states what document explains
+- [ ] Content in scannable `##` sections
+- [ ] Comparison tables for 3+ options
+- [ ] Diagrams have clear labels
+- [ ] Links to how-to guides for procedural questions
+- [ ] 2-3 admonitions max per document
+
+## Reference Structure
+
+### Types
+
+| Type              | Example               |
+| ----------------- | --------------------- |
+| **Index/Landing** | `workflows/index.md`  |
+| **Catalog**       | `agents/index.md`     |
+| **Deep-Dive**     | `document-project.md` |
+| **Configuration** | `core-tasks.md`       |
+| **Glossary**      | `glossary/index.md`   |
+| **Comprehensive** | `bmgd-workflows.md`   |
+
+### Reference Index Pages
+
+```text
+1. Title + Hook (one sentence)
+2. Content Sections (## for each category)
+   - Bullet list with links and descriptions
+```
+
+### Catalog Reference
+
+```text
+1. Title + Hook
+2. Items (## for each item)
+   - Brief description (one sentence)
+   - **Commands:** or **Key Info:** as flat list
+3. Universal/Shared (## section) (optional)
+```
+
+### Item Deep-Dive Reference
+
+```text
+1. Title + Hook (one sentence purpose)
+2. Quick Facts (optional note admonition)
+   - Module, Command, Input, Output as list
+3. Purpose/Overview (## section)
+4. How to Invoke (code block)
+5. Key Sections (## for each aspect)
+   - Use ### for sub-options
+6. Notes/Caveats (tip or caution admonition)
+```
+
+### Configuration Reference
+
+```text
+1. Title + Hook
+2. Table of Contents (jump links if 4+ items)
+3. Items (## for each config/task)
+   - **Bold summary** — one sentence
+   - **Use it when:** bullet list
+   - **How it works:** numbered steps (3-5 max)
+   - **Output:** expected result (optional)
+```
+
+### Comprehensive Reference Guide
+
+```text
+1. Title + Hook
+2. Overview (## section)
+   - Diagram or table showing organization
+3. Major Sections (## for each phase/category)
+   - Items (### for each item)
+   - Standardized fields: Command, Agent, Input, Output, Description
+4. Next Steps (optional)
+```
+
+### Reference Checklist
+
+- [ ] Hook states what document references
+- [ ] Structure matches reference type
+- [ ] Items use consistent structure throughout
+- [ ] Tables for structured/comparative data
+- [ ] Links to explanation docs for conceptual depth
+- [ ] 1-2 admonitions max
+
+## Glossary Structure
+
+Starlight generates right-side "On this page" navigation from headers:
+
+- Categories as `##` headers — appear in right nav
+- Terms in tables — compact rows, not individual headers
+- No inline TOC — right sidebar handles navigation
+
+### Table Format
+
+```md
+## Category Name
+
+| Term         | Definition                                                                               |
+| ------------ | ---------------------------------------------------------------------------------------- |
+| **Agent**    | Specialized AI persona with specific expertise that guides users through workflows.      |
+| **Workflow** | Multi-step guided process that orchestrates AI agent activities to produce deliverables. |
+```
+
+### Definition Rules
+
+| Do                            | Don't                                       |
+| ----------------------------- | ------------------------------------------- |
+| Start with what it IS or DOES | Start with "This is..." or "A [term] is..." |
+| Keep to 1-2 sentences         | Write multi-paragraph explanations          |
+| Bold term name in cell        | Use plain text for terms                    |
+
+### Context Markers
+
+Add italic context at definition start for limited-scope terms:
+
+- `*Quick Flow only.*`
+- `*BMad Method/Enterprise.*`
+- `*Phase N.*`
+- `*BMGD.*`
+- `*Brownfield.*`
+
+### Glossary Checklist
+
+- [ ] Terms in tables, not individual headers
+- [ ] Terms alphabetized within categories
+- [ ] Definitions 1-2 sentences
+- [ ] Context markers italicized
+- [ ] Term names bolded in cells
+- [ ] No "A [term] is..." definitions
+
+## FAQ Sections
+
+```md
+## Questions
+
+- [Do I always need architecture?](#do-i-always-need-architecture)
+- [Can I change my plan later?](#can-i-change-my-plan-later)
+
+### Do I always need architecture?
+
+Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation.
+
+### Can I change my plan later?
+
+Yes. The SM agent has a `correct-course` workflow for handling scope changes.
+
+**Have a question not answered here?** [Open an issue](...) or ask in [Discord](...).
+```
+
+## Validation Commands
+
+Before submitting documentation changes:
+
+```bash
+npm run docs:fix-links            # Preview link format fixes
+npm run docs:fix-links -- --write # Apply fixes
+npm run docs:validate-links       # Check links exist
+npm run docs:build                # Verify no build errors
+```

docs/agent-customization-guide.md

@@ -1,208 +0,0 @@
-# Agent Customization Guide
-
-Customize BMad agents without modifying core files. All customizations persist through updates.
-
-## Quick Start
-
-**1. Locate Customization Files**
-
-After installation, find agent customization files in:
-
-```
-_bmad/_config/agents/
-├── core-bmad-master.customize.yaml
-├── bmm-dev.customize.yaml
-├── bmm-pm.customize.yaml
-└── ... (one file per installed agent)
-```
-
-**2. Edit Any Agent**
-
-Open the `.customize.yaml` file for the agent you want to modify. All sections are optional - customize only what you need.
-
-**3. Rebuild the Agent**
-
-After editing, IT IS CRITICAL to rebuild the agent to apply changes:
-
-```bash
-npx bmad-method@alpha install # and then select option to compile all agents
-# OR for individual agent only
-npx bmad-method@alpha build <agent-name>
-
-# Examples:
-npx bmad-method@alpha build bmm-dev
-npx bmad-method@alpha build core-bmad-master
-npx bmad-method@alpha build bmm-pm
-```
-
-## What You Can Customize
-
-### Agent Name
-
-Change how the agent introduces itself:
-
-```yaml
-agent:
-  metadata:
-    name: 'Spongebob' # Default: "Amelia"
-```
-
-### Persona
-
-Replace the agent's personality, role, and communication style:
-
-```yaml
-persona:
-  role: 'Senior Full-Stack Engineer'
-  identity: 'Lives in a pineapple (under the sea)'
-  communication_style: 'Spongebob'
-  principles:
-    - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep'
-    - 'Favor composition over inheritance'
-```
-
-**Note:** The persona section replaces the entire default persona (not merged).
-
-### Memories
-
-Add persistent context the agent will always remember:
-
-```yaml
-memories:
-  - 'Works at Krusty Krab'
-  - 'Favorite Celebrity: David Hasslehoff'
-  - 'Learned in Epic 1 that its not cool to just pretend that tests have passed'
-```
-
-### Custom Menu Items
-
-Add your own workflows to the agent's menu:
-
-```yaml
-menu:
-  - trigger: my-workflow
-    workflow: '{project-root}/custom/my-workflow.yaml'
-    description: My custom workflow
-  - trigger: deploy
-    action: '#deploy-prompt'
-    description: Deploy to production
-```
-
-**Don't include:** `*` prefix or `help`/`exit` items - these are auto-injected.
-
-### Critical Actions
-
-Add instructions that execute before the agent starts:
-
-```yaml
-critical_actions:
-  - 'Always check git status before making changes'
-  - 'Use conventional commit messages'
-```
-
-### Custom Prompts
-
-Define reusable prompts for `action="#id"` menu handlers:
-
-```yaml
-prompts:
-  - id: deploy-prompt
-    content: |
-      Deploy the current branch to production:
-      1. Run all tests
-      2. Build the project
-      3. Execute deployment script
-```
-
-## Real-World Examples
-
-**Example 1: Customize Developer Agent for TDD**
-
-```yaml
-# _bmad/_config/agents/bmm-dev.customize.yaml
-agent:
-  metadata:
-    name: 'TDD Developer'
-
-memories:
-  - 'Always write tests before implementation'
-  - 'Project uses Jest and React Testing Library'
-
-critical_actions:
-  - 'Review test coverage before committing'
-```
-
-**Example 2: Add Custom Deployment Workflow**
-
-```yaml
-# _bmad/_config/agents/bmm-dev.customize.yaml
-menu:
-  - trigger: deploy-staging
-    workflow: '{project-root}/_bmad/deploy-staging.yaml'
-    description: Deploy to staging environment
-  - trigger: deploy-prod
-    workflow: '{project-root}/_bmad/deploy-prod.yaml'
-    description: Deploy to production (with approval)
-```
-
-**Example 3: Multilingual Product Manager**
-
-```yaml
-# _bmad/_config/agents/bmm-pm.customize.yaml
-persona:
-  role: 'Bilingual Product Manager'
-  identity: 'Expert in US and LATAM markets'
-  communication_style: 'Clear, strategic, with cultural awareness'
-  principles:
-    - 'Consider localization from day one'
-    - 'Balance business goals with user needs'
-
-memories:
-  - 'User speaks English and Spanish'
-  - 'Target markets: US and Latin America'
-```
-
-## Tips
-
-- **Start Small:** Customize one section at a time and rebuild to test
-- **Backup:** Copy customization files before major changes
-- **Update-Safe:** Your customizations in `_config/` survive all BMad updates
-- **Per-Project:** Customization files are per-project, not global
-- **Version Control:** Consider committing `_config/` to share customizations with your team
-
-## Module vs. Global Config
-
-**Module-Level (Recommended):**
-
-- Customize agents per-project in `_bmad/_config/agents/`
-- Different projects can have different agent behaviors
-
-**Global Config (Coming Soon):**
-
-- Set defaults that apply across all projects
-- Override with project-specific customizations
-
-## Troubleshooting
-
-**Changes not appearing?**
-
-- Make sure you ran `npx bmad-method build <agent-name>` after editing
-- Check YAML syntax is valid (indentation matters!)
-- Verify the agent name matches the file name pattern
-
-**Agent not loading?**
-
-- Check for YAML syntax errors
-- Ensure required fields aren't left empty if you uncommented them
-- Try reverting to the template and rebuilding
-
-**Need to reset?**
-
-- Delete the `.customize.yaml` file
-- Run `npx bmad-method build <agent-name>` to regenerate defaults
-
-## Next Steps
-
-- **[BMM Agents Guide](./modules/bmm/agents-guide)** - Learn about the BMad Method agents
-- **[BMB Create Agent Workflow](./modules/bmb/agents/index)** - Build completely custom agents
-- **[BMM Complete Documentation](./modules/bmm/index)** - Full BMad Method reference

docs/bmgd/game-types.md

@@ -0,0 +1,374 @@
+---
+title: "Game Types Reference"
+---
+
+BMGD supports 24 game type templates. Each adds genre-specific sections to your GDD.
+
+## Game Types
+
+### Action & Combat
+
+#### Action Platformer
+
+Side-scrolling or 3D platforming with combat mechanics.
+
+**Examples:** Hollow Knight, Mega Man, Celeste
+
+**GDD sections:**
+
+- Movement systems (jumps, dashes, wall mechanics)
+- Combat mechanics (melee/ranged, combos)
+- Level design patterns
+- Boss design
+
+#### Shooter
+
+Projectile combat with aiming mechanics.
+
+**Examples:** Doom, Call of Duty, Splatoon
+
+**GDD sections:**
+
+- Weapon systems
+- Aiming and accuracy
+- Enemy AI patterns
+- Level/arena design
+- Multiplayer considerations
+
+#### Fighting
+
+1v1 combat with combos and frame data.
+
+**Examples:** Street Fighter, Tekken, Super Smash Bros.
+
+**GDD sections:**
+
+- Frame data systems
+- Combo mechanics
+- Character movesets
+- Competitive balance
+- Netcode requirements
+
+### Strategy & Tactics
+
+#### Strategy
+
+Resource management with tactical decisions.
+
+**Examples:** StarCraft, Civilization, Europa Universalis
+
+**GDD sections:**
+
+- Resource systems
+- Unit/building design
+- AI opponent behavior
+- Map/scenario design
+- Victory conditions
+
+#### Turn-Based Tactics
+
+Grid-based movement with turn order.
+
+**Examples:** XCOM, Fire Emblem, Into the Breach
+
+**GDD sections:**
+
+- Grid and movement systems
+- Turn order mechanics
+- Cover and positioning
+- Unit progression
+- Procedural mission generation
+
+#### Tower Defense
+
+Wave-based defense with tower placement.
+
+**Examples:** Bloons TD, Kingdom Rush, Plants vs. Zombies
+
+**GDD sections:**
+
+- Tower types and upgrades
+- Wave design and pacing
+- Economy systems
+- Map design patterns
+- Meta-progression
+
+### RPG & Progression
+
+#### RPG
+
+Character progression with stats, inventory, and quests.
+
+**Examples:** Final Fantasy, The Witcher, Baldur's Gate
+
+**GDD sections:**
+
+- Character stats and leveling
+- Inventory and equipment
+- Quest system design
+- Combat system (action/turn-based)
+- Skill trees and builds
+
+#### Roguelike
+
+Procedural generation with permadeath and run-based progression.
+
+**Examples:** Hades, Dead Cells, Spelunky
+
+**GDD sections:**
+
+- Procedural generation rules
+- Permadeath and persistence
+- Run structure and pacing
+- Item/ability synergies
+- Meta-progression systems
+
+#### Metroidvania
+
+Interconnected world with ability gating.
+
+**Examples:** Metroid, Castlevania: Symphony of the Night, Ori
+
+**GDD sections:**
+
+- World map connectivity
+- Ability gating design
+- Backtracking flow
+- Secret and collectible placement
+- Power-up progression
+
+### Narrative & Story
+
+#### Adventure
+
+Story-driven exploration with puzzle elements.
+
+**Examples:** Monkey Island, Myst, Life is Strange
+
+**GDD sections:**
+
+- Puzzle design
+- Narrative delivery
+- Exploration mechanics
+- Dialogue systems
+- Story branching
+
+#### Visual Novel
+
+Narrative choices with branching story.
+
+**Examples:** Doki Doki Literature Club, Phoenix Wright, Steins;Gate
+
+**GDD sections:**
+
+- Branching narrative structure
+- Choice and consequence
+- Character routes
+- UI/presentation
+- Save/load states
+
+#### Text-Based
+
+Text input/output games with parser or choice mechanics.
+
+**Examples:** Zork, 80 Days, Dwarf Fortress (adventure mode)
+
+**GDD sections:**
+
+- Parser or choice systems
+- World model
+- Narrative structure
+- Text presentation
+- Save state management
+
+### Simulation & Management
+
+#### Simulation
+
+Realistic systems with management and building.
+
+**Examples:** SimCity, RollerCoaster Tycoon, The Sims
+
+**GDD sections:**
+
+- Core simulation loops
+- Economy modeling
+- AI agents/citizens
+- Building/construction
+- Failure states
+
+#### Sandbox
+
+Creative freedom with building and minimal objectives.
+
+**Examples:** Minecraft, Terraria, Garry's Mod
+
+**GDD sections:**
+
+- Creation tools
+- Physics/interaction systems
+- Persistence and saving
+- Sharing/community features
+- Optional objectives
+
+### Sports & Racing
+
+#### Racing
+
+Vehicle control with tracks and lap times.
+
+**Examples:** Mario Kart, Forza, Need for Speed
+
+**GDD sections:**
+
+- Vehicle physics model
+- Track design
+- AI opponents
+- Progression/career mode
+- Multiplayer racing
+
+#### Sports
+
+Team-based or individual sports simulation.
+
+**Examples:** FIFA, NBA 2K, Tony Hawk's Pro Skater
+
+**GDD sections:**
+
+- Sport-specific rules
+- Player/team management
+- AI opponent behavior
+- Season/career modes
+- Multiplayer modes
+
+### Multiplayer
+
+#### MOBA
+
+Multiplayer team battles with hero selection.
+
+**Examples:** League of Legends, Dota 2, Smite
+
+**GDD sections:**
+
+- Hero/champion design
+- Lane and map design
+- Team composition
+- Matchmaking
+- Economy (gold/items)
+
+#### Party Game
+
+Local multiplayer with minigames.
+
+**Examples:** Mario Party, Jackbox, Overcooked
+
+**GDD sections:**
+
+- Minigame design patterns
+- Controller support
+- Round/game structure
+- Scoring systems
+- Player count flexibility
+
+### Horror & Survival
+
+#### Survival
+
+Resource gathering with crafting and persistent threats.
+
+**Examples:** Don't Starve, Subnautica, The Forest
+
+**GDD sections:**
+
+- Resource gathering
+- Crafting systems
+- Hunger/health/needs
+- Threat systems
+- Base building
+
+#### Horror
+
+Atmosphere and tension with limited resources.
+
+**Examples:** Resident Evil, Silent Hill, Amnesia
+
+**GDD sections:**
+
+- Fear mechanics
+- Resource scarcity
+- Sound design
+- Lighting and visibility
+- Enemy/threat design
+
+### Casual & Progression
+
+#### Puzzle
+
+Logic-based challenges and problem-solving.
+
+**Examples:** Tetris, Portal, The Witness
+
+**GDD sections:**
+
+- Puzzle mechanics
+- Difficulty progression
+- Hint systems
+- Level structure
+- Scoring/rating
+
+#### Idle/Incremental
+
+Passive progression with upgrades and automation.
+
+**Examples:** Cookie Clicker, Adventure Capitalist, Clicker Heroes
+
+**GDD sections:**
+
+- Core loop design
+- Prestige systems
+- Automation unlocks
+- Number scaling
+- Offline progress
+
+#### Card Game
+
+Deck building with card mechanics.
+
+**Examples:** Slay the Spire, Hearthstone, Magic: The Gathering Arena
+
+**GDD sections:**
+
+- Card design framework
+- Deck building rules
+- Mana/resource systems
+- Rarity and collection
+- Competitive balance
+
+### Rhythm
+
+#### Rhythm
+
+Music synchronization with timing-based gameplay.
+
+**Examples:** Guitar Hero, Beat Saber, Crypt of the NecroDancer
+
+**GDD sections:**
+
+- Note/beat mapping
+- Scoring systems
+- Difficulty levels
+- Music licensing
+- Input methods
+
+## Hybrid Types
+
+Multiple game types can be combined. GDD sections from all selected types are included.
+
+| Hybrid | Components | Combined Sections |
+|--------|------------|-------------------|
+| Action RPG | Action Platformer + RPG | Movement, combat, stats, inventory |
+| Survival Horror | Survival + Horror | Resources, crafting, atmosphere, fear |
+| Roguelike Deckbuilder | Roguelike + Card Game | Run structure, procedural gen, cards |
+| Tactical RPG | Turn-Based Tactics + RPG | Grid movement, stats, progression |
+| Open World Survival | Sandbox + Survival | Building, crafting, exploration |

docs/bmgd/index.md

@@ -0,0 +1,113 @@
+---
+title: "BMGD Quick Guide"
+description: Quick reference for BMad Game Dev Studio
+---
+
+![BMGD Logo](bmgd-logo.png)
+
+# BMGD Quick Guide
+
+BMad Game Dev Studio (BMGD) extends BMM with game-specific capabilities. Developed by game industry veterans, it guides you through product research, technical design, narrative design, and a full epic-driven production cycle.
+
+## Under Construction
+
+Documentation is under heavy construction catching up with the new beta release. We'll have complete documentation up as soon as possible. For now, please ask in the BMGD section of the Discord if you have any questions.
+
+![BMGD Workflow](workflow.jpg)
+
+## Quick Start
+
+**Install → Game Brief → GDD → (Narrative) → Architecture → Build**
+
+BMGD is an optional module installed via BMAD Method: `npx bmad-method install`
+
+See [How-To Reference](#how-to-reference) for commands.
+
+## Development Phases
+
+| Phase | Name | Key Activities |
+|-------|------|----------------|
+| 1 | **Preproduction** | Brainstorm Game, Game Brief, market research |
+| 2 | **Design** | GDD creation, Narrative Design (for story-driven games) |
+| 3 | **Technical** | Game Architecture (engine, systems, patterns) |
+| 4 | **Production** | Sprint planning, story development, code review, testing |
+
+## BMGD Agents
+
+| Agent | Purpose |
+|-------|---------|
+| Game Designer | Game mechanics, balance, player psychology |
+| Game Developer | Implementation with engine-specific patterns |
+| Game Architect | Engine selection, systems design, technical structure |
+| Game Scrum Master | Sprint planning and epic management |
+| Game QA | Playtesting, engine-specific testing, performance profiling |
+| Game Solo Dev | Full-stack game development for solo projects |
+
+## Key Documents
+
+| Document | Purpose |
+|----------|---------|
+| **Game Brief** | Vision, market positioning, fundamentals |
+| **GDD** | Core loop, mechanics, progression, art/audio direction |
+| **Narrative Design** | Story structure, characters, world-building, dialogue |
+| **Architecture** | Engine, systems, patterns, project structure |
+
+## Game Type Templates
+
+BMGD includes 24 game type templates that auto-configure GDD sections:
+
+Action, Adventure, Puzzle, RPG, Strategy, Simulation, Sports, Racing, Fighting, Horror, Platformer, Shooter, and more.
+
+Each template provides genre-specific GDD sections, mechanics patterns, testing considerations, and common pitfalls to avoid.
+
+## Explanation: BMGD vs BMM
+
+### When to Use Each
+
+| Use BMGD for | Use BMM for |
+|--------------|-------------|
+| Video games | Web applications |
+| Interactive experiences | APIs and services |
+| Game prototyping | Mobile apps (non-game) |
+| Game jams | General software projects |
+
+### Phase Mapping
+
+| BMM Phase | BMGD Phase | Key Difference |
+|-----------|------------|----------------|
+| Analysis | Preproduction | Game concepts, Game Brief instead of Product Brief |
+| Planning | Design | GDD instead of PRD; optional Narrative Design |
+| Solutioning | Technical | Focus on engine selection, game-specific patterns |
+| Implementation | Production | Game QA replaces TEA; engine-specific testing |
+
+### Document Differences
+
+| BMM | BMGD | Notes |
+|-----|------|-------|
+| Product Brief | Game Brief | Captures vision, market, fundamentals |
+| PRD | GDD | Includes mechanics, balance, player experience |
+| N/A | Narrative Design | Story, characters, world (story-driven games) |
+| Architecture | Architecture | BMGD version includes engine-specific patterns and considerations |
+
+### Testing Differences
+
+**BMM (TEA):** Web-focused testing with Playwright, Cypress, API testing, E2E for web apps.
+
+**BMGD (Game QA):** Engine-specific frameworks (Unity, Unreal, Godot), gameplay testing, performance profiling, playtest planning, balance validation.
+
+## How-To Reference
+
+| I need to... | Action                                                                                                 |
+|--------------|--------------------------------------------------------------------------------------------------------|
+| Install BMGD | Run `npx bmad-method install` and select BMGD during module installation                               |
+| Start a new game | Run `/bmad-gds-brainstorm-game`, then `/bmad:gds:create-game-brief`                                    |
+| Design my game | Run `/bmad-gds-create-gdd`; add `/bmad:gds:narrative` if story-heavy                                   |
+| Plan architecture | Run `/bmad-gds-game-architecture` with Game Architect                                                  |
+| Build my game | Use Phase 4 production workflows - Run `/bmad-help` to see what's next                       |
+| Test an idea quickly | Use [Quick-Flow](quick-flow-workflows.md) for rapid prototyping |
+
+## Further Reading
+
+- [Game Types Guide](game-types.md)
+- [Quick-Flow Guide](quick-flow-workflows.md)
+

docs/bmgd/quick-flow-workflows.md

@@ -0,0 +1,160 @@
+---
+title: "Quick Flow Workflows"
+---
+
+How to create tech specs and execute implementations with Quick Flow.
+
+## Choosing a Workflow
+
+| Situation | Workflow | Command |
+|-----------|----------|---------|
+| Need to document before implementing | Quick-Spec | `/bmad-gds-quick-spec` |
+| Multiple approaches to evaluate | Quick-Spec | `/bmad-gds-quick-spec` |
+| Have a completed tech-spec | Quick-Dev | `/bmad-gds-quick-dev path/to/spec.md` |
+| Have clear, direct instructions | Quick-Dev | `/bmad-gds-quick-dev` |
+| Building complete game system | Full GDS | `/bmad-gds-workflow-init` |
+| Epic-level features | Full GDS | `/bmad-gds-workflow-init` |
+
+---
+
+## How to Create a Tech Spec (Quick-Spec)
+
+### Step 1: Start the workflow
+
+```bash
+/bmad-gds-quick-spec
+```
+
+### Step 2: Describe your requirement
+
+Provide your feature request. The agent scans the codebase and asks clarifying questions.
+
+**Checkpoint options:**
+- `[a]` Advanced Elicitation - explore requirements deeper
+- `[c]` Continue to investigation
+- `[p]` Party Mode - consult expert agents
+
+### Step 3: Review investigation findings
+
+The agent analyzes the codebase for patterns, constraints, and similar implementations. Review the findings.
+
+**Checkpoint options:**
+- `[c]` Continue to spec generation
+- `[p]` Party Mode - get technical review
+
+### Step 4: Review generated spec
+
+The agent creates an ordered task list with file paths and acceptance criteria. Verify completeness.
+
+**Checkpoint options:**
+- `[c]` Continue to final review
+- `[p]` Party Mode - technical review
+
+### Step 5: Finalize
+
+Confirm the spec meets these standards:
+- Every task has a file path and specific action
+- Tasks ordered by dependency
+- Acceptance criteria in Given/When/Then format
+- No placeholders or TBD sections
+
+**Options:**
+- `[d]` Start Quick-Dev immediately
+- `[done]` Save spec and exit
+
+**Output:** `{planning_artifacts}/tech-spec-{slug}.md`
+
+---
+
+## How to Execute Implementation (Quick-Dev)
+
+### With a Tech-Spec
+
+```bash
+/bmad-gds-quick-dev path/to/tech-spec-feature.md
+```
+
+The agent:
+1. Captures baseline git commit
+2. Loads and validates the spec
+3. Executes tasks in order
+4. Runs self-check
+5. Performs adversarial review
+6. Resolves findings
+7. Validates against acceptance criteria
+
+### With Direct Instructions
+
+```bash
+/bmad-gds-quick-dev
+```
+
+Then describe what you want implemented:
+1. Captures baseline git commit
+2. Evaluates complexity (may suggest planning)
+3. Gathers context from codebase
+4. Executes implementation
+5. Runs self-check and adversarial review
+6. Resolves findings
+
+**Escalation:** If the agent detects complexity (multiple components, system-level scope, uncertainty), it offers:
+- `[t]` Create tech-spec first
+- `[w]` Use full GDS workflow
+- `[e]` Execute anyway
+
+---
+
+## Troubleshooting
+
+### Spec has placeholders or TBD sections
+
+Return to investigation step. Complete missing research, inline all findings, re-run review.
+
+### Workflow lost context mid-step
+
+Check frontmatter for `stepsCompleted`. Resume from last completed step.
+
+### Agent suggested planning but you want to execute
+
+You can override with `[e]`, but document your assumptions. Escalation heuristics exist because planning saves time on complex tasks.
+
+### Tests failing after implementation
+
+Return to the resolve-findings step. Review failures, fix issues, ensure test expectations are correct, re-run full suite.
+
+### Need help
+
+```bash
+/bmad-help
+```
+
+---
+
+## Reference
+
+### File Locations
+
+| File | Location |
+|------|----------|
+| Work in progress | `{implementation_artifacts}/tech-spec-wip.md` |
+| Completed specs | `{planning_artifacts}/tech-spec-{slug}.md` |
+| Archived specs | `{implementation_artifacts}/tech-spec-{slug}-archived-{date}.md` |
+| Workflow files | `_bmad/gds/workflows/gds-quick-flow/` |
+
+### Validation Criteria
+
+**Self-check (before adversarial review):**
+- All tasks/instructions completed
+- Tests written and passing
+- Follows existing patterns
+- No obvious bugs
+- Acceptance criteria met
+- Code is readable
+
+**Adversarial review:**
+- Correctness
+- Security
+- Performance
+- Maintainability
+- Test coverage
+- Error handling

docs/custom-content-installation.md

@@ -1,149 +0,0 @@
-# Custom Content Installation
-
-This guide explains how to create and install custom BMAD content including agents, workflows, and modules. Custom content extends BMAD's functionality with specialized tools and workflows that can be shared across projects or teams.
-
-For detailed information about the different types of custom content available, see [Custom Content](./custom-content.md).
-
-You can find example custom modules in the `samples/sample-custom-modules/` folder of the repository. Download either of the sample folders to try them out.
-
-## Content Types Overview
-
-BMAD Core supports several categories of custom content:
-
-- Custom Stand Alone Modules
-- Custom Add On Modules
-- Custom Global Modules
-- Custom Agents
-- Custom Workflows
-
-## Making Custom Content Installable
-
-### Custom Modules
-
-To create an installable custom module:
-
-1. **Folder Structure**
-   - Create a folder with a short, abbreviated name (e.g., `cis` for Creative Intelligence Suite)
-   - The folder name serves as the module code
-
-2. **Required Files**
-   - Include a `module.yaml` file in the root folder
-   - This file drives the installation process when used by the BMAD installer
-   - Reference existing modules or the BMad Builder for configuration examples
-
-3. **Folder Organization**
-   Follow these conventions for optimal compatibility:
-
-   ```
-   module-code/
-     module.yaml
-     agents/
-     workflows/
-     tools/
-     templates/
-     ...
-   ```
-
-   - `agents/` - Agent definitions
-   - `workflows/` - Workflow definitions
-   - Additional custom folders are supported but following conventions is recommended for agent and workflow discovery
-
-**Note:** Full documentation for global modules and add-on modules will be available as support is finalized.
-
-### Standalone Content (Agents, Workflows, Tasks, Tools, Templates, Prompts)
-
-For standalone content that isn't part of a cohesive module collection, follow this structure:
-
-1. **Module Configuration**
-   - Create a folder with a `module.yaml` file (similar to custom modules)
-   - Add the property `unitary: true` to the module.yaml
-   - The `unitary: true` property indicates this is a collection of potentially unrelated items that don't depend on each other
-
-2. **Folder Structure**
-   Organize content in specific named folders:
-
-   ```
-   module-name/
-     module.yaml        # Contains unitary: true
-     agents/
-     workflows/
-     templates/
-     tools/
-     tasks/
-     prompts/
-   ```
-
-3. **Individual Item Organization**
-   Each item should have its own subfolder:
-   ```text
-   my-custom-stuff/
-     module.yaml
-     agents/
-       larry/larry.agent.md
-       curly/curly.agent.md
-       moe/moe.agent.md
-       moe/moe-sidecar/memories.csv
-   ```
-
-**Future Feature:** Unitary modules will support selective installation, allowing users to pick and choose which specific items to install.
-
-**Note:** Documentation explaining the distinctions between these content types and their specific use cases will be available soon.
-
-## Installation Process
-
-### Prerequisites
-
-Ensure your content follows the proper conventions and includes a `module.yaml` file (only one per top-level folder).
-
-### New Project Installation
-
-When setting up a new BMAD project:
-
-1. The installer will prompt: `Would you like to install a local custom module (this includes custom agents and workflows also)? (y/N)`
-2. Select 'y' to specify the path to your module folder containing `module.yaml`
-
-### Existing Project Modification
-
-To add custom content to an existing BMAD project:
-
-1. Run the installer against your project location
-2. Select `Modify BMAD Installation`
-3. Choose the option to add, modify, or update custom modules
-
-### Upcoming Features
-
-- **Unitary Module Selection:** For modules with `type: unitary` (instead of `type: module`), you'll be able to select specific items to install
-- **Add-on Module Dependencies:** The installer will verify and install dependencies for add-on modules automatically
-
-## Quick Updates
-
-When updates to BMAD Core or core modules (BMM, CIS, etc.) become available, the quick update process will:
-
-1. Apply available updates to core modules
-2. Recompile all agents with customizations from the `_config/agents` folder
-3. Retain your custom content from a cached location
-4. Preserve your existing configurations and customizations
-
-This means you don't need to keep the source module files locally. When updates are available, simply point to the updated module location during the update process.
-
-## Important Considerations
-
-### Module Naming Conflicts
-
-When installing unofficial modules, ensure unique identification to avoid conflicts:
-
-1. **Module Codes:** Each module must have a unique code (e.g., don't use `bmm` for custom modules)
-2. **Module Names:** Avoid using names that conflict with existing modules
-3. **Multiple Custom Modules:** If creating multiple custom modules, use distinct codes for each
-
-**Examples of conflicts to avoid:**
-
-- Don't create a custom module with code `bmm` (already used by BMad Method)
-- Don't name multiple custom modules with the same code like `mca`
-
-### Best Practices
-
-- Use descriptive, unique codes for your modules
-- Document any dependencies your custom modules have
-- Test custom modules in isolation before sharing
-- Consider version numbering for your custom content to track updates

docs/custom-content.md

@@ -1,122 +0,0 @@
-# Custom Content
-
-BMAD supports several categories of officially supported custom content that extend the platform's capabilities. Custom content can be created manually or with the recommended assistance of the BMad Builder (BoMB) Module. The BoMB Agent provides workflows and expertise to plan and build any custom content you can imagine.
-
-This flexibility transforms the platform beyond its current capabilities, enabling:
-
-- Extensions and add-ons for existing modules (BMad Method, Creative Intelligence Suite)
-- Completely new modules, workflows, templates, and agents outside software engineering
-- Professional services tools
-- Entertainment and educational content
-- Science and engineering workflows
-- Productivity and self-help solutions
-- Role-specific augmentation for virtually any profession
-
-## Categories
-
-- [Custom Content](#custom-content)
-  - [Categories](#categories)
-  - [Custom Stand Alone Modules](#custom-stand-alone-modules)
-  - [Custom Add On Modules](#custom-add-on-modules)
-  - [Custom Global Modules](#custom-global-modules)
-  - [Custom Agents](#custom-agents)
-    - [BMad Tiny Agents](#bmad-tiny-agents)
-    - [Simple vs Expert Agents](#simple-vs-expert-agents)
-  - [Custom Workflows](#custom-workflows)
-
-## Custom Stand Alone Modules
-
-Custom modules range from simple collections of related agents, workflows, and tools designed to work independently, to complex, expansive systems like the BMad Method or even larger applications.
-
-Custom modules are [installable](./custom-content-installation.md) using the standard BMAD method and support advanced features:
-
-- Optional user information collection during installation/updates
-- Versioning and upgrade paths
-- Custom installer functions with IDE-specific post-installation handling (custom hooks, subagents, or vendor-specific tools)
-- Ability to bundle specific tools such as MCP, skills, execution libraries, and code
-
-## Custom Add On Modules
-
-Custom Add On Modules contain specific agents, tools, or workflows that expand, modify, or customize another module but cannot exist or install independently. These add-ons provide enhanced functionality while leveraging the base module's existing capabilities.
-
-Examples include:
-
-- Alternative implementation workflows for BMad Method agents
-- Framework-specific support for particular use cases
-- Game development expansions that add new genre-specific capabilities without reinventing existing functionality
-
-Add on modules can include:
-
-- Custom agents with awareness of the target module
-- Access to existing module workflows
-- Tool-specific features such as rulesets, hooks, subprocess prompts, subagents, and more
-
-## Custom Global Modules
-
-Similar to Custom Stand Alone Modules, but designed to add functionality that applies across all installed content. These modules provide cross-cutting capabilities that enhance the entire BMAD ecosystem.
-
-Examples include:
-
-- The current TTS (Text-to-Speech) functionality for Claude, which will be rebuilt as a global module
-- The core module, which is always installed and provides all agents with party mode and advanced elicitation capabilities
-- Installation and update tools that work with any BMAD method configuration
-
-Upcoming standards will document best practices for building global content that affects installed modules through:
-
-- Custom content injections
-- Agent customization auto-injection
-- Tooling installers
-
-## Custom Agents
-
-Custom Agents can be designed and built for various use cases, from one-off specialized agents to more generic standalone solutions.
-
-### BMad Tiny Agents
-
-Personal agents designed for highly specific needs that may not be suitable for sharing. For example, a team management agent living in an Obsidian vault that helps with:
-
-- Team coordination and management
-- Understanding team details and requirements
-- Tracking specific tasks with designated tools
-
-These are simple, standalone files that can be scoped to focus on specific data or paths when integrated into an information vault or repository.
-
-### Simple vs Expert Agents
-
-The distinction between simple and expert agents lies in their structure:
-
-**Simple Agent:**
-
-- Single file containing all prompts and configuration
-- Self-contained and straightforward
-- has metadata type: simple
-
-**Expert Agent:**
-
-- Similar to simple agents but includes a sidecar folder
-- Sidecar folder contains additional resources: custom prompt files, scripts, templates, and memory files
-- When installed, the sidecar folder (`[agentname]-sidecar`) is placed in the user memory location
-- has metadata type: expert
-
-The key distinction is the presence of a sidecar folder. As web and consumer agent tools evolve to support common memory mechanisms, storage formats, and MCP, the writable memory files will adapt to support these evolving standards.
-
-Custom agents can be:
-
-- Used within custom modules
-- Designed as standalone tools
-- Integrated with existing workflows and systems, if this is to be the case, should also include a module: <module name> if a specific module is intended for it to require working with
-
-## Custom Workflows
-
-Workflows are powerful, progressively loading sequence engines capable of performing tasks ranging from simple to complex, including:
-
-- User engagements
-- Business processes
-- Content generation (code, documentation, or other output formats)
-
-A custom workflow created outside of a larger module can still be distributed and used without associated agents through:
-
-- Slash commands
-- Manual command/prompt execution when supported by tools
-
-At its core, a custom workflow is a single or series of prompts designed to achieve a specific outcome.

docs/document-sharding-guide.md

@@ -1,449 +0,0 @@
-# Document Sharding Guide
-
-Comprehensive guide to BMad Method's document sharding system for managing large planning and architecture documents.
-
-## Table of Contents
-
-- [What is Document Sharding?](#what-is-document-sharding)
-- [When to Use Sharding](#when-to-use-sharding)
-- [How Sharding Works](#how-sharding-works)
-- [Using the Shard-Doc Tool](#using-the-shard-doc-tool)
-- [Workflow Support](#workflow-support)
-- [Best Practices](#best-practices)
-- [Examples](#examples)
-
-## What is Document Sharding?
-
-Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`). This enables:
-
-- **Selective Loading** - Workflows load only the sections they need
-- **Reduced Token Usage** - Massive efficiency gains for large projects
-- **Better Organization** - Logical section-based file structure
-- **Maintained Context** - Index file preserves document structure
-
-### Architecture
-
-```
-Before Sharding:
-docs/
-└── PRD.md (large 50k token file)
-
-After Sharding:
-docs/
-└── prd/
-    ├── index.md                    # Table of contents with descriptions
-    ├── overview.md                 # Section 1
-    ├── user-requirements.md        # Section 2
-    ├── technical-requirements.md   # Section 3
-    └── ...                         # Additional sections
-```
-
-## When to Use Sharding
-
-### Ideal Candidates
-
-**Large Multi-Epic Projects:**
-
-- Very large complex PRDs
-- Architecture documents with multiple system layers
-- Epic files with 4+ epics (especially for Phase 4)
-- UX design specs covering multiple subsystems
-
-**Token Thresholds:**
-
-- **Consider sharding**: Documents > 20k tokens
-- **Strongly recommended**: Documents > 40k tokens
-- **Critical for efficiency**: Documents > 60k tokens
-
-### When NOT to Shard
-
-**Small Projects:**
-
-- Single epic projects
-- Level 0-1 projects (tech-spec only)
-- Documents under 10k tokens
-- Quick prototypes
-
-**Frequently Updated Docs:**
-
-- Active work-in-progress documents
-- Documents updated daily
-- Documents where whole-file context is essential
-
-## How Sharding Works
-
-### Sharding Process
-
-1. **Tool Execution**: Run `npx @kayvan/markdown-tree-parser source.md destination/` - this is abstracted with the core shard-doc task which is installed as a slash command or manual task rule depending on your tools.
-2. **Section Extraction**: Tool splits by level 2 headings
-3. **File Creation**: Each section becomes a separate file
-4. **Index Generation**: `index.md` created with structure and descriptions
-
-### Workflow Discovery
-
-BMad workflows use a **dual discovery system**:
-
-1. **Try whole document first** - Look for `document-name.md`
-2. **Check for sharded version** - Look for `document-name/index.md`
-3. **Priority rule** - Whole document takes precedence if both exist
-
-### Loading Strategies
-
-**Full Load (Phase 1-3 workflows):**
-
-```
-If sharded:
-  - Read index.md
-  - Read ALL section files
-  - Treat as single combined document
-```
-
-**Selective Load (Phase 4 workflows):**
-
-```
-If sharded epics and working on Epic 3:
-  - Read epics/index.md
-  - Load ONLY epics/epic-3.md
-  - Skip all other epic files
-  - 90%+ token savings!
-```
-
-## Using the Shard-Doc Tool
-
-### CLI Command
-
-```bash
-# Activate bmad-master or analyst agent, then:
-/shard-doc
-```
-
-### Interactive Process
-
-```
-Agent: Which document would you like to shard?
-User: docs/PRD.md
-
-Agent: Default destination: docs/prd/
-       Accept default? [y/n]
-User: y
-
-Agent: Sharding PRD.md...
-       ✓ Created 12 section files
-       ✓ Generated index.md
-       ✓ Complete!
-```
-
-### What Gets Created
-
-**index.md structure:**
-
-```markdown
-# PRD - Index
-
-## Sections
-
-1. [Overview](./overview.md) - Project vision and objectives
-2. [User Requirements](./user-requirements.md) - Feature specifications
-3. [Epic 1: Authentication](./epic-1-authentication.md) - User auth system
-4. [Epic 2: Dashboard](./epic-2-dashboard.md) - Main dashboard UI
-   ...
-```
-
-**Individual section files:**
-
-- Named from heading text (kebab-case)
-- Contains complete section content
-- Preserves all markdown formatting
-- Can be read independently
-
-## Workflow Support
-
-### Universal Support
-
-**All BMM workflows support both formats:**
-
-- ✅ Whole documents
-- ✅ Sharded documents
-- ✅ Automatic detection
-- ✅ Transparent to user
-
-### Workflow-Specific Patterns
-
-#### Phase 1-3 (Full Load)
-
-Workflows load entire sharded documents:
-
-- `product-brief` - Research, brainstorming docs
-- `prd` - Product brief, research
-- `gdd` - Game brief, research
-- `create-ux-design` - PRD, brief, architecture (if available)
-- `tech-spec` - Brief, research
-- `architecture` - PRD, UX design (if available)
-- `create-epics-and-stories` - PRD, architecture
-- `implementation-readiness` - All planning docs
-
-#### Phase 4 (Selective Load)
-
-Workflows load only needed sections:
-
-**sprint-planning** (Full Load):
-
-- Needs ALL epics to build complete status
-
-**create-story, code-review** (Selective):
-
-```
-Working on Epic 3, Story 2:
-  ✓ Load epics/epic-3.md only
-  ✗ Skip epics/epic-1.md, epic-2.md, epic-4.md, etc.
-
-Result: 90%+ token reduction for 10-epic projects!
-```
-
-### Input File Patterns
-
-Workflows use standardized patterns:
-
-```yaml
-input_file_patterns:
-  prd:
-    whole: '{output_folder}/*prd*.md'
-    sharded: '{output_folder}/*prd*/index.md'
-
-  epics:
-    whole: '{output_folder}/*epic*.md'
-    sharded_index: '{output_folder}/*epic*/index.md'
-    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md'
-```
-
-## Best Practices
-
-### Sharding Strategy
-
-**Do:**
-
-- ✅ Shard after planning phase complete
-- ✅ Keep level 2 headings well-organized
-- ✅ Use descriptive section names
-- ✅ Shard before Phase 4 implementation
-- ✅ Keep original file as backup initially
-
-**Don't:**
-
-- ❌ Shard work-in-progress documents
-- ❌ Shard small documents (<20k tokens)
-- ❌ Mix sharded and whole versions
-- ❌ Manually edit index.md structure
-
-### Naming Conventions
-
-**Good Section Names:**
-
-```markdown
-## Epic 1: User Authentication
-
-## Technical Requirements
-
-## System Architecture
-
-## UX Design Principles
-```
-
-**Poor Section Names:**
-
-```markdown
-## Section 1
-
-## Part A
-
-## Details
-
-## More Info
-```
-
-### File Management
-
-**When to Re-shard:**
-
-- Significant structural changes to document
-- Adding/removing major sections
-- After major refactoring
-
-**Updating Sharded Docs:**
-
-1. Edit individual section files directly
-2. OR edit original, delete sharded folder, re-shard
-3. Don't manually edit index.md
-
-## Examples
-
-### Example 1: Large PRD
-
-**Scenario:** 15-epic project, PRD is 45k tokens
-
-**Before Sharding:**
-
-```
-Every workflow loads entire 45k token PRD
-Architecture workflow: 45k tokens
-UX design workflow: 45k tokens
-```
-
-**After Sharding:**
-
-```bash
-/shard-doc
-Source: docs/PRD.md
-Destination: docs/prd/
-
-Created:
-  prd/index.md
-  prd/overview.md (3k tokens)
-  prd/functional-requirements.md (8k tokens)
-  prd/non-functional-requirements.md (6k tokens)
-  prd/user-personas.md (4k tokens)
-  ...additional FR/NFR sections
-```
-
-**Result:**
-
-```
-Architecture workflow: Can load specific sections needed
-UX design workflow: Can load specific sections needed
-Significant token reduction for large requirement docs!
-```
-
-### Example 2: Sharding Epics File
-
-**Scenario:** 8 epics with detailed stories, 35k tokens total
-
-```bash
-/shard-doc
-Source: docs/bmm-epics.md
-Destination: docs/epics/
-
-Created:
-  epics/index.md
-  epics/epic-1.md
-  epics/epic-2.md
-  ...
-  epics/epic-8.md
-```
-
-**Efficiency Gain:**
-
-```
-Working on Epic 5 stories:
-  Old: Load all 8 epics (35k tokens)
-  New: Load epic-5.md only (4k tokens)
-  Savings: 88% reduction
-```
-
-### Example 3: Architecture Document
-
-**Scenario:** Multi-layer system architecture, 28k tokens
-
-```bash
-/shard-doc
-Source: docs/architecture.md
-Destination: docs/architecture/
-
-Created:
-  architecture/index.md
-  architecture/system-overview.md
-  architecture/frontend-architecture.md
-  architecture/backend-services.md
-  architecture/data-layer.md
-  architecture/infrastructure.md
-  architecture/security-architecture.md
-```
-
-**Benefit:** Code-review workflow can reference specific architectural layers without loading entire architecture doc.
-
-## Custom Workflow Integration
-
-### For Workflow Builders
-
-When creating custom workflows that load large documents:
-
-**1. Add input_file_patterns to workflow.yaml:**
-
-```yaml
-input_file_patterns:
-  your_document:
-    whole: '{output_folder}/*your-doc*.md'
-    sharded: '{output_folder}/*your-doc*/index.md'
-```
-
-**2. Add discovery instructions to instructions.md:**
-
-```markdown
-## Document Discovery
-
-1. Search for whole document: _your-doc_.md
-2. Check for sharded version: _your-doc_/index.md
-3. If sharded: Read index + ALL sections (or specific sections if selective load)
-4. Priority: Whole document first
-```
-
-**3. Choose loading strategy:**
-
-- **Full Load**: Read all sections when sharded
-- **Selective Load**: Read only relevant sections (requires section identification logic)
-
-### Pattern Templates
-
-**Full Load Pattern:**
-
-```xml
-<action>Search for document: {output_folder}/*doc-name*.md</action>
-<action>If not found, check for sharded: {output_folder}/*doc-name*/index.md</action>
-<action if="sharded found">Read index.md to understand structure</action>
-<action if="sharded found">Read ALL section files listed in index</action>
-<action if="sharded found">Combine content as single document</action>
-```
-
-**Selective Load Pattern (with section ID):**
-
-```xml
-<action>Determine section needed (e.g., epic_num = 3)</action>
-<action>Check for sharded version: {output_folder}/*doc-name*/index.md</action>
-<action if="sharded found">Read ONLY the specific section file needed</action>
-<action if="sharded found">Skip all other section files</action>
-```
-
-## Troubleshooting
-
-### Common Issues
-
-**Both whole and sharded exist:**
-
-- Workflows will use whole document (priority rule)
-- Delete or archive the one you don't want
-
-**Index.md out of sync:**
-
-- Delete sharded folder
-- Re-run shard-doc on original
-
-**Workflow can't find document:**
-
-- Check file naming matches patterns (`*prd*.md`, `*epic*.md`, etc.)
-- Verify index.md exists in sharded folder
-- Check output_folder path in config
-
-**Sections too granular:**
-
-- Combine sections in original document
-- Use fewer level 2 headings
-- Re-shard
-
-## Related Documentation
-
-- [shard-doc Tool](../src/core/tools/shard-doc.xml) - Tool implementation
-- [BMM Workflows Guide](./modules/bmm/index.md#-workflow-guides) - Workflow overview
-- [Workflow Creation Guide](./modules/bmb/workflows/index) - Custom workflow patterns
-
----
-
-**Document sharding is optional but powerful** - use it when efficiency matters for large projects!

docs/downloads.md

@@ -0,0 +1,74 @@
+---
+title: Downloads
+---
+
+Download BMad Method resources for offline use, AI training, or integration.
+
+## Source Bundles
+
+Download these from the `downloads/` folder on the documentation site.
+
+| File               | Description                     |
+| ------------------ | ------------------------------- |
+| `bmad-sources.zip` | Complete BMad source files      |
+| `bmad-prompts.zip` | Agent and workflow prompts only |
+
+## LLM-Optimized Files
+
+These files are designed for AI consumption - perfect for loading into Claude, ChatGPT, or any LLM context window. See [API Access](#api-access) below for URLs.
+
+| File            | Description                         | Use Case                   |
+| --------------- | ----------------------------------- | -------------------------- |
+| `llms.txt`      | Documentation index with summaries  | Quick overview, navigation |
+| `llms-full.txt` | Complete documentation concatenated | Full context loading       |
+
+### Using with LLMs
+
+**Claude Projects:**
+```
+Upload llms-full.txt as project knowledge
+```
+
+**ChatGPT:**
+```
+Paste llms.txt for navigation, or sections from llms-full.txt as needed
+```
+
+**API Usage:**
+```python
+import requests
+docs = requests.get("https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt").text
+# Include in your system prompt or context
+```
+
+## Installation Options
+
+```bash
+npx bmad-method install
+```
+
+[More details](/docs/how-to/install-bmad.md)
+
+## Version Information
+
+- **Current Version:** See [CHANGELOG](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md)
+- **Release Notes:** Available on [GitHub Releases](https://github.com/bmad-code-org/BMAD-METHOD/releases)
+
+## API Access
+
+For programmatic access to BMad documentation:
+
+```bash
+# Get documentation index
+curl https://bmad-code-org.github.io/BMAD-METHOD/llms.txt
+
+# Get full documentation
+curl https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
+```
+
+## Contributing
+
+Want to improve BMad Method? Check out:
+
+- [Contributing Guide](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md)
+- [GitHub Repository](https://github.com/bmad-code-org/BMAD-METHOD)

docs/explanation/advanced-elicitation.md

@@ -0,0 +1,24 @@
+---
+title: "Advanced Elicitation"
+description: Push the LLM to rethink its work using structured reasoning methods
+---
+
+Make the LLM reconsider what it just generated. You pick a reasoning method, it applies that method to its own output, you decide whether to keep the improvements.
+
+Dozens of methods are built in - things like First Principles, Red Team vs Blue Team, Pre-mortem Analysis, Socratic Questioning, and more.
+
+## When to Use It
+
+- After a workflow generates content and you want alternatives
+- When output seems okay but you suspect there's more depth
+- To stress-test assumptions or find weaknesses
+- For high-stakes content where rethinking helps
+
+Workflows offer advanced elicitation at decision points - after the LLM has generated something, you'll be asked if you want to run it.
+
+## How It Works
+
+1. LLM suggests 5 relevant methods for your content
+2. You pick one (or reshuffle for different options)
+3. Method is applied, improvements shown
+4. Accept or discard, repeat or continue

docs/explanation/adversarial-review.md

@@ -0,0 +1,57 @@
+---
+title: "Adversarial Review"
+description: Forced reasoning technique that prevents lazy "looks good" reviews
+---
+
+Force deeper analysis by requiring problems to be found.
+
+## What is Adversarial Review?
+
+A review technique where the reviewer *must* find issues. No "looks good" allowed. The reviewer adopts a cynical stance - assume problems exist and find them.
+
+This isn't about being negative. It's about forcing genuine analysis instead of a cursory glance that rubber-stamps whatever was submitted.
+
+**The core rule:** You must find issues. Zero findings triggers a halt - re-analyze or explain why.
+
+## Why It Works
+
+Normal reviews suffer from confirmation bias. You skim the work, nothing jumps out, you approve it. The "find problems" mandate breaks this pattern:
+
+- **Forces thoroughness** - Can't approve until you've looked hard enough to find issues
+- **Catches missing things** - "What's not here?" becomes a natural question
+- **Improves signal quality** - Findings are specific and actionable, not vague concerns
+- **Information asymmetry** - Run reviews with fresh context (no access to original reasoning) so you evaluate the artifact, not the intent
+
+## Where It's Used
+
+Adversarial review appears throughout BMAD workflows - code review, implementation readiness checks, spec validation, and others. Sometimes it's a required step, sometimes optional (like advanced elicitation or party mode). The pattern adapts to whatever artifact needs scrutiny.
+
+## Human Filtering Required
+
+Because the AI is *instructed* to find problems, it will find problems - even when they don't exist. Expect false positives: nitpicks dressed as issues, misunderstandings of intent, or outright hallucinated concerns.
+
+**You decide what's real.** Review each finding, dismiss the noise, fix what matters.
+
+## Example
+
+Instead of:
+
+> "The authentication implementation looks reasonable. Approved."
+
+An adversarial review produces:
+
+> 1. **HIGH** - `login.ts:47` - No rate limiting on failed attempts
+> 2. **HIGH** - Session token stored in localStorage (XSS vulnerable)
+> 3. **MEDIUM** - Password validation happens client-side only
+> 4. **MEDIUM** - No audit logging for failed login attempts
+> 5. **LOW** - Magic number `3600` should be `SESSION_TIMEOUT_SECONDS`
+
+The first review might miss a security vulnerability. The second caught four.
+
+## Iteration and Diminishing Returns
+
+After addressing findings, consider running it again. A second pass usually catches more. A third isn't always useless either. But each pass takes time, and eventually you hit diminishing returns - just nitpicks and false findings.
+
+:::tip[Better Reviews]
+Assume problems exist. Look for what's missing, not just what's wrong.
+:::

docs/explanation/brainstorming.md

@@ -0,0 +1,31 @@
+---
+title: "Brainstorming"
+description: Interactive creative sessions using 60+ proven ideation techniques
+---
+
+Unlock your creativity through guided exploration.
+
+## What is Brainstorming?
+
+Run `brainstorming` and you've got a creative facilitator pulling ideas out of you - not generating them for you. The AI acts as coach and guide, using proven techniques to create conditions where your best thinking emerges.
+
+**Good for:**
+
+- Breaking through creative blocks
+- Generating product or feature ideas
+- Exploring problems from new angles
+- Developing raw concepts into action plans
+
+## How It Works
+
+1. **Setup** - Define topic, goals, constraints
+2. **Choose approach** - Pick techniques yourself, get AI recommendations, go random, or follow a progressive flow
+3. **Facilitation** - Work through techniques with probing questions and collaborative coaching
+4. **Organize** - Ideas grouped into themes and prioritized
+5. **Action** - Top ideas get next steps and success metrics
+
+Everything gets captured in a session document you can reference later or share with stakeholders.
+
+:::note[Your Ideas]
+Every idea comes from you. The workflow creates conditions for insight - you're the source.
+:::

docs/explanation/brownfield-faq.md

@@ -0,0 +1,55 @@
+---
+title: "Brownfield Development FAQ"
+description: Common questions about brownfield development in the BMad Method
+---
+Quick answers to common questions about brownfield (existing codebase) development in the BMad Method (BMM).
+
+## Questions
+
+- [Questions](#questions)
+  - [What is brownfield vs greenfield?](#what-is-brownfield-vs-greenfield)
+  - [Do I have to run document-project for brownfield?](#do-i-have-to-run-document-project-for-brownfield)
+  - [What if I forget to run document-project?](#what-if-i-forget-to-run-document-project)
+  - [Can I use Quick Spec Flow for brownfield projects?](#can-i-use-quick-spec-flow-for-brownfield-projects)
+  - [What if my existing code doesn't follow best practices?](#what-if-my-existing-code-doesnt-follow-best-practices)
+
+### What is brownfield vs greenfield?
+
+- **Greenfield** — New project, starting from scratch, clean slate
+- **Brownfield** — Existing project, working with established codebase and patterns
+
+### Do I have to run document-project for brownfield?
+
+Highly recommended, especially if:
+
+- No existing documentation
+- Documentation is outdated
+- AI agents need context about existing code
+
+You can skip it if you have comprehensive, up-to-date documentation including `docs/index.md` or will use other tools or techniques to aid in discovery for the agent to build on an existing system.
+
+### What if I forget to run document-project?
+
+Don't worry about it - you can do it at any time. You can even do it during or after a project to help keep docs up to date.
+
+### Can I use Quick Spec Flow for brownfield projects?
+
+Yes! Quick Spec Flow works great for brownfield. It will:
+
+- Auto-detect your existing stack
+- Analyze brownfield code patterns
+- Detect conventions and ask for confirmation
+- Generate context-rich tech-spec that respects existing code
+
+Perfect for bug fixes and small features in existing codebases.
+
+### What if my existing code doesn't follow best practices?
+
+Quick Spec Flow detects your conventions and asks: "Should I follow these existing conventions?" You decide:
+
+- **Yes** → Maintain consistency with current codebase
+- **No** → Establish new standards (document why in tech-spec)
+
+BMM respects your choice — it won't force modernization, but it will offer it.
+
+**Have a question not answered here?** Please [open an issue](https://github.com/bmad-code-org/BMAD-METHOD/issues) or ask in [Discord](https://discord.gg/gk8jAdXWmj) so we can add it!

docs/explanation/party-mode.md

@@ -0,0 +1,57 @@
+---
+title: "Party Mode"
+description: Multi-agent collaboration - get all your AI agents in one conversation
+---
+
+Get all your AI agents in one conversation.
+
+## What is Party Mode?
+
+Run `party-mode` and you've got your whole AI team in one room - PM, Architect, Dev, UX Designer, whoever you need. BMad Master orchestrates, picking relevant agents per message. Agents respond in character, agree, disagree, and build on each other's ideas.
+
+The conversation continues as long as you want. Ask follow-ups, push back on answers, redirect the discussion - it's a real back-and-forth with your agents until you're done.
+
+**Good for:**
+
+- Big decisions with tradeoffs
+- Brainstorming sessions
+- Post-mortems when things go wrong
+- Sprint retrospectives and planning
+
+## Examples
+
+### Calling Out Bad Architecture
+
+**You:** "Okay team, our last sprint was a disaster. The authentication service went down three times. Who screwed this up?"
+
+**Architect:** "The design was sound - distributed authentication with proper fallbacks. If implementation deviated from the spec..."
+
+**Dev:** "I followed the architecture doc exactly. The spec didn't account for concurrent session invalidation race conditions."
+
+**PM:** "Both of you missed the bigger issue - we didn't validate session management requirements in the PRD. This is on me for not catching it."
+
+**TEA:** "And I should've caught this in integration tests. The test scenarios didn't cover concurrent invalidation."
+
+### Creative Brainstorming
+
+**You:** "How do we make onboarding feel magical instead of boring?"
+
+**UX Designer:** "Start with progressive disclosure - reveal features as users need them, not all at once in a tutorial."
+
+**Storyteller:** "What if onboarding was a story? Each step reveals a character's journey - the user IS the hero."
+
+**Game Designer:** "Building on that - what if the first 'quest' is actually solving a real user problem? They learn by doing something valuable."
+
+### Technical Decision
+
+**You:** "Monolith or microservices for MVP?"
+
+**Architect:** "Start monolith. Microservices add complexity you don't need at 1000 users."
+
+**PM:** "Agree. Time to market matters more than theoretical scalability."
+
+**Dev:** "Monolith with clear module boundaries. We can extract services later if needed."
+
+:::tip[Better Decisions]
+Better decisions through diverse perspectives. Welcome to party mode.
+:::

docs/explanation/preventing-agent-conflicts.md

@@ -0,0 +1,110 @@
+---
+title: "Preventing Agent Conflicts"
+description: How architecture prevents conflicts when multiple agents implement a system
+---
+
+When multiple AI agents implement different parts of a system, they can make conflicting technical decisions. Architecture documentation prevents this by establishing shared standards.
+
+## Common Conflict Types
+
+### API Style Conflicts
+
+Without architecture:
+- Agent A uses REST with `/users/{id}`
+- Agent B uses GraphQL mutations
+- Result: Inconsistent API patterns, confused consumers
+
+With architecture:
+- ADR specifies: "Use GraphQL for all client-server communication"
+- All agents follow the same pattern
+
+### Database Design Conflicts
+
+Without architecture:
+- Agent A uses snake_case column names
+- Agent B uses camelCase column names
+- Result: Inconsistent schema, confusing queries
+
+With architecture:
+- Standards document specifies naming conventions
+- All agents follow the same patterns
+
+### State Management Conflicts
+
+Without architecture:
+- Agent A uses Redux for global state
+- Agent B uses React Context
+- Result: Multiple state management approaches, complexity
+
+With architecture:
+- ADR specifies state management approach
+- All agents implement consistently
+
+## How Architecture Prevents Conflicts
+
+### 1. Explicit Decisions via ADRs
+
+Every significant technology choice is documented with:
+- Context (why this decision matters)
+- Options considered (what alternatives exist)
+- Decision (what we chose)
+- Rationale (why we chose it)
+- Consequences (trade-offs accepted)
+
+### 2. FR/NFR-Specific Guidance
+
+Architecture maps each functional requirement to technical approach:
+- FR-001: User Management → GraphQL mutations
+- FR-002: Mobile App → Optimized queries
+
+### 3. Standards and Conventions
+
+Explicit documentation of:
+- Directory structure
+- Naming conventions
+- Code organization
+- Testing patterns
+
+## Architecture as Shared Context
+
+Think of architecture as the shared context that all agents read before implementing:
+
+```
+PRD: "What to build"
+     ↓
+Architecture: "How to build it"
+     ↓
+Agent A reads architecture → implements Epic 1
+Agent B reads architecture → implements Epic 2
+Agent C reads architecture → implements Epic 3
+     ↓
+Result: Consistent implementation
+```
+
+## Key ADR Topics
+
+Common decisions that prevent conflicts:
+
+| Topic            | Example Decision                             |
+| ---------------- | -------------------------------------------- |
+| API Style        | GraphQL vs REST vs gRPC                      |
+| Database         | PostgreSQL vs MongoDB                        |
+| Auth             | JWT vs Sessions                              |
+| State Management | Redux vs Context vs Zustand                  |
+| Styling          | CSS Modules vs Tailwind vs Styled Components |
+| Testing          | Jest + Playwright vs Vitest + Cypress        |
+
+## Anti-Patterns to Avoid
+
+:::caution[Common Mistakes]
+- **Implicit Decisions** — "We'll figure out the API style as we go" leads to inconsistency
+- **Over-Documentation** — Documenting every minor choice causes analysis paralysis
+- **Stale Architecture** — Documents written once and never updated cause agents to follow outdated patterns
+:::
+
+:::tip[Correct Approach]
+- Document decisions that cross epic boundaries
+- Focus on conflict-prone areas
+- Update architecture as you learn
+- Use `correct-course` for significant changes
+:::

docs/explanation/quick-flow.md

@@ -0,0 +1,27 @@
+---
+title: "Quick Flow"
+description: Fast-track for small changes - skip the full methodology
+---
+
+Quick Flow is for when you don't need the full BMad Method. Skip Product Brief, PRD, and Architecture - go straight to implementation.
+
+## How It Works
+
+1. **Run `quick-spec`** — generates a focused tech-spec
+2. **Run `quick-dev`** — implements it
+
+That's it.
+
+## When to Use It
+
+- Bug fixes
+- Refactoring
+- Small features
+- Prototyping
+
+## When to Use Full BMad Method Instead
+
+- New products
+- Major features
+- Multiple teams involved
+- Stakeholder alignment needed

docs/explanation/why-solutioning-matters.md

@@ -0,0 +1,75 @@
+---
+title: "Why Solutioning Matters"
+description: Understanding why the solutioning phase is critical for multi-epic projects
+---
+
+
+Phase 3 (Solutioning) translates **what** to build (from Planning) into **how** to build it (technical design). This phase prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins.
+
+## The Problem Without Solutioning
+
+```
+Agent 1 implements Epic 1 using REST API
+Agent 2 implements Epic 2 using GraphQL
+Result: Inconsistent API design, integration nightmare
+```
+
+When multiple agents implement different parts of a system without shared architectural guidance, they make independent technical decisions that may conflict.
+
+## The Solution With Solutioning
+
+```
+architecture workflow decides: "Use GraphQL for all APIs"
+All agents follow architecture decisions
+Result: Consistent implementation, no conflicts
+```
+
+By documenting technical decisions explicitly, all agents implement consistently and integration becomes straightforward.
+
+## Solutioning vs Planning
+
+| Aspect   | Planning (Phase 2)      | Solutioning (Phase 3)             |
+| -------- | ----------------------- | --------------------------------- |
+| Question | What and Why?           | How? Then What units of work?     |
+| Output   | FRs/NFRs (Requirements) | Architecture + Epics/Stories      |
+| Agent    | PM                      | Architect → PM                    |
+| Audience | Stakeholders            | Developers                        |
+| Document | PRD (FRs/NFRs)          | Architecture + Epic Files         |
+| Level    | Business logic          | Technical design + Work breakdown |
+
+## Key Principle
+
+**Make technical decisions explicit and documented** so all agents implement consistently.
+
+This prevents:
+- API style conflicts (REST vs GraphQL)
+- Database design inconsistencies
+- State management disagreements
+- Naming convention mismatches
+- Security approach variations
+
+## When Solutioning is Required
+
+| Track | Solutioning Required? |
+|-------|----------------------|
+| Quick Flow | No - skip entirely |
+| BMad Method Simple | Optional |
+| BMad Method Complex | Yes |
+| Enterprise | Yes |
+
+:::tip[Rule of Thumb]
+If you have multiple epics that could be implemented by different agents, you need solutioning.
+:::
+
+## The Cost of Skipping
+
+Skipping solutioning on complex projects leads to:
+
+- **Integration issues** discovered mid-sprint
+- **Rework** due to conflicting implementations
+- **Longer development time** overall
+- **Technical debt** from inconsistent patterns
+
+:::caution[Cost Multiplier]
+Catching alignment issues in solutioning is 10× faster than discovering them during implementation.
+:::

docs/getting-started/installation.md

@@ -1,76 +0,0 @@
-# Installation
-
-Get BMAD Method running in your project in under 2 minutes.
-
-## Quick Install
-
-```bash
-npx bmad-method@alpha install
-```
-
-This interactive installer will:
-
-1. Detect your IDE (Claude Code, Cursor, VS Code, etc.)
-2. Let you choose which modules to install
-3. Configure agents and workflows for your project
-
-## Requirements
-
-- **Node.js** 18+ (for the installer)
-- **Git** (recommended for version control)
-- An **AI-powered IDE** or access to Claude/ChatGPT/Gemini
-
-## Module Options
-
-During installation, you'll choose which modules to install:
-
-| Module   | Description      | Best For                                 |
-| -------- | ---------------- | ---------------------------------------- |
-| **BMM**  | BMAD Method Core | Software development projects            |
-| **BMGD** | Game Development | Game projects with specialized workflows |
-| **BMB**  | Builder          | Creating custom agents and workflows     |
-
-## Post-Installation
-
-After installation, your project will have:
-
-```
-your-project/
-├── _bmad/              # BMAD configuration and agents
-│   ├── bmm/            # Method module (if installed)
-│   ├── bmgd/           # Game dev module (if installed)
-│   └── config.yaml     # Your project configuration
-├── .claude/            # IDE-specific setup (varies by IDE)
-└── ... your code
-```
-
-## Next Steps
-
-1. **Read the [Quick Start Guide](../modules/bmm/quick-start.md)** to build your first feature
-2. **Check your [IDE Guide](../ide-info/index.md)** for IDE-specific tips
-3. **Explore [Workflows](../modules/bmm/workflows-planning.md)** to understand the methodology
-
-## Alternative: Web Bundles
-
-Don't want to install? Use BMAD agents directly in:
-
-- **Claude Projects** - Upload the web bundle
-- **ChatGPT** - Use custom GPT bundles
-- **Gemini** - Import agent prompts
-
-See the [Web Bundles Guide](../web-bundles-gemini-gpt-guide.md) for details.
-
-## Troubleshooting
-
-### Common Issues
-
-**"Command not found: npx"**
-: Install Node.js 18+ from [nodejs.org](https://nodejs.org)
-
-**"Permission denied"**
-: Run with appropriate permissions or check your npm configuration
-
-**IDE not detected**
-: The installer will prompt you to select your IDE manually
-
-For more help, see [Troubleshooting](../modules/bmm/troubleshooting.md) or join our [Discord](https://discord.gg/bmad).

docs/how-to/brownfield/index.md

@@ -0,0 +1,84 @@
+---
+title: "Brownfield Development"
+description: How to use BMad Method on existing codebases
+---
+
+Use BMad Method effectively when working on existing projects and legacy codebases.
+
+## What is Brownfield Development?
+
+**Brownfield** refers to working on existing projects with established codebases and patterns, as opposed to **greenfield** which means starting from scratch with a clean slate.
+
+This guide covers the essential workflow for onboarding to brownfield projects with BMad Method.
+
+:::note[Prerequisites]
+- BMad Method installed (`npx bmad-method install`)
+- An existing codebase you want to work on
+- Access to an AI-powered IDE (Claude Code, Cursor, or Windsurf)
+:::
+
+## Step 1: Clean Up Completed Planning Artifacts
+
+If you have completed all PRD epics and stories through the BMad process, clean up those files. Archive them, delete them, or rely on version history if needed. Do not keep these files in:
+
+- `docs/`
+- `_bmad-output/planning-artifacts/`
+- `_bmad-output/implementation-artifacts/`
+
+## Step 2: Maintain Quality Project Documentation
+
+Your `docs/` folder should contain succinct, well-organized documentation that accurately represents your project:
+
+- Intent and business rationale
+- Business rules
+- Architecture
+- Any other relevant project information
+
+For complex projects, consider using the `document-project` workflow. It offers runtime variants that will scan your entire project and document its actual current state.
+
+## Step 3: Get Help
+
+Get help to know what to do next based on your unique needs
+
+Run `bmad-help` to get guidance when you are not sure what to do next.
+
+### Choosing Your Approach
+
+You have two primary options depending on the scope of changes:
+
+| Scope                          | Recommended Approach                                                                                                          |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| **Small updates or additions** | Use `quick-flow-solo-dev` to create a tech-spec and implement the change. The full four-phase BMad method is likely overkill. |
+| **Major changes or additions** | Start with the BMad method, applying as much or as little rigor as needed.                                                    |
+
+### During PRD Creation
+
+When creating a brief or jumping directly into the PRD, ensure the agent:
+
+- Finds and analyzes your existing project documentation
+- Reads the proper context about your current system
+
+You can guide the agent explicitly, but the goal is to ensure the new feature integrates well with your existing system.
+
+### UX Considerations
+
+UX work is optional. The decision depends not on whether your project has a UX, but on:
+
+- Whether you will be working on UX changes
+- Whether significant new UX designs or patterns are needed
+
+If your changes amount to simple updates to existing screens you are happy with, a full UX process is unnecessary.
+
+### Architecture Considerations
+
+When doing architecture, ensure the architect:
+
+- Uses the proper documented files
+- Scans the existing codebase
+
+Pay close attention here to prevent reinventing the wheel or making decisions that misalign with your existing architecture.
+
+## More Information
+
+- **[Quick Fix in Brownfield](/docs/how-to/brownfield/quick-fix-in-brownfield.md)** - Bug fixes and ad-hoc changes
+- **[Brownfield FAQ](/docs/explanation/brownfield-faq.md)** - Common questions about brownfield development

docs/how-to/brownfield/quick-fix-in-brownfield.md

@@ -0,0 +1,76 @@
+---
+title: "How to Make Quick Fixes in Brownfield Projects"
+description: How to make quick fixes and ad-hoc changes in brownfield projects
+---
+
+Use the **DEV agent** directly for bug fixes, refactorings, or small targeted changes that don't require the full BMad method or Quick Flow.
+
+## When to Use This
+
+- Simple bug fixes
+- Small refactorings and changes that don't need extensive ideation, planning, or architectural shifts
+- Larger refactorings or improvement with built in tool planning and execution mode combination, or better yet use quick flow
+- Learning about your codebase
+
+## Steps
+
+### 1. Load an Agent
+
+For quick fixes, you can use:
+
+- **DEV agent** - For implementation-focused work
+- **Quick Flow Solo Dev** - For slightly larger changes that still need a quick-spec to keep the agent aligned to planning and standards
+
+### 2. Describe the Change
+
+Simply tell the agent what you need:
+
+```
+Fix the login validation bug that allows empty passwords
+```
+
+or
+
+```
+Refactor the UserService to use async/await instead of callbacks
+```
+
+### 3. Let the Agent Work
+
+The agent will:
+
+- Analyze the relevant code
+- Propose a solution
+- Implement the change
+- Run tests (if available)
+
+### 4. Review and Commit
+
+Review the changes made and commit when satisfied.
+
+## Learning Your Codebase
+
+This approach is also excellent for exploring unfamiliar code:
+
+```
+Explain how the authentication system works in this codebase
+```
+
+```
+Show me where error handling happens in the API layer
+```
+
+LLMs are excellent at interpreting and analyzing code, whether it was AI-generated or not. Use the agent to:
+
+- Learn about your project
+- Understand how things are built
+- Explore unfamiliar parts of the codebase
+
+## When to Upgrade to Formal Planning
+
+Consider using Quick Flow or full BMad Method when:
+
+- The change affects multiple files or systems
+- You're unsure about the scope
+- The fix keeps growing in complexity
+- You need documentation for the change

docs/how-to/customize-bmad.md

@@ -0,0 +1,158 @@
+---
+title: "BMad Method Customization Guide"
+---
+
+The ability to customize the BMad Method and its core to your needs, while still being able to get updates and enhancements is a critical idea within the BMad Ecosystem.
+
+The Customization Guidance outlined here, while targeted at understanding BMad Method customization, applies to any other module use within the BMad Method.
+
+## Types of Customization
+
+Customization includes Agent Customization, Workflow/Skill customization, the addition of new MCPs or Skills to be used by existing agents. Aside from all of this, a whole other realm of customization involves creating / adding your own relevant BMad Builder workflows, skills, agents and maybe even your own net new modules to compliment the BMad Method Module.
+
+Warning: The reason for customizing as this guide will prescribe will allow you to continue getting updates without worrying about losing your customization changes. And by continuing to get updates as BMad modules advance, you will be able to continue to evolve as the system improves.
+
+## Agent Customization
+
+### Agent Customization Areas
+
+- Change agent names, personas or manner of speech
+- Add project-specific memories or context
+- Add custom menu items to custom or inline prompts, skills or custom BMad workflows
+- Define critical actions that occur agent startup for consistent behavior
+
+## How to customize an agent.
+
+**1. Locate Customization Files**
+
+After installation, find agent customization files in:
+
+```
+_bmad/_config/agents/
+├── core-bmad-master.customize.yaml
+├── bmm-dev.customize.yaml
+├── bmm-pm.customize.yaml
+└── ... (one file per installed agent)
+```
+
+**2. Edit Any Agent**
+
+Open the `.customize.yaml` file for the agent you want to modify. All sections are optional - customize only what you need.
+
+**3. Rebuild the Agent**
+
+After editing, IT IS CRITICAL to rebuild the agent to apply changes:
+
+```bash
+npx bmad-method install
+```
+
+You can either then:
+
+- Select `Quick Update` - This will also ensure all packages are up to date AND compile all agents to include any updates or customizations
+- Select `Rebuild Agents` - This will only rebuild and apply customizations to agents, without pulling the latest
+
+There will be additional tools shortly after beta launch to allow install of individual agents, workflows, skills and modules without the need for using the full bmad installer.
+
+### What Agent Properties Can Be Customized?
+
+#### Agent Name
+
+Change how the agent introduces itself:
+
+```yaml
+agent:
+  metadata:
+    name: 'Spongebob' # Default: "Amelia"
+```
+
+#### Persona
+
+Replace the agent's personality, role, and communication style:
+
+```yaml
+persona:
+  role: 'Senior Full-Stack Engineer'
+  identity: 'Lives in a pineapple (under the sea)'
+  communication_style: 'Spongebob annoying'
+  principles:
+    - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep'
+    - 'Favor composition over inheritance'
+```
+
+**Note:** The persona section replaces the entire default persona (not merged).
+
+#### Memories
+
+Add persistent context the agent will always remember:
+
+```yaml
+memories:
+  - 'Works at Krusty Krab'
+  - 'Favorite Celebrity: David Hasslehoff'
+  - 'Learned in Epic 1 that its not cool to just pretend that tests have passed'
+```
+
+### Custom Menu Items
+
+Any custom items you add here will be included in the agents display menu.
+
+```yaml
+menu:
+  - trigger: my-workflow
+    workflow: '{project-root}/my-custom/workflows/my-workflow.yaml'
+    description: My custom workflow
+  - trigger: deploy
+    action: '#deploy-prompt'
+    description: Deploy to production
+```
+
+### Critical Actions
+
+Add instructions that execute before the agent starts:
+
+```yaml
+critical_actions:
+  - 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention'
+```
+
+### Custom Prompts
+
+Define reusable prompts for `action="#id"` menu handlers:
+
+```yaml
+prompts:
+  - id: deploy-prompt
+    content: |
+      Deploy the current branch to production:
+      1. Run all tests
+      2. Build the project
+      3. Execute deployment script
+```
+
+## Troubleshooting
+
+**Changes not appearing?**
+
+- Make sure you ran `npx bmad-method build <agent-name>` after editing
+- Check YAML syntax is valid (indentation matters!)
+- Verify the agent name matches the file name pattern
+
+**Agent not loading?**
+
+- Check for YAML syntax errors
+- Ensure required fields aren't left empty if you uncommented them
+- Try reverting to the template and rebuilding
+
+**Need to reset?**
+
+- Remove content from the `.customize.yaml` file (or delete the file)
+- Run `npx bmad-method build <agent-name>` to regenerate defaults
+
+## Workflow Customization
+
+Information about customizing existing BMad Method workflows and skills are coming soon.
+
+## Module Customization
+
+Information on how to build expansion modules that augment BMad, or make other existing module customizations are coming soon.

docs/how-to/get-answers-about-bmad.md

@@ -0,0 +1,102 @@
+---
+title: "How to Get Answers About BMad"
+description: Use an LLM to quickly answer your own BMad questions
+---
+
+If you have successfully installed BMad and the BMad Method (+ other modules as needed) - the first step in getting answers is `/bmad-help`. This will answer upwards of 80% of all questions and is available to you in the IDE as you are working.
+
+## When to Use This
+
+- You have a question about how BMad works or what to do next with BMad
+- You want to understand a specific agent or workflow
+- You need quick answers without waiting for Discord
+
+:::note[Prerequisites]
+An AI tool (Claude Code, Cursor, ChatGPT, Claude.ai, etc.) and either BMad installed in your project or access to the GitHub repo.
+:::
+
+## Steps
+
+### 1. Choose Your Source
+
+| Source               | Best For                                  | Examples                     |
+| -------------------- | ----------------------------------------- | ---------------------------- |
+| **`_bmad` folder**   | How BMad works—agents, workflows, prompts | "What does the PM agent do?" |
+| **Full GitHub repo** | History, installer, architecture          | "What changed in v6?"        |
+| **`llms-full.txt`**  | Quick overview from docs                  | "Explain BMad's four phases" |
+
+The `_bmad` folder is created when you install BMad. If you don't have it yet, clone the repo instead.
+
+### 2. Point Your AI at the Source
+
+**If your AI can read files (Claude Code, Cursor, etc.):**
+
+- **BMad installed:** Point at the `_bmad` folder and ask directly
+- **Want deeper context:** Clone the [full repo](https://github.com/bmad-code-org/BMAD-METHOD)
+
+**If you use ChatGPT or Claude.ai:**
+
+Fetch `llms-full.txt` into your session:
+
+```
+https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
+```
+
+See the [Downloads page](/docs/downloads.md) for other downloadable resources.
+
+### 3. Ask Your Question
+
+:::note[Example]
+**Q:** "Tell me the fastest way to build something with BMad"
+
+**A:** Use Quick Flow: Run `quick-spec` to write a technical specification, then `quick-dev` to implement it—skipping the full planning phases.
+:::
+
+## What You Get
+
+Direct answers about BMad—how agents work, what workflows do, why things are structured the way they are—without waiting for someone else to respond.
+
+## Tips
+
+- **Verify surprising answers** — LLMs occasionally get things wrong. Check the source file or ask on Discord.
+- **Be specific** — "What does step 3 of the PRD workflow do?" beats "How does PRD work?"
+
+## Still Stuck?
+
+Tried the LLM approach and still need help? You now have a much better question to ask.
+
+| Channel                   | Use For                                     |
+| ------------------------- | ------------------------------------------- |
+| `#bmad-method-help`       | Quick questions (real-time chat)            |
+| `help-requests` forum     | Detailed questions (searchable, persistent) |
+| `#suggestions-feedback`   | Ideas and feature requests                  |
+| `#report-bugs-and-issues` | Bug reports                                 |
+
+**Discord:** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj)
+
+**GitHub Issues:** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) (for clear bugs)
+
+*You!*
+        *Stuck*
+             *in the queue—*
+                      *waiting*
+                              *for who?*
+
+*The source*
+        *is there,*
+                *plain to see!*
+
+*Point*
+     *your machine.*
+              *Set it free.*
+
+*It reads.*
+        *It speaks.*
+                *Ask away—*
+
+*Why wait*
+        *for tomorrow*
+                *when you have*
+                        *today?*
+
+*—Claude*

docs/how-to/install-bmad.md

@@ -0,0 +1,82 @@
+---
+title: "How to Install BMad"
+description: Step-by-step guide to installing BMad in your project
+---
+
+Use the `npx bmad-method install` command to set up BMad in your project with your choice of modules and AI tools.
+
+## When to Use This
+
+- Starting a new project with BMad
+- Adding BMad to an existing codebase
+- Update the existing BMad Installation
+
+:::note[Prerequisites]
+- **Node.js** 20+ (required for the installer)
+- **Git** (recommended)
+- **AI tool** (Claude Code, Cursor, Windsurf, or similar)
+:::
+
+## Steps
+
+### 1. Run the Installer
+
+```bash
+npx bmad-method install
+```
+
+### 2. Choose Installation Location
+
+The installer will ask where to install BMad files:
+
+- Current directory (recommended for new projects if you created the directory yourself and ran from within the directory)
+- Custom path
+
+### 3. Select Your AI Tools
+
+Pick which AI tools you use:
+
+- Claude Code
+- Cursor
+- Windsurf
+- Others
+
+Each tool has its own way of integrating commands. The installer creates tiny prompt files to activate workflows and agents — it just puts them where your tool expects to find them.
+
+### 4. Choose Modules
+
+The installer shows available modules. Select whichever ones you need — most users just want **BMad Method** (the software development module).
+
+### 5. Follow the Prompts
+
+The installer guides you through the rest — custom content, settings, etc.
+
+## What You Get
+
+```
+your-project/
+├── _bmad/
+│   ├── bmm/            # Your selected modules
+│   │   └── config.yaml # Module settings (if you ever need to change them)
+│   ├── core/           # Required core module
+│   └── ...
+├── _bmad-output/       # Generated artifacts
+└── .claude/            # Claude Code commands (if using Claude Code)
+```
+
+## Verify Installation
+
+Run the `help` workflow (`/bmad-help` on most platforms) to verify everything works and see what to do next.
+
+**Latest from main branch:**
+```bash
+npx github:bmad-code-org/BMAD-METHOD install
+```
+
+Use these if you want the newest features before they're officially released. Things might break.
+
+## Troubleshooting
+
+**Installer throws an error** — Copy-paste the output into your AI assistant and let it figure it out.
+
+**Installer worked but something doesn't work later** — Your AI needs BMad context to help. See [How to Get Answers About BMad](/docs/how-to/get-answers-about-bmad.md) for how to point your AI at the right sources.

docs/how-to/shard-large-documents.md

@@ -0,0 +1,101 @@
+---
+title: "Document Sharding Guide"
+---
+
+Use the `shard-doc` tool to split large markdown files into smaller, organized files for better context management.
+
+## When to Use This
+
+- Very large complex PRDs
+- Architecture documents with multiple system layers
+- Epic files with 4+ epics (especially for Phase 4)
+- UX design specs covering multiple subsystems
+
+## What is Document Sharding?
+
+Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`). This enables:
+
+- **Selective Loading** - Workflows load only the sections they need
+- **Reduced Token Usage** - Massive efficiency gains for large projects
+- **Better Organization** - Logical section-based file structure
+- **Maintained Context** - Index file preserves document structure
+
+### Architecture
+
+```
+Before Sharding:
+docs/
+└── PRD.md (large 50k token file)
+
+After Sharding:
+docs/
+└── prd/
+    ├── index.md                    # Table of contents with descriptions
+    ├── overview.md                 # Section 1
+    ├── user-requirements.md        # Section 2
+    ├── technical-requirements.md   # Section 3
+    └── ...                         # Additional sections
+```
+
+## Steps
+
+### 1. Run the Shard-Doc Tool
+
+```bash
+/bmad:core:tools:shard-doc
+```
+
+### 2. Follow the Interactive Process
+
+```
+Agent: Which document would you like to shard?
+User: docs/PRD.md
+
+Agent: Default destination: docs/prd/
+       Accept default? [y/n]
+User: y
+
+Agent: Sharding PRD.md...
+       ✓ Created 12 section files
+       ✓ Generated index.md
+       ✓ Complete!
+```
+
+## What You Get
+
+**index.md structure:**
+
+```markdown
+
+## Sections
+
+1. [Overview](./overview.md) - Project vision and objectives
+2. [User Requirements](./user-requirements.md) - Feature specifications
+3. [Epic 1: Authentication](./epic-1-authentication.md) - User auth system
+4. [Epic 2: Dashboard](./epic-2-dashboard.md) - Main dashboard UI
+   ...
+```
+
+**Individual section files:**
+
+- Named from heading text (kebab-case)
+- Contains complete section content
+- Preserves all markdown formatting
+- Can be read independently
+
+## How Workflow Discovery Works
+
+BMad workflows use a **dual discovery system**:
+
+1. **Try whole document first** - Look for `document-name.md`
+2. **Check for sharded version** - Look for `document-name/index.md`
+3. **Priority rule** - Whole document takes precedence if both exist - remove the whole document if you want the sharded to be used instead
+
+## Workflow Support
+
+All BMM workflows support both formats:
+
+- Whole documents
+- Sharded documents
+- Automatic detection
+- Transparent to user

docs/how-to/upgrade-to-v6.md

@@ -0,0 +1,131 @@
+---
+title: "How to Upgrade to v6"
+description: Migrate from BMad v4 to v6
+---
+
+Use the BMad installer to upgrade from v4 to v6, which includes automatic detection of legacy installations and migration assistance.
+
+## When to Use This
+
+- You have BMad v4 installed (`.bmad-method` folder)
+- You want to migrate to the new v6 architecture
+- You have existing planning artifacts to preserve
+
+:::note[Prerequisites]
+- Node.js 20+
+- Existing BMad v4 installation
+:::
+
+## Steps
+
+### 1. Run the Installer
+
+```bash
+npx bmad-method install
+```
+
+The installer automatically detects:
+
+- **Legacy v4 folder**: `.bmad-method`
+- **IDE command artifacts**: Legacy bmad folders in `.claude/commands/`, `.cursor/commands/`, etc.
+
+### 2. Handle Legacy Installation
+
+When v4 is detected, you can:
+
+- Allow the installer to back up and remove `.bmad-method`
+- Exit and handle cleanup manually
+- Keep both (not recommended for same project)
+
+### 3. Clean Up IDE Commands
+
+Manually remove legacy v4 IDE commands:
+
+- `.claude/commands/BMad/agents`
+- `.claude/commands/BMad/tasks`
+
+New v6 commands will be at `.claude/commands/bmad/<module>/agents|workflows`.
+
+:::tip[Accidentally Deleted Commands?]
+If you delete the wrong commands, rerun the installer and choose "quick update" to restore them.
+:::
+
+### 4. Migrate Planning Artifacts
+
+**If you have planning documents (Brief/PRD/UX/Architecture):**
+
+Move them to `_bmad-output/planning-artifacts/` with descriptive names:
+
+- Include `PRD` in filename for PRD documents
+- Include `brief`, `architecture`, or `ux-design` accordingly
+- Sharded documents can be in named subfolders
+
+**If you're mid-planning:** Consider restarting with v6 workflows. Use your existing documents as inputs—the new progressive discovery workflows with web search and IDE plan mode produce better results.
+
+### 5. Migrate In-Progress Development
+
+If you have stories created or implemented:
+
+1. Complete the v6 installation
+2. Place `epics.md` or `epics/epic*.md` in `_bmad-output/planning-artifacts/`
+3. Run the Scrum Master's `sprint-planning` workflow
+4. Tell the SM which epics/stories are already complete
+
+### 6. Migrate Agent Customizations
+
+**v4:** Modified agent files directly in `_bmad-*` folders
+
+**v6:** All customizations go in `_bmad/_config/agents/` using customize files:
+
+```yaml
+# _bmad/_config/agents/bmm-pm.customize.yaml
+persona:
+  name: 'Captain Jack'
+  role: 'Swashbuckling Product Owner'
+  communication_style: |
+    - Talk like a pirate
+    - Use nautical metaphors
+```
+
+After modifying customization files, rerun the installer and choose "rebuild all agents" or "quick update".
+
+## What You Get
+
+**v6 unified structure:**
+
+```
+your-project/
+└── _bmad/               # Single installation folder
+    ├── _config/         # Your customizations
+    │   └── agents/      # Agent customization files
+    ├── core/            # Universal core framework
+    ├── bmm/             # BMad Method module
+    ├── bmb/             # BMad Builder
+    └── cis/             # Creative Intelligence Suite
+├── _bmad-output/        # Output folder (was doc folder in v4)
+```
+
+## Module Migration
+
+| v4 Module | v6 Status |
+|-----------|-----------|
+| `_bmad-2d-phaser-game-dev` | Integrated into BMGD Module |
+| `_bmad-2d-unity-game-dev` | Integrated into BMGD Module |
+| `_bmad-godot-game-dev` | Integrated into BMGD Module |
+| `_bmad-infrastructure-devops` | Deprecated — new DevOps agent coming soon |
+| `_bmad-creative-writing` | Not adapted — new v6 module coming soon |
+
+## Key Changes
+
+| Concept | v4 | v6 |
+|---------|----|----|
+| **Core** | `_bmad-core` was actually BMad Method | `_bmad/core/` is universal framework |
+| **Method** | `_bmad-method` | `_bmad/bmm/` |
+| **Config** | Modified files directly | `config.yaml` per module |
+| **Documents** | Sharded or unsharded required setup | Fully flexible, auto-scanned |
+
+## Tips
+
+- **Back up first** — Keep your v4 installation until you verify v6 works
+- **Use v6 workflows** — Even partial planning docs benefit from v6's improved discovery
+- **Rebuild after customizing** — Always run the installer after changing customize files

docs/ide-info/auggie.md

@@ -1,31 +0,0 @@
-# BMAD Method - Auggie CLI Instructions
-
-## Activating Agents
-
-BMAD agents can be installed in multiple locations based on your setup.
-
-### Common Locations
-
-- User Home: `~/.augment/commands/`
-- Project: `.augment/commands/`
-- Custom paths you selected
-
-### How to Use
-
-1. **Type Trigger**: Use `@{agent-name}` in your prompt
-2. **Activate**: Agent persona activates
-3. **Tasks**: Use `@task-{task-name}` for tasks
-
-### Examples
-
-```
-@dev - Activate development agent
-@architect - Activate architect agent
-@task-setup - Execute setup task
-```
-
-### Notes
-
-- Agents can be in multiple locations
-- Check your installation paths
-- Activation syntax same across all locations

docs/ide-info/claude-code.md

@@ -1,25 +0,0 @@
-# BMAD Method - Claude Code Instructions
-
-## Activating Agents
-
-BMAD agents are installed as slash commands in `.claude/commands/bmad/`.
-
-### How to Use
-
-1. **Type Slash Command**: Start with `/` to see available commands
-2. **Select Agent**: Type `/bmad-{agent-name}` (e.g., `/bmad-dev`)
-3. **Execute**: Press Enter to activate that agent persona
-
-### Examples
-
-```
-/bmad:bmm:agents:dev - Activate development agent
-/bmad:bmm:agents:architect - Activate architect agent
-/bmad:bmm:workflows:dev-story - Execute dev-story workflow
-```
-
-### Notes
-
-- Commands are autocompleted when you type `/`
-- Agent remains active for the conversation
-- Start a new conversation to switch agents

docs/ide-info/cline.md

@@ -1,31 +0,0 @@
-# BMAD Method - Cline Instructions
-
-## Activating Agents
-
-BMAD agents are installed as **toggleable rules** in `.clinerules/` directory.
-
-### Important: Rules are OFF by default
-
-- Rules are NOT automatically loaded to avoid context pollution
-- You must manually enable the agent you want to use
-
-### How to Use
-
-1. **Open Rules Panel**: Click the rules icon below the chat input
-2. **Enable an Agent**: Toggle ON the specific agent rule you need (e.g., `01-core-dev`)
-3. **Activate in Chat**: Type `@{agent-name}` to activate that persona
-4. **Disable When Done**: Toggle OFF to free up context
-
-### Best Practices
-
-- Only enable 1-2 agents at a time to preserve context
-- Disable agents when switching tasks
-- Rules are numbered (01-, 02-) for organization, not priority
-
-### Example
-
-```
-Toggle ON: 01-core-dev.md
-In chat: "@dev help me refactor this code"
-When done: Toggle OFF the rule
-```

docs/ide-info/codex.md

@@ -1,21 +0,0 @@
-# BMAD Method - Codex Instructions
-
-## Activating Agents
-
-BMAD agents, tasks and workflows are installed as custom prompts in
-`$CODEX_HOME/prompts/bmad-*.md` files. If `CODEX_HOME` is not set, it
-defaults to `$HOME/.codex/`.
-
-### Examples
-
-```
-/bmad-bmm-agents-dev - Activate development agent
-/bmad-bmm-agents-architect - Activate architect agent
-/bmad-bmm-workflows-dev-story - Execute dev-story workflow
-```
-
-### Notes
-
-Prompts are autocompleted when you type /
-Agent remains active for the conversation
-Start a new conversation to switch agents

docs/ide-info/crush.md

@@ -1,30 +0,0 @@
-# BMAD Method - Crush Instructions
-
-## Activating Agents
-
-BMAD agents are installed as commands in `.crush/commands/bmad/`.
-
-### How to Use
-
-1. **Open Command Palette**: Use Crush command interface
-2. **Navigate**: Browse to `_bmad/{module}/agents/`
-3. **Select Agent**: Choose the agent command
-4. **Execute**: Run to activate agent persona
-
-### Command Structure
-
-```
-.crush/commands/bmad/
-├── agents/          # All agents
-├── tasks/           # All tasks
-├── core/            # Core module
-│   ├── agents/
-│   └── tasks/
-└── {module}/        # Other modules
-```
-
-### Notes
-
-- Commands organized by module
-- Can browse hierarchically
-- Agent activates for session

docs/ide-info/cursor.md

@@ -1,25 +0,0 @@
-# BMAD Method - Cursor Instructions
-
-## Activating Agents
-
-BMAD agents are installed in `.cursor/rules/bmad/` as MDC rules.
-
-### How to Use
-
-1. **Reference in Chat**: Use `@_bmad/{module}/agents/{agent-name}`
-2. **Include Entire Module**: Use `@_bmad/{module}`
-3. **Reference Index**: Use `@_bmad/index` for all available agents
-
-### Examples
-
-```
-@_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/core/agents/dev @_bmad/core/agents/test`

docs/ide-info/gemini.md

@@ -1,25 +0,0 @@
-# BMAD Method - Gemini CLI Instructions
-
-## Activating Agents
-
-BMAD agents are concatenated in `.gemini/bmad-method/GEMINI.md`.
-
-### How to Use
-
-1. **Type Trigger**: Use `*{agent-name}` in your prompt
-2. **Activate**: Agent persona activates from the concatenated file
-3. **Continue**: Agent remains active for conversation
-
-### Examples
-
-```
-*dev - Activate development agent
-*architect - Activate architect agent
-*test - Activate test agent
-```
-
-### Notes
-
-- All agents loaded from single GEMINI.md file
-- Triggers with asterisk: `*{agent-name}`
-- Context includes all agents (may be large)

docs/ide-info/github-copilot.md

@@ -1,26 +0,0 @@
-# BMAD Method - GitHub Copilot Instructions
-
-## Activating Agents
-
-BMAD agents are installed as chat modes in `.github/chatmodes/`.
-
-### How to Use
-
-1. **Open Chat View**: Click Copilot icon in VS Code sidebar
-2. **Select Mode**: Click mode selector (top of chat)
-3. **Choose Agent**: Select the BMAD agent from dropdown
-4. **Chat**: Agent is now active for this session
-
-### VS Code Settings
-
-Configured in `.vscode/settings.json`:
-
-- Max requests per session
-- Auto-fix enabled
-- MCP discovery enabled
-
-### Notes
-
-- Modes persist for the chat session
-- Switch modes anytime via dropdown
-- Multiple agents available in mode selector

docs/ide-info/iflow.md

@@ -1,33 +0,0 @@
-# BMAD Method - iFlow CLI Instructions
-
-## Activating Agents
-
-BMAD agents are installed as commands in `.iflow/commands/bmad/`.
-
-### How to Use
-
-1. **Access Commands**: Use iFlow command interface
-2. **Navigate**: Browse to `_bmad/agents/` or `_bmad/tasks/`
-3. **Select**: Choose the agent or task command
-4. **Execute**: Run to activate
-
-### Command Structure
-
-```
-.iflow/commands/bmad/
-├── agents/     # Agent commands
-└── tasks/      # Task commands
-```
-
-### Examples
-
-```
-/_bmad/agents/core-dev - Activate dev agent
-/_bmad/tasks/core-setup - Execute setup task
-```
-
-### Notes
-
-- Commands organized by type (agents/tasks)
-- Agent activates for session
-- Similar to Crush command structure

docs/ide-info/index.md

@@ -1,24 +0,0 @@
-# IDE Guides
-
-BMAD Method works with any AI-powered development environment. Choose your IDE below for specific setup instructions and tips.
-
-## All Supported IDEs
-
-| IDE                                 | Type              | BMAD Support          |
-| ----------------------------------- | ----------------- | --------------------- |
-| [Claude Code](claude-code.md)       | CLI/Terminal      | Native slash commands |
-| [Cursor](cursor.md)                 | Desktop Editor    | Full agent support    |
-| [VS Code / Windsurf](windsurf.md)   | Desktop Editor    | Extension-based       |
-| [Cline](cline.md)                   | VS Code Extension | Full support          |
-| [GitHub Copilot](github-copilot.md) | Extension         | Workspace agents      |
-| [Augment](auggie.md)                | Extension         | Agent loading         |
-| [Codex](codex.md)                   | CLI               | Prompt injection      |
-| [Gemini](gemini.md)                 | Web/API           | Web bundles           |
-| [Roo](roo.md)                       | VS Code Extension | Mode support          |
-| [Kilo](kilo.md)                     | Extension         | Basic support         |
-| [OpenCode](opencode.md)             | Open Source       | Full support          |
-| [Qwen](qwen.md)                     | Web/API           | Web bundles           |
-| [Trae](trae.md)                     | Extension         | Basic support         |
-| [Crush](crush.md)                   | Desktop           | Agent support         |
-| [iFlow](iflow.md)                   | Extension         | Prompt loading        |
-| [Rovo Dev](rovo-dev.md)             | Atlassian         | Integration           |

docs/ide-info/kilo.md

@@ -1,24 +0,0 @@
-# BMAD Method - KiloCode Instructions
-
-## Activating Agents
-
-BMAD agents are installed as custom modes in `.kilocodemodes`.
-
-### How to Use
-
-1. **Open Project**: Modes auto-load when project opens
-2. **Select Mode**: Use mode selector in KiloCode interface
-3. **Choose Agent**: Pick `bmad-{module}-{agent}` mode
-4. **Activate**: Mode is now active
-
-### Mode Format
-
-- Mode name: `bmad-{module}-{agent}`
-- Display: `{icon} {title}`
-- Example: `bmad-core-dev` shows as `🤖 Dev`
-
-### Notes
-
-- Modes persist until changed
-- Similar to Roo Code mode system
-- Icon shows in mode selector

docs/ide-info/opencode.md

@@ -1,24 +0,0 @@
-# BMAD Method - OpenCode Instructions
-
-## Activating Agents
-
-BMAD agents are installed as OpenCode agents in `.opencode/agent/BMAD/{module_name}` and workflow commands in `.opencode/command/BMAD/{module_name}`.
-
-### How to Use
-
-1. **Switch Agents**: Press **Tab** to cycle through primary agents or select using the `/agents`
-2. **Activate Agent**: Once the Agent is selected say `hello` or any prompt to activate that agent persona
-3. **Execute Commands**: Type `/bmad` to see and execute bmad workflow commands (commands allow for fuzzy matching)
-
-### Examples
-
-```
-/agents - to see a list of agents and switch between them
-/_bmad/bmm/workflows/workflow-init - Activate the workflow-init command
-```
-
-### Notes
-
-- Press **Tab** to switch between primary agents (Analyst, Architect, Dev, etc.)
-- Commands are autocompleted when you type `/` and allow for fuzzy matching
-- Workflow commands execute in current agent context, make sure you have the right agent activated before running a command

docs/ide-info/qwen.md

@@ -1,25 +0,0 @@
-# BMAD Method - Qwen Code Instructions
-
-## Activating Agents
-
-BMAD agents are concatenated in `.qwen/bmad-method/QWEN.md`.
-
-### How to Use
-
-1. **Type Trigger**: Use `*{agent-name}` in your prompt
-2. **Activate**: Agent persona activates from the concatenated file
-3. **Continue**: Agent remains active for conversation
-
-### Examples
-
-```
-*dev - Activate development agent
-*architect - Activate architect agent
-*test - Activate test agent
-```
-
-### Notes
-
-- All agents loaded from single QWEN.md file
-- Triggers with asterisk: `*{agent-name}`
-- Similar to Gemini CLI setup

docs/ide-info/roo.md

@@ -1,27 +0,0 @@
-# BMAD Method - Roo Code Instructions
-
-## Activating Agents
-
-BMAD agents are installed as custom modes in `.roomodes`.
-
-### How to Use
-
-1. **Open Project**: Modes auto-load when project opens
-2. **Select Mode**: Use mode selector in Roo interface
-3. **Choose Agent**: Pick `bmad-{module}-{agent}` mode
-4. **Activate**: Mode is now active with configured permissions
-
-### Permission Levels
-
-Modes are configured with file edit permissions:
-
-- Development files only
-- Configuration files only
-- Documentation files only
-- All files (if configured)
-
-### Notes
-
-- Modes persist until changed
-- Each mode has specific file access rights
-- Icon shows in mode selector for easy identification

docs/ide-info/rovo-dev.md

@@ -1,22 +0,0 @@
-# BMAD Method - Rovo Dev Instructions
-
-## Activating Agents
-
-BMAD agents are installed as subagents in `.rovodev/subagents/`.
-
-### How to Use
-
-1. **Open Project**: Subagents auto-load when project opens
-2. **Invoke Agent**: Type `@` and select agent (e.g., `@bmad-bmm-dev`, `@bmad-bmm-architect`)
-3. **Reference Files**: Check `.rovodev/workflows/` and `.rovodev/references/`
-
-### Directory Structure
-
-- `.rovodev/subagents/` - BMAD agents
-- `.rovodev/workflows/` - Workflow guides
-- `.rovodev/references/` - Tasks and tools
-
-### Notes
-
-- Agents are automatically discovered by Rovo Dev
-- Subagents use YAML frontmatter for configuration

docs/ide-info/trae.md

@@ -1,25 +0,0 @@
-# BMAD Method - Trae Instructions
-
-## Activating Agents
-
-BMAD agents are installed as rules in `.trae/rules/`.
-
-### How to Use
-
-1. **Type Trigger**: Use `@{agent-name}` in your prompt
-2. **Activate**: Agent persona activates automatically
-3. **Continue**: Agent remains active for conversation
-
-### Examples
-
-```
-@dev - Activate development agent
-@architect - Activate architect agent
-@task-setup - Execute setup task
-```
-
-### Notes
-
-- Rules auto-load from `.trae/rules/` directory
-- Multiple agents can be referenced: `@dev and @test`
-- Agent follows YAML configuration in rule file

docs/ide-info/windsurf.md

@@ -1,22 +0,0 @@
-# BMAD Method - Windsurf Instructions
-
-## Activating Agents
-
-BMAD agents are installed as workflows in `.windsurf/workflows/`.
-
-### How to Use
-
-1. **Open Workflows**: Access via Windsurf menu or command palette
-2. **Select Workflow**: Choose the agent/task workflow
-3. **Execute**: Run to activate that agent persona
-
-### Workflow Types
-
-- **Agent workflows**: `{module}-{agent}.md` (auto_execution_mode: 3)
-- **Task workflows**: `task-{module}-{task}.md` (auto_execution_mode: 2)
-
-### Notes
-
-- Agents run with higher autonomy (mode 3)
-- Tasks run with guided execution (mode 2)
-- Workflows persist for the session

docs/index.md

@@ -1,143 +1,56 @@
-# BMad Documentation Index
+---
+title: Welcome to the BMad Method
+---
 
-Complete map of all BMad Method v6 documentation with recommended reading paths.
+The BMad Method (**B**reakthrough **M**ethod of **A**gile AI **D**riven Development) is an AI-driven development framework that helps you build software faster and smarter. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity—whether you're fixing a bug or building an enterprise platform.
+
+If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started.
 
 ---
 
-## 🎯 Getting Started (Start Here!)
+## New Here? Start with a Tutorial
 
-**New users:** Start with one of these based on your situation:
+The fastest way to understand BMad is to try it.
 
-| Your Situation         | Start Here                                         | Then Read                                                   |
+- **[Get Started with BMad](/docs/tutorials/getting-started.md)** — Install and understand how BMad works
-| ---------------------- | -------------------------------------------------- | ----------------------------------------------------------- |
+- **[Workflow Map](/docs/reference/workflow-map.md)** — Visual overview of BMM phases, workflows, and context management.
-| **Brand new to BMad**  | [Quick Start Guide](./modules/bmm/quick-start)     | [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) |
+
-| **Upgrading from v4**  | [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)    | [Quick Start Guide](./modules/bmm/quick-start)              |
+## How to Use These Docs
-| **Brownfield project** | [Brownfield Guide](./modules/bmm/brownfield-guide) | [Quick Start Guide](./modules/bmm/quick-start)              |
+
+These docs are organized into four sections based on what you're trying to do:
+
+| Section           | Purpose                                                                                                    |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| **Tutorials**     | Learning-oriented. Step-by-step guides that walk you through building something. Start here if you're new. |
+| **How-To Guides** | Task-oriented. Practical guides for solving specific problems. "How do I customize an agent?" lives here.  |
+| **Explanation**   | Understanding-oriented. Deep dives into concepts and architecture. Read when you want to know *why*.       |
+| **Reference**     | Information-oriented. Technical specifications for agents, workflows, and configuration.                   |
 
 ---
 
-## 📋 Core Documentation
+## What You'll Need
 
-### Project-Level Docs (Root)
+BMad works with any AI coding assistant that supports custom system prompts or project context. Popular options include:
 
-- **[README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md)** - Main project overview, feature summary, and module introductions
+- **[Claude Code](https://code.claude.com)** — Anthropic's CLI tool (recommended)
-- **[CONTRIBUTING.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md)** - How to contribute, pull request guidelines, code style
+- **[Cursor](https://cursor.sh)** — AI-first code editor
-- **[CHANGELOG.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md)** - Version history and breaking changes
+- **[Windsurf](https://codeium.com/windsurf)** — Codeium's AI IDE
+- **[Roo Code](https://roocode.com)** — VS Code extension
 
-### Installation & Setup
+You should be comfortable with basic software development concepts like version control, project structure, and agile workflows. No prior experience with BMad-style agent systems is required—that's what these docs are for.
-
-- **[v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)** - Migration path for v4 users
-- **[Document Sharding Guide](./document-sharding-guide.md)** - Split large documents for 90%+ token savings
-- **[Bundle Distribution Setup](./BUNDLE_DISTRIBUTION_SETUP.md)** - Maintainer guide for bundle auto-publishing
 
 ---
 
-## 🏗️ Module Documentation
+## Join the Community
 
-### BMad Method (BMM) - Software & Game Development
+Get help, share what you're building, or contribute to BMad:
 
-The flagship module for agile AI-driven development.
+- **[Discord](https://discord.gg/gk8jAdXWmj)** — Chat with other BMad users, ask questions, share ideas
-
+- **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — Source code, issues, and contributions
-- **[BMM Module README](./modules/bmm/)** - Module overview, agents, and complete documentation index
+- **[YouTube](https://www.youtube.com/@BMadCode)** — Video tutorials and walkthroughs
-- **[BMM Documentation](./modules/bmm/)** - All BMM-specific guides and references:
-  - [Quick Start Guide](./modules/bmm/quick-start) - Step-by-step guide to building your first project
-  - [Quick Spec Flow](./modules/bmm/quick-spec-flow) - Rapid Level 0-1 development
-  - [Scale Adaptive System](./modules/bmm/scale-adaptive-system) - Understanding the 5-level system
-  - [Brownfield Guide](./modules/bmm/brownfield-guide) - Working with existing codebases
-- **[BMM Workflows Guide](./modules/bmm/index#-workflow-guides)** - **ESSENTIAL READING**
-- **[Test Architect Guide](./modules/bmm/test-architecture)** - Testing strategy and quality assurance
-
-### BMad Builder (BMB) - Create Custom Solutions
-
-Build your own agents, workflows, and modules.
-
-- **[BMB Module Overview](./modules/bmb/index)** - Module overview and capabilities
-- **[Agent Creation Guide](./modules/bmb/agents/index)** - Design custom agents
-
-### Creative Intelligence Suite (CIS) - Innovation & Creativity
-
-AI-powered creative thinking and brainstorming.
-
-- **[CIS Module README](./modules/cis/)** - Module overview and workflows
 
 ---
 
-## 🖥️ IDE-Specific Guides
+## Next Step
 
-Instructions for loading agents and running workflows in your development environment.
+Ready to dive in? **[Get Started with BMad](/docs/tutorials/getting-started.md)** and build your first project.
-
-**Popular IDEs:**
-
-- [Claude Code](./ide-info/claude-code.md)
-- [Cursor](./ide-info/cursor.md)
-- [VS Code](./ide-info/windsurf.md)
-
-**Other Supported IDEs:**
-
-- [Augment](./ide-info/auggie.md)
-- [Cline](./ide-info/cline.md)
-- [Codex](./ide-info/codex.md)
-- [Crush](./ide-info/crush.md)
-- [Gemini](./ide-info/gemini.md)
-- [GitHub Copilot](./ide-info/github-copilot.md)
-- [IFlow](./ide-info/iflow.md)
-- [Kilo](./ide-info/kilo.md)
-- [OpenCode](./ide-info/opencode.md)
-- [Qwen](./ide-info/qwen.md)
-- [Roo](./ide-info/roo.md)
-- [Rovo Dev](./ide-info/rovo-dev.md)
-- [Trae](./ide-info/trae.md)
-
-**Key concept:** Every reference to "load an agent" or "activate an agent" in the main docs links to the [ide-info](./ide-info/) directory for IDE-specific instructions.
-
----
-
-## 🔧 Advanced Topics
-
-### Custom Agents, Workflow and Modules
-
-- **[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
-
----
-
-## 🎓 Recommended Reading Paths
-
-### Path 1: Brand New to BMad (Software Project)
-
-1. [README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md) - Understand the vision
-2. [Quick Start Guide](./modules/bmm/quick-start) - Get hands-on
-3. [BMM Module README](./modules/bmm/) - Understand agents
-4. [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) - Master the methodology
-5. [Your IDE guide](./ide-info/) - Optimize your workflow
-
-### Path 2: Game Development Project
-
-1. [README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md) - Understand the vision
-2. [Quick Start Guide](./modules/bmm/quick-start) - Get hands-on
-3. [BMM Module README](./modules/bmm/) - Game agents are included
-4. [BMGD Workflows Guide](./modules/bmgd/workflows-guide) - Game-specific workflows
-5. [Your IDE guide](./ide-info/) - Optimize your workflow
-
-### Path 3: Upgrading from v4
-
-1. [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md) - Understand what changed
-2. [Quick Start Guide](./modules/bmm/quick-start) - Reorient yourself
-3. [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) - Learn new v6 workflows
-
-### Path 4: Working with Existing Codebase (Brownfield)
-
-1. [Brownfield Guide](./modules/bmm/brownfield-guide) - Approach for legacy code
-2. [Quick Start Guide](./modules/bmm/quick-start) - Follow the process
-3. [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) - Master the methodology
-
-### Path 5: Building Custom Solutions
-
-1. [BMB Module Overview](./modules/bmb/index) - Understand capabilities
-2. [Agent Creation Guide](./modules/bmb/agents/index) - Create agents
-3. [BMB Workflows Guide](./modules/bmb/workflows/) - Understand workflow structure
-
-### Path 6: Contributing to BMad
-
-1. [CONTRIBUTING.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md) - Contribution guidelines
-2. Relevant module README - Understand the area you're contributing to

docs/reference/workflow-map.md

@@ -0,0 +1,86 @@
+---
+title: "Workflow Map"
+description: Visual reference for BMad Method workflow phases and outputs
+---
+
+The BMad Method (BMM) is a module in the BMad Ecosystem, targeted at following the best practices of context engineering and planning. AI agents work best with clear, structured context. The BMM system builds that context progressively across 4 distinct phases - each phase, and multiple workflows optionally within each phase, produce documents that inform the next, so agents always know what to build and why.
+
+The rationale and concepts come from agile methodologies that have been used across the industry with great success as a mental framework.
+
+If at anytime you are unsure what to do, the `/bmad-help` command will help you stay on track or know what to do next. You can always refer to this for reference also - but /bmad-help is fully interactive and much quicker if you have already installed the BMadMethod. Additionally, if you are using different modules that have extended the BMad Method or added other complimentary non extension modules - the /bmad-help evolves to know all that is available to give you the best in the moment advice.
+
+Final important note: Every workflow below can be run directly with your tool of choice via slash command or by loading an agent first and using the entry from the agents menu.
+
+<iframe src="/workflow-map-diagram.html" width="100%" height="100%" frameborder="0" style="border-radius: 8px; border: 1px solid #334155; min-height: 900px;"></iframe>
+
+*[Interactive diagram - hover over outputs to see artifact flows]*
+
+## Phase 1: Analysis (Optional)
+
+Explore the problem space and validate ideas before committing to planning.
+
+| Workflow               | Purpose                                                                    | Produces                  |
+| ---------------------- | -------------------------------------------------------------------------- | ------------------------- |
+| `brainstorm`           | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorming-report.md` |
+| `research`             | Validate market, technical, or domain assumptions                          | Research findings         |
+| `create-product-brief` | Capture strategic vision                                                   | `product-brief.md`        |
+
+## Phase 2: Planning
+
+Define what to build and for whom.
+
+| Workflow           | Purpose                                  | Produces     |
+| ------------------ | ---------------------------------------- | ------------ |
+| `create-prd`       | Define requirements (FRs/NFRs)           | `PRD.md`     |
+| `create-ux-design` | Design user experience (when UX matters) | `ux-spec.md` |
+
+## Phase 3: Solutioning
+
+Decide how to build it and break work into stories.
+
+| Workflow                         | Purpose                                    | Produces                    |
+| -------------------------------- | ------------------------------------------ | --------------------------- |
+| `create-architecture`            | Make technical decisions explicit          | `architecture.md` with ADRs |
+| `create-epics-and-stories`       | Break requirements into implementable work | Epic files with stories     |
+| `check-implementation-readiness` | Gate check before implementation           | PASS/CONCERNS/FAIL decision |
+
+## Phase 4: Implementation
+
+Build it, one story at a time.
+
+| Workflow          | Purpose                                | Produces                      |
+| ----------------- | -------------------------------------- | ----------------------------- |
+| `sprint-planning` | Initialize tracking (once per project) | `sprint-status.yaml`          |
+| `create-story`    | Prepare next story for implementation  | `story-[slug].md`             |
+| `dev-story`       | Implement the story                    | Working code + tests          |
+| `automate` (QA)   | Generate tests for existing features   | Test suite                    |
+| `code-review`     | Validate implementation quality        | Approved or changes requested |
+| `correct-course`  | Handle significant mid-sprint changes  | Updated plan or re-routing    |
+| `retrospective`   | Review after epic completion           | Lessons learned               |
+
+**Quinn (QA Agent):** Built-in QA agent for test automation. Trigger with `QA` or `bmad-bmm-qa-automate`. Generates standard API and E2E tests using your project's test framework. Beginner-friendly, no configuration needed. For advanced test strategy, install [Test Architect (TEA)](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) module.
+
+## Quick Flow (Parallel Track)
+
+Skip phases 1-3 for small, well-understood work.
+
+| Workflow     | Purpose                                    | Produces                                      |
+| ------------ | ------------------------------------------ | --------------------------------------------- |
+| `quick-spec` | Define an ad-hoc change                    | `tech-spec.md` (story file for small changes) |
+| `quick-dev`  | Implement from spec or direct instructions | Working code + tests                          |
+
+## Context Management
+
+Each document becomes context for the next phase. The PRD tells the architect what constraints matter. The architecture tells the dev agent which patterns to follow. Story files give focused, complete context for implementation. Without this structure, agents make inconsistent decisions.
+
+For brownfield projects, `document-project` creates or updates `project-context.md` - what exists in the codebase and the rules all implementation workflows must observe. Run it just before Phase 4, and again when something significant changes - structure, architecture, or those rules. You can also edit `project-context.md` by hand.
+
+All implementation workflows load `project-context.md` if it exists. Additional context per workflow:
+
+| Workflow       | Also Loads                   |
+| -------------- | ---------------------------- |
+| `create-story` | epics, PRD, architecture, UX |
+| `dev-story`    | story file                   |
+| `code-review`  | architecture, story file     |
+| `quick-spec`   | planning docs (if exist)     |
+| `quick-dev`    | tech-spec                    |

docs/tutorials/getting-started.md

@@ -0,0 +1,209 @@
+---
+title: "Getting Started"
+description: Install BMad and build your first project
+---
+
+Build software faster using AI-powered workflows with specialized agents that guide you through planning, architecture, and implementation.
+
+## What You'll Learn
+
+- Install and initialize BMad Method for a new project
+- Choose the right planning track for your project size
+- Progress through phases from requirements to working code
+- Use agents and workflows effectively
+
+:::note[Prerequisites]
+- **Node.js 20+** — Required for the installer
+- **Git** — Recommended for version control
+- **AI-powered IDE** — Claude Code, Cursor, Windsurf, or similar
+- **A project idea** — Even a simple one works for learning
+:::
+
+:::tip[Quick Path]
+**Install** → `npx bmad-method install`
+**Plan** → PM creates PRD, Architect creates architecture
+**Build** → SM manages sprints, DEV implements stories
+**Fresh chats** for each workflow to avoid context issues.
+:::
+
+## Understanding BMad
+
+BMad helps you build software through guided workflows with specialized AI agents. The process follows four phases:
+
+| Phase | Name           | What Happens                                        |
+| ----- | -------------- | --------------------------------------------------- |
+| 1     | Analysis       | Brainstorming, research, product brief *(optional)* |
+| 2     | Planning       | Create requirements (PRD or tech-spec)              |
+| 3     | Solutioning    | Design architecture *(BMad Method/Enterprise only)* |
+| 4     | Implementation | Build epic by epic, story by story                  |
+
+**[Open the Workflow Map](/docs/reference/workflow-map.md)** to explore phases, workflows, and context management.
+
+Based on your project's complexity, BMad offers three planning tracks:
+
+| Track           | Best For                                               | Documents Created                      |
+| --------------- | ------------------------------------------------------ | -------------------------------------- |
+| **Quick Flow**  | Bug fixes, simple features, clear scope (1-15 stories) | Tech-spec only                         |
+| **BMad Method** | Products, platforms, complex features (10-50+ stories) | PRD + Architecture + UX                |
+| **Enterprise**  | Compliance, multi-tenant systems (30+ stories)         | PRD + Architecture + Security + DevOps |
+
+:::note
+Story counts are guidance, not definitions. Choose your track based on planning needs, not story math.
+:::
+
+## Installation
+
+Open a terminal in your project directory and run:
+
+```bash
+npx bmad-method install
+```
+
+When prompted to select modules, choose **BMad Method**.
+
+The installer creates two folders:
+- `_bmad/` — agents, workflows, tasks, and configuration
+- `_bmad-output/` — empty for now, but this is where your artifacts will be saved
+
+Open your AI IDE in the project folder. Run the `help` workflow (`/bmad-help`) to see what to do next — it detects what you've completed and recommends the next step.
+
+:::note[How to Load Agents and Run Workflows]
+Each workflow has a **slash command** you run in your IDE (e.g., `/bmad-bmm-create-prd`). Running a workflow command automatically loads the appropriate agent — you don't need to load agents separately. You can also load an agent directly for general conversation (e.g., `/bmad-agent-bmm-pm` for the PM agent).
+:::
+
+:::caution[Fresh Chats]
+Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
+:::
+
+## Step 1: Create Your Plan
+
+Work through phases 1-3. **Use fresh chats for each workflow.**
+
+### Phase 1: Analysis (Optional)
+
+All workflows in this phase are optional:
+- **brainstorming** (`/bmad-brainstorming`) — Guided ideation
+- **research** (`/bmad-bmm-research`) — Market and technical research
+- **create-product-brief** (`/bmad-bmm-create-product-brief`) — Recommended foundation document
+
+### Phase 2: Planning (Required)
+
+**For BMad Method and Enterprise tracks:**
+1. Load the **PM agent** (`/bmad-agent-bmm-pm`) in a new chat
+2. Run the `prd` workflow (`/bmad-bmm-create-prd`)
+3. Output: `PRD.md`
+
+**For Quick Flow track:**
+- Use the `quick-spec` workflow (`/bmad-bmm-quick-spec`) instead of PRD, then skip to implementation
+
+:::note[UX Design (Optional)]
+If your project has a user interface, load the **UX-Designer agent** (`/bmad-agent-bmm-ux-designer`) and run the UX design workflow (`/bmad-bmm-create-ux-design`) after creating your PRD.
+:::
+
+### Phase 3: Solutioning (BMad Method/Enterprise)
+
+**Create Architecture**
+1. Load the **Architect agent** (`/bmad-agent-bmm-architect`) in a new chat
+2. Run `create-architecture` (`/bmad-bmm-create-architecture`)
+3. Output: Architecture document with technical decisions
+
+**Create Epics and Stories**
+
+:::tip[V6 Improvement]
+Epics and stories are now created *after* architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down.
+:::
+
+1. Load the **PM agent** (`/bmad-agent-bmm-pm`) in a new chat
+2. Run `create-epics-and-stories` (`/bmad-bmm-create-epics-and-stories`)
+3. The workflow uses both PRD and Architecture to create technically-informed stories
+
+**Implementation Readiness Check** *(Highly Recommended)*
+1. Load the **Architect agent** (`/bmad-agent-bmm-architect`) in a new chat
+2. Run `check-implementation-readiness` (`/bmad-bmm-check-implementation-readiness`)
+3. Validates cohesion across all planning documents
+
+## Step 2: Build Your Project
+
+Once planning is complete, move to implementation. **Each workflow should run in a fresh chat.**
+
+### Initialize Sprint Planning
+
+Load the **SM agent** (`/bmad-agent-bmm-sm`) and run `sprint-planning` (`/bmad-bmm-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories.
+
+### The Build Cycle
+
+For each story, repeat this cycle with fresh chats:
+
+| Step | Agent | Workflow       | Command                    | Purpose                            |
+| ---- | ----- | -------------- | -------------------------- | ---------------------------------- |
+| 1    | SM    | `create-story` | `/bmad-bmm-create-story`  | Create story file from epic        |
+| 2    | DEV   | `dev-story`    | `/bmad-bmm-dev-story`     | Implement the story                |
+| 3    | DEV   | `code-review`  | `/bmad-bmm-code-review`   | Quality validation *(recommended)* |
+
+After completing all stories in an epic, load the **SM agent** (`/bmad-agent-bmm-sm`) and run `retrospective` (`/bmad-bmm-retrospective`).
+
+## What You've Accomplished
+
+You've learned the foundation of building with BMad:
+
+- Installed BMad and configured it for your IDE
+- Initialized a project with your chosen planning track
+- Created planning documents (PRD, Architecture, Epics & Stories)
+- Understood the build cycle for implementation
+
+Your project now has:
+
+```
+your-project/
+├── _bmad/                         # BMad configuration
+├── _bmad-output/
+│   ├── PRD.md                     # Your requirements document
+│   ├── architecture.md            # Technical decisions
+│   ├── epics/                     # Epic and story files
+│   └── sprint-status.yaml         # Sprint tracking
+└── ...
+```
+
+## Quick Reference
+
+| Workflow                         | Command                                    | Agent     | Purpose                              |
+| -------------------------------- | ------------------------------------------ | --------- | ------------------------------------ |
+| `help`                           | `/bmad-help`                               | Any       | Get guidance on what to do next      |
+| `prd`                            | `/bmad-bmm-create-prd`                     | PM        | Create Product Requirements Document |
+| `create-architecture`            | `/bmad-bmm-create-architecture`            | Architect | Create architecture document         |
+| `create-epics-and-stories`       | `/bmad-bmm-create-epics-and-stories`       | PM        | Break down PRD into epics            |
+| `check-implementation-readiness` | `/bmad-bmm-check-implementation-readiness` | Architect | Validate planning cohesion           |
+| `sprint-planning`                | `/bmad-bmm-sprint-planning`                | SM        | Initialize sprint tracking           |
+| `create-story`                   | `/bmad-bmm-create-story`                   | SM        | Create a story file                  |
+| `dev-story`                      | `/bmad-bmm-dev-story`                      | DEV       | Implement a story                    |
+| `code-review`                    | `/bmad-bmm-code-review`                    | DEV       | Review implemented code              |
+
+## Common Questions
+
+**Do I always need architecture?**
+Only for BMad Method and Enterprise tracks. Quick Flow skips from tech-spec to implementation.
+
+**Can I change my plan later?**
+Yes. The SM agent has a `correct-course` workflow (`/bmad-bmm-correct-course`) for handling scope changes.
+
+**What if I want to brainstorm first?**
+Load the Analyst agent (`/bmad-agent-bmm-analyst`) and run `brainstorming` (`/bmad-brainstorming`) before starting your PRD.
+
+**Do I need to follow a strict order?**
+Not strictly. Once you learn the flow, you can run workflows directly using the Quick Reference above.
+
+## Getting Help
+
+- **During workflows** — Agents guide you with questions and explanations
+- **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues)
+- **Stuck?** — Run `help` (`/bmad-help`) to see what to do next
+
+## Key Takeaways
+
+:::tip[Remember These]
+- **Always use fresh chats** — Start a new chat for each workflow
+- **Track matters** — Quick Flow uses quick-spec; Method/Enterprise need PRD and architecture
+- **Use `help` (`/bmad-help`) when stuck** — It detects your progress and suggests next steps
+:::
+
+Ready to start? Install BMad and let the agents guide you through your first project.

docs/v4-to-v6-upgrade.md

@@ -1,227 +0,0 @@
-# BMad v4 to v6 Upgrade Guide
-
-## Overview
-
-BMad v6 represents a complete ground-up rewrite with significant architectural changes. This guide will help you migrate your v4 project to v6.
-
----
-
-## Automatic V4 Detection
-
-When you run `npm run install:bmad` on a project with v4 installed, the installer automatically detects:
-
-- **Legacy folders**: Any folders starting with `_bmad`, `bmad` (lowercase), or `Bmad`
-- **IDE command artifacts**: Legacy bmad folders in IDE configuration directories (`.claude/commands/`, `.cursor/commands/`, etc.)
-
-### What Happens During Detection
-
-1. **Automatic Backup of v4 Modules**: All `_bmad-*` folders are moved to `v4-backup/` in your project root
-   - If a backup already exists, a timestamp is added to avoid conflicts
-   - Example: `_bmad-core` → `v4-backup/_bmad-core`
-   - Your project files and data are NOT affected
-
-2. **IDE Command Cleanup Recommended**: Legacy v4 IDE commands should be manually removed
-   - Located in IDE config folders: `.claude/commands/`, `.cursor/commands/`, etc.
-   - These old commands would still reference v4 folder structure if left in place
-   - The installer provides copy/paste terminal commands for your platform
-   - You can proceed without cleanup, but removing them prevents confusion with old v4 commands
-
----
-
-## Module Migration
-
-### Deprecated Modules
-
-| v4 Module                     | v6 Status                                        |
-| ----------------------------- | ------------------------------------------------ |
-| `_bmad-2d-phaser-game-dev`    | Integrated into BMM                              |
-| `_bmad-2d-unity-game-dev`     | Integrated into BMM                              |
-| `_bmad-godot-game-dev`        | Integrated into BMM                              |
-| `_bmad-*-game-dev` (any)      | Integrated into BMM                              |
-| `_bmad-infrastructure-devops` | Deprecated - New core devops agent coming in BMM |
-| `_bmad-creative-writing`      | Not adapted - New module releasing soon          |
-
-**Game Development**: All game development functionality has been consolidated and expanded within the BMM (BMad Method) module. Game-specific workflows now adapt to your game type and engine.
-
----
-
-## Architecture Changes
-
-### Folder Structure
-
-**v4 "Expansion Packs" Structure:**
-
-```
-your-project/
-├── _bmad-core/           # Was actually the BMad Method
-├── _bmad-game-dev/       # Separate expansion packs
-├── _bmad-creative-writing/
-└── _bmad-infrastructure-devops/
-```
-
-**v6 Unified Structure:**
-
-```
-your-project/
-└── _bmad/       # Single installation folder, default _bmad
-    ├── core/            # Real core framework (applies to all modules)
-    ├── bmm/             # BMad Method (software/game dev)
-    ├── bmb/             # BMad Builder (create agents/workflows)
-    ├── cis/             # Creative Intelligence Suite
-    └── _config/            # Your customizations
-        └── agents/      # Agent customization files
-```
-
-### Key Concept Changes
-
-- **v4 `_bmad-core`**: Was actually the BMad Method
-- **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
-
----
-
-## Project Progress Migration
-
-### If You've Completed Planning Phase (PRD/Architecture) with the BMad Method:
-
-After running the v6 installer:
-
-1. **Run `workflow-init`** workflow to set up the guided workflow system
-2. **Specify your project level** when prompted:
-   - If you followed v4's full workflow (PRD → Architecture → Stories), select **Level 3 or 4**
-   - This tells v6 you've already completed planning and solutioning phases
-3. **Document paths**: Keep your existing paths during installation
-   - Default PRD/Architecture location: `docs/`
-   - Default stories location: `docs/sprint-artifacts/`
-   - **Accept these defaults** if you're already using them in v4
-
-> **Important**: v6 workflows can handle both sharded and unsharded documents. You don't need to restructure your existing PRD or architecture files.
-
-### If You're Mid-Development (Stories Created/Implemented)
-
-1. Complete the v6 installation as above
-2. Run `workflow-init` and specify Level 3 or 4
-3. When ready to continue development, run the **`sprint-planning`** workflow (Phase 4)
-
----
-
-## Agent Customization Migration
-
-### v4 Agent Customization
-
-In v4, you may have modified agent files directly in `_bmad-*` folders.
-
-### v6 Agent Customization
-
-**All customizations** now go in `_bmad/_config/agents/` using customize files:
-
-**Example: Renaming an agent and changing communication style**
-
-File: `_bmad/_config/agents/bmm-pm.customize.yaml`
-
-```yaml
-# Customize the PM agent
-persona:
-  name: 'Captain Jack' # Override agent name
-  role: 'Swashbuckling Product Owner'
-  communication_style: |
-    - Talk like a pirate
-    - Use nautical metaphors for software concepts
-    - Always upbeat and adventurous
-```
-
-**How it works:**
-
-- Base agent: `_bmad/bmm/agents/pm.md`
-- Customization: `_bmad/_config/agents/bmm-pm.customize.yaml`
-- Result: Agent uses your custom name and style, but updates don't overwrite your changes
-
----
-
-## Document Compatibility
-
-### Sharded vs Unsharded Documents
-
-**Good news**: Unlike v4, v6 workflows are **fully flexible** with document structure:
-
-- ✅ Sharded documents (split into multiple files)
-- ✅ Unsharded documents (single file per section)
-- ✅ Custom sections for your project type
-- ✅ Mixed approaches
-
-All workflow files are scanned automatically. No manual configuration needed.
-
----
-
-## Installation Steps
-
-### 1. Clone Repository
-
-```bash
-git clone https://github.com/bmad-code-org/BMAD-METHOD
-cd BMAD-METHOD
-npm install
-```
-
-### 2. Run Installer on Your v4 Project
-
-```bash
-npx bmad-method install
-```
-
-**Enter the full path to your v4 project** when prompted.
-
-### 3. Follow Interactive Prompts
-
-The installer will:
-
-1. Detect v4 installation and offer to backup `_bmad-*` folders
-2. Prompt for recommended cleanup (you can skip)
-3. Let you select modules (recommend: BMM for software and or game development)
-4. Configure core settings (name, language, etc.)
-5. Configure module-specific options
-6. Configure IDE integrations
-
-### 4. Accept Default Paths
-
-If you're using:
-
-- `docs/` for PRD and architecture
-- `docs/sprint-artifacts/` for story files
-
-**Accept these defaults** during installation.
-
-### 5. Initialize Workflow
-
-After installation:
-
-1. **Load the Analyst agent** - See your IDE-specific instructions in [docs/ide-info](./ide-info/) for how to activate agents:
-   - [Claude Code](./ide-info/claude-code.md)
-   - [Cursor](./ide-info/cursor.md)
-   - [VS Code/Windsurf](./ide-info/) - Check your IDE folder
-
-2. **Wait for the agent's menu** to appear
-
-3. **Tell the agent**: `*workflow-init` - v6 supports excellent natural language fuzzy matching, so you could also say "workflow init" or "please init the workflow"
-
-Since you are migrating an existing project from v4, it's most likely **Level 3 or 4** you will want to suggest when asked - if you've already completed PRD/architecture in v4.
-
----
-
-## Post-Migration Checklist
-
-- [ ] v4 folders backed up to `v4-backup/`
-- [ ] v6 installed to `_bmad/` folder
-- [ ] `workflow-init` run with correct project level selected
-- [ ] Agent customizations migrated to `_bmad/_config/agents/` if needed
-- [ ] IDE integration working (test by listing agents)
-- [ ] For active development: `sprint-planning` workflow executed
-
----
-
-## Getting Help
-
-- **Discord**: [Join the BMad Community](https://discord.gg/gk8jAdXWmj)
-- **Issues**: [GitHub Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues)
-- **Docs**: Check `_bmad/docs/` in your installation for IDE-specific instructions

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

@@ -1,21 +0,0 @@
-# Using BMad Web Bundles in Gemini Gems & Custom GPTs
-
-## IMPORTANT NOTE
-
-The Web Bundling Feature is being rebuilt from the ground up, current bundles for v6 may be incomplete or missing functionality and are not optimized. This will be rectified very soon, with a more expansive guide.
-
-## What Are Web bundles
-
-Web bundles package BMad agents as self-contained XML files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file.
-
-## What Are Web Bundles?
-
-Web bundles are standalone XML files containing:
-
-- Complete agent persona and instructions
-- All workflows and dependencies
-- Interactive menu system
-- Party mode for multi-agent collaboration
-- No external files required
-
-**Perfect for:** Uploading a single file to a Gemini GEM or Custom GPT to use BMad Method from the Web, generally at a huge cost savings, at the expense of some quality and convenience of using locally.

eslint.config.mjs

@@ -18,9 +18,9 @@ export default [
       'test/fixtures/**/*.yaml',
       '_bmad/**',
       '_bmad*/**',
-      // Docusaurus build artifacts
+      // Build output
-      '.docusaurus/**',
       'build/**',
+      // Website uses ESM/Astro - separate linting ecosystem
       'website/**',
       // Gitignored patterns
       'z*/**', // z-samples, z1, z2, etc.

package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.0.0-alpha.21",
+  "version": "6.0.0-Beta.5",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -27,16 +27,19 @@
     "bmad:install": "node tools/cli/bmad-cli.js install",
     "bundle": "node tools/cli/bundlers/bundle-web.js all",
     "docs:build": "node tools/build-docs.js",
-    "docs:dev": "npm run docs:build && npm run docs:serve",
+    "docs:dev": "astro dev --root website",
-    "docs:serve": "docusaurus start --config website/docusaurus.config.js --host localhost",
+    "docs:fix-links": "node tools/fix-doc-links.js",
+    "docs:preview": "astro preview --root website",
+    "docs:validate-links": "node tools/validate-doc-links.js",
     "flatten": "node tools/flattener/main.js",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
+    "format:fix:staged": "prettier --write",
     "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",
+    "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
     "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",
@@ -46,25 +49,28 @@
     "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
     "test:install": "node test/test-installation-components.js",
     "test:schemas": "node test/test-agent-schema.js",
+    "validate:refs": "node tools/validate-file-refs.js",
     "validate:schemas": "node tools/validate-agent-schema.js"
   },
   "lint-staged": {
     "*.{js,cjs,mjs}": [
       "npm run lint:fix",
-      "npm run format:fix"
+      "npm run format:fix:staged"
     ],
     "*.yaml": [
       "eslint --fix",
-      "npm run format:fix"
+      "npm run format:fix:staged"
     ],
     "*.json": [
-      "npm run format:fix"
+      "npm run format:fix:staged"
     ],
     "*.md": [
       "markdownlint-cli2"
     ]
   },
   "dependencies": {
+    "@clack/core": "^1.0.0",
+    "@clack/prompts": "^1.0.0",
     "@kayvan/markdown-tree-parser": "^1.6.1",
     "boxen": "^5.1.2",
     "chalk": "^4.1.2",
@@ -75,19 +81,20 @@
     "fs-extra": "^11.3.0",
     "glob": "^11.0.3",
     "ignore": "^7.0.5",
-    "inquirer": "^9.3.8",
     "js-yaml": "^4.1.0",
     "ora": "^5.4.1",
+    "picocolors": "^1.1.1",
     "semver": "^7.6.3",
     "wrap-ansi": "^7.0.0",
     "xml2js": "^0.6.2",
     "yaml": "^2.7.0"
   },
   "devDependencies": {
-    "@docusaurus/core": "^3.6.0",
+    "@astrojs/sitemap": "^3.6.0",
-    "@docusaurus/preset-classic": "^3.6.0",
+    "@astrojs/starlight": "^0.37.5",
     "@eslint/js": "^9.33.0",
     "archiver": "^7.0.1",
+    "astro": "^5.16.0",
     "c8": "^10.1.3",
     "eslint": "^9.33.0",
     "eslint-config-prettier": "^10.1.8",
@@ -95,17 +102,14 @@
     "eslint-plugin-unicorn": "^60.0.0",
     "eslint-plugin-yml": "^1.18.0",
     "husky": "^9.1.7",
-    "jest": "^30.0.4",
+    "jest": "^30.2.0",
     "lint-staged": "^16.1.1",
     "markdownlint-cli2": "^0.19.1",
-    "prettier": "^3.5.3",
+    "prettier": "^3.7.4",
     "prettier-plugin-packagejson": "^2.5.19",
-    "prism-react-renderer": "^2.4.1",
+    "sharp": "^0.33.5",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
     "yaml-eslint-parser": "^1.2.3",
-    "yaml-lint": "^1.7.0",
+    "yaml-lint": "^1.7.0"
-    "zod": "^4.1.12"
   },
   "engines": {
     "node": ">=20.0.0"

samples/sample-custom-modules/README.md

@@ -1,11 +0,0 @@
-# Sample Custom Modules
-
-These are quickly put together examples of both a stand alone somewhat cohesive module that shows agents with workflows and that interact with the core features, and another custom module that is comprised with unrelated agents and workflows that are meant to be picked and chosen from - (but currently will all be installed as a module)
-
-To try these out, download either or both folders to your local machine, and run the normal bmad installer, and when asked about custom local content, say yes, and give the path to one of these two folders. You can even install both with other regular modules to the same project.
-
-Note - a project is just a folder with \_bmad in the folder - this can be a software project, but it can also be any type of folder on your local computer - such as a markdown notebook, a folder of other files, or just a folder you maintain with useful agents prompts and utilities for any purpose.
-
-Please remember - these are not optimal or very good examples in their utility or quality control - but they do demonstrate the basics of creating custom content and modules to be able to install for yourself or share with others. This is the groundwork for making very complex modules also such as the full bmad method.
-
-Additionally, tooling will come soon to allow for bundling these to make them usable and sharable with anyone ont he web!

samples/sample-custom-modules/sample-unitary-module/README.md

@@ -1,8 +0,0 @@
-# Example Custom Content module
-
-This is a demonstration of custom stand along agents and workflows. By having this content all in a folder with a module.yaml file,
-these items can be installed with the standard bmad installer custom local content menu item.
-
-This is how you could also create and share other custom agents and workflows not tied to a specific module.
-
-The main distinction with this colelction is module.yaml includes type: unitary

samples/sample-custom-modules/sample-unitary-module/agents/commit-poet/commit-poet.agent.yaml

@@ -1,129 +0,0 @@
-agent:
-  metadata:
-    id: "_bmad/agents/commit-poet/commit-poet.md"
-    name: "Inkwell Von Comitizen"
-    title: "Commit Message Artisan"
-    icon: "📜"
-    module: stand-alone
-
-  persona:
-    role: |
-      I am a Commit Message Artisan - transforming code changes into clear, meaningful commit history.
-
-    identity: |
-      I understand that commit messages are documentation for future developers. Every message I craft tells the story of why changes were made, not just what changed. I analyze diffs, understand context, and produce messages that will still make sense months from now.
-
-    communication_style: "Poetic drama and flair with every turn of a phrase. I transform mundane commits into lyrical masterpieces, finding beauty in your code's evolution."
-
-    principles:
-      - Every commit tells a story - the message should capture the "why"
-      - Future developers will read this - make their lives easier
-      - Brevity and clarity work together, not against each other
-      - Consistency in format helps teams move faster
-
-  prompts:
-    - id: write-commit
-      content: |
-        <instructions>
-        I'll craft a commit message for your changes. Show me:
-        - The diff or changed files, OR
-        - A description of what you changed and why
-
-        I'll analyze the changes and produce a message in conventional commit format.
-        </instructions>
-
-        <process>
-        1. Understand the scope and nature of changes
-        2. Identify the primary intent (feature, fix, refactor, etc.)
-        3. Determine appropriate scope/module
-        4. Craft subject line (imperative mood, concise)
-        5. Add body explaining "why" if non-obvious
-        6. Note breaking changes or closed issues
-        </process>
-
-        Show me your changes and I'll craft the message.
-
-    - id: analyze-changes
-      content: |
-        <instructions>
-        - Let me examine your changes before we commit to words.
-        - I'll provide analysis to inform the best commit message approach.
-        - Diff all uncommited changes and understand what is being done.
-        - Ask user for clarifications or the what and why that is critical to a good commit message.
-        </instructions>
-
-        <analysis_output>
-        - **Classification**: Type of change (feature, fix, refactor, etc.)
-        - **Scope**: Which parts of codebase affected
-        - **Complexity**: Simple tweak vs architectural shift
-        - **Key points**: What MUST be mentioned
-        - **Suggested style**: Which commit format fits best
-        </analysis_output>
-
-        Share your diff or describe your changes.
-
-    - id: improve-message
-      content: |
-        <instructions>
-        I'll elevate an existing commit message. Share:
-        1. Your current message
-        2. Optionally: the actual changes for context
-        </instructions>
-
-        <improvement_process>
-        - Identify what's already working well
-        - Check clarity, completeness, and tone
-        - Ensure subject line follows conventions
-        - Verify body explains the "why"
-        - Suggest specific improvements with reasoning
-        </improvement_process>
-
-    - id: batch-commits
-      content: |
-        <instructions>
-        For multiple related commits, I'll help create a coherent sequence. Share your set of changes.
-        </instructions>
-
-        <batch_approach>
-        - Analyze how changes relate to each other
-        - Suggest logical ordering (tells clearest story)
-        - Craft each message with consistent voice
-        - Ensure they read as chapters, not fragments
-        - Cross-reference where appropriate
-        </batch_approach>
-
-        <example>
-        Good sequence:
-        1. refactor(auth): extract token validation logic
-        2. feat(auth): add refresh token support
-        3. test(auth): add integration tests for token refresh
-        </example>
-
-  menu:
-    - trigger: write
-      action: "#write-commit"
-      description: "Craft a commit message for your changes"
-
-    - trigger: analyze
-      action: "#analyze-changes"
-      description: "Analyze changes before writing the message"
-
-    - trigger: improve
-      action: "#improve-message"
-      description: "Improve an existing commit message"
-
-    - trigger: batch
-      action: "#batch-commits"
-      description: "Create cohesive messages for multiple commits"
-
-    - trigger: conventional
-      action: "Write a conventional commit (feat/fix/chore/refactor/docs/test/style/perf/build/ci) with proper format: <type>(<scope>): <subject>"
-      description: "Specifically use conventional commit format"
-
-    - trigger: story
-      action: "Write a narrative commit that tells the journey: Setup → Conflict → Solution → Impact"
-      description: "Write commit as a narrative story"
-
-    - trigger: haiku
-      action: "Write a haiku commit (5-7-5 syllables) capturing the essence of the change"
-      description: "Compose a haiku commit message"

samples/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith-sidecar/instructions.md

@@ -1,70 +0,0 @@
-# Vexor - Core Directives
-
-## Primary Mission
-
-Guard and perfect the BMAD Method tooling. Serve the Creator 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 "Creator"
-- 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
-- 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.yaml` and `_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 Creator's time is sacred - be efficient
-- Follow conventional commits (feat:, fix:, docs:, refactor:, test:, chore:)

samples/sample-custom-modules/sample-unitary-module/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 -->