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

package/docs/{agent-customization-guide.md → how-to/customization/customize-agents.md}

@@ -1,4 +1,7 @@
-# Agent Customization Guide
+---
+title: "Agent Customization Guide"
+---
+
 
 Customize BMad agents without modifying core files. All customizations persist through updates.
 
@@ -26,10 +29,8 @@ After editing, IT IS CRITICAL to rebuild the agent to apply changes:
 
 ```bash
 npx bmad-method@alpha install # and then select option to compile all agents
-# OR for individual agent only
 npx bmad-method@alpha build <agent-name>
 
-# Examples:
 npx bmad-method@alpha build bmm-dev
 npx bmad-method@alpha build core-bmad-master
 npx bmad-method@alpha build bmm-pm
@@ -81,7 +82,7 @@ Add your own workflows to the agent's menu:
 ```yaml
 menu:
   - trigger: my-workflow
-    workflow: '{project-root}/custom/my-workflow.yaml'
+    workflow: '{project-root}/my-custom/workflows/my-workflow.yaml'
     description: My custom workflow
   - trigger: deploy
     action: '#deploy-prompt'
@@ -119,7 +120,6 @@ prompts:
 **Example 1: Customize Developer Agent for TDD**
 
 ```yaml
-# _bmad/_config/agents/bmm-dev.customize.yaml
 agent:
   metadata:
     name: 'TDD Developer'
@@ -135,7 +135,6 @@ critical_actions:
 **Example 2: Add Custom Deployment Workflow**
 
 ```yaml
-# _bmad/_config/agents/bmm-dev.customize.yaml
 menu:
   - trigger: deploy-staging
     workflow: '{project-root}/_bmad/deploy-staging.yaml'
@@ -148,7 +147,6 @@ menu:
 **Example 3: Multilingual Product Manager**
 
 ```yaml
-# _bmad/_config/agents/bmm-pm.customize.yaml
 persona:
   role: 'Bilingual Product Manager'
   identity: 'Expert in US and LATAM markets'
@@ -203,6 +201,8 @@ memories:
 
 ## Next Steps
 
-- **[BMM Agents Guide](./modules/bmm/agents-guide)** - Learn about the BMad Method agents
-- **[BMB Create Agent Workflow](./modules/bmb/agents/index)** - Build completely custom agents
-- **[BMM Complete Documentation](./modules/bmm/index)** - Full BMad Method reference
+- **[Learn about Agents](/docs/explanation/core-concepts/what-are-agents.md)** - Understand Simple vs Expert agents
+- **[Agent Creation Guide](/docs/tutorials/advanced/create-custom-agent.md)** - Build completely custom agents
+- **[BMM Complete Documentation](/docs/explanation/bmm/index.md)** - Full BMad Method reference
+
+[← Back to Customization](/docs/how-to/customization/index.md)

package/docs/how-to/customization/customize-workflows.md

@@ -0,0 +1,33 @@
+---
+title: "Workflow Customization Guide"
+---
+
+
+Customize and optimize workflows with step replacement and hooks.
+
+## Status
+
+> **Coming Soon:** Workflow customization is an upcoming capability. This guide will be updated when the feature is available.
+
+## What to Expect
+
+Workflow customization will allow you to:
+
+- **Replace Steps** - Swap out specific workflow steps with custom implementations
+- **Add Hooks** - Inject custom behavior before/after workflow steps
+- **Extend Workflows** - Create new workflows based on existing ones
+- **Override Behavior** - Customize workflow logic for your project's needs
+
+## For Now
+
+While workflow customization is in development, you can:
+
+- **Create Custom Workflows** - Use the BMad Builder to create entirely new workflows
+- **Customize Agents** - Modify agent behavior using [Agent Customization](/docs/how-to/customization/customize-agents.md)
+- **Provide Feedback** - Share your workflow customization needs with the community
+
+---
+
+**In the meantime:** Learn how to [create custom workflows](/docs/explanation/bmad-builder/index.md) from scratch.
+
+[← Back to Customization](/docs/how-to/customization/index.md)

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/how-to/customization/shard-large-documents.md

@@ -0,0 +1,125 @@
+---
+title: "Document Sharding Guide"
+---
+
+
+Comprehensive guide to BMad Method's document sharding system for managing large planning and architecture documents.
+
+## Table of Contents
+
+- [What is Document Sharding?](#what-is-document-sharding)
+- [When to Use Sharding](#when-to-use-sharding)
+- [How Sharding Works](#how-sharding-works)
+- [Using the Shard-Doc Tool](#using-the-shard-doc-tool)
+- [Workflow Support](#workflow-support)
+
+## What is Document Sharding?
+
+Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`). This enables:
+
+- **Selective Loading** - Workflows load only the sections they need
+- **Reduced Token Usage** - Massive efficiency gains for large projects
+- **Better Organization** - Logical section-based file structure
+- **Maintained Context** - Index file preserves document structure
+
+### Architecture
+
+```
+Before Sharding:
+docs/
+└── PRD.md (large 50k token file)
+
+After Sharding:
+docs/
+└── prd/
+    ├── index.md                    # Table of contents with descriptions
+    ├── overview.md                 # Section 1
+    ├── user-requirements.md        # Section 2
+    ├── technical-requirements.md   # Section 3
+    └── ...                         # Additional sections
+```
+
+## When to Use Sharding
+
+### Ideal Candidates
+
+**Large Multi-Epic Projects:**
+
+- Very large complex PRDs
+- Architecture documents with multiple system layers
+- Epic files with 4+ epics (especially for Phase 4)
+- UX design specs covering multiple subsystems
+
+## How Sharding Works
+
+### Sharding Process
+
+1. **Tool Execution**: Run `npx @kayvan/markdown-tree-parser source.md destination/` - this is abstracted with the core shard-doc task which is installed as a slash command or manual task rule depending on your tools.
+2. **Section Extraction**: Tool splits by level 2 headings
+3. **File Creation**: Each section becomes a separate file
+4. **Index Generation**: `index.md` created with structure and descriptions
+
+### Workflow Discovery
+
+BMad workflows use a **dual discovery system**:
+
+1. **Try whole document first** - Look for `document-name.md`
+2. **Check for sharded version** - Look for `document-name/index.md`
+3. **Priority rule** - Whole document takes precedence if both exist - remove the whole document if you want the sharded to be used instead.
+
+## Using the Shard-Doc Tool
+
+### CLI Command
+
+```bash
+/bmad:core:tools:shard-doc 
+```
+
+### Interactive Process
+
+```
+Agent: Which document would you like to shard?
+User: docs/PRD.md
+
+Agent: Default destination: docs/prd/
+       Accept default? [y/n]
+User: y
+
+Agent: Sharding PRD.md...
+       ✓ Created 12 section files
+       ✓ Generated index.md
+       ✓ Complete!
+```
+
+### What Gets Created
+
+**index.md structure:**
+
+```markdown
+
+## Sections
+
+1. [Overview](./overview.md) - Project vision and objectives
+2. [User Requirements](./user-requirements.md) - Feature specifications
+3. [Epic 1: Authentication](./epic-1-authentication.md) - User auth system
+4. [Epic 2: Dashboard](./epic-2-dashboard.md) - Main dashboard UI
+   ...
+```
+
+**Individual section files:**
+
+- Named from heading text (kebab-case)
+- Contains complete section content
+- Preserves all markdown formatting
+- Can be read independently
+
+## Workflow Support
+
+### Universal Support
+
+**All BMM workflows support both formats:**
+
+- ✅ Whole documents
+- ✅ Sharded documents
+- ✅ Automatic detection
+- ✅ Transparent to user

