bmad-method 6.0.0-alpha.8 → 6.0.1

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

@@ -0,0 +1,103 @@
+---
+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.
+
+## When to Use This
+
+- 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
+
+:::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:
+
+```text
+https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
+```
+
+
+### 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/install-bmad.md

@@ -0,0 +1,88 @@
+---
+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, see [this guide](./non-interactive-installation.md).
+
+## 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 tool** (Claude Code, Cursor, Windsurf, or similar)
+:::
+
+## Steps
+
+### 1. Run the Installer
+
+```bash
+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:
+
+- 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
+
+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.
+
+### 4. Choose Modules
+
+The installer shows available modules. Select whichever ones you need — most users just want **BMad Method** (the software development module).
+
+### 5. Follow the Prompts
+
+The installer guides you through the rest — custom content, settings, etc.
+
+## What You Get
+
+```text
+your-project/
+├── _bmad/
+│   ├── bmm/            # Your selected modules
+│   │   └── config.yaml # Module settings (if you ever need to change them)
+│   ├── core/           # Required core module
+│   └── ...
+├── _bmad-output/       # Generated artifacts
+├── .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.
+
+## 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](./get-answers-about-bmad.md) for how to point your AI at the right sources.

package/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>.
+:::

package/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

package/docs/how-to/quick-fixes.md

@@ -0,0 +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.
+
+## When to Use This
+
+- 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 the DEV Agent
+
+Start a **fresh chat** in your AI IDE and load the DEV agent with its slash command:
+
+```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
+
+Tell the agent what you need in plain language. Be specific about the problem and, if you know it, where the relevant code lives.
+
+:::note[Example Prompts]
+**Bug fix** -- "Fix the login validation bug that allows empty passwords. The validation logic is in `src/auth/validate.ts`."
+
+**Refactoring** -- "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:
+
+- 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
+
+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).
+
+### 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
+
+The DEV agent is also useful for exploring unfamiliar code. Load it in a fresh chat and ask questions:
+
+:::note[Example Prompts]
+"Explain how the authentication system works in this codebase."
+
+"Show me where error handling happens in the API layer."
+
+"What does the `ProcessOrder` function do and what calls it?"
+:::
+
+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](../explanation/quick-flow.md) or the full BMad Method when:
+
+- 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

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

@@ -0,0 +1,78 @@
+---
+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.
+
+:::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 is failing to load and read all the documents as input when needed.
+
+## What is Document Sharding?
+
+Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`).
+
+### Architecture
+
+```text
+Before Sharding:
+_bmad-output/planning-artifacts/
+└── PRD.md (large 50k token file)
+
+After Sharding:
+_bmad-output/planning-artifacts/
+└── 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-shard-doc
+```
+
+### 2. Follow the Interactive Process
+
+```text
+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!
+```
+
+## 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