bmad-method 6.0.0-alpha.8 → 6.0.0-alpha.9

package/docs/agent-customization-guide.md

@@ -0,0 +1,208 @@
+# Agent Customization Guide
+
+Customize BMad agents without modifying core files. All customizations persist through updates.
+
+## Quick Start
+
+**1. Locate Customization Files**
+
+After installation, find agent customization files in:
+
+```
+{bmad_folder}/_cfg/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@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
+```
+
+## What You Can Customize
+
+### 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'
+  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
+
+Add your own workflows to the agent's menu:
+
+```yaml
+menu:
+  - trigger: my-workflow
+    workflow: '{project-root}/custom/my-workflow.yaml'
+    description: My custom workflow
+  - trigger: deploy
+    action: '#deploy-prompt'
+    description: Deploy to production
+```
+
+**Don't include:** `*` prefix or `help`/`exit` items - these are auto-injected.
+
+### Critical Actions
+
+Add instructions that execute before the agent starts:
+
+```yaml
+critical_actions:
+  - 'Always check git status before making changes'
+  - 'Use conventional commit messages'
+```
+
+### 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
+```
+
+## Real-World Examples
+
+**Example 1: Customize Developer Agent for TDD**
+
+```yaml
+# {bmad_folder}/_cfg/agents/bmm-dev.customize.yaml
+agent:
+  metadata:
+    name: 'TDD Developer'
+
+memories:
+  - 'Always write tests before implementation'
+  - 'Project uses Jest and React Testing Library'
+
+critical_actions:
+  - 'Review test coverage before committing'
+```
+
+**Example 2: Add Custom Deployment Workflow**
+
+```yaml
+# {bmad_folder}/_cfg/agents/bmm-dev.customize.yaml
+menu:
+  - trigger: deploy-staging
+    workflow: '{project-root}/.bmad-custom/deploy-staging.yaml'
+    description: Deploy to staging environment
+  - trigger: deploy-prod
+    workflow: '{project-root}/.bmad-custom/deploy-prod.yaml'
+    description: Deploy to production (with approval)
+```
+
+**Example 3: Multilingual Product Manager**
+
+```yaml
+# {bmad_folder}/_cfg/agents/bmm-pm.customize.yaml
+persona:
+  role: 'Bilingual Product Manager'
+  identity: 'Expert in US and LATAM markets'
+  communication_style: 'Clear, strategic, with cultural awareness'
+  principles:
+    - 'Consider localization from day one'
+    - 'Balance business goals with user needs'
+
+memories:
+  - 'User speaks English and Spanish'
+  - 'Target markets: US and Latin America'
+```
+
+## Tips
+
+- **Start Small:** Customize one section at a time and rebuild to test
+- **Backup:** Copy customization files before major changes
+- **Update-Safe:** Your customizations in `_cfg/` survive all BMad updates
+- **Per-Project:** Customization files are per-project, not global
+- **Version Control:** Consider committing `_cfg/` to share customizations with your team
+
+## Module vs. Global Config
+
+**Module-Level (Recommended):**
+
+- Customize agents per-project in `{bmad_folder}/_cfg/agents/`
+- Different projects can have different agent behaviors
+
+**Global Config (Coming Soon):**
+
+- Set defaults that apply across all projects
+- Override with project-specific customizations
+
+## 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?**
+
+- Delete the `.customize.yaml` file
+- Run `npx bmad-method build <agent-name>` to regenerate defaults
+
+## Next Steps
+
+- **[BMM Agents Guide](../src/modules/bmm/docs/agents-guide.md)** - Learn about all 12 BMad Method agents
+- **[BMB Create Agent Workflow](../src/modules/bmb/workflows/create-agent/README.md)** - Build completely custom agents
+- **[BMM Complete Documentation](../src/modules/bmm/docs/README.md)** - Full BMad Method reference

package/docs/ide-info/crush.md

@@ -7,7 +7,7 @@ BMAD agents are installed as commands in `.crush/commands/bmad/`.
 ### How to Use
 
 1. **Open Command Palette**: Use Crush command interface
-2. **Navigate**: Browse to `bmad/{module}/agents/`
+2. **Navigate**: Browse to `{bmad_folder}/{module}/agents/`
 3. **Select Agent**: Choose the agent command
 4. **Execute**: Run to activate agent persona
 

package/docs/ide-info/cursor.md

@@ -6,20 +6,20 @@ BMAD agents are installed in `.cursor/rules/bmad/` as MDC rules.
 
 ### How to Use
 
-1. **Reference in Chat**: Use `@bmad/{module}/agents/{agent-name}`
-2. **Include Entire Module**: Use `@bmad/{module}`
-3. **Reference Index**: Use `@bmad/index` for all available agents
+1. **Reference in Chat**: Use `@{bmad_folder}/{module}/agents/{agent-name}`
+2. **Include Entire Module**: Use `@{bmad_folder}/{module}`
+3. **Reference Index**: Use `@{bmad_folder}/index` for all available agents
 
 ### Examples
 
 ```