package/docs/how-to/customization/vendor-workflows.md

@@ -0,0 +1,45 @@
+---
+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.
+
+## Workflow Vendoring
+
+Workflow Vendoring allows an agent to have access to a workflow from another module, without having to install said module. At install time, the module workflow being vendored will be cloned and installed into the module that is receiving the vendored workflow the agent needs.
+
+### How to Vendor
+
+Lets assume you are building a module, and you do not want to recreate a workflow from the BMad Method, such as workflows/4-implementation/dev-story/workflow.md. Instead of copying all the context to your module, and having to maintain it over time as updates are made, you can instead use the exec-vendor menu item in your agent.
+
+From your modules agent definition, you would implement the menu item as follows in the agent:
+
+```yaml
+    - trigger: develop-story
+      exec-vendor: "{project-root}/_bmad/<source-module>/workflows/4-production/dev-story/workflow.md"
+      exec: "{project-root}/_bmad/<my-module>/workflows/dev-story/workflow.md"
+      description: "Execute Dev Story workflow, implementing tasks and tests, or performing updates to the story"
+```
+
+At install time, it will clone the workflow and all of its required assets, and the agent that gets built will have an exec to a path installed in its own module. The content gets added to the folder you specify in exec. While it does not have to exactly match the source path, you will want to ensure you are specifying the workflow.md to be in a new location (in other words in this example, dev-story would not already be the path of another custom module workflow that already exists.)
+
+## Workflow Inheritance (Official Support Coming Post Beta)
+
+Workflow Inheritance is a different concept, that allows you to modify or extend existing workflow.
+
+Party Mode from the core is an example of a workflow that is designed with inheritance in mind - customization for specific party needs. While party mode itself is generic - there might be specific agent collaborations you want to create. Without having to reinvent the whole party mode concept, or copy and paste all of its content - you could inherit from party mode to extend it to be specific.
+
+Some possible examples could be:
+
+- Retrospective
+- Sprint Planning
+- Collaborative Brainstorming Sessions
+
+## Workflow Customization (Official Support Coming Post Beta)
+
+Similar to Workflow Inheritance, Workflow Customization will soon be allowed for certain workflows that are meant to be user customized - similar in process to how agents are customized now.
+
+This will take the shape of workflows with optional hooks, configurable inputs, and the ability to replace whole at install time.
+
+For example, assume you are using the Create PRD workflow, which is comprised of 11 steps, and you want to always include specifics about your companies domain, technical landscape or something else. While project-context can be helpful with that, you can also through hooks and step overrides, have full replace steps, the key requirement being to ensure your step replace file is an exact file name match of an existing step, follows all conventions, and ends in a similar fashion to either hook back in to call the next existing step, or more custom steps that eventually hook back into the flow.

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/{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](./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
@@ -26,10 +29,8 @@ To create an installable custom module:
    - Create a folder with a short, abbreviated name (e.g., `cis` for Creative Intelligence Suite)
    - The folder name serves as the module code
 
-2. **Required Files**
-   - Include a `module.yaml` file in the root folder
-   - This file drives the installation process when used by the BMAD installer
-   - Reference existing modules or the BMad Builder for configuration examples
+2. **Required File**
+   - Include a `module.yaml` file in the root folder (this drives questions for the final generated config.yaml at install target)
 
 3. **Folder Organization**
    Follow these conventions for optimal compatibility:
@@ -56,8 +57,10 @@ For standalone content that isn't part of a cohesive module collection, follow t
 
 1. **Module Configuration**
    - Create a folder with a `module.yaml` file (similar to custom modules)
-   - Add the property `unitary: true` to the module.yaml
-   - The `unitary: true` property indicates this is a collection of potentially unrelated items that don't depend on each other
+   - 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.
 
 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