docs updates

docs/how-to/brownfield/index.md

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

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

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

docs/how-to/customize-bmad.md

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

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

@@ -3,11 +3,11 @@ title: "How to Get Answers About BMad"
 description: Use an LLM to quickly answer your own BMad questions
 ---
 
-Use your AI tool to get answers about BMad by pointing it at the source files.
+If you have successfully installed BMad and the BMad Method (+ other modules as needed) - the first step in getting answers is `/bmad-help`. This will answer upwards of 80% of all questions and is available to you in the IDE as you are working.
 
 ## When to Use This
 
-- You have a question about how BMad works
+- 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
 
@@ -19,11 +19,11 @@ An AI tool (Claude Code, Cursor, ChatGPT, Claude.ai, etc.) and either BMad insta
 
 ### 1. Choose Your Source
 
-| Source | Best For | Examples |
-|--------|----------|----------|
-| **`_bmad` folder** | How BMad works—agents, workflows, prompts | "What does the PM agent do?" |
-| **Full GitHub repo** | History, installer, architecture | "What changed in v6?" |
-| **`llms-full.txt`** | Quick overview from docs | "Explain BMad's four phases" |
+| Source               | Best For                                  | Examples                     |
+| -------------------- | ----------------------------------------- | ---------------------------- |
+| **`_bmad` folder**   | How BMad works—agents, workflows, prompts | "What does the PM agent do?" |
+| **Full GitHub repo** | History, installer, architecture          | "What changed in v6?"        |
+| **`llms-full.txt`**  | Quick overview from docs                  | "Explain BMad's four phases" |
 
 The `_bmad` folder is created when you install BMad. If you don't have it yet, clone the repo instead.
 
@@ -65,12 +65,12 @@ Direct answers about BMad—how agents work, what workflows do, why things are s
 
 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 |
+| 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)
 

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

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

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

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