-@bmad/core/agents/dev - Activate dev agent
-@bmad/bmm/agents/architect - Activate architect agent
-@bmad/core - Include all core agents/tasks
+@{bmad_folder}/core/agents/dev - Activate dev agent
+@{bmad_folder}/bmm/agents/architect - Activate architect agent
+@{bmad_folder}/core - Include all core agents/tasks
 ```
 
 ### Notes
 
 - Rules are Manual type - only loaded when explicitly referenced
 - No automatic context pollution
-- Can combine multiple agents: `@bmad/core/agents/dev @bmad/core/agents/test`
+- Can combine multiple agents: `@{bmad_folder}/core/agents/dev @{bmad_folder}/core/agents/test`

package/docs/ide-info/iflow.md

@@ -7,7 +7,7 @@ BMAD agents are installed as commands in `.iflow/commands/bmad/`.
 ### How to Use
 
 1. **Access Commands**: Use iFlow command interface
-2. **Navigate**: Browse to `bmad/agents/` or `bmad/tasks/`
+2. **Navigate**: Browse to `{bmad_folder}/agents/` or `{bmad_folder}/tasks/`
 3. **Select**: Choose the agent or task command
 4. **Execute**: Run to activate
 
@@ -22,8 +22,8 @@ BMAD agents are installed as commands in `.iflow/commands/bmad/`.
 ### Examples
 
 ```
-/bmad/agents/core-dev - Activate dev agent
-/bmad/tasks/core-setup - Execute setup task
+/{bmad_folder}/agents/core-dev - Activate dev agent
+/{bmad_folder}/tasks/core-setup - Execute setup task
 ```
 
 ### Notes

package/docs/ide-info/opencode.md

@@ -14,7 +14,7 @@ BMAD agents are installed as OpenCode agents in `.opencode/agent/BMAD/{module_na
 
 ```
 /agents - to see a list of agents and switch between them
-/bmad/bmm/workflows/workflow-init - Activate the workflow-init command
+/{bmad_folder}/bmm/workflows/workflow-init - Activate the workflow-init command
 ```
 
 ### Notes

package/docs/index.md

@@ -29,6 +29,8 @@ Complete map of all BMad Method v6 documentation with recommended reading paths.
 
 - **[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
 
 ---
 
@@ -212,7 +214,7 @@ BMM adapts to project complexity (Levels 0-4). Documentation is scale-adaptive -
 
 ### Update-Safe Customization
 
-All agent customizations go in `bmad/_cfg/agents/` and survive updates. See your IDE guide and module README for details.
+All agent customizations go in `{bmad_folder}/_cfg/agents/` and survive updates. See your IDE guide and module README for details.
 
 ---
 

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
 
@@ -326,8 +326,8 @@ Agents can specify both `workflow` (source location) and `workflow-install` (des
 ```yaml
 menu:
   - trigger: create-story
-    workflow: '{project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml'
-    workflow-install: '{project-root}/bmad/bmgd/workflows/4-production/create-story/workflow.yaml'
+    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'
 ```
 
@@ -347,10 +347,10 @@ menu:
 
    ```yaml
    # Source workflow (in bmm):
-   config_source: "{project-root}/bmad/bmm/config.yaml"
+   config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
 
    # Vendored workflow (in bmgd):
-   config_source: "{project-root}/bmad/bmgd/config.yaml"
+   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.

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.
 
@@ -212,9 +212,9 @@ Since you are migrating an existing project from v4, it's most likely **Level 3
 ## 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
 
@@ -224,4 +224,4 @@ Since you are migrating an existing project from v4, it's most likely **Level 3
 
 - **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