bmad-method 6.0.0-alpha.22 → 6.0.0-alpha.23

package/docs/how-to/customization/index.md

@@ -0,0 +1,27 @@
+---
+title: "BMad Customization"
+---
+
+
+Personalize agents and workflows to match your needs.
+
+## Guides
+
+| Guide | Description |
+|-------|-------------|
+| **[Agent Customization](/docs/how-to/customization/customize-agents.md)** | Modify agent behavior without editing core files |
+| **[Workflow Customization](/docs/how-to/customization/customize-workflows.md)** | Customize and optimize workflows |
+
+## Overview
+
+BMad provides two main customization approaches:
+
+### Agent Customization
+Modify any agent's persona, name, capabilities, or menu items using `.customize.yaml` files in `_bmad/_config/agents/`. Your customizations persist through updates.
+
+### Workflow Customization
+Replace or extend workflow steps to create tailored processes. (Coming soon)
+
+---
+
+**Next:** Read the [Agent Customization Guide](/docs/how-to/customization/customize-agents.md) to start personalizing your agents.

package/docs/{modules/core/document-sharding-guide.md → how-to/customization/shard-large-documents.md}

@@ -1,24 +1,17 @@
-# Document Sharding Guide
+---
+title: "Document Sharding Guide"
+---
+
 
 Comprehensive guide to BMad Method's document sharding system for managing large planning and architecture documents.
 
 ## Table of Contents
 
