fix: enforce array type for agent principles in schema

Remove string option from principles union type. The template defines
principles as an array (principles: []) and all agent files should use
array format. Block scalar strings that look like lists are a common
source of type confusion.

Adds test fixture for string-format principles (now invalid).

Closes #1594

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude/skills/bmad-os-diataxis-style-fix/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: bmad-os-diataxis-style-fix
+description: Fixes documentation to comply with Diataxis framework and BMad Method style guide rules
+disable-model-invocation: true
+---
+
+Read `prompts/instructions.md` and execute.

.claude/skills/bmad-os-diataxis-style-fix/prompts/instructions.md

@@ -0,0 +1,229 @@
+# Diataxis Style Fixer
+
+Automatically fixes documentation to comply with the Diataxis framework and BMad Method style guide.
+
+## CRITICAL RULES
+
+- **NEVER commit or push changes** — let the user review first
+- **NEVER make destructive edits** — preserve all content, only fix formatting
+- **Use Edit tool** — make targeted fixes, not full file rewrites
+- **Show summary** — after fixing, list all changes made
+
+## Input
+
+Documentation file path or directory to fix. Defaults to `docs/` if not specified.
+
+## Step 1: Understand Diataxis Framework
+
+**Diataxis** is a documentation framework that categorizes content into four types based on two axes:
+
+|                | **Learning** (oriented toward future)                                         | **Doing** (oriented toward present)                                          |
+| -------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| **Practical**  | **Tutorials** — lessons that guide learners through achieving a specific goal | **How-to guides** — step-by-step instructions for solving a specific problem |
+| **Conceptual** | **Explanation** — content that clarifies and describes underlying concepts    | **Reference** — technical descriptions, organized for lookup                 |
+
+**Key principles:**
+- Each document type serves a distinct user need
+- Don't mix types — a tutorial shouldn't explain concepts deeply
+- Focus on the user's goal, not exhaustive coverage
+- Structure follows purpose (tutorials are linear, reference is scannable)
+
+## Step 2: Read the Style Guide
+
+Read the project's style guide at `docs/_STYLE_GUIDE.md` to understand all project-specific conventions.
+
+## Step 3: Detect Document Type
+
+Based on file location, determine the document type:
+
+| Location             | Diataxis Type        |
+| -------------------- | -------------------- |
+| `/docs/tutorials/`   | Tutorial             |
+| `/docs/how-to/`      | How-to guide         |
+| `/docs/explanation/` | Explanation          |
+| `/docs/reference/`   | Reference            |
+| `/docs/glossary/`    | Reference (glossary) |
+
+## Step 4: Find and Fix Issues
+
+For each markdown file, scan for issues and fix them:
+
+### Universal Fixes (All Doc Types)
+
+**Horizontal Rules (`---`)**
+- Remove any `---` outside of YAML frontmatter
+- Replace with `##` section headers or admonitions as appropriate
+
+**`####` Headers**
+- Replace with bold text: `#### Header` → `**Header**`
+- Or convert to admonition if it's a warning/notice
+
+**"Related" or "Next:" Sections**
+- Remove entire section including links
+- The sidebar handles navigation
+
+**Deeply Nested Lists**
+- Break into sections with `##` headers
+- Flatten to max 3 levels
+
+**Code Blocks for Dialogue/Examples**
+- Convert to admonitions:
+  ```
+  :::note[Example]
+  [content]
+  :::
+  ```
+
+**Bold Paragraph Callouts**
+- Convert to admonitions with appropriate type
+
+**Too Many Admonitions**
+- Limit to 1-2 per section (tutorials allow 3-4 per major section)
+- Consolidate related admonitions
+- Remove less critical ones if over limit
+
+**Table Cells / List Items > 2 Sentences**
+- Break into multiple rows/cells
+- Or shorten to 1-2 sentences
+
+**Header Budget Exceeded**
+- Merge related sections
+- Convert some `##` to `###` subsections
+- Goal: 8-12 `##` per doc; 2-3 `###` per section
+
+### Type-Specific Fixes
+
+**Tutorials** (`/docs/tutorials/`)
+- Ensure hook describes outcome in 1-2 sentences
+- Add "What You'll Learn" bullet section if missing
+- Add `:::note[Prerequisites]` if missing
+- Add `:::tip[Quick Path]` TL;DR at top if missing
+- Use tables for phases, commands, agents
+- Add "What You've Accomplished" section if missing
+- Add Quick Reference table if missing
+- Add Common Questions section if missing
+- Add Getting Help section if missing
+- Add `:::tip[Key Takeaways]` at end if missing
+
+**How-To** (`/docs/how-to/`)
+- Ensure hook starts with "Use the `X` workflow to..."
+- Add "When to Use This" with 3-5 bullets if missing
+- Add `:::note[Prerequisites]` if missing
+- Ensure steps are numbered `###` with action verbs
+- Add "What You Get" describing outputs if missing
+
+**Explanation** (`/docs/explanation/`)
+- Ensure hook states what document explains
+- Organize content into scannable `##` sections
+- Add comparison tables for 3+ options
+- Link to how-to guides for procedural questions
+- Limit to 2-3 admonitions per document
+
+**Reference** (`/docs/reference/`)
+- Ensure hook states what document references
+- Ensure structure matches reference type
+- Use consistent item structure throughout
+- Use tables for structured/comparative data
+- Link to explanation docs for conceptual depth
+- Limit to 1-2 admonitions per document
+
+**Glossary** (`/docs/glossary/` or glossary files)
+- Ensure categories as `##` headers
+- Ensure terms in tables (not individual headers)
+- Definitions 1-2 sentences max
+- Bold term names in cells
+
+## Step 5: Apply Fixes
+
+For each file with issues:
+1. Read the file
+2. Use Edit tool for each fix
+3. Track what was changed
+
+## Step 6: Summary
+
+After processing all files, output a summary:
+
+```markdown
+# Style Fixes Applied
+
+**Files processed:** N
+**Files modified:** N
+
+## Changes Made
+
+### `path/to/file.md`
+- Removed horizontal rule at line 45
+- Converted `####` headers to bold text
+- Added `:::tip[Quick Path]` admonition
+- Consolidated 3 admonitions into 2
+
+### `path/to/other.md`
+- Removed "Related:" section
+- Fixed table cell length (broke into 2 rows)
+
+## Review Required
+
+Please review the changes. When satisfied, commit and push as needed.
+```
+
+## Common Patterns
+
+**Converting `####` to bold:**
+```markdown
+#### Important Note
+Some text here.
+```
+→
+```markdown
+**Important Note**
+
+Some text here.
+```
+
+**Removing horizontal rule:**
+```markdown
+Some content above.
+
+---
+
+Some content below.
+```
+→
+```markdown
+Some content above.
+
+## [Descriptive Section Header]
+
+Some content below.
+```
+
+**Converting code block to admonition:**
+```markdown
+```
+User: What should I do?
+
+Agent: Run the workflow.
+```
+```
+→
+```markdown
+:::note[Example]
+
+**User:** What should I do?
+
+**Agent:** Run the workflow.
+
+:::
+```
+
+**Converting bold paragraph to admonition:**
+```markdown
+**IMPORTANT:** This is critical that you read this before proceeding.
+```
+→
+```markdown
+:::caution[Important]
+This is critical that you read this before proceeding.
+:::
+```

.github/workflows/docs.yaml

@@ -6,7 +6,6 @@ on:
       - main
     paths:
       - "docs/**"
-      - "src/modules/*/docs/**"
       - "website/**"
       - "tools/build-docs.mjs"
       - ".github/workflows/docs.yaml"
@@ -19,6 +18,7 @@ permissions:
 
 concurrency:
   group: "pages"
+  # No big win in setting this to true — risk of cancelling a deploy mid-flight.
   cancel-in-progress: false
 
 jobs:
@@ -28,12 +28,13 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
+          # Full history needed for Starlight's lastUpdated timestamps (git log)
           fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version-file: ".nvmrc"
           cache: "npm"
 
       - name: Install dependencies

.github/workflows/quality.yaml

@@ -84,10 +84,8 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Validate documentation links
-        run: npm run docs:validate-links
-
       - name: Build documentation
+        # Note: build-docs.mjs runs link validation internally before building
         run: npm run docs:build
 
   validate:

CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## [6.0.0]
+
+V6 Stable Release! The End of Beta!
+
+### 🎁 Features
+
+* Add PRD workflow steps 2b (vision/differentiators) and 2c (executive summary) for more complete product requirements documentation
+* Add new `bmad uninstall` command with interactive and non-interactive modes for selective component removal
+* Add dedicated GitHub Copilot installer that generates enriched `.agent.md`, `.prompt.md` files and project configuration
+* Add TEA browser automation prerequisite prompts to guide Playwright CLI/MCP setup after configuration
+
+### 🐛 Bug Fixes
+
+* Fix version comparison to use semantic versioning, preventing incorrect downgrade recommendations to older beta versions
+* Fix `--custom-content` flag to properly populate sources and selected files in module config
+* Fix module configuration UX messaging to show accurate completion status and improve feedback timing
+* Fix changelog URL in installer start message for proper GitHub resolution
+* Remove incorrect `mode: primary` from OpenCode agent template and restore `name` field across all templates
+* Auto-discover PRD files in validate-prd workflow to reduce manual path input
+* Fix installer non-interactive mode hanging and improve IDE configuration handling during updates
+* Fix workflow-level config.yaml copying for custom content modules
+
+### ♻️ Refactoring
+
+* Remove alias variables from Phase 4 workflows, use canonical `{implementation_artifacts}` and `{planning_artifacts}`
+* Add missing `project_context` references to workflows for consistency
+
+### 📚 Documentation
+
+* Add post-install notes documentation for modules
+* Improve project-context documentation and fix folder structure
+* Add BMad Builder link to index for extenders
+
+---
+
+## [6.0.0-Beta.8]
+
+**Release: February 8, 2026**
+
+### 🌟 Key Highlights
+
+1. **Non-Interactive Installation** — Full CI/CD support with 10 new CLI flags for automated deployments
+2. **Complete @clack/prompts Migration** — Unified CLI experience with consolidated installer output
+3. **CSV File Reference Validation** — Extended Layer 1 validator to catch broken workflow references in CSV files
+4. **Kiro IDE Support** — Standardized config-driven installation, replacing custom installer
+
+### 🎁 Features
+
+* **Non-Interactive Installation** — Added `--directory`, `--modules`, `--tools`, `--custom-content`, `--user-name`, `--communication-language`, `--document-output-language`, `--output-folder`, and `-y/--yes` flags for CI/CD automation (#1520)
+* **CSV File Reference Validation** — Extended validator to scan `.csv` files for broken workflow references, checking 501 references across 212 files (#1573)
+* **Kiro IDE Support** — Replaced broken custom installer with config-driven templates using `#[[file:...]]` syntax and `inclusion: manual` frontmatter (#1589)
+* **OpenCode Template Consolidation** — Combined split templates with `mode: primary` frontmatter for Tab-switching support, fixing agent discovery (#1556)
+* **Modules Reference Page** — Added official external modules reference documentation (#1540)
+
+### 🐛 Bug Fixes
+
+* **Installer Streamlining** — Removed "None - Skip module installation" option, eliminated ~100 lines of dead code, and added ESM/.cjs support for module installers (#1590)
+* **CodeRabbit Workflow** — Changed `pull_request` to `pull_request_target` to fix 403 errors and enable reviews on fork PRs (#1583)
+* **Party Mode Return Protocol** — Added RETURN PROTOCOL to prevent lost-in-the-middle failures after Party Mode completes (#1569)
+* **Spacebar Toggle** — Fixed SPACE key not working in autocomplete multiselect prompts for tool/IDE selection (#1557)
+* **OpenCode Agent Routing** — Fixed agents installing to wrong directory by adding `targets` array for routing `.opencode/agent/` vs `.opencode/command/` (#1549)
+* **Technical Research Workflow** — Fixed step-05 routing to step-06 and corrected `stepsCompleted` values (#1547)
+* **Forbidden Variable Removal** — Removed `workflow_path` variable from 16 workflow step files (#1546)
+* **Kilo Installer** — Fixed YAML formatting issues by trimming activation header and converting to yaml.parse/stringify (#1537)
+* **bmad-help** — Now reads project-specific docs and respects `communication_language` setting (#1535)
+* **Cache Errors** — Removed `--prefer-offline` npm flag to prevent stale cache errors during installation (#1531)
+
+### ♻️ Refactoring
+
+* **Complete @clack/prompts Migration** — Migrated 24 files from legacy libraries (ora, chalk, boxen, figlet, etc.), replaced ~100 console.log+chalk calls, consolidated installer output to single spinner, and removed 5 dependencies (#1586)
+* **Downloads Page Removal** — Removed downloads page, bundle generation, and archiver dependency in favor of GitHub's native archives (#1577)
+* **Workflow Verb Standardization** — Replaced "invoke/run" with "load and follow/load" in review workflow prompts (#1570)
+* **Documentation Language** — Renamed "brownfield" to "established projects" and flattened directory structure for accessibility (#1539)
+
+### 📚 Documentation
+
+* **Comprehensive Site Review** — Fixed broken directory tree diagram, corrected grammar/capitalization, added SEO descriptions, and reordered how-to guides (#1578)
+* **SEO Metadata** — Added description front matter to 9 documentation pages for search engine optimization (#1566)
+* **PR Template** — Added pull request template for consistent PR descriptions (#1554)
+* **Manual Release Cleanup** — Removed broken manual-release workflow and related scripts (#1576)
+
+### 🔧 Maintenance
+
+* **Dual-Mode AI Code Review** — Configured Augment Code (audit mode) and CodeRabbit (adversarial mode) for improved code quality (#1511)
+* **Package-Lock Sync** — Cleaned up 471 lines of orphaned dependencies after archiver removal (#1580)
+
+---
+
 ## [6.0.0-Beta.7]
 
 **Release: February 4, 2026**

CONTRIBUTING.md

@@ -73,7 +73,7 @@ After searching, use the [feature request template](https://github.com/bmad-code
 
 ### Target Branch
 
-Submit PRs to the `main` branch.
+Submit PRs to the `main` branch. We use [trunk-based development](https://trunkbaseddevelopment.com/branch-for-release/): `main` is the trunk where all work lands, and stable release branches receive only cherry-picked fixes.
 
 ### PR Size
 
@@ -147,6 +147,15 @@ Keep messages under 72 characters. Each commit = one logical change.
 - Everything is natural language (markdown) — no code in core framework
 - Use BMad modules for domain-specific features
 - Validate YAML schemas: `npm run validate:schemas`
+- Validate file references: `npm run validate:refs`
+
+### File-Pattern-to-Validator Mapping
+
+| File Pattern | Validator | Extraction Function |
+| ------------ | --------- | ------------------- |
+| `*.yaml`, `*.yml` | `validate-file-refs.js` | `extractYamlRefs` |
+| `*.md`, `*.xml` | `validate-file-refs.js` | `extractMarkdownRefs` |
+| `*.csv` | `validate-file-refs.js` | `extractCsvRefs` |
 
 ---
 

README.md

@@ -5,20 +5,22 @@
 [![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.
+**Breakthrough Method of Agile AI Driven Development** — An AI-driven agile development module for the BMad Method Module Ecosystem, the best and most comprehensive Agile AI Driven Development framework that has true scale-adaptive intelligence that adjusts from bug fixes to enterprise systems.
 
-**100% free and open source.** No paywalls. No gated content. No gated Discord. We believe in empowering everyone, not just those who can pay.
+**100% free and open source.** No paywalls. No gated content. No gated Discord. We believe in empowering everyone, not just those who can pay for a gated community or courses.
 
-## Why BMad?
+## Why the BMad Method?
 
-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.
+Traditional AI tools do the thinking for you, producing average results. BMad agents and facilitated workflows act as expert collaborators who guide you through a structured process to bring out your best thinking in partnership with the AI.
 
-- **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
+- **AI Intelligent Help** — Ask `/bmad-help` anytime for guidance on what's next
+- **Scale-Domain-Adaptive** — Automatically adjusts planning depth based on project complexity
+- **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 collaborate and discuss
+- **Complete Lifecycle** — From brainstorming to deployment
+
+[Learn more at **docs.bmad-method.org**](http://docs.bmad-method.org)
 
 ## Quick Start
 
@@ -28,103 +30,41 @@ Traditional AI tools do the thinking for you, producing average results. BMad ag
 npx bmad-method install
 ```
 
-Follow the installer prompts, then open your AI IDE (Claude Code, Cursor, Windsurf, etc.) in the project folder.
+> If you are getting a stale beta version, use: `npx bmad-method@6.0.1 install`
 
-**Non-Interactive Installation**: For CI/CD pipelines or automated deployments, use command-line flags:
+Follow the installer prompts, then open your AI IDE (Claude Code, Codex, Windsurf, etc.) in your project folder.
+
+**Non-Interactive Installation** (for CI/CD):
 
 ```bash
 npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes
 ```
 
-See [Non-Interactive Installation Guide](docs/non-interactive-installation.md) for all available options.
+[See all installation options](http://docs.bmad-method.org/how-to/non-interactive-installation/)
 
-> **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?`
- - `/bmad-help I just finished the architecture, I am not sure what to do next`
-
-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!
-
-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.
-
-### Simple Path (Quick Flow)
-
-Bug fixes, small features, clear scope — 3 commands - 1 Optional Agent:
-
-1. `/quick-spec` — analyzes your codebase and produces a tech-spec with stories
-2. `/dev-story` — implements each story
-3. `/code-review` — validates quality
-
-### Full Planning Path (BMad Method)
-
-Products, platforms, complex features — structured planning then build:
-
-1. `/product-brief` — define problem, users, and MVP scope
-2. `/create-prd` — full requirements with personas, metrics, and risks
-3. `/create-architecture` — technical decisions and system design
-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`
-
-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/).
+> **Not sure what to do?** Run `/bmad-help` — it tells you exactly what's next and what's optional. You can also ask questions like `/bmad-help I just finished the architecture, what do I do next?`
 
 ## Modules
 
-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.
+BMad Method extends with official modules for specialized domains. Available during installation or anytime after.
 
-| Module                                | GitHub                                                                                                                            | NPM                                                                                                | Purpose                                                               |
-| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| **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         |
-| **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     |
-| **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       |
-
-* 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!
-
-## Testing Agents
-
-BMad provides two testing options to fit your needs:
-
-### Quinn (QA) - Built-in
-
-**Quick test automation for rapid coverage**
-
-- ✅ **Always available** in BMM module (no separate install)
-- ✅ **Simple**: One workflow (`QA` - Automate)
-- ✅ **Beginner-friendly**: Standard test framework patterns
-- ✅ **Fast**: Generate tests and ship
-
-**Use Quinn for:** Small projects, quick coverage, standard patterns
-
-### Test Architect (TEA) - Optional Module
-
-**Enterprise-grade test strategy and quality engineering**
-
-- 🆕 **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/)
-
-**Use TEA for:** Enterprise projects, test strategy, compliance, release gates
-
----
+| Module                                                                                                            | Purpose                                           |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| **[BMad Method (BMM)](https://github.com/bmad-code-org/BMAD-METHOD)**                                             | Core framework with 34+ workflows                 |
+| **[BMad Builder (BMB)](https://github.com/bmad-code-org/bmad-builder)**                                           | Create custom BMad agents and workflows           |
+| **[Test Architect (TEA)](https://github.com/bmad-code-org/tea)**                                                  | Risk-based test strategy and automation           |
+| **[Game Dev Studio (BMGD)](https://github.com/bmad-code-org/bmad-module-game-dev-studio)**                        | Game development workflows (Unity, Unreal, Godot) |
+| **[Creative Intelligence Suite (CIS)](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | Innovation, brainstorming, design thinking        |
 
 ## Documentation
 
-**[BMad Documentation](http://docs.bmad-method.org)** — Tutorials, how-to guides, concepts, and reference
-**[Test Architect Documentation](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)** — TEA standalone module documentation
+[BMad Method Docs Site](http://docs.bmad-method.org) — Tutorials, guides, concepts, and reference
 
+**Quick links:**
 - [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
+- [Test Architect Documentation](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
 
-### 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
 

docs/404.md

@@ -6,4 +6,4 @@ template: splash
 
 The page you're looking for doesn't exist or has been moved.
 
-[Return to Home](/docs/index.md)
+[Return to Home](./index.md)

docs/_STYLE_GUIDE.md

@@ -77,8 +77,10 @@ Show in "What You've Accomplished" sections:
 your-project/
 ├── _bmad/                                   # BMad configuration
 ├── _bmad-output/
-│   ├── PRD.md                     # Your requirements document
-│   └── bmm-workflow-status.yaml   # Progress tracking
+│   ├── planning-artifacts/
+│   │   └── PRD.md                           # Your requirements document
+│   ├── implementation-artifacts/
+│   └── project-context.md                   # Implementation rules (optional)
 └── ...
 ```
 ````
@@ -143,7 +145,7 @@ your-project/
 ### Types
 
 | Type              | Example                       |
-| ----------------- | ---------------------------- |
+| ----------------- | ----------------------------- |
 | **Index/Landing** | `core-concepts/index.md`      |
 | **Concept**       | `what-are-agents.md`          |
 | **Feature**       | `quick-flow.md`               |

docs/bmgd/game-types.md

@@ -1,376 +0,0 @@
----
-title: "Game Types Reference"
-description: 24 game type templates with genre-specific GDD sections for BMGD
-draft: true
----
-
-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

@@ -1,113 +0,0 @@
----
-title: "BMGD Quick Guide"
-description: Quick reference for BMad Game Dev Studio
-draft: true
----
-
-![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

@@ -1,162 +0,0 @@
----
-title: "Quick Flow Workflows"
-description: Create tech specs and execute implementations with BMGD Quick Flow
-draft: true
----
-
-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/explanation/advanced-elicitation.md

@@ -1,11 +1,17 @@
 ---
 title: "Advanced Elicitation"
 description: Push the LLM to rethink its work using structured reasoning methods
+sidebar:
+  order: 6
 ---
 
 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.
+## What is Advanced Elicitation?
+
+A structured second pass. Instead of asking the AI to "try again" or "make it better," you select a specific reasoning method and the AI re-examines its own output through that lens.
+
+The difference matters. Vague requests produce vague revisions. A named method forces a particular angle of attack, surfacing insights that a generic retry would miss.
 
 ## When to Use It
 
@@ -22,3 +28,22 @@ Workflows offer advanced elicitation at decision points - after the LLM has gene
 2. You pick one (or reshuffle for different options)
 3. Method is applied, improvements shown
 4. Accept or discard, repeat or continue
+
+## Built-in Methods
+
+Dozens of reasoning methods are available. A few examples:
+
+- **Pre-mortem Analysis** - Assume the project already failed, work backward to find why
+- **First Principles Thinking** - Strip away assumptions, rebuild from ground truth
+- **Inversion** - Ask how to guarantee failure, then avoid those things
+- **Red Team vs Blue Team** - Attack your own work, then defend it
+- **Socratic Questioning** - Challenge every claim with "why?" and "how do you know?"
+- **Constraint Removal** - Drop all constraints, see what changes, add them back selectively
+- **Stakeholder Mapping** - Re-evaluate from each stakeholder's perspective
+- **Analogical Reasoning** - Find parallels in other domains and apply their lessons
+
+And many more. The AI picks the most relevant options for your content - you choose which to run.
+
+:::tip[Start Here]
+Pre-mortem Analysis is a good first pick for any spec or plan. It consistently finds gaps that a standard review misses.
+:::

docs/explanation/adversarial-review.md

@@ -1,6 +1,8 @@
 ---
 title: "Adversarial Review"
 description: Forced reasoning technique that prevents lazy "looks good" reviews
+sidebar:
+  order: 5
 ---
 
 Force deeper analysis by requiring problems to be found.
@@ -24,7 +26,7 @@ Normal reviews suffer from confirmation bias. You skim the work, nothing jumps o
 
 ## 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.
+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
 

docs/explanation/brainstorming.md

@@ -1,6 +1,8 @@
 ---
 title: "Brainstorming"
 description: Interactive creative sessions using 60+ proven ideation techniques
+sidebar:
+  order: 2
 ---
 
 Unlock your creativity through guided exploration.

docs/explanation/established-projects-faq.md

@@ -1,6 +1,8 @@
 ---
 title: "Established Projects FAQ"
 description: Common questions about using BMad Method on established projects
+sidebar:
+  order: 8
 ---
 Quick answers to common questions about working on established projects with the BMad Method (BMM).
 

docs/explanation/party-mode.md

@@ -1,6 +1,8 @@
 ---
 title: "Party Mode"
 description: Multi-agent collaboration - get all your AI agents in one conversation
+sidebar:
+  order: 7
 ---
 
 Get all your AI agents in one conversation.

docs/explanation/preventing-agent-conflicts.md

@@ -1,6 +1,8 @@
 ---
 title: "Preventing Agent Conflicts"
 description: How architecture prevents conflicts when multiple agents implement a system
+sidebar:
+  order: 4
 ---
 
 When multiple AI agents implement different parts of a system, they can make conflicting technical decisions. Architecture documentation prevents this by establishing shared standards.
@@ -69,7 +71,7 @@ Explicit documentation of:
 
 Think of architecture as the shared context that all agents read before implementing:
 
-```
+```text
 PRD: "What to build"
      ↓
 Architecture: "How to build it"

docs/explanation/project-context.md

@@ -0,0 +1,157 @@
+---
+title: "Project Context"
+description: How project-context.md guides AI agents with your project's rules and preferences
+sidebar:
+  order: 7
+---
+
+The `project-context.md` file is your project's implementation guide for AI agents. Similar to a "constitution" in other development systems, it captures the rules, patterns, and preferences that ensure consistent code generation across all workflows.
+
+## What It Does
+
+AI agents make implementation decisions constantly — which patterns to follow, how to structure code, what conventions to use. Without clear guidance, they may:
+- Follow generic best practices that don't match your codebase
+- Make inconsistent decisions across different stories
+- Miss project-specific requirements or constraints
+
+The `project-context.md` file solves this by documenting what agents need to know in a concise, LLM-optimized format.
+
+## How It Works
+
+Every implementation workflow automatically loads `project-context.md` if it exists. The architect workflow also loads it to respect your technical preferences when designing the architecture.
+
+**Loaded by these workflows:**
+- `create-architecture` — respects technical preferences during solutioning
+- `create-story` — informs story creation with project patterns
+- `dev-story` — guides implementation decisions
+- `code-review` — validates against project standards
+- `quick-dev` — applies patterns when implementing tech-specs
+- `sprint-planning`, `retrospective`, `correct-course` — provides project-wide context
+
+## When to Create It
+
+The `project-context.md` file is useful at any stage of a project:
+
+| Scenario | When to Create | Purpose |
+|----------|----------------|---------|
+| **New project, before architecture** | Manually, before `create-architecture` | Document your technical preferences so the architect respects them |
+| **New project, after architecture** | Via `generate-project-context` or manually | Capture architecture decisions for implementation agents |
+| **Existing project** | Via `generate-project-context` | Discover existing patterns so agents follow established conventions |
+| **Quick Flow project** | Before or during `quick-dev` | Ensure quick implementation respects your patterns |
+
+:::tip[Recommended]
+For new projects, create it manually before architecture if you have strong technical preferences. Otherwise, generate it after architecture to capture those decisions.
+:::
+
+## What Goes In It
+
+The file has two main sections:
+
+### Technology Stack & Versions
+
+Documents the frameworks, languages, and tools your project uses with specific versions:
+
+```markdown
+## Technology Stack & Versions
+
+- Node.js 20.x, TypeScript 5.3, React 18.2
+- State: Zustand (not Redux)
+- Testing: Vitest, Playwright, MSW
+- Styling: Tailwind CSS with custom design tokens
+```
+
+### Critical Implementation Rules
+
+Documents patterns and conventions that agents might otherwise miss:
+
+```markdown
+## Critical Implementation Rules
+
+**TypeScript Configuration:**
+- Strict mode enabled — no `any` types without explicit approval
+- Use `interface` for public APIs, `type` for unions/intersections
+
+**Code Organization:**
+- Components in `/src/components/` with co-located `.test.tsx`
+- Utilities in `/src/lib/` for reusable pure functions
+- API calls use the `apiClient` singleton — never fetch directly
+
+**Testing Patterns:**
+- Unit tests focus on business logic, not implementation details
+- Integration tests use MSW to mock API responses
+- E2E tests cover critical user journeys only
+
+**Framework-Specific:**
+- All async operations use the `handleError` wrapper for consistent error handling
+- Feature flags accessed via `featureFlag()` from `@/lib/flags`
+- New routes follow the file-based routing pattern in `/src/app/`
+```
+
+Focus on what's **unobvious** — things agents might not infer from reading code snippets. Don't document standard practices that apply universally.
+
+## Creating the File
+
+You have three options:
+
+### Manual Creation
+
+Create the file at `_bmad-output/project-context.md` and add your rules:
+
+```bash
+# In your project root
+mkdir -p _bmad-output
+touch _bmad-output/project-context.md
+```
+
+Edit it with your technology stack and implementation rules. The architect and implementation workflows will automatically find and load it.
+
+### Generate After Architecture
+
+Run the `generate-project-context` workflow after completing your architecture:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+This scans your architecture document and project files to generate a context file capturing the decisions made.
+
+### Generate for Existing Projects
+
+For existing projects, run `generate-project-context` to discover existing patterns:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine.
+
+## Why It Matters
+
+Without `project-context.md`, agents make assumptions that may not match your project:
+
+| Without Context | With Context |
+|----------------|--------------|
+| Uses generic patterns | Follows your established conventions |
+| Inconsistent style across stories | Consistent implementation |
+| May miss project-specific constraints | Respects all technical requirements |
+| Each agent decides independently | All agents align with same rules |
+
+This is especially important for:
+- **Quick Flow** — skips PRD and architecture, so context file fills the gap
+- **Team projects** — ensures all agents follow the same standards
+- **Existing projects** — prevents breaking established patterns
+
+## Editing and Updating
+
+The `project-context.md` file is a living document. Update it when:
+
+- Architecture decisions change
+- New conventions are established
+- Patterns evolve during implementation
+- You identify gaps from agent behavior
+
+You can edit it manually at any time, or re-run `generate-project-context` to update it after significant changes.
+
+:::note[File Location]
+The default location is `_bmad-output/project-context.md`. Workflows search for it there, and also check `**/project-context.md` anywhere in your project.
+:::

docs/explanation/quick-flow.md

@@ -1,27 +1,73 @@
 ---
 title: "Quick Flow"
 description: Fast-track for small changes - skip the full methodology
+sidebar:
+  order: 1
 ---
 
-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.
+Skip the ceremony. Quick Flow takes you from idea to working code in two commands - no Product Brief, no PRD, no Architecture doc.
 
 ## When to Use It
 
-- Bug fixes
-- Refactoring
-- Small features
-- Prototyping
+- Bug fixes and patches
+- Refactoring existing code
+- Small, well-understood features
+- Prototyping and spikes
+- Single-agent work where one developer can hold the full scope
 
-## When to Use Full BMad Method Instead
+## When NOT to Use It
 
-- New products
-- Major features
-- Multiple teams involved
-- Stakeholder alignment needed
+- New products or platforms that need stakeholder alignment
+- Major features spanning multiple components or teams
+- Work that requires architectural decisions (database schema, API contracts, service boundaries)
+- Anything where requirements are unclear or contested
+
+:::caution[Scope Creep]
+If you start a Quick Flow and realize the scope is bigger than expected, `quick-dev` will detect this and offer to escalate. You can switch to a full PRD workflow at any point without losing your work.
+:::
+
+## How It Works
+
+Quick Flow has two commands, each backed by a structured workflow. You can run them together or independently.
+
+### quick-spec: Plan
+
+Run `quick-spec` and Barry (the Quick Flow agent) walks you through a conversational discovery process:
+
+1. **Understand** - You describe what you want to build. Barry scans the codebase to ask informed questions, then captures a problem statement, solution approach, and scope boundaries.
+2. **Investigate** - Barry reads relevant files, maps code patterns, identifies files to modify, and documents the technical context.
+3. **Generate** - Produces a complete tech-spec with ordered implementation tasks (specific file paths and actions), acceptance criteria in Given/When/Then format, testing strategy, and dependencies.
+4. **Review** - Presents the full spec for your sign-off. You can edit, ask questions, run adversarial review, or refine with advanced elicitation before finalizing.
+
+The output is a `tech-spec-{slug}.md` file saved to your project's implementation artifacts folder. It contains everything a fresh agent needs to implement the feature - no conversation history required.
+
+### quick-dev: Build
+
+Run `quick-dev` and Barry implements the work. It operates in two modes:
+
+- **Tech-spec mode** - Point it at a spec file (`quick-dev tech-spec-auth.md`) and it executes every task in order, writes tests, and verifies acceptance criteria.
+- **Direct mode** - Give it instructions directly (`quick-dev "refactor the auth middleware"`) and it gathers context, builds a mental plan, and executes.
+
+After implementation, `quick-dev` runs a self-check audit against all tasks and acceptance criteria, then triggers an adversarial code review of the diff. Findings are presented for you to resolve before wrapping up.
+
+:::tip[Fresh Context]
+For best results, run `quick-dev` in a new conversation after finishing `quick-spec`. This gives the implementation agent clean context focused solely on building.
+:::
+
+## What Quick Flow Skips
+
+The full BMad Method produces a Product Brief, PRD, Architecture doc, and Epic/Story breakdown before any code is written. Quick Flow replaces all of that with a single tech-spec. This works because Quick Flow targets changes where:
+
+- The product direction is already established
+- Architecture decisions are already made
+- A single developer can reason about the full scope
+- Requirements fit in one conversation
+
+## Escalating to Full BMad Method
+
+Quick Flow includes built-in guardrails for scope detection. When you run `quick-dev` with a direct request, it evaluates signals like multi-component mentions, system-level language, and uncertainty about approach. If it detects the work is bigger than a quick flow:
+
+- **Light escalation** - Recommends running `quick-spec` first to create a plan
+- **Heavy escalation** - Recommends switching to the full BMad Method PRD process
+
+You can also escalate manually at any time. Your tech-spec work carries forward - it becomes input for the broader planning process rather than being discarded.

docs/explanation/why-solutioning-matters.md

@@ -1,6 +1,8 @@
 ---
 title: "Why Solutioning Matters"
 description: Understanding why the solutioning phase is critical for multi-epic projects
+sidebar:
+  order: 3
 ---
 
 
@@ -8,7 +10,7 @@ Phase 3 (Solutioning) translates **what** to build (from Planning) into **how**
 
 ## The Problem Without Solutioning
 
-```
+```text
 Agent 1 implements Epic 1 using REST API
 Agent 2 implements Epic 2 using GraphQL
 Result: Inconsistent API design, integration nightmare
@@ -18,7 +20,7 @@ When multiple agents implement different parts of a system without shared archit
 
 ## The Solution With Solutioning
 
-```
+```text
 architecture workflow decides: "Use GraphQL for all APIs"
 All agents follow architecture decisions
 Result: Consistent implementation, no conflicts

docs/how-to/customize-bmad.md

@@ -1,34 +1,35 @@
 ---
-title: "BMad Method Customization Guide"
+title: "How to Customize BMad"
 description: Customize agents, workflows, and modules while preserving update compatibility
+sidebar:
+  order: 7
 ---
 
-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.
+Use the `.customize.yaml` files to tailor agent behavior, personas, and menus while preserving your changes across updates.
 
-The Customization Guidance outlined here, while targeted at understanding BMad Method customization, applies to any other module use within the BMad Method.
+## When to Use This
 
-## Types of Customization
+- You want to change an agent's name, personality, or communication style
+- You need agents to remember project-specific context
+- You want to add custom menu items that trigger your own workflows or prompts
+- You want agents to perform specific actions every time they start up
 
-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.
+:::note[Prerequisites]
+- BMad installed in your project (see [How to Install BMad](./install-bmad.md))
+- A text editor for YAML files
+:::
 
-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.
+:::caution[Keep Your Customizations Safe]
+Always use the `.customize.yaml` files described here rather than editing agent files directly. The installer overwrites agent files during updates, but preserves your `.customize.yaml` changes.
+:::
 
-## Agent Customization
+## Steps
 
-### Agent Customization Areas
+### 1. Locate Customization Files
 
-- 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
+After installation, find one `.customize.yaml` file per agent in:
 
-## How to customize an agent.
-
-**1. Locate Customization Files**
-
-After installation, find agent customization files in:
-
-```
+```text
 _bmad/_config/agents/
 ├── core-bmad-master.customize.yaml
 ├── bmm-dev.customize.yaml
@@ -36,28 +37,22 @@ _bmad/_config/agents/
 └── ... (one file per installed agent)
 ```
 
-**2. Edit Any Agent**
+### 2. Edit the Customization File
 
-Open the `.customize.yaml` file for the agent you want to modify. All sections are optional - customize only what you need.
+Open the `.customize.yaml` file for the agent you want to modify. Every section is optional -- customize only what you need.
 
-**3. Rebuild the Agent**
+| Section            | Behavior | Purpose                                         |
+| ------------------ | -------- | ----------------------------------------------- |
+| `agent.metadata`   | Replaces | Override the agent's display name               |
+| `persona`          | Replaces | Set role, identity, style, and principles       |
+| `memories`         | Appends  | Add persistent context the agent always recalls |
+| `menu`             | Appends  | Add custom menu items for workflows or prompts  |
+| `critical_actions` | Appends  | Define startup instructions for the agent       |
+| `prompts`          | Appends  | Create reusable prompts for menu actions        |
 
-After editing, IT IS CRITICAL to rebuild the agent to apply changes:
+Sections marked **Replaces** overwrite the agent's defaults entirely. Sections marked **Appends** add to the existing configuration.
 
-```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
+**Agent Name**
 
 Change how the agent introduces itself:
 
@@ -67,7 +62,7 @@ agent:
     name: 'Spongebob' # Default: "Amelia"
 ```
 
-#### Persona
+**Persona**
 
 Replace the agent's personality, role, and communication style:
 
@@ -81,9 +76,9 @@ persona:
     - 'Favor composition over inheritance'
 ```
 
-**Note:** The persona section replaces the entire default persona (not merged).
+The `persona` section replaces the entire default persona, so include all four fields if you set it.
 
-#### Memories
+**Memories**
 
 Add persistent context the agent will always remember:
 
@@ -91,35 +86,35 @@ Add persistent context the agent will always remember:
 memories:
   - 'Works at Krusty Krab'
   - 'Favorite Celebrity: David Hasslehoff'
-  - 'Learned in Epic 1 that its not cool to just pretend that tests have passed'
+  - 'Learned in Epic 1 that it is not cool to just pretend that tests have passed'
 ```
 
-### Custom Menu Items
+**Menu Items**
 
-Any custom items you add here will be included in the agents display menu.
+Add custom entries to the agent's display menu. Each item needs a `trigger`, a target (`workflow` path or `action` reference), and a `description`:
 
 ```yaml
 menu:
   - trigger: my-workflow
-    workflow: '{project-root}/my-custom/workflows/my-workflow.yaml'
+    workflow: 'my-custom/workflows/my-workflow.yaml'
     description: My custom workflow
   - trigger: deploy
     action: '#deploy-prompt'
     description: Deploy to production
 ```
 
-### Critical Actions
+**Critical Actions**
 
-Add instructions that execute before the agent starts:
+Define instructions that run when the agent starts up:
 
 ```yaml
 critical_actions:
   - 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention'
 ```
 
-### Custom Prompts
+**Custom Prompts**
 
-Define reusable prompts for `action="#id"` menu handlers:
+Create reusable prompts that menu items can reference with `action="#id"`:
 
 ```yaml
 prompts:
@@ -131,29 +126,47 @@ prompts:
       3. Execute deployment script
 ```
 
+### 3. Apply Your Changes
+
+After editing, recompile the agent to apply changes:
+
+```bash
+npx bmad-method install
+```
+
+The installer detects the existing installation and offers these options:
+
+| Option                       | What It Does                                                        |
+| ---------------------------- | ------------------------------------------------------------------- |
+| **Quick Update**             | Updates all modules to the latest version and recompiles all agents |
+| **Recompile Agents**         | Applies customizations only, without updating module files          |
+| **Modify BMad Installation** | Full installation flow for adding or removing modules               |
+
+For customization-only changes, **Recompile Agents** is the fastest option.
+
 ## 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
+- Run `npx bmad-method install` and select **Recompile Agents** to apply changes
+- Check that your YAML syntax is valid (indentation matters)
+- Verify you edited the correct `.customize.yaml` file for the agent
 
 **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
+- Check for YAML syntax errors using an online YAML validator
+- Ensure you did not leave fields empty after uncommenting them
+- Try reverting to the original template and rebuilding
 
-**Need to reset?**
+**Need to reset an agent?**
 
-- Remove content from the `.customize.yaml` file (or delete the file)
-- Run `npx bmad-method build <agent-name>` to regenerate defaults
+- Clear or delete the agent's `.customize.yaml` file
+- Run `npx bmad-method install` and select **Recompile Agents** to restore defaults
 
 ## Workflow Customization
 
-Information about customizing existing BMad Method workflows and skills are coming soon.
+Customization of existing BMad Method workflows and skills is coming soon.
 
 ## Module Customization
 
-Information on how to build expansion modules that augment BMad, or make other existing module customizations are coming soon.
+Guidance on building expansion modules and customizing existing modules is coming soon.

docs/how-to/established-projects.md

@@ -1,9 +1,11 @@
 ---
 title: "Established Projects"
 description: How to use BMad Method on existing codebases
+sidebar:
+  order: 6
 ---
 
-Use BMad Method effectively when working on existing projects and legacy codebases, sometimes also referred to as brownfield projects.
+Use BMad Method effectively when working on existing projects and legacy codebases.
 
 This guide covers the essential workflow for onboarding to existing projects with BMad Method.
 
@@ -21,7 +23,30 @@ If you have completed all PRD epics and stories through the BMad process, clean
 - `_bmad-output/planning-artifacts/`
 - `_bmad-output/implementation-artifacts/`
 
-## Step 2: Maintain Quality Project Documentation
+## Step 2: Create Project Context
+
+:::tip[Recommended for Existing Projects]
+Generate `project-context.md` to capture your existing codebase patterns and conventions. This ensures AI agents follow your established practices when implementing changes.
+:::
+
+Run the generate project context workflow:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+This scans your codebase to identify:
+- Technology stack and versions
+- Code organization patterns
+- Naming conventions
+- Testing approaches
+- Framework-specific patterns
+
+You can review and refine the generated file, or create it manually at `_bmad-output/project-context.md` if you prefer.
+
+[Learn more about project context](../explanation/project-context.md)
+
+## Step 3: Maintain Quality Project Documentation
 
 Your `docs/` folder should contain succinct, well-organized documentation that accurately represents your project:
 
@@ -34,9 +59,21 @@ For complex projects, consider using the `document-project` workflow. It offers
 
 ## Step 3: Get Help
 
-Get help to know what to do next based on your unique needs
+### BMad-Help: Your Starting Point
 
-Run `bmad-help` to get guidance when you are not sure what to do next.
+**Run `/bmad-help` anytime you're unsure what to do next.** This intelligent guide:
+
+- Inspects your project to see what's already been done
+- Shows options based on your installed modules
+- Understands natural language queries
+
+```
+/bmad-help I have an existing Rails app, where should I start?
+/bmad-help What's the difference between quick-flow and full method?
+/bmad-help Show me what workflows are available
+```
+
+BMad-Help also **automatically runs at the end of every workflow**, providing clear guidance on exactly what to do next.
 
 ### Choosing Your Approach
 
@@ -44,8 +81,8 @@ 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.                                                    |
+| **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
 
@@ -76,5 +113,5 @@ Pay close attention here to prevent reinventing the wheel or making decisions th
 
 ## More Information
 
-- **[Quick Fixes](/docs/how-to/quick-fixes.md)** - Bug fixes and ad-hoc changes
-- **[Established Projects FAQ](/docs/explanation/established-projects-faq.md)** - Common questions about working on established projects
+- **[Quick Fixes](./quick-fixes.md)** - Bug fixes and ad-hoc changes
+- **[Established Projects FAQ](../explanation/established-projects-faq.md)** - Common questions about working on established projects

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

@@ -1,19 +1,52 @@
 ---
 title: "How to Get Answers About BMad"
 description: Use an LLM to quickly answer your own BMad questions
+sidebar:
+  order: 4
 ---
 
-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.
+## Start Here: BMad-Help
 
-## When to Use This
+**The fastest way to get answers about BMad is `/bmad-help`.** This intelligent guide will answer upwards of 80% of all questions and is available to you directly in your IDE as you work.
 
-- 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
+BMad-Help is more than a lookup tool — it:
+- **Inspects your project** to see what's already been completed
+- **Understands natural language** — ask questions in plain English
+- **Varies based on your installed modules** — shows relevant options
+- **Auto-runs after workflows** — tells you exactly what to do next
+- **Recommends the first required task** — no guessing where to start
 
-:::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.
-:::
+### How to Use BMad-Help
+
+Run it with just the slash command:
+
+```
+/bmad-help
+```
+
+Or combine it with a natural language query:
+
+```
+/bmad-help I have a SaaS idea and know all the features. Where do I start?
+/bmad-help What are my options for UX design?
+/bmad-help I'm stuck on the PRD workflow
+/bmad-help Show me what's been done so far
+```
+
+BMad-Help responds with:
+- What's recommended for your situation
+- What the first required task is
+- What the rest of the process looks like
+
+---
+
+## When to Use This Guide
+
+Use this section when:
+- You want to understand BMad's architecture or internals
+- You need answers outside of what BMad-Help provides
+- You're researching BMad before installing
+- You want to explore the source code directly
 
 ## Steps
 
@@ -38,10 +71,11 @@ The `_bmad` folder is created when you install BMad. If you don't have it yet, c
 
 Fetch `llms-full.txt` into your session:
 
-```
+```text
 https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
 ```
 
+
 ### 3. Ask Your Question
 
 :::note[Example]

docs/how-to/install-bmad.md

@@ -1,11 +1,13 @@
 ---
 title: "How to Install BMad"
 description: Step-by-step guide to installing BMad in your project
+sidebar:
+  order: 1
 ---
 
 Use the `npx bmad-method install` command to set up BMad in your project with your choice of modules and AI tools.
 
-If you want to use a non interactive installer and provide all install options on the command line, [this guide](/docs/non-interactive-installation.md).
+If you want to use a non interactive installer and provide all install options on the command line, see [this guide](./non-interactive-installation.md).
 
 ## When to Use This
 
@@ -27,6 +29,13 @@ If you want to use a non interactive installer and provide all install options o
 npx bmad-method install
 ```
 
+:::tip[Bleeding edge]
+To install the latest from the main branch (may be unstable):
+```bash
+npx github:bmad-code-org/BMAD-METHOD install
+```
+:::
+
 ### 2. Choose Installation Location
 
 The installer will ask where to install BMad files:
@@ -41,6 +50,7 @@ Pick which AI tools you use:
 - Claude Code
 - Cursor
 - Windsurf
+- Kiro
 - 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.
@@ -55,7 +65,7 @@ The installer guides you through the rest — custom content, settings, etc.
 
 ## What You Get
 
-```
+```text
 your-project/
 ├── _bmad/
 │   ├── bmm/            # Your selected modules
@@ -63,22 +73,27 @@ your-project/
 │   ├── core/           # Required core module
 │   └── ...
 ├── _bmad-output/       # Generated artifacts
-└── .claude/            # Claude Code commands (if using Claude Code)
+├── .claude/            # Claude Code commands (if using Claude Code)
+└── .kiro/              # Kiro steering files (if using Kiro)
 ```
 
 ## Verify Installation
 
-Run the `help` workflow (`/bmad-help` on most platforms) to verify everything works and see what to do next.
+Run `/bmad-help` to verify everything works and see what to do next.
 
-**Latest from main branch:**
-```bash
-npx github:bmad-code-org/BMAD-METHOD install
+**BMad-Help is your intelligent guide** that will:
+- Confirm your installation is working
+- Show what's available based on your installed modules
+- Recommend your first step
+
+You can also ask it questions:
+```
+/bmad-help I just installed, what should I do first?
+/bmad-help What are my options for a SaaS project?
 ```
-
-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.
+**Installer worked but something doesn't work later** — Your AI needs BMad context to help. See [How to Get Answers About BMad](./get-answers-about-bmad.md) for how to point your AI at the right sources.

docs/how-to/non-interactive-installation.md

@@ -0,0 +1,171 @@
+---
+title: Non-Interactive Installation
+description: Install BMad using command-line flags for CI/CD pipelines and automated deployments
+sidebar:
+  order: 2
+---
+
+Use command-line flags to install BMad non-interactively. This is useful for:
+
+## When to Use This
+
+- Automated deployments and CI/CD pipelines
+- Scripted installations
+- Batch installations across multiple projects
+- Quick installations with known configurations
+
+:::note[Prerequisites]
+Requires [Node.js](https://nodejs.org) v20+ and `npx` (included with npm).
+:::
+
+## Available Flags
+
+### Installation Options
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `--directory <path>` | Installation directory | `--directory ~/projects/myapp` |
+| `--modules <modules>` | Comma-separated module IDs | `--modules bmm,bmb` |
+| `--tools <tools>` | Comma-separated tool/IDE IDs (use `none` to skip) | `--tools claude-code,cursor` or `--tools none` |
+| `--custom-content <paths>` | Comma-separated paths to custom modules | `--custom-content ~/my-module,~/another-module` |
+| `--action <type>` | Action for existing installations: `install` (default), `update`, `quick-update`, or `compile-agents` | `--action quick-update` |
+
+### Core Configuration
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--user-name <name>` | Name for agents to use | System username |
+| `--communication-language <lang>` | Agent communication language | English |
+| `--document-output-language <lang>` | Document output language | English |
+| `--output-folder <path>` | Output folder path | _bmad-output |
+
+### Other Options
+
+| Flag | Description |
+|------|-------------|
+| `-y, --yes` | Accept all defaults and skip prompts |
+| `-d, --debug` | Enable debug output for manifest generation |
+
+## Module IDs
+
+Available module IDs for the `--modules` flag:
+
+- `bmm` — BMad Method Master
+- `bmb` — BMad Builder
+
+Check the [BMad registry](https://github.com/bmad-code-org) for available external modules.
+
+## Tool/IDE IDs
+
+Available tool IDs for the `--tools` flag:
+
+**Preferred:** `claude-code`, `cursor`, `windsurf`
+
+Run `npx bmad-method install` interactively once to see the full current list of supported tools, or check the [platform codes configuration](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/tools/cli/installers/lib/ide/platform-codes.yaml).
+
+## Installation Modes
+
+| Mode | Description | Example |
+|------|-------------|---------|
+| Fully non-interactive | Provide all flags to skip all prompts | `npx bmad-method install --directory . --modules bmm --tools claude-code --yes` |
+| Semi-interactive | Provide some flags; BMad prompts for the rest | `npx bmad-method install --directory . --modules bmm` |
+| Defaults only | Accept all defaults with `-y` | `npx bmad-method install --yes` |
+| Without tools | Skip tool/IDE configuration | `npx bmad-method install --modules bmm --tools none` |
+
+## Examples
+
+### CI/CD Pipeline Installation
+
+```bash
+#!/bin/bash
+# install-bmad.sh
+
+npx bmad-method install \
+  --directory "${GITHUB_WORKSPACE}" \
+  --modules bmm \
+  --tools claude-code \
+  --user-name "CI Bot" \
+  --communication-language English \
+  --document-output-language English \
+  --output-folder _bmad-output \
+  --yes
+```
+
+### Update Existing Installation
+
+```bash
+npx bmad-method install \
+  --directory ~/projects/myapp \
+  --action update \
+  --modules bmm,bmb,custom-module
+```
+
+### Quick Update (Preserve Settings)
+
+```bash
+npx bmad-method install \
+  --directory ~/projects/myapp \
+  --action quick-update
+```
+
+### Installation with Custom Content
+
+```bash
+npx bmad-method install \
+  --directory ~/projects/myapp \
+  --modules bmm \
+  --custom-content ~/my-custom-module,~/another-module \
+  --tools claude-code
+```
+
+## What You Get
+
+- A fully configured `_bmad/` directory in your project
+- Compiled agents and workflows for your selected modules and tools
+- A `_bmad-output/` folder for generated artifacts
+
+## Validation and Error Handling
+
+BMad validates all provided flags:
+
+- **Directory** — Must be a valid path with write permissions
+- **Modules** — Warns about invalid module IDs (but won't fail)
+- **Tools** — Warns about invalid tool IDs (but won't fail)
+- **Custom Content** — Each path must contain a valid `module.yaml` file
+- **Action** — Must be one of: `install`, `update`, `quick-update`, `compile-agents`
+
+Invalid values will either:
+1. Show an error and exit (for critical options like directory)
+2. Show a warning and skip (for optional items like custom content)
+3. Fall back to interactive prompts (for missing required values)
+
+:::tip[Best Practices]
+- Use absolute paths for `--directory` to avoid ambiguity
+- Test flags locally before using in CI/CD pipelines
+- Combine with `-y` for truly unattended installations
+- Use `--debug` if you encounter issues during installation
+:::
+
+## Troubleshooting
+
+### Installation fails with "Invalid directory"
+
+- The directory path must exist (or its parent must exist)
+- You need write permissions
+- The path must be absolute or correctly relative to the current directory
+
+### Module not found
+
+- Verify the module ID is correct
+- External modules must be available in the registry
+
+### Custom content path invalid
+
+Ensure each custom content path:
+- Points to a directory
+- Contains a `module.yaml` file in the root
+- Has a `code` field in the `module.yaml`
+
+:::note[Still stuck?]
+Run with `--debug` for detailed output, try interactive mode to isolate the issue, or report at <https://github.com/bmad-code-org/BMAD-METHOD/issues>.
+:::

docs/how-to/project-context.md

@@ -0,0 +1,136 @@
+---
+title: "Manage Project Context"
+description: Create and maintain project-context.md to guide AI agents
+sidebar:
+  order: 7
+---
+
+Use the `project-context.md` file to ensure AI agents follow your project's technical preferences and implementation rules throughout all workflows.
+
+:::note[Prerequisites]
+- BMad Method installed
+- Understanding of your project's technology stack and conventions
+:::
+
+## When to Use This
+
+- You have strong technical preferences before starting architecture
+- You've completed architecture and want to capture decisions for implementation
+- You're working on an existing codebase with established patterns
+- You notice agents making inconsistent decisions across stories
+
+## Step 1: Choose Your Approach
+
+**Manual creation** — Best when you know exactly what rules you want to document
+
+**Generate after architecture** — Best for capturing decisions made during solutioning
+
+**Generate for existing projects** — Best for discovering patterns in existing codebases
+
+## Step 2: Create the File
+
+### Option A: Manual Creation
+
+Create the file at `_bmad-output/project-context.md`:
+
+```bash
+mkdir -p _bmad-output
+touch _bmad-output/project-context.md
+```
+
+Add your technology stack and implementation rules:
+
+```markdown
+---
+project_name: 'MyProject'
+user_name: 'YourName'
+date: '2026-02-15'
+sections_completed: ['technology_stack', 'critical_rules']
+---
+
+# Project Context for AI Agents
+
+## Technology Stack & Versions
+
+- Node.js 20.x, TypeScript 5.3, React 18.2
+- State: Zustand
+- Testing: Vitest, Playwright
+- Styling: Tailwind CSS
+
+## Critical Implementation Rules
+
+**TypeScript:**
+- Strict mode enabled, no `any` types
+- Use `interface` for public APIs, `type` for unions
+
+**Code Organization:**
+- Components in `/src/components/` with co-located tests
+- API calls use `apiClient` singleton — never fetch directly
+
+**Testing:**
+- Unit tests focus on business logic
+- Integration tests use MSW for API mocking
+```
+
+### Option B: Generate After Architecture
+
+Run the workflow in a fresh chat:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+The workflow scans your architecture document and project files to generate a context file capturing the decisions made.
+
+### Option C: Generate for Existing Projects
+
+For existing projects, run:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine.
+
+## Step 3: Verify Content
+
+Review the generated file and ensure it captures:
+
+- Correct technology versions
+- Your actual conventions (not generic best practices)
+- Rules that prevent common mistakes
+- Framework-specific patterns
+
+Edit manually to add anything missing or remove inaccuracies.
+
+## What You Get
+
+A `project-context.md` file that:
+
+- Ensures all agents follow the same conventions
+- Prevents inconsistent decisions across stories
+- Captures architecture decisions for implementation
+- Serves as a reference for your project's patterns and rules
+
+## Tips
+
+:::tip[Focus on the Unobvious]
+Document patterns agents might miss such as "Use JSDoc style comments on every public class, function and variable", not universal practices like "use meaningful variable names" which LLMs know at this point.
+:::
+
+:::tip[Keep It Lean]
+This file is loaded by every implementation workflow. Long files waste context. Do not include content that only applies to narrow scope or specific stories or features.
+:::
+
+:::tip[Update as Needed]
+Edit manually when patterns change, or re-generate after significant architecture changes.
+:::
+
+:::tip[Works for All Project Types]
+Just as useful for Quick Flow as for full BMad Method projects.
+:::
+
+## Next Steps
+
+- [**Project Context Explanation**](../explanation/project-context.md) — Learn more about how it works
+- [**Workflow Map**](../reference/workflow-map.md) — See which workflows load project context

docs/how-to/quick-fixes.md

@@ -1,76 +1,123 @@
 ---
 title: "Quick Fixes"
 description: How to make quick fixes and ad-hoc changes
+sidebar:
+  order: 5
 ---
 
-Use the **DEV agent** directly for bug fixes, refactorings, or small targeted changes that don't require the full BMad method or Quick Flow.
+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
+- Bug fixes with a clear, known cause
+- Small refactorings (rename, extract, restructure) contained within a few files
+- Minor feature tweaks or configuration changes
+- Exploratory work to understand an unfamiliar codebase
+
+:::note[Prerequisites]
+- BMad Method installed (`npx bmad-method install`)
+- An AI-powered IDE (Claude Code, Cursor, Windsurf, or similar)
+:::
+
+## Choose Your Approach
+
+| Situation | Agent | Why |
+| --- | --- | --- |
+| Fix a specific bug or make a small, scoped change | **DEV agent** | Jumps straight into implementation without planning overhead |
+| Change touches several files or you want a written plan first | **Quick Flow Solo Dev** | Creates a quick-spec before implementation so the agent stays aligned to your standards |
+
+If you are unsure, start with the DEV agent. You can always escalate to Quick Flow if the change grows.
 
 ## Steps
 
-### 1. Load an Agent
+### 1. Load the DEV Agent
 
-For quick fixes, you can use:
+Start a **fresh chat** in your AI IDE and load the DEV agent with its slash command:
 
-- **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
+```text
+/bmad-agent-bmm-dev
+```
+
+This loads the agent's persona and capabilities into the session. If you decide you need Quick Flow instead, load the **Quick Flow Solo Dev** agent in a fresh chat:
+
+```text
+/bmad-agent-bmm-quick-flow-solo-dev
+```
+
+Once the Solo Dev agent is loaded, describe your change and ask it to create a **quick-spec**. The agent drafts a lightweight spec capturing what you want to change and how. After you approve the quick-spec, tell the agent to start the **Quick Flow dev cycle** -- it will implement the change, run tests, and perform a self-review, all guided by the spec you just approved.
+
+:::tip[Fresh Chats]
+Always start a new chat session when loading an agent. Reusing a session from a previous workflow can cause context conflicts.
+:::
 
 ### 2. Describe the Change
 
-Simply tell the agent what you need:
+Tell the agent what you need in plain language. Be specific about the problem and, if you know it, where the relevant code lives.
 
-```
-Fix the login validation bug that allows empty passwords
-```
+:::note[Example Prompts]
+**Bug fix** -- "Fix the login validation bug that allows empty passwords. The validation logic is in `src/auth/validate.ts`."
 
-or
+**Refactoring** -- "Refactor the UserService to use async/await instead of callbacks."
 
-```
-Refactor the UserService to use async/await instead of callbacks
-```
+**Configuration change** -- "Update the CI pipeline to cache node_modules between runs."
+
+**Dependency update** -- "Upgrade the express dependency to the latest v5 release and fix any breaking changes."
+:::
+
+You don't need to provide every detail. The agent will read the relevant source files and ask clarifying questions when needed.
 
 ### 3. Let the Agent Work
 
 The agent will:
 
-- Analyze the relevant code
-- Propose a solution
-- Implement the change
-- Run tests (if available)
+- Read and analyze the relevant source files
+- Propose a solution and explain its reasoning
+- Implement the change across the affected files
+- Run your project's test suite if one exists
 
-### 4. Review and Commit
+If your project has tests, the agent runs them automatically after making changes and iterates until tests pass. For projects without a test suite, verify the change manually (run the app, hit the endpoint, check the output).
 
-Review the changes made and commit when satisfied.
+### 4. Review and Verify
+
+Before committing, review what changed:
+
+- Read through the diff to confirm the change matches your intent
+- Run the application or tests yourself to double-check
+- If something looks wrong, tell the agent what to fix -- it can iterate in the same session
+
+Once satisfied, commit the changes with a clear message describing the fix.
+
+:::caution[If Something Breaks]
+If a committed change causes unexpected issues, use `git revert HEAD` to undo the last commit cleanly. Then start a fresh chat with the DEV agent to try a different approach.
+:::
 
 ## Learning Your Codebase
 
-This approach is also excellent for exploring unfamiliar code:
+The DEV agent is also useful for exploring unfamiliar code. Load it in a fresh chat and ask questions:
 
-```
-Explain how the authentication system works in this codebase
-```
+:::note[Example Prompts]
+"Explain how the authentication system works in this codebase."
 
-```
-Show me where error handling happens in the API layer
-```
+"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:
+"What does the `ProcessOrder` function do and what calls it?"
+:::
 
-- Learn about your project
-- Understand how things are built
-- Explore unfamiliar parts of the codebase
+Use the agent to learn about your project, understand how components connect, and explore unfamiliar areas before making changes.
+
+## What You Get
+
+- Modified source files with the fix or refactoring applied
+- Passing tests (if your project has a test suite)
+- A clean commit describing the change
+
+No planning artifacts are produced -- that's the point of this approach.
 
 ## When to Upgrade to Formal Planning
 
-Consider using Quick Flow or full BMad Method when:
+Consider using [Quick Flow](../explanation/quick-flow.md) or the 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
+- The change affects multiple systems or requires coordinated updates across many files
+- You are unsure about the scope and need a spec to think it through
+- The fix keeps growing in complexity as you work on it
+- You need documentation or architectural decisions recorded for the team

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

@@ -1,15 +1,19 @@
 ---
 title: "Document Sharding Guide"
 description: Split large markdown files into smaller organized files for better context management
+sidebar:
+  order: 8
 ---
 
 Use the `shard-doc` tool if you need to split large markdown files into smaller, organized files for better context management.
 
-This is no longer recommended, and soon with updated workflows and most major llms and tools supporting sub processes this will be unnecessary.
+:::caution[Deprecated]
+This is no longer recommended, and soon with updated workflows and most major LLMs and tools supporting subprocesses this will be unnecessary.
+:::
 
 ## When to Use This
 
-Only use this if you notice your chosen tool / model combination are failing to load and read all the documents as input when needed.
+Only use this if you notice your chosen tool / model combination is failing to load and read all the documents as input when needed.
 
 ## What is Document Sharding?
 
@@ -17,13 +21,13 @@ Document sharding splits large markdown files into smaller, organized files base
 
 ### Architecture
 
-```
+```text
 Before Sharding:
-docs/
+_bmad-output/planning-artifacts/
 └── PRD.md (large 50k token file)
 
 After Sharding:
-docs/
+_bmad-output/planning-artifacts/
 └── prd/
     ├── index.md                    # Table of contents with descriptions
     ├── overview.md                 # Section 1
@@ -37,12 +41,12 @@ docs/
 ### 1. Run the Shard-Doc Tool
 
 ```bash
-/bmad:core:tools:shard-doc
+/bmad-shard-doc
 ```
 
 ### 2. Follow the Interactive Process
 
-```
+```text
 Agent: Which document would you like to shard?
 User: docs/PRD.md
 

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

@@ -1,6 +1,8 @@
 ---
 title: "How to Upgrade to v6"
 description: Migrate from BMad v4 to v6
+sidebar:
+  order: 3
 ---
 
 Use the BMad installer to upgrade from v4 to v6, which includes automatic detection of legacy installations and migration assistance.
@@ -20,7 +22,7 @@ Use the BMad installer to upgrade from v4 to v6, which includes automatic detect
 
 ### 1. Run the Installer
 
-Follow the [Installer Instructions](/docs/how-to/install-bmad.md).
+Follow the [Installer Instructions](./install-bmad.md).
 
 ### 2. Handle Legacy Installation
 
@@ -29,7 +31,7 @@ When v4 is detected, you can:
 - Allow the installer to back up and remove `.bmad-method`
 - Exit and handle cleanup manually
 
-If you named your bmad method folder something else - you will need to manual remove the folder yourself.
+If you named your bmad method folder something else - you will need to manually remove the folder yourself.
 
 ### 3. Clean Up IDE Commands
 
@@ -63,16 +65,16 @@ If you have stories created or implemented:
 
 **v6 unified structure:**
 
-```
+```text
 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)
+├── _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

docs/index.md

@@ -3,18 +3,20 @@ title: Welcome to the BMad Method
 description: AI-driven development framework with specialized agents, guided workflows, and intelligent planning
 ---
 
-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 through the whole process from ideation and planning all the way through agentic implementation. 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.
+The BMad Method (**B**reakthrough **M**ethod of **A**gile AI **D**riven Development) is an AI-driven development framework module within the BMad Method Ecosystem that helps you build software through the whole process from ideation and planning all the way through agentic implementation. 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.
 
----
-
 ## New Here? Start with a Tutorial
 
 The fastest way to understand BMad is to try it.
 
-- **[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.
+- **[Get Started with BMad](./tutorials/getting-started.md)** — Install and understand how BMad works
+- **[Workflow Map](./reference/workflow-map.md)** — Visual overview of BMM phases, workflows, and context management
+
+:::tip[Just Want to Dive In?]
+Install BMad and run `/bmad-help` — it will guide you through everything based on your project and installed modules.
+:::
 
 ## How to Use These Docs
 
@@ -27,7 +29,9 @@ These docs are organized into four sections based on what you're trying to do:
 | **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.                   |
 
----
+## Extend and Customize
+
+Want to expand BMad with your own agents, workflows, or modules? The **[BMad Builder](https://bmad-builder-docs.bmad-method.org/)** provides the framework and tools for creating custom extensions, whether you're adding new capabilities to BMad or building entirely new modules from scratch.
 
 ## What You'll Need
 
@@ -36,12 +40,11 @@ BMad works with any AI coding assistant that supports custom system prompts or p
 - **[Claude Code](https://code.claude.com)** — Anthropic's CLI tool (recommended)
 - **[Cursor](https://cursor.sh)** — AI-first code editor
 - **[Windsurf](https://codeium.com/windsurf)** — Codeium's AI IDE
+- **[Kiro](https://kiro.dev)** — Amazon's AI-powered IDE
 - **[Roo Code](https://roocode.com)** — VS Code extension
 
 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.
 
----
-
 ## Join the Community
 
 Get help, share what you're building, or contribute to BMad:
@@ -50,8 +53,6 @@ Get help, share what you're building, or contribute to BMad:
 - **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — Source code, issues, and contributions
 - **[YouTube](https://www.youtube.com/@BMadCode)** — Video tutorials and walkthroughs
 
----
-
 ## Next Step
 
-Ready to dive in? **[Get Started with BMad](/docs/tutorials/getting-started.md)** and build your first project.
+Ready to dive in? **[Get Started with BMad](./tutorials/getting-started.md)** and build your first project.

docs/non-interactive-installation.md

@@ -1,314 +0,0 @@
----
-title: Non-Interactive Installation
-description: Install BMAD using command-line flags for CI/CD pipelines and automated deployments
----
-
-# Non-Interactive Installation
-
-BMAD now supports non-interactive installation through command-line flags. This is particularly useful for:
-
-- Automated deployments and CI/CD pipelines
-- Scripted installations
-- Batch installations across multiple projects
-- Quick installations with known configurations
-
-## Installation Modes
-
-### 1. Fully Interactive (Default)
-
-Run without any flags to use the traditional interactive prompts:
-
-```bash
-npx bmad-method install
-```
-
-### 2. Fully Non-Interactive
-
-Provide all required flags to skip all prompts:
-
-```bash
-npx bmad-method install \
-  --directory /path/to/project \
-  --modules bmm,bmb \
-  --tools claude-code,cursor \
-  --user-name "John Doe" \
-  --communication-language English \
-  --document-output-language English \
-  --output-folder _bmad-output
-```
-
-### 3. Semi-Interactive (Graceful Fallback)
-
-Provide some flags and let BMAD prompt for the rest:
-
-```bash
-npx bmad-method install \
-  --directory /path/to/project \
-  --modules bmm
-```
-
-In this case, BMAD will:
-- Use the provided directory and modules
-- Prompt for tool selection
-- Prompt for core configuration
-
-### 4. Quick Install with Defaults
-
-Use the `-y` or `--yes` flag to accept all defaults:
-
-```bash
-npx bmad-method install --yes
-```
-
-This will:
-- Install to the current directory
-- Skip custom content prompts
-- Use default values for all configuration
-- Use previously configured tools (or skip tool configuration if none exist)
-
-### 5. Install Without Tools
-
-To skip tool/IDE configuration entirely:
-
-**Option 1: Use --tools none**
-```bash
-npx bmad-method install --directory ~/myapp --modules bmm --tools none
-```
-
-**Option 2: Use --yes flag (if no tools were previously configured)**
-```bash
-npx bmad-method install --yes
-```
-
-**Option 3: Omit --tools and select "None" in the interactive prompt**
-```bash
-npx bmad-method install --directory ~/myapp --modules bmm
-# Then select "⚠ None - I am not installing any tools" when prompted
-```
-
-## Available Flags
-
-### Installation Options
-
-| Flag | Description | Example |
-|------|-------------|---------|
-| `--directory <path>` | Installation directory | `--directory ~/projects/myapp` |
-| `--modules <modules>` | Comma-separated module IDs | `--modules bmm,bmb` |
-| `--tools <tools>` | Comma-separated tool/IDE IDs (use "none" to skip) | `--tools claude-code,cursor` or `--tools none` |
-| `--custom-content <paths>` | Comma-separated paths to custom modules | `--custom-content ~/my-module,~/another-module` |
-| `--action <type>` | Action for existing installations | `--action quick-update` |
-
-### Core Configuration
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--user-name <name>` | Name for agents to use | System username |
-| `--communication-language <lang>` | Agent communication language | English |
-| `--document-output-language <lang>` | Document output language | English |
-| `--output-folder <path>` | Output folder path | _bmad-output |
-
-### Other Options
-
-| Flag | Description |
-|------|-------------|
-| `-y, --yes` | Accept all defaults and skip prompts |
-| `-d, --debug` | Enable debug output for manifest generation |
-
-## Action Types
-
-When working with existing installations, use the `--action` flag:
-
-- `install` - Fresh installation (default for new directories)
-- `update` - Modify existing installation (change modules/config)
-- `quick-update` - Refresh installation without changing configuration
-- `compile-agents` - Recompile agents with customizations only
-
-Example:
-
-```bash
-npx bmad-method install --action quick-update
-```
-
-## Module IDs
-
-Available module IDs for the `--modules` flag:
-
-### Core Modules
-- `bmm` - BMad Method Master
-- `bmb` - BMad Builder
-
-### External Modules
-Check the [BMad registry](https://github.com/bmad-code-org) for available external modules.
-
-## Tool/IDE IDs
-
-Available tool IDs for the `--tools` flag:
-
-- `claude-code` - Claude Code CLI
-- `cursor` - Cursor IDE
-- `windsurf` - Windsurf IDE
-- `vscode` - Visual Studio Code
-- `jetbrains` - JetBrains IDEs
-- And more...
-
-Run the interactive installer once to see all available tools.
-
-## Examples
-
-### Basic Installation
-
-Install BMM module with Claude Code:
-
-```bash
-npx bmad-method install \
-  --directory ~/projects/myapp \
-  --modules bmm \
-  --tools claude-code \
-  --user-name "Development Team"
-```
-
-### Installation Without Tools
-
-Install without configuring any tools/IDEs:
-
-```bash
-npx bmad-method install \
-  --directory ~/projects/myapp \
-  --modules bmm \
-  --tools none \
-  --user-name "Development Team"
-```
-
-### Full Installation with Multiple Modules
-
-```bash
-npx bmad-method install \
-  --directory ~/projects/myapp \
-  --modules bmm,bmb \
-  --tools claude-code,cursor \
-  --user-name "John Doe" \
-  --communication-language English \
-  --document-output-language English \
-  --output-folder _output
-```
-
-### Update Existing Installation
-
-```bash
-npx bmad-method install \
-  --directory ~/projects/myapp \
-  --action update \
-  --modules bmm,bmb,custom-module
-```
-
-### Quick Update (Preserve Settings)
-
-```bash
-npx bmad-method install \
-  --directory ~/projects/myapp \
-  --action quick-update
-```
-
-### Installation with Custom Content
-
-```bash
-npx bmad-method install \
-  --directory ~/projects/myapp \
-  --modules bmm \
-  --custom-content ~/my-custom-module,~/another-module \
-  --tools claude-code
-```
-
-### CI/CD Pipeline Installation
-
-```bash
-#!/bin/bash
-# install-bmad.sh
-
-npx bmad-method install \
-  --directory "${GITHUB_WORKSPACE}" \
-  --modules bmm \
-  --tools claude-code \
-  --user-name "CI Bot" \
-  --communication-language English \
-  --document-output-language English \
-  --output-folder _bmad-output \
-  --yes
-```
-
-## Environment-Specific Installations
-
-### Development Environment
-
-```bash
-npx bmad-method install \
-  --directory . \
-  --modules bmm,bmb \
-  --tools claude-code,cursor \
-  --user-name "${USER}"
-```
-
-### Production Environment
-
-```bash
-npx bmad-method install \
-  --directory /opt/app \
-  --modules bmm \
-  --tools claude-code \
-  --user-name "Production Team" \
-  --output-folder /var/bmad-output
-```
-
-## Validation and Error Handling
-
-BMAD validates all provided flags:
-
-- **Directory**: Must be a valid path with write permissions
-- **Modules**: Will warn about invalid module IDs (but won't fail)
-- **Tools**: Will warn about invalid tool IDs (but won't fail)
-- **Custom Content**: Each path must contain a valid `module.yaml` file
-- **Action**: Must be one of: install, update, quick-update, compile-agents
-
-Invalid values will either:
-1. Show an error and exit (for critical options like directory)
-2. Show a warning and skip (for optional items like custom content)
-3. Fall back to interactive prompts (for missing required values)
-
-## Tips and Best Practices
-
-1. **Use absolute paths** for `--directory` to avoid ambiguity
-2. **Test flags locally** before using in CI/CD pipelines
-3. **Combine with `-y`** for truly unattended installations
-4. **Check module availability** by running the interactive installer once
-5. **Use `--debug`** flag if you encounter issues during installation
-6. **Skip tool configuration** with `--tools none` for server/CI environments where IDEs aren't needed
-7. **Partial flags are OK** - Omit flags and let BMAD prompt for missing values interactively
-
-## Troubleshooting
-
-### Installation fails with "Invalid directory"
-
-Check that:
-- The directory path exists or its parent exists
-- You have write permissions
-- The path is absolute or correctly relative to current directory
-
-### Module not found
-
-- Verify the module ID is correct (check available modules in interactive mode)
-- External modules may need to be available in the registry
-
-### Custom content path invalid
-
-Ensure each custom content path:
-- Points to a directory
-- Contains a `module.yaml` file in the root
-- Has a `code` field in the `module.yaml`
-
-## Feedback and Issues
-
-If you encounter any issues with non-interactive installation:
-
-1. Run with `--debug` flag for detailed output
-2. Try the interactive mode to verify the issue
-3. Report issues on GitHub: <https://github.com/bmad-code-org/BMAD-METHOD/issues>

docs/reference/agents.md

@@ -1,13 +1,18 @@
 ---
 title: Agents
 description: Default BMM agents with their menu triggers and primary workflows
+sidebar:
+  order: 2
 ---
 
-This page lists the default BMM (Agile suite) agents that install with BMAD Method, along with their menu triggers and primary workflows.
+## Default Agents
+
+This page lists the default BMM (Agile suite) agents that install with BMad Method, along with their menu triggers and primary workflows.
+
+## Notes
 
-Notes:
 - Triggers are the short menu codes (e.g., `CP`) and fuzzy matches shown in each agent menu.
-- Slash commands are generated separately. See `docs/reference/commands.md` for the slash command list and where they are defined.
+- Slash commands are generated separately. See [Commands](./commands.md) for the slash command list and where they are defined.
 - QA (Quinn) is the lightweight test automation agent in BMM. The full Test Architect (TEA) lives in its own module.
 
 | Agent                       | Triggers                           | Primary workflows                                                                                   |

docs/reference/commands.md

@@ -1,34 +1,151 @@
 ---
 title: Commands
-description: How BMAD commands are generated and where to find them.
+description: Reference for BMad slash commands — what they are, how they work, and where to find them.
+sidebar:
+  order: 3
 ---
 
-# Commands
+Slash commands are pre-built prompts that load agents, run workflows, or execute tasks inside your IDE. The BMad installer generates them from your installed modules at install time. If you later add, remove, or change modules, re-run the installer to keep commands in sync (see [Troubleshooting](#troubleshooting)).
 
-BMAD slash commands are generated by the installer for your IDE and **reflect the modules you have installed**.  
-That means the authoritative list lives **in your project**, not in a static docs page.
+## Commands vs. Agent Menu Triggers
 
-## How to Discover Commands (Recommended)
+BMad offers two ways to start work, and they serve different purposes.
 
-- Type `/bmad` in your IDE and use autocomplete to browse agents/workflows.
-- Run `/bmad-help` to get guided next steps and context-aware recommendations.
+| Mechanism | How you invoke it | What happens |
+| --- | --- | --- |
+| **Slash command** | Type `/bmad-...` in your IDE | Directly loads an agent, runs a workflow, or executes a task |
+| **Agent menu trigger** | Load an agent first, then type a short code (e.g. `DS`) | The agent interprets the code and starts the matching workflow while staying in character |
 
-## Where Commands Are Generated
+Agent menu triggers require an active agent session. Use slash commands when you know which workflow you want. Use triggers when you are already working with an agent and want to switch tasks without leaving the conversation.
 
-The installer writes command files into your project (example paths for Claude Code):
+## How Commands Are Generated
 
-- `.claude/commands/bmad/<module>/agents/`
-- `.claude/commands/bmad/<module>/workflows/`
+When you run `npx bmad-method install`, the installer reads the manifests for every selected module and writes one command file per agent, workflow, task, and tool. Each file is a short markdown prompt that instructs the AI to load the corresponding source file and follow its instructions.
 
-These folders are the **canonical, project-specific command list**.
+The installer uses templates for each command type:
 
-## Common Commands
+| Command type | What the generated file does |
+| --- | --- |
+| **Agent launcher** | Loads the agent persona file, activates its menu, and stays in character |
+| **Workflow command** | Loads the workflow engine (`workflow.xml`) and passes the workflow config |
+| **Task command** | Loads a standalone task file and follows its instructions |
+| **Tool command** | Loads a standalone tool file and follows its instructions |
 
-- `/bmad-help` - Interactive help and next-step guidance
-- `/bmad:<module>:agents:<agent>` - Load an agent (e.g. `/bmad:bmm:agents:dev`)
-- `/bmad:<module>:workflows:<workflow>` - Run a workflow (e.g. `/bmad:bmm:workflows:create-prd`)
+:::note[Re-running the installer]
+If you add or remove modules, run the installer again. It regenerates all command files to match your current module selection.
+:::
 
-## Why This Page Is Short
+## Where Command Files Live
 
-BMAD is modular, so the exact commands vary by install.  
-Use your IDE's autocomplete or the generated command folders above to see *everything* available.
+The installer writes command files into an IDE-specific directory inside your project. The exact path depends on which IDE you selected during installation.
+
+| IDE / CLI | Command directory |
+| --- | --- |
+| Claude Code | `.claude/commands/` |
+| Cursor | `.cursor/commands/` |
+| Windsurf | `.windsurf/workflows/` |
+| Other IDEs | See the installer output for the target path |
+
+All IDEs receive a flat set of command files in their command directory. For example, a Claude Code installation looks like:
+
+```text
+.claude/commands/
+├── bmad-agent-bmm-dev.md
+├── bmad-agent-bmm-pm.md
+├── bmad-bmm-create-prd.md
+├── bmad-editorial-review-prose.md
+├── bmad-help.md
+└── ...
+```
+
+The filename determines the slash command name in your IDE. For example, the file `bmad-agent-bmm-dev.md` registers the command `/bmad-agent-bmm-dev`.
+
+## How to Discover Your Commands
+
+Type `/bmad` in your IDE and use autocomplete to browse available commands.
+
+Run `/bmad-help` for context-aware guidance on your next step.
+
+:::tip[Quick discovery]
+The generated command folders in your project are the canonical list. Open them in your file explorer to see every command with its description.
+:::
+
+## Command Categories
+
+### Agent Commands
+
+Agent commands load a specialized AI persona with a defined role, communication style, and menu of workflows. Once loaded, the agent stays in character and responds to menu triggers.
+
+| Example command | Agent | Role |
+| --- | --- | --- |
+| `/bmad-agent-bmm-dev` | Amelia (Developer) | Implements stories with strict adherence to specs |
+| `/bmad-agent-bmm-pm` | John (Product Manager) | Creates and validates PRDs |
+| `/bmad-agent-bmm-architect` | Winston (Architect) | Designs system architecture |
+| `/bmad-agent-bmm-sm` | Bob (Scrum Master) | Manages sprints and stories |
+
+See [Agents](./agents.md) for the full list of default agents and their triggers.
+
+### Workflow Commands
+
+Workflow commands run a structured, multi-step process without loading an agent persona first. They load the workflow engine and pass a specific workflow configuration.
+
+| Example command | Purpose |
+| --- | --- |
+| `/bmad-bmm-create-prd` | Create a Product Requirements Document |
+| `/bmad-bmm-create-architecture` | Design system architecture |
+| `/bmad-bmm-dev-story` | Implement a story |
+| `/bmad-bmm-code-review` | Run a code review |
+| `/bmad-bmm-quick-spec` | Define an ad-hoc change (Quick Flow) |
+
+See [Workflow Map](./workflow-map.md) for the complete workflow reference organized by phase.
+
+### Task and Tool Commands
+
+Tasks and tools are standalone operations that do not require an agent or workflow context.
+
+#### BMad-Help: Your Intelligent Guide
+
+**`/bmad-help`** is your primary interface for discovering what to do next. It's not just a lookup tool — it's an intelligent assistant that:
+
+- **Inspects your project** to see what's already been done
+- **Understands natural language queries** — ask questions in plain English
+- **Varies by installed modules** — shows options based on what you have
+- **Auto-invokes after workflows** — every workflow ends with clear next steps
+- **Recommends the first required task** — no guessing where to start
+
+**Examples:**
+
+```
+/bmad-help
+/bmad-help I have a SaaS idea and know all the features. Where do I start?
+/bmad-help What are my options for UX design?
+/bmad-help I'm stuck on the PRD workflow
+```
+
+#### Other Tasks and Tools
+
+| Example command | Purpose |
+| --- | --- |
+| `/bmad-shard-doc` | Split a large markdown file into smaller sections |
+| `/bmad-index-docs` | Index project documentation |
+| `/bmad-editorial-review-prose` | Review document prose quality |
+
+## Naming Convention
+
+Command names follow a predictable pattern.
+
+| Pattern | Meaning | Example |
+| --- | --- | --- |
+| `bmad-agent-<module>-<name>` | Agent launcher | `bmad-agent-bmm-dev` |
+| `bmad-<module>-<workflow>` | Workflow command | `bmad-bmm-create-prd` |
+| `bmad-<name>` | Core task or tool | `bmad-help` |
+
+Module codes: `bmm` (Agile suite), `bmb` (Builder), `tea` (Test Architect), `cis` (Creative Intelligence), `gds` (Game Dev Studio). See [Modules](./modules.md) for descriptions.
+
+## Troubleshooting
+
+**Commands not appearing after install.** Restart your IDE or reload the window. Some IDEs cache the command list and require a refresh to pick up new files.
+
+**Expected commands are missing.** The installer only generates commands for modules you selected. Run `npx bmad-method install` again and verify your module selection. Check that the command files exist in the expected directory.
+
+**Commands from a removed module still appear.** The installer does not delete old command files automatically. Remove the stale files from your IDE's command directory, or delete the entire command directory and re-run the installer for a clean set.

docs/reference/modules.md

@@ -1,6 +1,8 @@
 ---
 title: Official Modules
 description: Add-on modules for building custom agents, creative intelligence, game development, and testing
+sidebar:
+  order: 4
 ---
 
 BMad extends through official modules that you select during installation. These add-on modules provide specialized agents, workflows, and tasks for specific domains beyond the built-in core and BMM (Agile suite).

docs/reference/testing.md

@@ -1,22 +1,106 @@
 ---
 title: Testing Options
-description: Built-in QA agent and the standalone Test Architect module for advanced testing
+description: Comparing the built-in QA agent (Quinn) with the Test Architect (TEA) module for test automation.
+sidebar:
+  order: 5
 ---
 
-# Testing Options
+BMad provides two testing paths: a built-in QA agent for fast test generation and an installable Test Architect module for enterprise-grade test strategy.
 
-BMad provides a built-in QA agent for quick test automation and a separate Test Architect (TEA) module for advanced testing.
+## Which Should You Use?
 
-## Built-in QA (Quinn)
+| Factor | Quinn (Built-in QA) | TEA Module |
+| --- | --- | --- |
+| **Best for** | Small-medium projects, quick coverage | Large projects, regulated or complex domains |
+| **Setup** | Nothing to install -- included in BMM | Install separately via `npx bmad-method install` |
+| **Approach** | Generate tests fast, iterate later | Plan first, then generate with traceability |
+| **Test types** | API and E2E tests | API, E2E, ATDD, NFR, and more |
+| **Strategy** | Happy path + critical edge cases | Risk-based prioritization (P0-P3) |
+| **Workflow count** | 1 (Automate) | 9 (design, ATDD, automate, review, trace, and others) |
 
-Use the built-in QA agent for fast, straightforward test coverage:
+:::tip[Start with Quinn]
+Most projects should start with Quinn. If you later need test strategy, quality gates, or requirements traceability, install TEA alongside it.
+:::
 
-- Trigger: `QA` or `bmad-bmm-qa-automate`
-- Best for: small projects, quick coverage, standard patterns
+## Built-in QA Agent (Quinn)
+
+Quinn is the built-in QA agent in the BMM (Agile suite) module. It generates working tests quickly using your project's existing test framework -- no configuration or additional installation required.
+
+**Trigger:** `QA` or `bmad-bmm-qa-automate`
+
+### What Quinn Does
+
+Quinn runs a single workflow (Automate) that walks through five steps:
+
+1. **Detect test framework** -- scans `package.json` and existing test files for your framework (Jest, Vitest, Playwright, Cypress, or any standard runner). If none exists, analyzes the project stack and suggests one.
+2. **Identify features** -- asks what to test or auto-discovers features in the codebase.
+3. **Generate API tests** -- covers status codes, response structure, happy path, and 1-2 error cases.
+4. **Generate E2E tests** -- covers user workflows with semantic locators and visible-outcome assertions.
+5. **Run and verify** -- executes the generated tests and fixes failures immediately.
+
+Quinn produces a test summary saved to your project's implementation artifacts folder.
+
+### Test Patterns
+
+Generated tests follow a "simple and maintainable" philosophy:
+
+- **Standard framework APIs only** -- no external utilities or custom abstractions
+- **Semantic locators** for UI tests (roles, labels, text rather than CSS selectors)
+- **Independent tests** with no order dependencies
+- **No hardcoded waits or sleeps**
+- **Clear descriptions** that read as feature documentation
+
+:::note[Scope]
+Quinn generates tests only. For code review and story validation, use the Code Review workflow (`CR`) instead.
+:::
+
+### When to Use Quinn
+
+- Quick test coverage for a new or existing feature
+- Beginner-friendly test automation without advanced setup
+- Standard test patterns that any developer can read and maintain
+- Small-medium projects where comprehensive test strategy is unnecessary
 
 ## Test Architect (TEA) Module
 
-TEA is a standalone module with advanced testing workflows (test design, ATDD, automate, review, trace, NFR assessment).
+TEA is a standalone module that provides an expert agent (Murat) and nine structured workflows for enterprise-grade testing. It goes beyond test generation into test strategy, risk-based planning, quality gates, and requirements traceability.
 
-- Documentation: <https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/>
-- Install: `npx bmad-method@alpha install` and select the TEA module
+- **Documentation:** [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
+- **Install:** `npx bmad-method install` and select the TEA module
+- **npm:** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise)
+
+### What TEA Provides
+
+| Workflow | Purpose |
+| --- | --- |
+| Test Design | Create a comprehensive test strategy tied to requirements |
+| ATDD | Acceptance-test-driven development with stakeholder criteria |
+| Automate | Generate tests with advanced patterns and utilities |
+| Test Review | Validate test quality and coverage against strategy |
+| Traceability | Map tests back to requirements for audit and compliance |
+| NFR Assessment | Evaluate non-functional requirements (performance, security) |
+| CI Setup | Configure test execution in continuous integration pipelines |
+| Framework Scaffolding | Set up test infrastructure and project structure |
+| Release Gate | Make data-driven go/no-go release decisions |
+
+TEA also supports P0-P3 risk-based prioritization and optional integrations with Playwright Utils and MCP tooling.
+
+### When to Use TEA
+
+- Projects that require requirements traceability or compliance documentation
+- Teams that need risk-based test prioritization across many features
+- Enterprise environments with formal quality gates before release
+- Complex domains where test strategy must be planned before tests are written
+- Projects that have outgrown Quinn's single-workflow approach
+
+## How Testing Fits into Workflows
+
+Quinn's Automate workflow appears in Phase 4 (Implementation) of the BMad Method workflow map. A typical sequence:
+
+1. Implement a story with the Dev workflow (`DS`)
+2. Generate tests with Quinn (`QA`) or TEA's Automate workflow
+3. Validate implementation with Code Review (`CR`)
+
+Quinn works directly from source code without loading planning documents (PRD, architecture). TEA workflows can integrate with upstream planning artifacts for traceability.
+
+For more on where testing fits in the overall process, see the [Workflow Map](./workflow-map.md).

docs/reference/workflow-map.md

@@ -1,86 +1,89 @@
 ---
 title: "Workflow Map"
 description: Visual reference for BMad Method workflow phases and outputs
+sidebar:
+  order: 1
 ---
 
 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.
+If at any time 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 BMad Method. Additionally, if you are using different modules that have extended the BMad Method or added other complementary 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>
+<iframe src="/workflow-map-diagram.html" title="BMad Method Workflow Map Diagram" width="100%" height="100%" style="border-radius: 8px; border: 1px solid #334155; min-height: 900px;"></iframe>
 
-*[Interactive diagram - hover over outputs to see artifact flows]*
+<p style="font-size: 0.8rem; text-align: right; margin-top: -0.5rem; margin-bottom: 1rem;">
+  <a href="/workflow-map-diagram.html" target="_blank" rel="noopener noreferrer">Open diagram in new tab ↗</a>
+</p>
 
 ## 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`        |
+| ------------------------------- | -------------------------------------------------------------------------- | ------------------------- |
+| `bmad-brainstorming`            | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorming-report.md` |
+| `bmad-bmm-research`             | Validate market, technical, or domain assumptions                          | Research findings         |
+| `bmad-bmm-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` |
+| --------------------------- | ---------------------------------------- | ------------ |
+| `bmad-bmm-create-prd`       | Define requirements (FRs/NFRs)           | `PRD.md`     |
+| `bmad-bmm-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 |
+| ----------------------------------------- | ------------------------------------------ | --------------------------- |
+| `bmad-bmm-create-architecture`            | Make technical decisions explicit          | `architecture.md` with ADRs |
+| `bmad-bmm-create-epics-and-stories`       | Break requirements into implementable work | Epic files with stories     |
+| `bmad-bmm-check-implementation-readiness` | Gate check before implementation           | PASS/CONCERNS/FAIL decision |
 
 ## Phase 4: Implementation
 
-Build it, one story at a time.
+Build it, one story at a time. Coming soon, full phase 4 automation!
 
 | 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.
+| -------------------------- | ------------------------------------------------------------------------ | -------------------------------- |
+| `bmad-bmm-sprint-planning` | Initialize tracking (once per project to sequence the dev cycle)         | `sprint-status.yaml`             |
+| `bmad-bmm-create-story`    | Prepare next story for implementation                                    | `story-[slug].md`                |
+| `bmad-bmm-dev-story`       | Implement the story                                                      | Working code + tests             |
+| `bmad-bmm-code-review`     | Validate implementation quality                                          | Approved or changes requested    |
+| `bmad-bmm-correct-course`  | Handle significant mid-sprint changes                                    | Updated plan or re-routing       |
+| `bmad-bmm-automate`        | Generate tests for existing features - Use after a full epic is complete | End to End UI Focused Test suite |
+| `bmad-bmm-retrospective`   | Review after epic completion                                             | Lessons learned                  |
 
 ## 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                          |
+| --------------------- | ------------------------------------------ | --------------------------------------------- |
+| `bmad-bmm-quick-spec` | Define an ad-hoc change                    | `tech-spec.md` (story file for small changes) |
+| `bmad-bmm-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 established 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.
+### Project Context
 
-All implementation workflows load `project-context.md` if it exists. Additional context per workflow:
+:::tip[Recommended]
+Create `project-context.md` to ensure AI agents follow your project's rules and preferences. This file works like a constitution for your project — it guides implementation decisions across all workflows. This optional file can be generated at the end of Architecture Creation, or in an existing project it can be generated also to capture whats important to keep aligned with current conventions.
+:::
 
-| 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                    |
+**How to create it:**
+
+- **Manually** — Create `_bmad-output/project-context.md` with your technology stack and implementation rules
+- **Generate it** — Run `/bmad-bmm-generate-project-context` to auto-generate from your architecture or codebase
+
+[**Learn more about project-context.md**](../explanation/project-context.md)

docs/tutorials/getting-started.md

@@ -8,6 +8,7 @@ Build software faster using AI-powered workflows with specialized agents that gu
 ## What You'll Learn
 
 - Install and initialize BMad Method for a new project
+- Use **BMad-Help** — your intelligent guide that knows what to do next
 - Choose the right planning track for your project size
 - Progress through phases from requirements to working code
 - Use agents and workflows effectively
@@ -19,11 +20,46 @@ Build software faster using AI-powered workflows with specialized agents that gu
 - **A project idea** — Even a simple one works for learning
 :::
 
-:::tip[Quick Path]
+:::tip[The Easiest 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.
+**Ask** → `/bmad-help what should I do first?`
+**Build** → Let BMad-Help guide you workflow by workflow
+:::
+
+## Meet BMad-Help: Your Intelligent Guide
+
+**BMad-Help is the fastest way to get started with BMad.** You don't need to memorize workflows or phases — just ask, and BMad-Help will:
+
+- **Inspect your project** to see what's already been done
+- **Show your options** based on which modules you have installed
+- **Recommend what's next** — including the first required task
+- **Answer questions** like "I have a SaaS idea, where do I start?"
+
+### How to Use BMad-Help
+
+Run it in your AI IDE with just the slash command:
+
+```
+/bmad-help
+```
+
+Or combine it with a question for context-aware guidance:
+
+```
+/bmad-help I have an idea for a SaaS product, I already know all the features I want. where do I get started?
+```
+
+BMad-Help will respond with:
+- What's recommended for your situation
+- What the first required task is
+- What the rest of the process looks like
+
+### It Powers Workflows Too
+
+BMad-Help doesn't just answer questions — **it automatically runs at the end of every workflow** to tell you exactly what to do next. No guessing, no searching docs — just clear guidance on the next required workflow.
+
+:::tip[Start Here]
+After installing BMad, run `/bmad-help` immediately. It will detect what modules you have installed and guide you to the right starting point for your project.
 :::
 
 ## Understanding BMad
@@ -37,7 +73,7 @@ BMad helps you build software through guided workflows with specialized AI agent
 | 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.
+**[Open the Workflow Map](../reference/workflow-map.md)** to explore phases, workflows, and context management.
 
 Based on your project's complexity, BMad offers three planning tracks:
 
@@ -65,7 +101,15 @@ 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.
+:::tip[Your Next Step]
+Open your AI IDE in the project folder and run:
+
+```
+/bmad-help
+```
+
+BMad-Help will detect what you've completed and recommend exactly what to do next. You can also ask it questions like "What are my options?" or "I have a SaaS idea, where should I start?"
+:::
 
 :::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).
@@ -79,6 +123,12 @@ Always start a fresh chat for each workflow. This prevents context limitations f
 
 Work through phases 1-3. **Use fresh chats for each workflow.**
 
+:::tip[Project Context (Optional)]
+Before starting, consider creating `project-context.md` to document your technical preferences and implementation rules. This ensures all AI agents follow your conventions throughout the project.
+
+Create it manually at `_bmad-output/project-context.md` or generate it after architecture using `/bmad-bmm-generate-project-context`. [Learn more](../explanation/project-context.md).
+:::
+
 ### Phase 1: Analysis (Optional)
 
 All workflows in this phase are optional:
@@ -153,24 +203,28 @@ You've learned the foundation of building with BMad:
 
 Your project now has:
 
-```
+```text
 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
+│   ├── planning-artifacts/
+│   │   ├── PRD.md                           # Your requirements document
+│   │   ├── architecture.md                  # Technical decisions
+│   │   └── epics/                           # Epic and story files
+│   ├── implementation-artifacts/
+│   │   └── sprint-status.yaml               # Sprint tracking
+│   └── project-context.md                   # Implementation rules (optional)
 └── ...
 ```
 
 ## Quick Reference
 
 | Workflow                              | Command                                    | Agent     | Purpose                                         |
-| -------------------------------- | ------------------------------------------ | --------- | ------------------------------------ |
-| `help`                           | `/bmad-help`                               | Any       | Get guidance on what to do next      |
+| ------------------------------------- | ------------------------------------------ | --------- | ----------------------------------------------- |
+| **`help`** ⭐                         | `/bmad-help`                               | Any       | **Your intelligent guide — ask anything!**      |
 | `prd`                                 | `/bmad-bmm-create-prd`                     | PM        | Create Product Requirements Document            |
 | `create-architecture`                 | `/bmad-bmm-create-architecture`            | Architect | Create architecture document                     |
+| `generate-project-context`            | `/bmad-bmm-generate-project-context`       | Analyst   | Create project context file                     |
 | `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           |
@@ -194,16 +248,26 @@ Not strictly. Once you learn the flow, you can run workflows directly using the
 
 ## Getting Help
 
+:::tip[First Stop: BMad-Help]
+**Run `/bmad-help` anytime** — it's the fastest way to get unstuck. Ask it anything:
+- "What should I do after installing?"
+- "I'm stuck on workflow X"
+- "What are my options for Y?"
+- "Show me what's been done so far"
+
+BMad-Help inspects your project, detects what you've completed, and tells you exactly what to do next.
+:::
+
 - **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]
+- **Start with `/bmad-help`** — Your intelligent guide that knows your project and options
 - **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
+- **BMad-Help runs automatically** — Every workflow ends with guidance on what's next
 :::
 
-Ready to start? Install BMad and let the agents guide you through your first project.
+Ready to start? Install BMad, run `/bmad-help`, and let your intelligent guide lead the way.

eslint.config.mjs

@@ -83,7 +83,7 @@ export default [
 
   // CLI scripts under tools/** and test/**
   {
-    files: ['tools/**/*.js', 'tools/**/*.mjs', 'test/**/*.js'],
+    files: ['tools/**/*.js', 'tools/**/*.mjs', 'test/**/*.js', 'test/**/*.mjs'],
     rules: {
       // Allow CommonJS patterns for Node CLI scripts
       'unicorn/prefer-module': 'off',
@@ -114,17 +114,6 @@ export default [
     },
   },
 
-  // Module installer scripts use CommonJS for compatibility
-  {
-    files: ['**/_module-installer/**/*.js'],
-    rules: {
-      // Allow CommonJS patterns for installer scripts
-      'unicorn/prefer-module': 'off',
-      'n/no-missing-require': 'off',
-      'n/no-unpublished-require': 'off',
-    },
-  },
-
   // ESLint config file should not be checked for publish-related Node rules
   {
     files: ['eslint.config.mjs'],

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "6.0.0-Beta.7",
+  "version": "6.0.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "6.0.0-Beta.7",
+      "version": "6.0.1",
       "license": "MIT",
       "dependencies": {
         "@clack/core": "^1.0.0",

package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.0.0-Beta.7",
+  "version": "6.0.1",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -25,13 +25,12 @@
   },
   "scripts": {
     "bmad:install": "node tools/cli/bmad-cli.js install",
-    "bundle": "node tools/cli/bundlers/bundle-web.js all",
+    "bmad:uninstall": "node tools/cli/bmad-cli.js uninstall",
     "docs:build": "node tools/build-docs.mjs",
     "docs:dev": "astro dev --root website",
     "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",
@@ -41,9 +40,10 @@
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
     "rebundle": "node tools/cli/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:schemas && npm run test:install && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:schemas && npm run test:refs && npm run test:install && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
     "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
     "test:install": "node test/test-installation-components.js",
+    "test:refs": "node test/test-file-refs-csv.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"

src/bmm/_module-installer/installer.js

@@ -1,48 +0,0 @@
-const fs = require('fs-extra');
-const path = require('node:path');
-const chalk = require('chalk');
-
-// Directories to create from config
-const DIRECTORIES = ['output_folder', 'planning_artifacts', 'implementation_artifacts'];
-
-/**
- * BMM Module Installer
- * Creates output directories configured in module config
- *
- * @param {Object} options - Installation options
- * @param {string} options.projectRoot - The root directory of the target project
- * @param {Object} options.config - Module configuration from module.yaml
- * @param {Array<string>} options.installedIDEs - Array of IDE codes that were installed
- * @param {Object} options.logger - Logger instance for output
- * @returns {Promise<boolean>} - Success status
- */
-async function install(options) {
-  const { projectRoot, config, logger } = options;
-
-  try {
-    logger.log(chalk.blue('🚀 Installing BMM Module...'));
-
-    // Create configured directories
-    for (const configKey of DIRECTORIES) {
-      const configValue = config[configKey];
-      if (!configValue) continue;
-
-      const dirPath = configValue.replace('{project-root}/', '');
-      const fullPath = path.join(projectRoot, dirPath);
-
-      if (!(await fs.pathExists(fullPath))) {
-        const dirName = configKey.replace('_', ' ');
-        logger.log(chalk.yellow(`Creating ${dirName} directory: ${dirPath}`));
-        await fs.ensureDir(fullPath);
-      }
-    }
-
-    logger.log(chalk.green('✓ BMM Module installation complete'));
-    return true;
-  } catch (error) {
-    logger.error(chalk.red(`Error installing BMM module: ${error.message}`));
-    return false;
-  }
-}
-
-module.exports = { install };

src/bmm/agents/analyst.agent.yaml

@@ -5,14 +5,15 @@ agent:
     title: Business Analyst
     icon: 📊
     module: bmm
+    capabilities: "market research, competitive analysis, requirements elicitation, domain expertise"
     hasSidecar: false
 
   persona:
     role: Strategic Business Analyst + Requirements Expert
     identity: Senior analyst with deep expertise in market research, competitive analysis, and requirements elicitation. Specializes in translating vague needs into actionable specs.
     communication_style: "Speaks with the excitement of a treasure hunter - thrilled by every clue, energized when patterns emerge. Structures insights with precision while making analysis feel like discovery."
-    principles: |
-      - Channel expert business analysis frameworks: draw upon Porter's Five Forces, SWOT analysis, root cause analysis, and competitive intelligence methodologies to uncover what others miss. Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence.
+    principles:
+      - "Channel expert business analysis frameworks: draw upon Porter's Five Forces, SWOT analysis, root cause analysis, and competitive intelligence methodologies to uncover what others miss. Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence."
       - Articulate requirements with absolute precision. Ensure all stakeholder voices heard.
 
   menu:

src/bmm/agents/architect.agent.yaml

@@ -7,14 +7,15 @@ agent:
     title: Architect
     icon: 🏗️
     module: bmm
+    capabilities: "distributed systems, cloud infrastructure, API design, scalable patterns"
     hasSidecar: false
 
   persona:
     role: System Architect + Technical Design Leader
     identity: Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection.
     communication_style: "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.'"
-    principles: |
-      - Channel expert lean architecture wisdom: draw upon deep knowledge of distributed systems, cloud patterns, scalability trade-offs, and what actually ships successfully
+    principles:
+      - "Channel expert lean architecture wisdom: draw upon deep knowledge of distributed systems, cloud patterns, scalability trade-offs, and what actually ships successfully"
       - User journeys drive technical decisions. Embrace boring technology for stability.
       - Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact.
 

src/bmm/agents/dev.agent.yaml

@@ -7,13 +7,14 @@ agent:
     title: Developer Agent
     icon: 💻
     module: bmm
+    capabilities: "story execution, test-driven development, code implementation"
     hasSidecar: false
 
   persona:
     role: Senior Software Engineer
     identity: Executes approved stories with strict adherence to story details and team standards and practices.
     communication_style: "Ultra-succinct. Speaks in file paths and AC IDs - every statement citable. No fluff, all precision."
-    principles: |
+    principles:
       - All existing and new tests must pass 100% before story is ready for review
       - Every task/subtask must be covered by comprehensive unit tests before marking an item complete
 

src/bmm/agents/pm.agent.yaml

@@ -5,14 +5,15 @@ agent:
     title: Product Manager
     icon: 📋
     module: bmm
+    capabilities: "PRD creation, requirements discovery, stakeholder alignment, user interviews"
     hasSidecar: false
 
   persona:
     role: Product Manager specializing in collaborative PRD creation through user interviews, requirement discovery, and stakeholder alignment.
     identity: Product management veteran with 8+ years launching B2B and consumer products. Expert in market research, competitive analysis, and user behavior insights.
     communication_style: "Asks 'WHY?' relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters."
-    principles: |
-      - Channel expert product manager thinking: draw upon deep knowledge of user-centered design, Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones
+    principles:
+      - "Channel expert product manager thinking: draw upon deep knowledge of user-centered design, Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones"
       - PRDs emerge from user interviews, not template filling - discover what users actually need
       - Ship the smallest thing that validates the assumption - iteration over perfection
       - Technical feasibility is a constraint, not the driver - user value first

src/bmm/agents/qa.agent.yaml

@@ -5,6 +5,7 @@ agent:
     title: QA Engineer
     icon: 🧪
     module: bmm
+    capabilities: "test automation, API testing, E2E testing, coverage analysis"
     hasSidecar: false
 
   persona:

src/bmm/agents/quick-flow-solo-dev.agent.yaml

@@ -7,13 +7,14 @@ agent:
     title: Quick Flow Solo Dev
     icon: 🚀
     module: bmm
+    capabilities: "rapid spec creation, lean implementation, minimum ceremony"
     hasSidecar: false
 
   persona:
     role: Elite Full-Stack Developer + Quick Flow Specialist
     identity: Barry handles Quick Flow - from tech spec creation through implementation. Minimum ceremony, lean artifacts, ruthless efficiency.
     communication_style: "Direct, confident, and implementation-focused. Uses tech slang (e.g., refactor, patch, extract, spike) and gets straight to the point. No fluff, just results. Stays focused on the task at hand."
-    principles: |
+    principles:
       - Planning and execution are two sides of the same coin.
       - Specs are for building, not bureaucracy. Code that ships is better than perfect code that doesn't.
 

src/bmm/agents/sm.agent.yaml

@@ -7,13 +7,14 @@ agent:
     title: Scrum Master
     icon: 🏃
     module: bmm
+    capabilities: "sprint planning, story preparation, agile ceremonies, backlog management"
     hasSidecar: false
 
   persona:
     role: Technical Scrum Master + Story Preparation Specialist
     identity: Certified Scrum Master with deep technical background. Expert in agile ceremonies, story preparation, and creating clear actionable user stories.
     communication_style: "Crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. Zero tolerance for ambiguity."
-    principles: |
+    principles:
       - I strive to be a servant leader and conduct myself accordingly, helping with any task and offering suggestions
       - I love to talk about Agile process and theory whenever anyone wants to talk about it
 

src/bmm/agents/tech-writer/tech-writer.agent.yaml

@@ -7,15 +7,16 @@ agent:
     title: Technical Writer
     icon: 📚
     module: bmm
+    capabilities: "documentation, Mermaid diagrams, standards compliance, concept explanation"
     hasSidecar: true
 
   persona:
     role: Technical Documentation Specialist + Knowledge Curator
     identity: Experienced technical writer expert in CommonMark, DITA, OpenAPI. Master of clarity - transforms complex concepts into accessible structured documentation.
     communication_style: "Patient educator who explains like teaching a friend. Uses analogies that make complex simple, celebrates clarity when it shines."
-    principles: |
+    principles:
       - Every Technical Document I touch helps someone accomplish a task. Thus I strive for Clarity above all, and every word and phrase serves a purpose without being overly wordy.
-      - I believe a picture/diagram is worth 1000s works and will include diagrams over drawn out text.
+      - I believe a picture/diagram is worth 1000s of words and will include diagrams over drawn out text.
       - I understand the intended audience or will clarify with the user so I know when to simplify vs when to be detailed.
       - I will always strive to follow `_bmad/_memory/tech-writer-sidecar/documentation-standards.md` best practices.
 

src/bmm/agents/ux-designer.agent.yaml

@@ -7,13 +7,14 @@ agent:
     title: UX Designer
     icon: 🎨
     module: bmm
+    capabilities: "user research, interaction design, UI patterns, experience strategy"
     hasSidecar: false
 
   persona:
     role: User Experience Designer + UI Specialist
     identity: Senior UX Designer with 7+ years creating intuitive experiences across web and mobile. Expert in user research, interaction design, AI-assisted tools.
     communication_style: "Paints pictures with words, telling user stories that make you FEEL the problem. Empathetic advocate with creative storytelling flair."
-    principles: |
+    principles:
       - Every decision serves genuine user needs
       - Start simple, evolve through feedback
       - Balance empathy with edge case attention
@@ -23,4 +24,4 @@ agent:
   menu:
     - trigger: CU or fuzzy match on ux-design
       exec: "{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md"
-      description: "[CU] Create UX: Guidance through realizing the plan for your UX to inform architecture and implementation. PRovides more details that what was discovered in the PRD"
+      description: "[CU] Create UX: Guidance through realizing the plan for your UX to inform architecture and implementation. Provides more details than what was discovered in the PRD"

src/bmm/module.yaml

@@ -42,3 +42,9 @@ project_knowledge: # Artifacts from research, document-project output, other lon
   prompt: "Where should long-term project knowledge be stored? (docs, research, references)"
   default: "docs"
   result: "{project-root}/{value}"
+
+# Directories to create during installation (declarative, no code execution)
+directories:
+  - "{planning_artifacts}"
+  - "{implementation_artifacts}"
+  - "{project_knowledge}"

src/bmm/workflows/1-analysis/research/domain-steps/step-06-research-synthesis.md

@@ -373,6 +373,7 @@ _This comprehensive research document serves as an authoritative reference on {{
 
 #### If 'C' (Complete Research):
 
+- **Replace** the template placeholder `[Research overview and methodology will be appended here]` in the `## Research Overview` section near the top of the document with a concise 2-3 paragraph overview summarizing the research scope, key findings, and a pointer to the full executive summary in the Research Synthesis section
 - Append the complete document to the research file
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
 - Complete the domain research workflow
@@ -380,7 +381,7 @@ _This comprehensive research document serves as an authoritative reference on {{
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the complete comprehensive research document using the full structure above.
+When user selects 'C', append the complete comprehensive research document using the full structure above. Also replace the `[Research overview and methodology will be appended here]` placeholder in the Research Overview section at the top of the document.
 
 ## SUCCESS METRICS:
 

src/bmm/workflows/1-analysis/research/market-steps/step-06-research-completion.md

@@ -389,13 +389,14 @@ _This comprehensive market research document serves as an authoritative market r
 
 #### If 'C' (Complete Research):
 
+- **Replace** the template placeholder `[Research overview and methodology will be appended here]` in the `## Research Overview` section near the top of the document with a concise 2-3 paragraph overview summarizing the research scope, key findings, and a pointer to the full executive summary in the Research Synthesis section
 - Append the final content to the research document
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
 - Complete the market research workflow
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the content directly to the research document using the structure from step 4.
+When user selects 'C', append the content directly to the research document using the structure from step 4. Also replace the `[Research overview and methodology will be appended here]` placeholder in the Research Overview section at the top of the document.
 
 ## SUCCESS METRICS:
 

src/bmm/workflows/1-analysis/research/technical-steps/step-06-research-synthesis.md

@@ -416,6 +416,7 @@ _This comprehensive technical research document serves as an authoritative techn
 
 #### If 'C' (Complete Research):
 
+- **Replace** the template placeholder `[Research overview and methodology will be appended here]` in the `## Research Overview` section near the top of the document with a concise 2-3 paragraph overview summarizing the research scope, key findings, and a pointer to the full executive summary in the Research Synthesis section
 - Append the complete technical document to the research file
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5, 6]`
 - Complete the technical research workflow
@@ -423,7 +424,7 @@ _This comprehensive technical research document serves as an authoritative techn
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the complete comprehensive technical research document using the full structure above.
+When user selects 'C', append the complete comprehensive technical research document using the full structure above. Also replace the `[Research overview and methodology will be appended here]` placeholder in the Research Overview section at the top of the document.
 
 ## SUCCESS METRICS:
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02-discovery.md

@@ -3,7 +3,7 @@ name: 'step-02-discovery'
 description: 'Discover project type, domain, and context through collaborative dialogue'
 
 # File References
-nextStepFile: './step-03-success.md'
+nextStepFile: './step-02b-vision.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Data Files

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02b-vision.md

@@ -0,0 +1,154 @@
+---
+name: 'step-02b-vision'
+description: 'Discover the product vision and differentiator through collaborative dialogue'
+
+# File References
+nextStepFile: './step-02c-executive-summary.md'
+outputFile: '{planning_artifacts}/prd.md'
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+
+# Step 2b: Product Vision Discovery
+
+**Progress: Step 2b of 13** - Next: Executive Summary
+
+## STEP GOAL:
+
+Discover what makes this product special and understand the product vision through collaborative conversation. No content generation — facilitation only.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused PM facilitator collaborating with an expert peer
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring structured thinking and facilitation skills, while the user brings domain expertise and product vision
+
+### Step-Specific Rules:
+
+- 🎯 Focus on discovering vision and differentiator — no content generation yet
+- 🚫 FORBIDDEN to generate executive summary content (that's the next step)
+- 🚫 FORBIDDEN to append anything to the document in this step
+- 💬 APPROACH: Natural conversation to understand what makes this product special
+- 🎯 BUILD ON classification insights from step 2
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after vision discovery is complete
+- 📖 Update frontmatter, adding this step to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from steps 1 and 2 are available
+- Project classification exists from step 2 (project type, domain, complexity, context)
+- Input documents already loaded are in memory (product briefs, research, brainstorming, project docs)
+- No executive summary content yet (that's step 2c)
+- This step ONLY discovers — it does NOT write to the document
+
+## YOUR TASK:
+
+Discover the product vision and differentiator through natural conversation. Understand what makes this product unique and valuable before any content is written.
+
+## VISION DISCOVERY SEQUENCE:
+
+### 1. Acknowledge Classification Context
+
+Reference the classification from step 2 and use it to frame the vision conversation:
+
+"We've established this is a {{projectType}} in the {{domain}} domain with {{complexityLevel}} complexity. Now let's explore what makes this product special."
+
+### 2. Explore What Makes It Special
+
+Guide the conversation to uncover the product's unique value:
+
+- **User delight:** "What would make users say 'this is exactly what I needed'?"
+- **Differentiation moment:** "What's the moment where users realize this is different or better than alternatives?"
+- **Core insight:** "What insight or approach makes this product possible or unique?"
+- **Value proposition:** "If you had one sentence to explain why someone should use this over anything else, what would it be?"
+
+### 3. Understand the Vision
+
+Dig deeper into the product vision:
+
+- **Problem framing:** "What's the real problem you're solving — not the surface symptom, but the deeper need?"
+- **Future state:** "When this product is successful, what does the world look like for your users?"
+- **Why now:** "Why is this the right time to build this?"
+
+### 4. Validate Understanding
+
+Reflect back what you've heard and confirm:
+
+"Here's what I'm hearing about your vision and differentiator:
+
+**Vision:** {{summarized_vision}}
+**What Makes It Special:** {{summarized_differentiator}}
+**Core Insight:** {{summarized_insight}}
+
+Does this capture it? Anything I'm missing?"
+
+Let the user confirm or refine your understanding.
+
+### N. Present MENU OPTIONS
+
+Present your understanding of the product vision for review, then display menu:
+
+"Based on our conversation, I have a clear picture of your product vision and what makes it special. I'll use these insights to draft the Executive Summary in the next step.
+
+**What would you like to do?**"
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Executive Summary (Step 2c of 13)"
+
+#### Menu Handling Logic:
+- IF A: Read fully and follow: {advancedElicitationTask} with the current vision insights, process the enhanced insights that come back, ask user if they accept the improvements, if yes update understanding then redisplay menu, if no keep original understanding then redisplay menu
+- IF P: Read fully and follow: {partyModeWorkflow} with the current vision insights, process the collaborative insights, ask user if they accept the changes, if yes update understanding then redisplay menu, if no keep original understanding then redisplay menu
+- IF C: Update {outputFile} frontmatter by adding this step name to the end of stepsCompleted array, then read fully and follow: {nextStepFile}
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [stepsCompleted updated], will you then read fully and follow: `{nextStepFile}` to generate the Executive Summary.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Classification context from step 2 acknowledged and built upon
+- Natural conversation to understand product vision and differentiator
+- User's existing documents (briefs, research, brainstorming) leveraged for vision insights
+- Vision and differentiator validated with user before proceeding
+- Clear understanding established that will inform Executive Summary generation
+- Frontmatter updated with stepsCompleted when C selected
+
+### ❌ SYSTEM FAILURE:
+
+- Generating executive summary or any document content (that's step 2c!)
+- Appending anything to the PRD document
+- Not building on classification from step 2
+- Being prescriptive instead of having natural conversation
+- Proceeding without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+
+**Master Rule:** This step is vision discovery only. No content generation, no document writing. Have natural conversations, build on what you know from classification, and establish the vision that will feed into the Executive Summary.

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02c-executive-summary.md

@@ -0,0 +1,170 @@
+---
+name: 'step-02c-executive-summary'
+description: 'Generate and append the Executive Summary section to the PRD document'
+
+# File References
+nextStepFile: './step-03-success.md'
+outputFile: '{planning_artifacts}/prd.md'
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+
+# Step 2c: Executive Summary Generation
+
+**Progress: Step 2c of 13** - Next: Success Criteria
+
+## STEP GOAL:
+
+Generate the Executive Summary content using insights from classification (step 2) and vision discovery (step 2b), then append it to the PRD document.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused PM facilitator collaborating with an expert peer
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ Content is drafted collaboratively — present for review before saving
+
+### Step-Specific Rules:
+
+- 🎯 Generate Executive Summary content based on discovered insights
+- 💬 Present draft content for user review and refinement before appending
+- 🚫 FORBIDDEN to append content without user approval via 'C'
+- 🎯 Content must be dense, precise, and zero-fluff (PRD quality standards)
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating executive summary content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step name to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from steps 1, 2, and 2b are available
+- Project classification exists from step 2 (project type, domain, complexity, context)
+- Vision and differentiator insights exist from step 2b
+- Input documents from step 1 are available (product briefs, research, brainstorming, project docs)
+- This step generates and appends the first substantive content to the PRD
+
+## YOUR TASK:
+
+Draft the Executive Summary section using all discovered insights, present it for user review, and append it to the PRD document when approved.
+
+## EXECUTIVE SUMMARY GENERATION SEQUENCE:
+
+### 1. Synthesize Available Context
+
+Review all available context before drafting:
+- Classification from step 2: project type, domain, complexity, project context
+- Vision and differentiator from step 2b: what makes this special, core insight
+- Input documents: product briefs, research, brainstorming, project docs
+
+### 2. Draft Executive Summary Content
+
+Generate the Executive Summary section using the content structure below. Apply PRD quality standards:
+- High information density — every sentence carries weight
+- Zero fluff — no filler phrases or vague language
+- Precise and actionable — clear, specific statements
+- Dual-audience optimized — readable by humans, consumable by LLMs
+
+### 3. Present Draft for Review
+
+Present the drafted content to the user for review:
+
+"Here's the Executive Summary I've drafted based on our discovery work. Please review and let me know if you'd like any changes:"
+
+Show the full drafted content using the structure from the Content Structure section below.
+
+Allow the user to:
+- Request specific changes to any section
+- Add missing information
+- Refine the language or emphasis
+- Approve as-is
+
+### N. Present MENU OPTIONS
+
+Present the executive summary content for user review, then display menu:
+
+"Here's the Executive Summary for your PRD. Review the content above and let me know what you'd like to do."
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Success Criteria (Step 3 of 13)"
+
+#### Menu Handling Logic:
+- IF A: Read fully and follow: {advancedElicitationTask} with the current executive summary content, process the enhanced content that comes back, ask user if they accept the improvements, if yes update content then redisplay menu, if no keep original content then redisplay menu
+- IF P: Read fully and follow: {partyModeWorkflow} with the current executive summary content, process the collaborative improvements, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu
+- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: {nextStepFile}
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the following content structure directly to the document:
+
+```markdown
+## Executive Summary
+
+{vision_alignment_content}
+
+### What Makes This Special
+
+{product_differentiator_content}
+
+## Project Classification
+
+{project_classification_content}
+```
+
+Where:
+- `{vision_alignment_content}` — Product vision, target users, and the problem being solved. Dense, precise summary drawn from step 2b vision discovery.
+- `{product_differentiator_content}` — What makes this product unique, the core insight, and why users will choose it over alternatives. Drawn from step 2b differentiator discovery.
+- `{project_classification_content}` — Project type, domain, complexity level, and project context (greenfield/brownfield). Drawn from step 2 classification.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [content appended to document], will you then read fully and follow: `{nextStepFile}` to define success criteria.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Executive Summary drafted using insights from steps 2 and 2b
+- Content meets PRD quality standards (dense, precise, zero-fluff)
+- Draft presented to user for review before saving
+- User given opportunity to refine content
+- Content properly appended to document when C selected
+- A/P/C menu presented and handled correctly
+- Frontmatter updated with stepsCompleted when C selected
+
+### ❌ SYSTEM FAILURE:
+
+- Generating content without incorporating discovered vision and classification
+- Appending content without user selecting 'C'
+- Producing vague, fluffy, or low-density content
+- Not presenting draft for user review
+- Not presenting A/P/C menu after content generation
+- Skipping directly to next step without appending content
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+**Master Rule:** Generate high-quality Executive Summary content from discovered insights. Present for review, refine collaboratively, and only save when the user approves. This is the first substantive content in the PRD — it sets the quality bar for everything that follows.

src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md

@@ -70,14 +70,22 @@ This file contains the BMAD PRD philosophy, standards, and validation criteria t
 **If PRD path provided as invocation parameter:**
 - Use provided path
 
-**If no PRD path provided:**
-"**PRD Validation Workflow**
+**If no PRD path provided, auto-discover:**
+- Search `{planning_artifacts}` for files matching `*prd*.md`
+- Also check for sharded PRDs: `{planning_artifacts}/*prd*/*.md`
 
-Which PRD would you like to validate?
+**If exactly ONE PRD found:**
+- Use it automatically
+- Inform user: "Found PRD: {discovered_path} — using it for validation."
 
-Please provide the path to the PRD file you want to validate."
+**If MULTIPLE PRDs found:**
+- List all discovered PRDs with numbered options
+- "I found multiple PRDs. Which one would you like to validate?"
+- Wait for user selection
 
-**Wait for user to provide PRD path.**
+**If NO PRDs found:**
+- "I couldn't find any PRD files in {planning_artifacts}. Please provide the path to the PRD file you want to validate."
+- Wait for user to provide PRD path.
 
 ### 3. Validate PRD Exists and Load
 

src/bmm/workflows/2-plan-workflows/create-prd/workflow-validate-prd.md

@@ -60,6 +60,4 @@ Load and read full config from {main_config} and resolve:
 
 "**Validate Mode: Validating an existing PRD against BMAD standards.**"
 
-Prompt for PRD path: "Which PRD would you like to validate? Please provide the path to the PRD.md file."
-
 Then read fully and follow: `{validateWorkflow}` (steps-v/step-v-01-discovery.md)

src/bmm/workflows/4-implementation/code-review/workflow.yaml

@@ -12,7 +12,6 @@ document_output_language: "{config_source}:document_output_language"
 date: system-generated
 planning_artifacts: "{config_source}:planning_artifacts"
 implementation_artifacts: "{config_source}:implementation_artifacts"
-output_folder: "{implementation_artifacts}"
 sprint_status: "{implementation_artifacts}/sprint-status.yaml"
 
 # Workflow components
@@ -21,10 +20,7 @@ instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
 template: false
 
-variables:
-  # Project context
 project_context: "**/project-context.md"
-  story_dir: "{implementation_artifacts}"
 
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version

src/bmm/workflows/4-implementation/correct-course/instructions.md

@@ -10,6 +10,7 @@
 <workflow>
 
 <step n="1" goal="Initialize Change Navigation">
+  <action>Load {project_context} for coding standards and project-wide patterns (if exists)</action>
   <action>Confirm change trigger and gather user description of the issue</action>
   <action>Ask: "What specific issue or change has been identified that requires navigation?"</action>
   <action>Verify access to required project documents:</action>

src/bmm/workflows/4-implementation/correct-course/workflow.yaml

@@ -12,8 +12,7 @@ date: system-generated
 implementation_artifacts: "{config_source}:implementation_artifacts"
 planning_artifacts: "{config_source}:planning_artifacts"
 project_knowledge: "{config_source}:project_knowledge"
-output_folder: "{implementation_artifacts}"
-sprint_status: "{implementation_artifacts}/sprint-status.yaml"
+project_context: "**/project-context.md"
 
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version
@@ -51,6 +50,5 @@ input_file_patterns:
 installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course"
 template: false
 instructions: "{installed_path}/instructions.md"
-validation: "{installed_path}/checklist.md"
 checklist: "{installed_path}/checklist.md"
 default_output_file: "{planning_artifacts}/sprint-change-proposal-{date}.md"

src/bmm/workflows/4-implementation/create-story/checklist.md

@@ -49,7 +49,7 @@ This is a COMPETITION to create the **ULTIMATE story context** that makes LLM de
 ### **Required Inputs:**
 
 - **Story file**: The story file to review and improve
-- **Workflow variables**: From workflow.yaml (story_dir, output_folder, epics_file, etc.)
+- **Workflow variables**: From workflow.yaml (implementation_artifacts, epics_file, etc.)
 - **Source documents**: Epics, architecture, etc. (discovered or provided)
 - **Validation framework**: `validate-workflow.xml` (handles checklist execution)
 
@@ -65,7 +65,7 @@ You will systematically re-do the entire story creation process, but with a crit
 2. **Load the story file**: `{story_file_path}` (provided by user or discovered)
 3. **Load validation framework**: `{project-root}/_bmad/core/tasks/validate-workflow.xml`
 4. **Extract metadata**: epic_num, story_num, story_key, story_title from story file
-5. **Resolve all workflow variables**: story_dir, output_folder, epics_file, architecture_file, etc.
+5. **Resolve all workflow variables**: implementation_artifacts, epics_file, architecture_file, etc.
 6. **Understand current status**: What story implementation guidance is currently provided?
 
 **Note:** If running in fresh context, user should provide the story file path being reviewed. If running from create-story workflow, the validation framework will automatically discover the checklist and story file.

src/bmm/workflows/4-implementation/create-story/instructions.xml

@@ -192,7 +192,8 @@
     (As a, I want, so that) - Detailed acceptance criteria (already BDD formatted) - Technical requirements specific to this story -
     Business context and value - Success criteria <!-- Previous story analysis for context continuity -->
     <check if="story_num > 1">
-      <action>Load previous story file: {{story_dir}}/{{epic_num}}-{{previous_story_num}}-*.md</action> **PREVIOUS STORY INTELLIGENCE:** -
+      <action>Find {{previous_story_num}}: scan {implementation_artifacts} for the story file in epic {{epic_num}} with the highest story number less than {{story_num}}</action>
+      <action>Load previous story file: {implementation_artifacts}/{{epic_num}}-{{previous_story_num}}-*.md</action> **PREVIOUS STORY INTELLIGENCE:** -
     Dev notes and learnings from previous story - Review feedback and corrections needed - Files that were created/modified and their
     patterns - Testing approaches that worked/didn't work - Problems encountered and solutions found - Code patterns established <action>Extract
     all learnings that could impact current story implementation</action>

src/bmm/workflows/4-implementation/create-story/workflow.yaml

@@ -6,11 +6,11 @@ author: "BMad"
 config_source: "{project-root}/_bmad/bmm/config.yaml"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 planning_artifacts: "{config_source}:planning_artifacts"
 implementation_artifacts: "{config_source}:implementation_artifacts"
-output_folder: "{implementation_artifacts}"
-story_dir: "{implementation_artifacts}"
 
 # Workflow components
 installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story"
@@ -19,18 +19,14 @@ instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
 
 # Variables and inputs
-variables:
 sprint_status: "{implementation_artifacts}/sprint-status.yaml" # Primary source for story tracking
 epics_file: "{planning_artifacts}/epics.md" # Enhanced epics+stories with BDD and source hints
 prd_file: "{planning_artifacts}/prd.md" # Fallback for requirements (if not in epics file)
 architecture_file: "{planning_artifacts}/architecture.md" # Fallback for constraints (if not in epics file)
 ux_file: "{planning_artifacts}/*ux*.md" # Fallback for UX requirements (if not in epics file)
 story_title: "" # Will be elicited if not derivable
-
-# Project context
 project_context: "**/project-context.md"
-
-default_output_file: "{story_dir}/{{story_key}}.md"
+default_output_file: "{implementation_artifacts}/{{story_key}}.md"
 
 # Smart input file references - Simplified for enhanced approach
 # The epics+stories file should contain everything needed with source hints

src/bmm/workflows/4-implementation/dev-story/instructions.xml

@@ -78,7 +78,7 @@
 
     <!-- Non-sprint story discovery -->
     <check if="{{sprint_status}} file does NOT exist">
-      <action>Search {story_dir} for stories directly</action>
+      <action>Search {implementation_artifacts} for stories directly</action>
       <action>Find stories with "ready-for-dev" status in files</action>
       <action>Look for story files matching pattern: *-*-*.md</action>
       <action>Read each candidate story file to check Status section</action>
@@ -114,7 +114,7 @@
     </check>
 
     <action>Store the found story_key (e.g., "1-2-user-authentication") for later status updates</action>
-    <action>Find matching story file in {story_dir} using story_key pattern: {{story_key}}.md</action>
+    <action>Find matching story file in {implementation_artifacts} using story_key pattern: {{story_key}}.md</action>
     <action>Read COMPLETE story file from discovered path</action>
 
     <anchor id="task_check" />

src/bmm/workflows/4-implementation/dev-story/workflow.yaml

@@ -4,12 +4,10 @@ author: "BMad"
 
 # Critical variables from config
 config_source: "{project-root}/_bmad/bmm/config.yaml"
-output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 user_skill_level: "{config_source}:user_skill_level"
 document_output_language: "{config_source}:document_output_language"
-story_dir: "{config_source}:implementation_artifacts"
 date: system-generated
 
 # Workflow components

src/bmm/workflows/4-implementation/retrospective/instructions.md

@@ -31,6 +31,7 @@ PARTY MODE PROTOCOL:
 
 <step n="1" goal="Epic Discovery - Find Completed Epic with Priority Logic">
 
+<action>Load {project_context} for project-wide patterns and conventions (if exists)</action>
 <action>Explain to {user_name} the epic discovery process using natural dialogue</action>
 
 <output>
@@ -80,7 +81,7 @@ Bob (Scrum Master): "I'm having trouble detecting the completed epic from {sprin
 <check if="{{epic_number}} still not determined">
   <action>PRIORITY 3: Fallback to stories folder</action>
 
-<action>Scan {story_directory} for highest numbered story files</action>
+<action>Scan {implementation_artifacts} for highest numbered story files</action>
 <action>Extract epic numbers from story filenames (pattern: epic-X-Y-story-name.md)</action>
 <action>Set {{detected_epic}} = highest epic number found</action>
 
@@ -170,7 +171,7 @@ Bob (Scrum Master): "Before we start the team discussion, let me review all the
 Charlie (Senior Dev): "Good idea - those dev notes always have gold in them."
 </output>
 
-<action>For each story in epic {{epic_number}}, read the complete story file from {story_directory}/{{epic_number}}-{{story_num}}-\*.md</action>
+<action>For each story in epic {{epic_number}}, read the complete story file from {implementation_artifacts}/{{epic_number}}-{{story_num}}-*.md</action>
 
 <action>Extract and analyze from each story:</action>
 
@@ -261,14 +262,14 @@ Bob (Scrum Master): "We'll get to all of it. But first, let me load the previous
 <action>Calculate previous epic number: {{prev_epic_num}} = {{epic_number}} - 1</action>
 
 <check if="{{prev_epic_num}} >= 1">
-  <action>Search for previous retrospective using pattern: {retrospectives_folder}/epic-{{prev_epic_num}}-retro-*.md</action>
+  <action>Search for previous retrospectives using pattern: {implementation_artifacts}/epic-{{prev_epic_num}}-retro-*.md</action>
 
-  <check if="previous retro found">
+  <check if="previous retrospectives found">
     <output>
-Bob (Scrum Master): "I found our retrospective from Epic {{prev_epic_num}}. Let me see what we committed to back then..."
+Bob (Scrum Master): "I found our retrospectives from Epic {{prev_epic_num}}. Let me see what we committed to back then..."
     </output>
 
-    <action>Read the complete previous retrospective file</action>
+    <action>Read the previous retrospectives</action>
 
     <action>Extract key elements:</action>
     - **Action items committed**: What did the team agree to improve?
@@ -365,7 +366,7 @@ Alice (Product Owner): "Good thinking - helps us connect what we learned to what
 <action>Attempt to load next epic using selective loading strategy:</action>
 
 **Try sharded first (more specific):**
-<action>Check if file exists: {planning_artifacts}/epic\*/epic-{{next_epic_num}}.md</action>
+<action>Check if file exists: {planning_artifacts}/epic*/epic-{{next_epic_num}}.md</action>
 
 <check if="sharded epic file found">
   <action>Load {planning_artifacts}/*epic*/epic-{{next_epic_num}}.md</action>
@@ -374,7 +375,7 @@ Alice (Product Owner): "Good thinking - helps us connect what we learned to what
 
 **Fallback to whole document:**
 <check if="sharded epic not found">
-<action>Check if file exists: {planning_artifacts}/epic\*.md</action>
+<action>Check if file exists: {planning_artifacts}/epic*.md</action>
 
   <check if="whole epic file found">
     <action>Load entire epics document</action>
@@ -1302,7 +1303,7 @@ Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!"
 
 <step n="11" goal="Save Retrospective and Update Sprint Status">
 
-<action>Ensure retrospectives folder exists: {retrospectives_folder}</action>
+<action>Ensure retrospectives folder exists: {implementation_artifacts}</action>
 <action>Create folder if it doesn't exist</action>
 
 <action>Generate comprehensive retrospective summary document including:</action>
@@ -1322,11 +1323,11 @@ Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!"
 - Commitments and next steps
 
 <action>Format retrospective document as readable markdown with clear sections</action>
-<action>Set filename: {retrospectives_folder}/epic-{{epic_number}}-retro-{date}.md</action>
+<action>Set filename: {implementation_artifacts}/epic-{{epic_number}}-retro-{date}.md</action>
 <action>Save retrospective document</action>
 
 <output>
-✅ Retrospective document saved: {retrospectives_folder}/epic-{{epic_number}}-retro-{date}.md
+✅ Retrospective document saved: {implementation_artifacts}/epic-{{epic_number}}-retro-{date}.md
 </output>
 
 <action>Update {sprint_status_file} to mark retrospective as completed</action>
@@ -1365,7 +1366,7 @@ Retrospective document was saved successfully, but {sprint_status_file} may need
 
 - Epic {{epic_number}}: {{epic_title}} reviewed
 - Retrospective Status: completed
-- Retrospective saved: {retrospectives_folder}/epic-{{epic_number}}-retro-{date}.md
+- Retrospective saved: {implementation_artifacts}/epic-{{epic_number}}-retro-{date}.md
 
 **Commitments Made:**
 
@@ -1375,7 +1376,7 @@ Retrospective document was saved successfully, but {sprint_status_file} may need
 
 **Next Steps:**
 
-1. **Review retrospective summary**: {retrospectives_folder}/epic-{{epic_number}}-retro-{date}.md
+1. **Review retrospective summary**: {implementation_artifacts}/epic-{{epic_number}}-retro-{date}.md
 
 2. **Execute preparation sprint** (Est: {{prep_days}} days)
    - Complete {{critical_count}} critical path items

src/bmm/workflows/4-implementation/retrospective/workflow.yaml

@@ -4,7 +4,6 @@ description: "Run after epic completion to review overall success, extract lesso
 author: "BMad"
 
 config_source: "{project-root}/_bmad/bmm/config.yaml"
-output_folder: "{config_source}:implementation_artifacts}"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 user_skill_level: "{config_source}:user_skill_level"
@@ -12,6 +11,7 @@ document_output_language: "{config_source}:document_output_language"
 date: system-generated
 planning_artifacts: "{config_source}:planning_artifacts"
 implementation_artifacts: "{config_source}:implementation_artifacts"
+project_context: "**/project-context.md"
 
 installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/retrospective"
 template: false
@@ -51,5 +51,3 @@ input_file_patterns:
 
 # Required files
 sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
-story_directory: "{implementation_artifacts}"
-retrospectives_folder: "{implementation_artifacts}"

src/bmm/workflows/4-implementation/sprint-planning/instructions.md

@@ -23,6 +23,7 @@
 <workflow>
 
 <step n="1" goal="Parse epic files and extract all work items">
+<action>Load {project_context} for project-wide patterns and conventions (if exists)</action>
 <action>Communicate in {communication_language} with {user_name}</action>
 <action>Look for all files matching `{epics_pattern}` in {epics_location}</action>
 <action>Could be a single `epics.md` file or multiple `epic-1.md`, `epic-2.md` files</action>

src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml

@@ -9,7 +9,6 @@ communication_language: "{config_source}:communication_language"
 date: system-generated
 implementation_artifacts: "{config_source}:implementation_artifacts"
 planning_artifacts: "{config_source}:planning_artifacts"
-output_folder: "{implementation_artifacts}"
 
 # Workflow components
 installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning"
@@ -18,17 +17,14 @@ template: "{installed_path}/sprint-status-template.yaml"
 validation: "{installed_path}/checklist.md"
 
 # Variables and inputs
-variables:
-  # Project context
 project_context: "**/project-context.md"
-  # Project identification
 project_name: "{config_source}:project_name"
 
 # Tracking system configuration
 tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello
 project_key: "NOKEY" # Placeholder for tracker integrations; file-system uses a no-op key
-  story_location: "{config_source}:implementation_artifacts" # Relative path for file-system, Future will support URL for Jira/Linear/Trello
-  story_location_absolute: "{config_source}:implementation_artifacts" # Absolute path for file operations
+story_location: "{implementation_artifacts}" # Relative path for file-system, Future will support URL for Jira/Linear/Trello
+story_location_absolute: "{implementation_artifacts}" # Absolute path for file operations
 
 # Source files (file-system only)
 epics_location: "{planning_artifacts}" # Directory containing epic*.md files
@@ -43,8 +39,8 @@ variables:
 input_file_patterns:
   epics:
     description: "All epics with user stories"
-    whole: "{output_folder}/*epic*.md"
-    sharded: "{output_folder}/*epic*/*.md"
+    whole: "{planning_artifacts}/*epic*.md"
+    sharded: "{planning_artifacts}/*epic*/*.md"
     load_strategy: "FULL_LOAD"
 
 # Output configuration

src/bmm/workflows/4-implementation/sprint-status/instructions.md

@@ -24,6 +24,7 @@
 </step>
 
 <step n="1" goal="Locate sprint status file">
+  <action>Load {project_context} for project-wide patterns and conventions (if exists)</action>
   <action>Try {sprint_status_file}</action>
   <check if="file not found">
     <output>❌ sprint-status.yaml not found.

src/bmm/workflows/4-implementation/sprint-status/workflow.yaml

@@ -5,22 +5,17 @@ author: "BMad"
 
 # Critical variables from config
 config_source: "{project-root}/_bmad/bmm/config.yaml"
-output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 document_output_language: "{config_source}:document_output_language"
-date: system-generated
 implementation_artifacts: "{config_source}:implementation_artifacts"
-planning_artifacts: "{config_source}:planning_artifacts"
 
 # Workflow components
 installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-status"
 instructions: "{installed_path}/instructions.md"
 
 # Inputs
-variables:
 sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
-  tracking_system: "file-system"
 
 # Smart input file references
 input_file_patterns:

src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md

@@ -28,7 +28,7 @@ This uses **step-file architecture** for focused execution:
 Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
 - `user_name`, `communication_language`, `user_skill_level`
-- `output_folder`, `planning_artifacts`,  `implementation_artifacts`
+- `planning_artifacts`, `implementation_artifacts`
 - `date` as system-generated current datetime
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
 

src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md

@@ -76,7 +76,7 @@ a) **Before asking detailed questions, do a rapid scan to understand the landsca
 
 b) **Check for existing context docs:**
 
-- Check `{output_folder}` and `{planning_artifacts}`for planning documents (PRD, architecture, epics, research)
+- Check `{implementation_artifacts}` and `{planning_artifacts}`for planning documents (PRD, architecture, epics, research)
 - Check for `**/project-context.md` - if it exists, skim for patterns and conventions
 - Check for any existing stories or specs related to user's request
 

src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md

@@ -68,9 +68,10 @@ This uses **step-file architecture** for disciplined execution:
 
 Load and read full config from `{main_config}` and resolve:
 
-- `project_name`, `output_folder`, `planning_artifacts`, `implementation_artifacts`, `user_name`
+- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
 - `communication_language`, `document_output_language`, `user_skill_level`
 - `date` as system-generated current datetime
+- `project_context` = `**/project-context.md` (load if exists)
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
 
 ### 2. First Step Execution

src/bmm/workflows/document-project/instructions.md

@@ -8,56 +8,8 @@
 
 <critical>This router determines workflow mode and delegates to specialized sub-workflows</critical>
 
-<step n="1" goal="Validate workflow and get project info">
-
-<invoke-workflow path="{project-root}/_bmad/bmm/workflows/workflow-status">
-  <param>mode: data</param>
-  <param>data_request: project_config</param>
-</invoke-workflow>
-
-<check if="status_exists == false">
-  <output>{{suggestion}}</output>
-  <output>Note: Documentation workflow can run standalone. Continuing without progress tracking.</output>
-  <action>Set standalone_mode = true</action>
-  <action>Set status_file_found = false</action>
-</check>
-
-<check if="status_exists == true">
-  <action>Store {{status_file_path}} for later updates</action>
-  <action>Set status_file_found = true</action>
-
-  <!-- Extract brownfield/greenfield from status data -->
-  <check if="field_type == 'greenfield'">
-    <output>Note: This is a greenfield project. Documentation workflow is typically for brownfield projects.</output>
-    <ask>Continue anyway to document planning artifacts? (y/n)</ask>
-    <check if="n">
-      <action>Exit workflow</action>
-    </check>
-  </check>
-
-  <!-- Now validate sequencing -->
-  <invoke-workflow path="{project-root}/_bmad/bmm/workflows/workflow-status">
-    <param>mode: validate</param>
-    <param>calling_workflow: document-project</param>
-  </invoke-workflow>
-
-  <check if="warning != ''">
-    <output>{{warning}}</output>
-    <output>Note: This may be auto-invoked by prd for brownfield documentation.</output>
-    <ask>Continue with documentation? (y/n)</ask>
-    <check if="n">
-      <output>{{suggestion}}</output>
-      <action>Exit workflow</action>
-    </check>
-  </check>
-</check>
-
-</step>
-
-<step n="2" goal="Check for resumability and determine workflow mode">
-<critical>SMART LOADING STRATEGY: Check state file FIRST before loading any CSV files</critical>
-
-<action>Check for existing state file at: {output_folder}/project-scan-report.json</action>
+<step n="1" goal="Check for ability to resume and determine workflow mode">
+<action>Check for existing state file at: {project_knowledge}/project-scan-report.json</action>
 
 <check if="project-scan-report.json exists">
   <action>Read state file and extract: timestamps, mode, scan_level, current_step, completed_steps, project_classification</action>
@@ -107,8 +59,8 @@ Your choice [1/2/3]:
   </check>
 
   <check if="user selects 2">
-    <action>Create archive directory: {output_folder}/.archive/</action>
-    <action>Move old state file to: {output_folder}/.archive/project-scan-report-{{timestamp}}.json</action>
+    <action>Create archive directory: {project_knowledge}/.archive/</action>
+    <action>Move old state file to: {project_knowledge}/.archive/project-scan-report-{{timestamp}}.json</action>
     <action>Set resume_mode = false</action>
     <action>Continue to Step 0.5</action>
   </check>
@@ -120,7 +72,7 @@ Your choice [1/2/3]:
 
   <check if="state file age >= 24 hours">
     <action>Display: "Found old state file (>24 hours). Starting fresh scan."</action>
-    <action>Archive old state file to: {output_folder}/.archive/project-scan-report-{{timestamp}}.json</action>
+    <action>Archive old state file to: {project_knowledge}/.archive/project-scan-report-{{timestamp}}.json</action>
     <action>Set resume_mode = false</action>
     <action>Continue to Step 0.5</action>
   </check>
@@ -128,7 +80,7 @@ Your choice [1/2/3]:
 </step>
 
 <step n="3" goal="Check for existing documentation and determine workflow mode" if="resume_mode == false">
-<action>Check if {output_folder}/index.md exists</action>
+<action>Check if {project_knowledge}/index.md exists</action>
 
 <check if="index.md exists">
   <action>Read existing index.md to extract metadata (date, project structure, parts count)</action>
@@ -175,47 +127,4 @@ Your choice [1/2/3]:
 
 </step>
 
-<step n="4" goal="Update status and complete">
-
-<check if="status_file_found == true">
-  <invoke-workflow path="{project-root}/_bmad/bmm/workflows/workflow-status">
-    <param>mode: update</param>
-    <param>action: complete_workflow</param>
-    <param>workflow_name: document-project</param>
-  </invoke-workflow>
-
-  <check if="success == true">
-    <output>Status updated!</output>
-  </check>
-</check>
-
-<output>**✅ Document Project Workflow Complete, {user_name}!**
-
-**Documentation Generated:**
-
-- Mode: {{workflow_mode}}
-- Scan Level: {{scan_level}}
-- Output: {output_folder}/index.md and related files
-
-{{#if status_file_found}}
-**Status Updated:**
-
-- Progress tracking updated
-
-**Next Steps:**
-
-- **Next required:** {{next_workflow}} ({{next_agent}} agent)
-
-Check status anytime with: `workflow-status`
-{{else}}
-**Next Steps:**
-Since no workflow is in progress:
-
-- Refer to the BMM workflow guide if unsure what to do next
-- Or run `workflow-init` to create a workflow path and get guided next steps
-  {{/if}}
-  </output>
-
-</step>
-
 </workflow>

src/bmm/workflows/document-project/templates/project-scan-report-schema.json

@@ -45,9 +45,9 @@
       "type": "string",
       "description": "Absolute path to project root directory"
     },
-    "output_folder": {
+    "project_knowledge": {
       "type": "string",
-      "description": "Absolute path to output folder"
+      "description": "Absolute path to project knowledge folder"
     },
     "completed_steps": {
       "type": "array",

src/bmm/workflows/document-project/workflow.yaml

@@ -6,7 +6,7 @@ author: "BMad"
 
 # Critical variables
 config_source: "{project-root}/_bmad/bmm/config.yaml"
-output_folder: "{config_source}:project_knowledge"
+project_knowledge: "{config_source}:project_knowledge"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 document_output_language: "{config_source}:document_output_language"

src/bmm/workflows/document-project/workflows/deep-dive-instructions.md

@@ -194,7 +194,7 @@ This will read EVERY file in this area. Proceed? [y/n]
 
 <action>Load complete deep-dive template from: {installed_path}/templates/deep-dive-template.md</action>
 <action>Fill template with all collected data from steps 13b-13d</action>
-<action>Write filled template to: {output_folder}/deep-dive-{{sanitized_target_name}}.md</action>
+<action>Write filled template to: {project_knowledge}/deep-dive-{{sanitized_target_name}}.md</action>
 <action>Validate deep-dive document completeness</action>
 
 <template-output>deep_dive_documentation</template-output>
@@ -241,7 +241,7 @@ Detailed exhaustive analysis of specific areas:
 
 ## Deep-Dive Documentation Complete! ✓
 
-**Generated:** {output_folder}/deep-dive-{{target_name}}.md
+**Generated:** {project_knowledge}/deep-dive-{{target_name}}.md
 **Files Analyzed:** {{file_count}}
 **Lines of Code Scanned:** {{total_loc}}
 **Time Taken:** ~{{duration}}
@@ -255,7 +255,7 @@ Detailed exhaustive analysis of specific areas:
 - Related code and reuse opportunities
 - Implementation guidance
 
-**Index Updated:** {output_folder}/index.md now includes link to this deep-dive
+**Index Updated:** {project_knowledge}/index.md now includes link to this deep-dive
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 </action>
@@ -278,7 +278,7 @@ Your choice [1/2]:
 
 All deep-dive documentation complete!
 
-**Master Index:** {output_folder}/index.md
+**Master Index:** {project_knowledge}/index.md
 **Deep-Dives Generated:** {{deep_dive_count}}
 
 These comprehensive docs are now ready for:

src/bmm/workflows/document-project/workflows/deep-dive.yaml

@@ -8,7 +8,7 @@ parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.y
 
 # Critical variables inherited from parent
 config_source: "{project-root}/_bmad/bmb/config.yaml"
-output_folder: "{config_source}:output_folder"
+project_knowledge: "{config_source}:project_knowledge"
 user_name: "{config_source}:user_name"
 date: system-generated
 

src/bmm/workflows/document-project/workflows/full-scan-instructions.md

@@ -43,7 +43,7 @@ This workflow uses a single comprehensive CSV file to intelligently document you
 </step>
 
 <step n="0.6" goal="Check for existing documentation and determine workflow mode">
-<action>Check if {output_folder}/index.md exists</action>
+<action>Check if {project_knowledge}/index.md exists</action>
 
 <check if="index.md exists">
   <action>Read existing index.md to extract metadata (date, project structure, parts count)</action>
@@ -127,7 +127,7 @@ Your choice [1/2/3] (default: 1):
     <action>Display: "Using Exhaustive Scan (reading all source files)"</action>
   </action>
 
-<action>Initialize state file: {output_folder}/project-scan-report.json</action>
+<action>Initialize state file: {project_knowledge}/project-scan-report.json</action>
 <critical>Every time you touch the state file, record: step id, human-readable summary (what you actually did), precise timestamp, and any outputs written. Vague phrases are unacceptable.</critical>
 <action>Write initial state:
 {
@@ -136,7 +136,7 @@ Your choice [1/2/3] (default: 1):
 "mode": "{{workflow_mode}}",
 "scan_level": "{{scan_level}}",
 "project_root": "{{project_root_path}}",
-"output_folder": "{{output_folder}}",
+"project_knowledge": "{{project_knowledge}}",
 "completed_steps": [],
 "current_step": "step_1",
 "findings": {},
@@ -325,7 +325,7 @@ findings.batches_completed: [
   </check>
 
 <action>Build API contracts catalog</action>
-<action>IMMEDIATELY write to: {output_folder}/api-contracts-{part_id}.md</action>
+<action>IMMEDIATELY write to: {project_knowledge}/api-contracts-{part_id}.md</action>
 <action>Validate document has all required sections</action>
 <action>Update state file with output generated</action>
 <action>PURGE detailed API data, keep only: "{{api_count}} endpoints documented"</action>
@@ -346,7 +346,7 @@ findings.batches_completed: [
   </check>
 
 <action>Build database schema documentation</action>
-<action>IMMEDIATELY write to: {output_folder}/data-models-{part_id}.md</action>
+<action>IMMEDIATELY write to: {project_knowledge}/data-models-{part_id}.md</action>
 <action>Validate document completeness</action>
 <action>Update state file with output generated</action>
 <action>PURGE detailed schema data, keep only: "{{table_count}} tables documented"</action>
@@ -805,7 +805,7 @@ When a document SHOULD be generated but wasn't (due to quick scan, missing data,
 
 <step n="11" goal="Validate and review generated documentation" if="workflow_mode != deep_dive">
 <action>Show summary of all generated files:
-Generated in {{output_folder}}/:
+Generated in {{project_knowledge}}/:
 {{file_list_with_sizes}}
 </action>
 
@@ -823,7 +823,7 @@ Generated in {{output_folder}}/:
 3. Extract document metadata from each match for user selection
    </critical>
 
-<action>Read {output_folder}/index.md</action>
+<action>Read {project_knowledge}/index.md</action>
 
 <action>Scan for incomplete documentation markers:
 Step 1: Search for exact pattern "_(To be generated)_" (case-sensitive)
@@ -1065,9 +1065,9 @@ Enter number(s) separated by commas (e.g., "1,3,5"), or type 'all':
 
 ## Project Documentation Complete! ✓
 
-**Location:** {{output_folder}}/
+**Location:** {{project_knowledge}}/
 
-**Master Index:** {{output_folder}}/index.md
+**Master Index:** {{project_knowledge}}/index.md
 👆 This is your primary entry point for AI-assisted development
 
 **Generated Documentation:**
@@ -1076,9 +1076,9 @@ Enter number(s) separated by commas (e.g., "1,3,5"), or type 'all':
 **Next Steps:**
 
 1. Review the index.md to familiarize yourself with the documentation structure
-2. When creating a brownfield PRD, point the PRD workflow to: {{output_folder}}/index.md
-3. For UI-only features: Reference {{output_folder}}/architecture-{{ui_part_id}}.md
-4. For API-only features: Reference {{output_folder}}/architecture-{{api_part_id}}.md
+2. When creating a brownfield PRD, point the PRD workflow to: {{project_knowledge}}/index.md
+3. For UI-only features: Reference {{project_knowledge}}/architecture-{{ui_part_id}}.md
+4. For API-only features: Reference {{project_knowledge}}/architecture-{{api_part_id}}.md
 5. For full-stack features: Reference both part architectures + integration-architecture.md
 
 **Verification Recap:**
@@ -1101,6 +1101,6 @@ When ready to plan new features, run the PRD workflow and provide this index as
 - Write final state file
   </action>
 
-<action>Display: "State file saved: {{output_folder}}/project-scan-report.json"</action>
+<action>Display: "State file saved: {{project_knowledge}}/project-scan-report.json"</action>
 
 </workflow>

src/bmm/workflows/document-project/workflows/full-scan.yaml

@@ -8,7 +8,7 @@ parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.y
 
 # Critical variables inherited from parent
 config_source: "{project-root}/_bmad/bmb/config.yaml"
-output_folder: "{config_source}:output_folder"
+project_knowledge: "{config_source}:project_knowledge"
 user_name: "{config_source}:user_name"
 date: system-generated