bmad-method 6.0.0-alpha.1 → 6.0.0-alpha.10

package/docs/index.md

@@ -0,0 +1,227 @@
+# BMad Documentation Index
+
+Complete map of all BMad Method v6 documentation with recommended reading paths.
+
+---
+
+## 🎯 Getting Started (Start Here!)
+
+**New users:** Start with one of these based on your situation:
+
+| Your Situation         | Start Here                                                      | Then Read                                                     |
+| ---------------------- | --------------------------------------------------------------- | ------------------------------------------------------------- |
+| **Brand new to BMad**  | [Quick Start Guide](../src/modules/bmm/docs/quick-start.md)     | [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) |
+| **Upgrading from v4**  | [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)                 | [Quick Start Guide](../src/modules/bmm/docs/quick-start.md)   |
+| **Brownfield project** | [Brownfield Guide](../src/modules/bmm/docs/brownfield-guide.md) | [Quick Start Guide](../src/modules/bmm/docs/quick-start.md)   |
+
+---
+
+## 📋 Core Documentation
+
+### Project-Level Docs (Root)
+
+- **[README.md](../README.md)** - Main project overview, feature summary, and module introductions
+- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - How to contribute, pull request guidelines, code style
+- **[CHANGELOG.md](../CHANGELOG.md)** - Version history and breaking changes
+- **[CLAUDE.md](../CLAUDE.md)** - Claude Code specific guidelines for this project
+
+### Installation & Setup
+
+- **[v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)** - Migration path for v4 users
+- **[Document Sharding Guide](./document-sharding-guide.md)** - Split large documents for 90%+ token savings
+- **[Web Bundles](./USING_WEB_BUNDLES.md)** - Use BMAD agents in Claude Projects, ChatGPT, or Gemini without installation
+- **[Bundle Distribution Setup](./BUNDLE_DISTRIBUTION_SETUP.md)** - Maintainer guide for bundle auto-publishing
+
+---
+
+## 🏗️ Module Documentation
+
+### BMad Method (BMM) - Software & Game Development
+
+The flagship module for agile AI-driven development.
+
+- **[BMM Module README](../src/modules/bmm/README.md)** - Module overview, agents, and complete documentation index
+- **[BMM Documentation](../src/modules/bmm/docs/)** - All BMM-specific guides and references:
+  - [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Step-by-step guide to building your first project
+  - [Quick Spec Flow](../src/modules/bmm/docs/quick-spec-flow.md) - Rapid Level 0-1 development
+  - [Scale Adaptive System](../src/modules/bmm/docs/scale-adaptive-system.md) - Understanding the 5-level system
+  - [Brownfield Guide](../src/modules/bmm/docs/brownfield-guide.md) - Working with existing codebases
+- **[BMM Workflows Guide](../src/modules/bmm/workflows/README.md)** - **ESSENTIAL READING**
+- **[Test Architect Guide](../src/modules/bmm/testarch/README.md)** - Testing strategy and quality assurance
+
+### BMad Builder (BMB) - Create Custom Solutions
+
+Build your own agents, workflows, and modules.
+
+- **[BMB Module README](../src/modules/bmb/README.md)** - Module overview and capabilities
+- **[Agent Creation Guide](../src/modules/bmb/workflows/create-agent/README.md)** - Design custom agents
+
+### Creative Intelligence Suite (CIS) - Innovation & Creativity
+
+AI-powered creative thinking and brainstorming.
+
+- **[CIS Module README](../src/modules/cis/README.md)** - Module overview and workflows
+
+---
+
+## 🖥️ IDE-Specific Guides
+
+Instructions for loading agents and running workflows in your development environment.
+
+**Popular IDEs:**
+
+- [Claude Code](./ide-info/claude-code.md)
+- [Cursor](./ide-info/cursor.md)
+- [VS Code](./ide-info/windsurf.md)
+
+**Other Supported IDEs:**
+
+- [Augment](./ide-info/auggie.md)
+- [Cline](./ide-info/cline.md)
+- [Codex](./ide-info/codex.md)
+- [Crush](./ide-info/crush.md)
+- [Gemini](./ide-info/gemini.md)
+- [GitHub Copilot](./ide-info/github-copilot.md)
+- [IFlow](./ide-info/iflow.md)
+- [Kilo](./ide-info/kilo.md)
+- [OpenCode](./ide-info/opencode.md)
+- [Qwen](./ide-info/qwen.md)
+- [Roo](./ide-info/roo.md)
+- [Trae](./ide-info/trae.md)
+
+**Key concept:** Every reference to "load an agent" or "activate an agent" in the main docs links to the [ide-info](./ide-info/) directory for IDE-specific instructions.
+
+---
+
+## 🔧 Advanced Topics
+
+### Installation & Bundling
+
+- [IDE Injections Reference](./installers-bundlers/ide-injections.md) - How agents are installed to IDEs
+- [Installers & Platforms Reference](./installers-bundlers/installers-modules-platforms-reference.md) - CLI tool and platform support
+- [Web Bundler Usage](./installers-bundlers/web-bundler-usage.md) - Creating web-compatible bundles
+
+---
+
+## 📊 Documentation Map
+
+```
+docs/                              # Core/cross-module documentation
+├── index.md (this file)
+├── v4-to-v6-upgrade.md
+├── document-sharding-guide.md
+├── ide-info/                      # IDE setup guides
+│   ├── claude-code.md
+│   ├── cursor.md
+│   ├── windsurf.md
+│   └── [14+ other IDEs]
+└── installers-bundlers/           # Installation reference
+    ├── ide-injections.md
+    ├── installers-modules-platforms-reference.md
+    └── web-bundler-usage.md
+
+src/modules/
+├── bmm/                           # BMad Method module
+│   ├── README.md                  # Module overview & docs index
+│   ├── docs/                      # BMM-specific documentation
+│   │   ├── quick-start.md
+│   │   ├── quick-spec-flow.md
+│   │   ├── scale-adaptive-system.md
+│   │   └── brownfield-guide.md
+│   ├── workflows/README.md        # ESSENTIAL workflow guide
+│   └── testarch/README.md         # Testing strategy
+├── bmb/                           # BMad Builder module
+│   ├── README.md
+│   └── workflows/create-agent/README.md
+└── cis/                           # Creative Intelligence Suite
+    └── README.md
+```
+
+---
+
+## 🎓 Recommended Reading Paths
+
+### Path 1: Brand New to BMad (Software Project)
+
+1. [README.md](../README.md) - Understand the vision
+2. [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Get hands-on
+3. [BMM Module README](../src/modules/bmm/README.md) - Understand agents
+4. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Master the methodology
+5. [Your IDE guide](./ide-info/) - Optimize your workflow
+
+### Path 2: Game Development Project
+
+1. [README.md](../README.md) - Understand the vision
+2. [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Get hands-on
+3. [BMM Module README](../src/modules/bmm/README.md) - Game agents are included
+4. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Game workflows
+5. [Your IDE guide](./ide-info/) - Optimize your workflow
+
+### Path 3: Upgrading from v4
+
+1. [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md) - Understand what changed
+2. [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Reorient yourself
+3. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Learn new v6 workflows
+
+### Path 4: Working with Existing Codebase (Brownfield)
+
+1. [Brownfield Guide](../src/modules/bmm/docs/brownfield-guide.md) - Approach for legacy code
+2. [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Follow the process
+3. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Master the methodology
+
+### Path 5: Building Custom Solutions
+
+1. [BMB Module README](../src/modules/bmb/README.md) - Understand capabilities
+2. [Agent Creation Guide](../src/modules/bmb/workflows/create-agent/README.md) - Create agents
+3. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Understand workflow structure
+
+### Path 6: Contributing to BMad
+
+1. [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines
+2. Relevant module README - Understand the area you're contributing to
+3. [Code Style section in CONTRIBUTING.md](../CONTRIBUTING.md#code-style) - Follow standards
+
+---
+
+## 🔍 Quick Reference
+
+**What is each module for?**
+
+- **BMM** - AI-driven software and game development
+- **BMB** - Create custom agents and workflows
+- **CIS** - Creative thinking and brainstorming
+
+**How do I load an agent?**
+→ See [ide-info](./ide-info/) folder for your IDE
+
+**I'm stuck, what's next?**
+→ Check the [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) or run `workflow-status`
+
+**I want to contribute**
+→ Start with [CONTRIBUTING.md](../CONTRIBUTING.md)
+
+---
+
+## 📚 Important Concepts
+
+### Fresh Chats
+
+Each workflow should run in a fresh chat with the specified agent to avoid context limitations. This is emphasized throughout the docs because it's critical to successful workflows.
+
+### Scale Levels
+
+BMM adapts to project complexity (Levels 0-4). Documentation is scale-adaptive - you only need what's relevant to your project size.
+
+### Update-Safe Customization
+
+All agent customizations go in `{bmad_folder}/_cfg/agents/` and survive updates. See your IDE guide and module README for details.
+
+---
+
+## 🆘 Getting Help
+
+- **Discord**: [Join the BMad Community](https://discord.gg/gk8jAdXWmj)
+  - #general-dev - Technical questions
+  - #bugs-issues - Bug reports
+- **Issues**: [GitHub Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues)
+- **YouTube**: [BMad Code Channel](https://www.youtube.com/@BMadCode)

package/docs/installers-bundlers/ide-injections.md

@@ -158,7 +158,7 @@ src/modules/bmm/
 
 ```yaml
 injections:
-  - file: 'bmad/bmm/agents/pm.md'
+  - file: '{bmad_folder}/bmm/agents/pm.md'
     point: 'pm-agent-instructions'
     requires: 'any' # Injected if ANY subagent is selected
     content: |
@@ -166,7 +166,7 @@ injections:
         <i>Use 'market-researcher' subagent for analysis</i>
       </llm>
 
-  - file: 'bmad/bmm/templates/prd.md'
+  - file: '{bmad_folder}/bmm/templates/prd.md'
     point: 'prd-goals-context-delegation'
     requires: 'market-researcher' # Only if this specific subagent selected
     content: |

package/docs/installers-bundlers/installers-modules-platforms-reference.md

@@ -19,7 +19,7 @@ BMad Core is a modular AI agent framework with intelligent installation, platfor
 
 - **Modular Design**: Core + optional modules (BMB, BMM, CIS)
 - **Smart Installation**: Interactive configuration with dependency resolution
-- **Clean Architecture**: Centralized `bmad/` directory add to project, no source pollution with multiple folders added
+- **Clean Architecture**: Centralized `{bmad_folder}` directory add to project, no source pollution with multiple folders added
 
 ## Architecture
 
@@ -27,7 +27,7 @@ BMad Core is a modular AI agent framework with intelligent installation, platfor
 
 ```
 project-root/
-├── bmad/                      # Centralized installation
+├── {bmad_folder}/             # Centralized installation
 │   ├── _cfg/                  # Configuration
 │   │   ├── agents/            # Agent configs
 │   │   └── agent-manifest.csv # Agent manifest
@@ -184,7 +184,7 @@ Cline, Roo, Auggie, GitHub Copilot, Codex, Gemini, Qwen, Trae, Kilo, Crush, iFlo
 
    ```yaml
    injections:
-     - file: 'bmad/bmm/agents/pm.md'
+     - file: '{bmad_folder}/bmm/agents/pm.md'
        point: 'pm-agent-instructions'
        content: |
          <i>Platform-specific instruction</i>
@@ -270,14 +270,14 @@ Generated in: `bmad/_cfg/agents/{module}-{agent}.md`
 
 ### Common Issues
 
-| Issue                     | Solution                            |
-| ------------------------- | ----------------------------------- |
-| Existing installation     | Use `bmad update` or remove `bmad/` |
-| Module not found          | Check `src/modules/` exists         |
-| Config not applied        | Verify `bmad/{module}/config.yaml`  |
-| Missing config.yaml       | Fixed: All modules now get configs  |
-| Agent unavailable         | Check for `localskip="true"`        |
-| \_module-installer copied | Fixed: Now excluded from copy       |
+| Issue                   | Solution                                     |
+| ----------------------- | -------------------------------------------- |
+| Existing installation   | Use `bmad update` or remove `{bmad_folder}/` |
+| Module not found        | Check `src/modules/` exists                  |
+| Config not applied      | Verify `{bmad_folder}/{module}/config.yaml`  |
+| Missing config.yaml     | Fixed: All modules now get configs           |
+| Agent unavailable       | Check for `localskip="true"`                 |
+| module-installer copied | Fixed: Now excluded from copy                |
 
 ### Debug Commands
 
@@ -289,19 +289,19 @@ bmad status -v      # Detailed status
 ### Best Practices
 
 1. Run from project root
-2. Backup `bmad/_cfg/` before updates
+2. Backup `{bmad_folder}/_cfg/` before updates
 3. Use interactive mode for guidance
 4. Review generated configs post-install
 
 ## Migration from v4
 
-| v4                  | v6                  |
-| ------------------- | ------------------- |
-| Scattered files     | Centralized `bmad/` |
-| Monolithic          | Modular             |
-| Manual config       | Interactive setup   |
-| Limited IDE support | 15+ platforms       |
-| Source modification | Clean injection     |
+| v4                  | v6                           |
+| ------------------- | ---------------------------- |
+| Scattered files     | Centralized `{bmad_folder}/` |
+| Monolithic          | Modular                      |
+| Manual config       | Interactive setup            |
+| Limited IDE support | 15+ platforms                |
+| Source modification | Clean injection              |
 
 ## Technical Notes
 
@@ -311,6 +311,66 @@ bmad status -v      # Detailed status
 - Agent references (cross-module)
 - Template dependencies
 - Partial module installation (only required files)
+- Workflow vendoring for standalone module operation
+
+## Workflow Vendoring
+
+**Problem**: Modules that reference workflows from other modules create dependencies, forcing users to install multiple modules even when they only need one.
+
+**Solution**: Workflow vendoring allows modules to copy workflows from other modules during installation, making them fully standalone.
+
+### How It Works
+
+Agents can specify both `workflow` (source location) and `workflow-install` (destination location) in their menu items:
+
+```yaml
+menu:
+  - trigger: create-story
+    workflow: '{project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story/workflow.yaml'
+    workflow-install: '{project-root}/{bmad_folder}/bmgd/workflows/4-production/create-story/workflow.yaml'
+    description: 'Create a game feature story'
+```
+
+**During Installation:**
+
+1. **Vendoring Phase**: Before copying module files, the installer:
+   - Scans source agent YAML files for `workflow-install` attributes
+   - Copies entire workflow folders from `workflow` path to `workflow-install` path
+   - Updates vendored `workflow.yaml` files to reference target module's config
+
+2. **Compilation Phase**: When compiling agents:
+   - If `workflow-install` exists, uses its value for the `workflow` attribute
+   - `workflow-install` is build-time metadata only, never appears in final XML
+   - Compiled agent references vendored workflow location
+
+3. **Config Update**: Vendored workflows get their `config_source` updated:
+
+   ```yaml
+   # Source workflow (in bmm):
+   config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
+
+   # Vendored workflow (in bmgd):
+   config_source: "{project-root}/{bmad_folder}/bmgd/config.yaml"
+   ```
+
+**Result**: Modules become completely standalone with their own copies of needed workflows, configured for their specific use case.
+
+### Example Use Case: BMGD Module
+
+The BMad Game Development module vendors implementation workflows from BMM:
+
+- Game Dev Scrum Master agent references BMM workflows
+- During installation, workflows are copied to `bmgd/workflows/4-production/`
+- Vendored workflows use BMGD's config (with game-specific settings)
+- BMGD can be installed without BMM dependency
+
+### Benefits
+
+✅ **Module Independence** - No forced dependencies
+✅ **Clean Namespace** - Workflows live in their module
+✅ **Config Isolation** - Each module uses its own configuration
+✅ **Customization Ready** - Vendored workflows can be modified independently
+✅ **No User Confusion** - Avoid partial module installations
 
 ### File Processing
 
@@ -318,6 +378,7 @@ bmad status -v      # Detailed status
 - Excludes `_module-installer/` directories
 - Replaces path placeholders at runtime
 - Injects activation blocks
+- Vendors cross-module workflows (see Workflow Vendoring below)
 
 ### Web Bundling
 

package/docs/v4-to-v6-upgrade.md

@@ -63,7 +63,7 @@ your-project/
 
 ```
 your-project/
-└── bmad/                 # Single installation folder
+└── {bmad_folder}/       # Single installation folder, default .bmad
     ├── core/            # Real core framework (applies to all modules)
     ├── bmm/             # BMad Method (software/game dev)
     ├── bmb/             # BMad Builder (create agents/workflows)
@@ -75,8 +75,8 @@ your-project/
 ### Key Concept Changes
 
 - **v4 `.bmad-core`**: Was actually the BMad Method
-- **v6 `bmad/core/`**: Is the real universal core framework
-- **v6 `bmad/bmm/`**: Is the BMad Method module
+- **v6 `{bmad_folder}/core/`**: Is the real universal core framework
+- **v6 `{bmad_folder}/bmm/`**: Is the BMad Method module
 - **Module identification**: All modules now have a `config.yaml` file
 
 ---
@@ -93,7 +93,7 @@ After running the v6 installer:
    - This tells v6 you've already completed planning and solutioning phases
 3. **Document paths**: Keep your existing paths during installation
    - Default PRD/Architecture location: `docs/`
-   - Default stories location: `docs/stories/`
+   - Default stories location: `docs/sprint-artifacts/`
    - **Accept these defaults** if you're already using them in v4
 
 > **Important**: v6 workflows can handle both sharded and unsharded documents. You don't need to restructure your existing PRD or architecture files.
@@ -114,11 +114,11 @@ In v4, you may have modified agent files directly in `.bmad-*` folders.
 
 ### v6 Agent Customization
 
-**All customizations** now go in `bmad/_cfg/agents/` using customize files:
+**All customizations** now go in `{bmad_folder}/_cfg/agents/` using customize files:
 
 **Example: Renaming an agent and changing communication style**
 
-File: `bmad/_cfg/agents/bmm-pm.customize.yaml`
+File: `{bmad_folder}/_cfg/agents/bmm-pm.customize.yaml`
 
 ```yaml
 # Customize the PM agent
@@ -133,8 +133,8 @@ persona:
 
 **How it works:**
 
-- Base agent: `bmad/bmm/agents/pm.md`
-- Customization: `bmad/_cfg/agents/bmm-pm.customize.yaml`
+- Base agent: `{bmad_folder}/bmm/agents/pm.md`
+- Customization: `{bmad_folder}/_cfg/agents/bmm-pm.customize.yaml`
 - Result: Agent uses your custom name and style, but updates don't overwrite your changes
 
 ---
@@ -188,7 +188,7 @@ The installer will:
 If you're using:
 
 - `docs/` for PRD and architecture
-- `docs/stories/` for story files
+- `docs/sprint-artifacts/` for story files
 
 **Accept these defaults** during installation.
 
@@ -196,23 +196,25 @@ If you're using:
 
 After installation:
 
-```bash
-# In your project have the agent mode run workflow-init, in Claude Code:
-/workflow-init
-# or run the analyst and tell the analyst after it loads
-*workflow-init
-```
+1. **Load the Analyst agent** - See your IDE-specific instructions in [docs/ide-info](./ide-info/) for how to activate agents:
+   - [Claude Code](./ide-info/claude-code.md)
+   - [Cursor](./ide-info/cursor.md)
+   - [VS Code/Windsurf](./ide-info/) - Check your IDE folder
+
+2. **Wait for the agent's menu** to appear
+
+3. **Tell the agent**: `*workflow-init` - v6 supports excellent natural language fuzzy matching, so you could also say "workflow init" or "please init the workflow"
 
-Select **Level 3 or 4** if you've already completed PRD/architecture in v4.
+Since you are migrating an existing project from v4, it's most likely **Level 3 or 4** you will want to suggest when asked - if you've already completed PRD/architecture in v4.
 
 ---
 
 ## Post-Migration Checklist
 
 - [ ] v4 folders backed up to `v4-backup/`
-- [ ] v6 installed to `bmad/` folder
+- [ ] v6 installed to `{bmad_folder}/` folder
 - [ ] `workflow-init` run with correct project level selected
-- [ ] Agent customizations migrated to `bmad/_cfg/agents/` if needed
+- [ ] Agent customizations migrated to `{bmad_folder}/_cfg/agents/` if needed
 - [ ] IDE integration working (test by listing agents)
 - [ ] For active development: `sprint-planning` workflow executed
 
@@ -222,4 +224,4 @@ Select **Level 3 or 4** if you've already completed PRD/architecture in v4.
 
 - **Discord**: [Join the BMad Community](https://discord.gg/gk8jAdXWmj)
 - **Issues**: [GitHub Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues)
-- **Docs**: Check `bmad/docs/` in your installation for IDE-specific instructions
+- **Docs**: Check `{bmad_folder}/docs/` in your installation for IDE-specific instructions