bmad-fh 6.0.0-alpha.052779ef

package/docs/how-to/customization/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

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

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

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

@@ -0,0 +1,12 @@
+---
+title: "Installation Guides"
+description: How to install and upgrade BMad Method
+---
+
+How-to guides for installing and configuring the BMad Method.
+
+| 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,111 @@
+---
+title: "How to Install BMad"
+description: Step-by-step guide to installing BMad in your project
+---
+
+Use the `npx bmad-method install` command to set up BMad in your project with your choice of modules and AI tools.
+
+## When to Use This
+
+- Starting a new project with BMad
+- Adding BMad to an existing codebase
+- Update the existing BMad Installation
+
+:::note[Prerequisites]
+- **Node.js** 20+ (required for the installer)
+- **Git** (recommended)
+- **AI-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:
+
+- Current directory (recommended for new projects if you created the directory yourself and ran from within the directory)
+- Custom path
+
+### 3. Select Your AI Tools
+
+Choose which AI tools you'll be using:
+
+- Claude Code
+- Cursor
+- Windsurf
+-  Many others to choose from
+
+The installer configures BMad for your selected tools by setting up commands that will call the ui.
+
+### 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 and the installer will integrate them.
+
+### 6. Configure Settings
+
+For each module, either accept recommended defaults (faster) or customize settings (more control).
+
+## What You Get
+
+```
+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
+```
+
+## Verify Installation
+
+1. Check the `_bmad/` directory exists
+2. Load an agent in your AI tool
+3. Run `/workflow-init`  which will autocomplete to the full command to see available commands
+
+## Configuration
+
+Edit `_bmad/[module]/config.yaml` to customize. For example these could be changed:
+
+```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
+```

package/docs/how-to/installation/install-custom-modules.md

@@ -0,0 +1,118 @@
+---
+title: "How to Install Custom Modules"
+description: Add custom agents, workflows, and modules to BMad
+---
+
+Use the BMad installer to add custom agents, workflows, and modules that extend BMad's functionality.
+
+## When to Use This
+
+- Adding third-party BMad modules to your project
+- Installing your own custom agents or workflows
+- Sharing custom content across projects or teams
+
+:::note[Prerequisites]
+- BMad installed in your project
+- Custom content with a valid `module.yaml` file
+:::
+
+## Steps
+
+### 1. Prepare Your Custom Content
+
+Your custom content needs a `module.yaml` file. Choose the appropriate structure:
+
+**For a cohesive module** (agents and workflows that work together):
+
+```
+module-code/
+  module.yaml
+  agents/
+  workflows/
+  tools/
+  templates/
+```
+
+**For standalone items** (unrelated agents/workflows):
+
+```
+module-name/
+  module.yaml        # Contains unitary: true
+  agents/
+    larry/larry.agent.md
+    curly/curly.agent.md
+  workflows/
+```
+
+Add `unitary: true` in your `module.yaml` to indicate items don't depend on each other.
+
+### 2. Run the Installer
+
+**New project:**
+
+```bash
+npx bmad-method install
+```
+
+When prompted "Would you like to install a local custom module?", select 'y' and provide the path to your module folder.
+
+**Existing project:**
+
+```bash
+npx bmad-method install
+```
+
+1. Select `Modify BMad Installation`
+2. Choose the option to add, modify, or update custom modules
+3. Provide the path to your module folder
+
+### 3. Verify Installation
+
+Check that your custom content appears in the `_bmad/` directory and is accessible from your AI tool.
+
+## What You Get
+
+- Custom agents available in your AI tool
+- Custom workflows accessible via `*workflow-name`
+- Content integrated with BMad's update system
+
+## Content Types
+
+BMad supports several categories of custom content:
+
+| Type                    | Description                                          |
+| ----------------------- | ---------------------------------------------------- |
+| **Stand Alone Modules** | Complete modules with their own agents and workflows |
+| **Add On Modules**      | Extensions that add to existing modules              |
+| **Global Modules**      | Content available across all modules                 |
+| **Custom Agents**       | Individual agent definitions                         |
+| **Custom Workflows**    | Individual workflow definitions                      |
+
+For detailed information about content types, see [Custom Content Types](https://github.com/bmad-code-org/bmad-builder/blob/main/docs/explanation/bmad-builder/custom-content-types.md).
+
+## Updating Custom Content
+
+When BMad Core or module updates are available, the quick update process:
+
+1. Applies updates to core modules
+2. Recompiles all agents with your customizations
+3. Retains your custom content from cache
+4. Preserves your configurations
+
+You don't need to keep source module files locally—just point to the updated location during updates.
+
+## Tips
+
+- **Use unique module codes** — Don't use `bmm` or other existing module codes
+- **Avoid naming conflicts** — Each module needs a distinct code
+- **Document dependencies** — Note any modules your custom content requires
+- **Test in isolation** — Verify custom modules work before sharing
+- **Version your content** — Track updates with version numbers
+
+:::caution[Naming Conflicts]
+Don't create custom modules with codes like `bmm` (already used by BMad Method). Each custom module needs a unique code.
+:::
+
+## Example Modules
+
+Find example custom modules in the `samples/sample-custom-modules/` folder of the [BMad repository](https://github.com/bmad-code-org/BMAD-METHOD). Download either sample folder to try them out.

package/docs/how-to/installation/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