-- [Document Sharding Guide](#document-sharding-guide)
-  - [Table of Contents](#table-of-contents)
-  - [What is Document Sharding?](#what-is-document-sharding)
-    - [Architecture](#architecture)
-  - [When to Use Sharding](#when-to-use-sharding)
-    - [Ideal Candidates](#ideal-candidates)
-  - [How Sharding Works](#how-sharding-works)
-    - [Sharding Process](#sharding-process)
-    - [Workflow Discovery](#workflow-discovery)
-  - [Using the Shard-Doc Tool](#using-the-shard-doc-tool)
-    - [CLI Command](#cli-command)
-    - [Interactive Process](#interactive-process)
-    - [What Gets Created](#what-gets-created)
-  - [Workflow Support](#workflow-support)
-    - [Universal Support](#universal-support)
+- [What is Document Sharding?](#what-is-document-sharding)
+- [When to Use Sharding](#when-to-use-sharding)
+- [How Sharding Works](#how-sharding-works)
+- [Using the Shard-Doc Tool](#using-the-shard-doc-tool)
+- [Workflow Support](#workflow-support)
 
 ## What is Document Sharding?
 
@@ -103,7 +96,6 @@ Agent: Sharding PRD.md...
 **index.md structure:**
 
 ```markdown
-# PRD - Index
 
 ## Sections
 

package/docs/{modules/bmb-bmad-builder/workflow-vendoring-customization-inheritance.md → how-to/customization/vendor-workflows.md}

@@ -1,4 +1,7 @@
-# Workflow Vendoring, Customization, and Inheritance (Official Support Consing Soon)
+---
+title: "Workflow Vendoring, Customization, and Inheritance (Official Support Coming Soon)"
+---
+
 
 Vendoring and Inheritance of workflows are 2 ways of sharing or reutilizing workflows - but with some key distinctions and use cases.
 

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

@@ -0,0 +1,98 @@
+---
+title: "How to Get Answers About BMad"
+description: Use an LLM to quickly answer your own BMad questions
+---
+
+Point an LLM at BMad's source files and ask your question. That's the technique—the rest of this guide shows you how.
+
+## See It Work
+
+:::note[Example]
+**Q:** "Tell me the fastest way to build something with BMad"
+
+**A:** Use Quick Flow: Run `quick-spec` to write a technical specification, then `quick-dev` to implement it—skipping the full planning phases. This gets small features shipped in a single focused session instead of going through the full 4-phase BMM workflow.
+:::
+
+## Why This Works
+
+BMad's prompts are written in plain English, not code. The `_bmad` folder contains readable instructions, workflows, and agent definitions—exactly what LLMs are good at processing. You're not asking the LLM to guess; you're giving it the actual source material.
+
+## How to Do It
+
+### What Each Source Gives You
+
+| Source | Best For | Examples |
+|--------|----------|----------|
+| **`_bmad` folder** (installed) | How BMad works in detail—agents, workflows, prompts | "What does the PM agent do?" "How does the PRD workflow work?" |
+| **Full GitHub repo** (cloned) | Why things are the way they are—history, installer, architecture | "Why is the installer structured this way?" "What changed in v6?" |
+| **`llms-full.txt`** | Quick overview from documentation perspective | "Explain BMad's four phases" "What's the difference between levels?" |
+
+:::note[What's `_bmad`?]
+The `_bmad` folder is created when you install BMad. It contains all the agent definitions, workflows, and prompts. If you don't have this folder yet, you haven't installed BMad—see the "clone the repo" option below.
+:::
+
+### If Your AI Can Read Files (Claude Code, Cursor, etc.)
+
+**BMad installed:** Point your LLM at the `_bmad` folder and ask directly.
+
+**Want deeper context:** Clone the [full repo](https://github.com/bmad-code-org/BMAD-METHOD) for git history and installer details.
+
+### If You Use ChatGPT or Claude.ai
+
+Fetch `llms-full.txt` into your session:
+
+```
+https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
+```
+
+You can also find this and other downloadable resources on the [Downloads page](/docs/downloads.md).
+
+:::tip[Verify Surprising Answers]
+LLMs occasionally get things wrong. If an answer seems off, check the source file it referenced or ask on Discord.
+:::
+
+## Still Stuck?
+
+Tried the LLM approach and still need help? You now have a much better question to ask.
+
+| Channel | Use For |
+|---------|---------|
+| `#bmad-method-help` | Quick questions (real-time chat) |
+| `help-requests` forum | Detailed questions (searchable, persistent) |
+| `#suggestions-feedback` | Ideas and feature requests |
+| `#report-bugs-and-issues` | Bug reports |
+
+**Discord:** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj)
+
+## Found a Bug?
+
+If it's clearly a bug in BMad itself, skip Discord and go straight to GitHub Issues:
+
+**GitHub Issues:** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)
+
+---
+
+*You!*
+        *Stuck*
+             *in the queue—*
+                      *waiting*
+                              *for who?*
+
+*The source*
+        *is there,*
+                *plain to see!*
+
+*Point*
+     *your machine.*
+              *Set it free.*
+
+*It reads.*
+        *It speaks.*
+                *Ask away—*
+
+*Why wait*
+        *for tomorrow*
+                *when you have*
+                        *today?*
+
+*—Claude*

package/docs/how-to/installation/index.md

@@ -0,0 +1,15 @@
+---
+title: "Installation Guides"
+description: How to install and upgrade BMad Method
+---
+
+
+How-to guides for installing and configuring the BMad Method.
+
+## Available Guides
+
+| Guide | Description |
+|-------|-------------|
+| **[Install BMad](/docs/how-to/installation/install-bmad.md)** | Step-by-step installation instructions |
+| **[Install Custom Modules](/docs/how-to/installation/install-custom-modules.md)** | Add custom agents, workflows, and modules |
+| **[Upgrade to v6](/docs/how-to/installation/upgrade-to-v6.md)** | Migrate from BMad v4 to v6 |

package/docs/how-to/installation/install-bmad.md

@@ -0,0 +1,138 @@
+---
+title: "How to Install BMad"
+description: Step-by-step guide to installing BMad in your project
+---
+
+
+Complete guide to installing BMad in your project.
+
+---
+
+## Prerequisites
+
+- **Node.js** 20+ (required for the installer)
+- **Git** (recommended)
+- **AI-powered IDE** (Claude Code, Cursor, Windsurf, or similar)
+
+---
+
+## Steps
+
+### 1. Run the Installer
+
+```bash
+npx bmad-method install
+```
+
+### 2. Choose Installation Location
+
+The installer will ask where to install BMad files. Options:
+- Current directory (recommended for new projects)
+- Subdirectory
+- Custom path
+
+### 3. Select Your AI Tools
+
+Choose which AI tools you'll be using:
+- Claude Code
+- Cursor
+- Windsurf
+- Other
+
+The installer configures BMad for your selected tools.
+
+### 4. Choose Modules
+
+Select which modules to install:
+
+| Module | Purpose |
+|--------|---------|
+| **BMM** | Core methodology for software development |
+| **BMGD** | Game development workflows |
+| **CIS** | Creative intelligence and facilitation |
+| **BMB** | Building custom agents and workflows |
+
+### 5. Add Custom Content (Optional)
+
+If you have custom agents, workflows, or modules:
+- Point to their location
+- The installer will integrate them
+
+### 6. Configure Settings
+
+For each module, either:
+- Accept recommended defaults (faster)
+- Customize settings (more control)
+
+---
+
+## Verify Installation
+
+After installation, verify by:
+
+1. Checking the `_bmad/` directory exists
+2. Loading an agent in your AI tool
+3. Running `*menu` to see available commands
+
+---
+
+## Directory Structure
+
+```
+your-project/
+├── _bmad/
+│   ├── bmm/            # Method module
+│   │   ├── agents/     # Agent files
+│   │   ├── workflows/  # Workflow files
+│   │   └── config.yaml # Module config
+│   ├── core/           # Core utilities
+│   └── ...
+├── _bmad-output/       # Generated artifacts
+└── .claude/            # IDE configuration
+```
+
+---
+
+## Configuration
+
+Edit `_bmad/[module]/config.yaml` to customize:
+
+```yaml
+output_folder: ./_bmad-output
+user_name: Your Name
+communication_language: english
+```
+
+---
+
+## Troubleshooting
+
+### "Command not found: npx"
+
+Install Node.js 20+:
+```bash
+brew install node
+
+```
+
+### "Permission denied"
+
+Check npm permissions:
+```bash
+npm config set prefix ~/.npm-global
+```
+
+### Installer hangs
+
+Try running with verbose output:
+```bash
+npx bmad-method install --verbose
+```
+
+---
+
+## Related
+
+- [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) - Getting started with BMM
+- [Upgrade to V6](/docs/how-to/installation/upgrade-to-v6.md) - Upgrading from previous versions
+- [Install Custom Modules](/docs/how-to/installation/install-custom-modules.md) - Adding custom content

package/docs/{modules/bmb-bmad-builder/custom-content-installation.md → how-to/installation/install-custom-modules.md}

@@ -1,14 +1,17 @@
-# Custom Content Installation
+---
+title: "Custom Content Installation"
+---
 
-This guide explains how to create and install custom BMAD content including agents, workflows, and modules. Custom content extends BMAD's functionality with specialized tools and workflows that can be shared across projects or teams.
 
-For detailed information about the different types of custom content available, see [Custom Content](modules/bmb-bmad-builder/custom-content.md).
+This guide explains how to create and install custom BMad content including agents, workflows, and modules. Custom content extends BMad's functionality with specialized tools and workflows that can be shared across projects or teams.
+
+For detailed information about the different types of custom content available, see [Custom Content Types](/docs/explanation/bmad-builder/custom-content-types.md).
 
 You can find example custom modules in the `samples/sample-custom-modules/` folder of the repository. Download either of the sample folders to try them out.
 
 ## Content Types Overview
 
-BMAD Core supports several categories of custom content:
+BMad Core supports several categories of custom content:
 
 - Custom Stand Alone Modules
 - Custom Add On Modules
@@ -57,7 +60,7 @@ For standalone content that isn't part of a cohesive module collection, follow t
    - Add the property `unitary: true` in the module.yaml
      - The `unitary: true` property indicates this is a collection of potentially unrelated items that don't depend on each other
    - Any content you add to this folder should still be nested under workflows and agents - but the key with stand alone content is they do not rely on each other.
-     - Agents do not reference other workflows even if stored in a unitary:true module. But unitary Agents can have their own workflows in their sidecar, or reference workflows as requirements from other modules - with a process known as workflow vendoring. Keep in mind, this will require that the workflow referenced from the other module would need to be available for the end user to install, so its recommended to only vendor workflows from the core module, or official bmm modules (See [Workflow Vendoring, Customization, and Inheritance](workflow-vendoring-customization-inheritance.md)).
+     - Agents do not reference other workflows even if stored in a unitary:true module. But unitary Agents can have their own workflows in their sidecar, or reference workflows as requirements from other modules - with a process known as workflow vendoring. Keep in mind, this will require that the workflow referenced from the other module would need to be available for the end user to install, so its recommended to only vendor workflows from the core module, or official bmm modules.
 
 2. **Folder Structure**
    Organize content in specific named folders:
@@ -97,17 +100,17 @@ Ensure your content follows the proper conventions and includes a `module.yaml`
 
 ### New Project Installation
 
-When setting up a new BMAD project:
+When setting up a new BMad project:
 
 1. The installer will prompt: `Would you like to install a local custom module (this includes custom agents and workflows also)? (y/N)`
 2. Select 'y' to specify the path to your module folder containing `module.yaml`
 
 ### Existing Project Modification
 
-To add custom content to an existing BMAD project:
+To add custom content to an existing BMad project:
 
 1. Run the installer against your project location
-2. Select `Modify BMAD Installation`
+2. Select `Modify BMad Installation`
 3. Choose the option to add, modify, or update custom modules
 
 ### Upcoming Features
@@ -117,7 +120,7 @@ To add custom content to an existing BMAD project:
 
 ## Quick Updates
 
-When updates to BMAD Core or core modules (BMM, CIS, etc.) become available, the quick update process will:
+When updates to BMad Core or core modules (BMM, CIS, etc.) become available, the quick update process will:
 
 1. Apply available updates to core modules
 2. Recompile all agents with customizations from the `_config/agents` folder

package/docs/{bmad-core-concepts/installing/upgrading.md → how-to/installation/upgrade-to-v6.md}

@@ -1,8 +1,11 @@
-# BMad v4 to v6 Upgrade Guide
+---
+title: "Upgrading from Previous Versions"
+---
+
 
 ## Overview
 
-BMad v6 represents a complete ground-up rewrite with significant architectural changes. This guide will help you migrate your v4 project to v6.
+The latest version of BMad represents a complete ground-up rewrite with significant architectural changes. This guide will help you migrate from version 4.
 
 ---
 
@@ -120,7 +123,7 @@ persona:
     - Always upbeat and adventurous
 ```
 
-There is a lot more that is possible with agent customization, which is covered in detail in the [Agent Customization Guide](../bmad-customization/agents.md)
+There is a lot more that is possible with agent customization, which is covered in detail in the [Agent Customization Guide](/docs/how-to/customization/customize-agents.md)
 
 CRITICAL NOTE: After you modify the customization file, you need to run the npx installer against your installed location, and choose the option to rebuild all agents, or just do a quick update again. This always builds agents fresh and applies customizations.
 

package/docs/{modules/bmgd-bmad-game-dev/troubleshooting.md → how-to/troubleshooting/bmgd-troubleshooting.md}

@@ -1,4 +1,7 @@
-# BMGD Troubleshooting
+---
+title: "BMGD Troubleshooting"
+---
+
 
 Common issues and solutions when using BMGD workflows.
 
@@ -26,7 +29,6 @@ Common issues and solutions when using BMGD workflows.
 Check for `_bmad/bmgd/config.yaml` in your project. If missing, create it:
 
 ```yaml
-# BMGD Configuration
 output_folder: '{project-root}/docs/game-design'
 user_name: 'Your Name'
 communication_language: 'English'
@@ -254,6 +256,6 @@ When reporting issues, include:
 
 ## Next Steps
 
-- **[Quick Start Guide](./quick-start.md)** - Getting started
-- **[Workflows Guide](./workflows-guide.md)** - Workflow reference
-- **[Glossary](./glossary.md)** - Terminology
+- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Getting started
+- **[Workflows Guide](/docs/reference/workflows/index.md)** - Workflow reference
+- **[Glossary](/docs/reference/glossary/index.md)** - Terminology

package/docs/{modules/bmgd-bmad-game-dev/quick-flow-guide.md → how-to/workflows/bmgd-quick-flow.md}

@@ -1,4 +1,7 @@
-# BMGD Quick-Flow Guide
+---
+title: "BMGD Quick-Flow Guide"
+---
+
 
 Fast-track workflows for rapid game prototyping and flexible development.
 
@@ -14,7 +17,7 @@ The Game Solo Dev agent includes:
 
 - `quick-prototype` - Rapid mechanic testing
 - `quick-dev` - Flexible feature implementation
-- `create-tech-spec` - Create implementation-ready specs
+- `quick-spec` - Create implementation-ready specs
 - `code-review` - Quality checks
 - `test-framework` - Automated testing setup
 
@@ -283,6 +286,6 @@ If quick-dev keeps expanding scope, stop and create proper stories.
 
 ## Next Steps
 
-- **[Workflows Guide](./workflows-guide.md)** - Full workflow reference
-- **[Agents Guide](./agents-guide.md)** - Agent capabilities
-- **[Quick Start Guide](./quick-start.md)** - Getting started with BMGD
+- **[Workflows Guide](/docs/reference/workflows/bmgd-workflows.md)** - Full workflow reference
+- **[Agents Guide](/docs/explanation/game-dev/agents.md)** - Agent capabilities
+- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Getting started with BMGD

package/docs/how-to/workflows/conduct-research.md

@@ -0,0 +1,130 @@
+---
+title: "How to Conduct Research"
+description: How to conduct market, technical, and competitive research using BMad Method
+---
+
+
+Use the `research` workflow to perform comprehensive multi-type research for validating ideas, understanding markets, and making informed decisions.
+
+---
+
+## When to Use This
+
+- Need market viability validation
+- Choosing frameworks or platforms
+- Understanding competitive landscape
+- Need user understanding
+- Understanding domain or industry
+- Need deeper AI-assisted research
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- Analyst agent available
+
+---
+
+## Steps
+
+### 1. Load the Analyst Agent
+
+Start a fresh chat and load the Analyst agent.
+
+### 2. Run the Research Workflow
+
+```
+*research
+```
+
+### 3. Choose Research Type
+
+Select the type of research you need:
+
+| Type            | Purpose                                                | Use When                            |
+| --------------- | ------------------------------------------------------ | ----------------------------------- |
+| **market**      | TAM/SAM/SOM, competitive analysis                      | Need market viability validation    |
+| **technical**   | Technology evaluation, ADRs                            | Choosing frameworks/platforms       |
+| **competitive** | Deep competitor analysis                               | Understanding competitive landscape |
+| **user**        | Customer insights, personas, JTBD                      | Need user understanding             |
+| **domain**      | Industry deep dives, trends                            | Understanding domain/industry       |
+| **deep_prompt** | Generate AI research prompts (ChatGPT, Claude, Gemini) | Need deeper AI-assisted research    |
+
+### 4. Provide Context
+
+Give the agent details about what you're researching:
+
+- "SaaS project management tool"
+- "React vs Vue for our dashboard"
+- "Fintech compliance requirements"
+
+### 5. Set Research Depth
+
+Choose your depth level:
+
+- **Quick** - Fast overview
+- **Standard** - Balanced depth
+- **Comprehensive** - Deep analysis
+
+---
+
+## What You Get
+
+### Market Research Example
+
+```
+TAM: $50B
+SAM: $5B
+SOM: $50M
+
+Top Competitors:
+- Asana
+- Monday
+- etc.
+
+Positioning Recommendation: ...
+```
+
+### Technical Research Example
+
+Technology evaluation with:
+- Comparison matrix
+- Trade-off analysis
+- Recommendations with rationale
+
+---
+
+## Key Features
+
+- Real-time web research
+- Multiple analytical frameworks (Porter's Five Forces, SWOT, Technology Adoption Lifecycle)
+- Platform-specific optimization for deep_prompt type
+- Configurable research depth
+
+---
+
+## Next Steps
+
+After research:
+
+1. **Product Brief** - Capture strategic vision informed by research
+2. **PRD** - Use findings as context for requirements
+3. **Architecture** - Use technical research in ADRs
+
+---
+
+## Tips
+
+- Use market research early for new products
+- Technical research helps with architecture decisions
+- Competitive research informs positioning
+- Domain research is valuable for specialized industries
+
+---
+
+## Related
+
+- [Run Brainstorming Session](/docs/how-to/workflows/run-brainstorming-session.md) - Explore ideas before research
+- [Create Product Brief](/docs/how-to/workflows/create-product-brief.md) - Capture strategic vision
+- [Create PRD](/docs/how-to/workflows/create-prd.md) - Move to formal planning