bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.20

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/_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@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/_config/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/_config/agents/bmm-dev.customize.yaml
+menu:
+  - trigger: deploy-staging
+    workflow: '{project-root}/_bmad/deploy-staging.yaml'
+    description: Deploy to staging environment
+  - trigger: deploy-prod
+    workflow: '{project-root}/_bmad/deploy-prod.yaml'
+    description: Deploy to production (with approval)
+```
+
+**Example 3: Multilingual Product Manager**
+
+```yaml
+# _bmad/_config/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 `_config/` survive all BMad updates
+- **Per-Project:** Customization files are per-project, not global
+- **Version Control:** Consider committing `_config/` to share customizations with your team
+
+## Module vs. Global Config
+
+**Module-Level (Recommended):**
+
+- Customize agents per-project in `_bmad/_config/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](./modules/bmm/agents-guide)** - Learn about the BMad Method agents
+- **[BMB Create Agent Workflow](./modules/bmb/agents/index)** - Build completely custom agents
+- **[BMM Complete Documentation](./modules/bmm/index)** - Full BMad Method reference

package/docs/custom-content-installation.md

@@ -0,0 +1,149 @@
+# Custom Content Installation
+
+This guide explains how to create and install custom BMAD content including agents, workflows, and modules. Custom content extends BMAD's functionality with specialized tools and workflows that can be shared across projects or teams.
+
+For detailed information about the different types of custom content available, see [Custom Content](./custom-content.md).
+
+You can find example custom modules in the `samples/sample-custom-modules/` folder of the repository. Download either of the sample folders to try them out.
+
+## Content Types Overview
+
+BMAD Core supports several categories of custom content:
+
+- Custom Stand Alone Modules
+- Custom Add On Modules
+- Custom Global Modules
+- Custom Agents
+- Custom Workflows
+
+## Making Custom Content Installable
+
+### Custom Modules
+
+To create an installable custom module:
+
+1. **Folder Structure**
+   - Create a folder with a short, abbreviated name (e.g., `cis` for Creative Intelligence Suite)
+   - The folder name serves as the module code
+
+2. **Required Files**
+   - Include a `module.yaml` file in the root folder
+   - This file drives the installation process when used by the BMAD installer
+   - Reference existing modules or the BMad Builder for configuration examples
+
+3. **Folder Organization**
+   Follow these conventions for optimal compatibility:
+
+   ```
+   module-code/
+     module.yaml
+     agents/
+     workflows/
+     tools/
+     templates/
+     ...
+   ```
+
+   - `agents/` - Agent definitions
+   - `workflows/` - Workflow definitions
+   - Additional custom folders are supported but following conventions is recommended for agent and workflow discovery
+
+**Note:** Full documentation for global modules and add-on modules will be available as support is finalized.
+
+### Standalone Content (Agents, Workflows, Tasks, Tools, Templates, Prompts)
+
+For standalone content that isn't part of a cohesive module collection, follow this structure:
+
+1. **Module Configuration**
+   - Create a folder with a `module.yaml` file (similar to custom modules)
+   - Add the property `unitary: true` to the module.yaml
+   - The `unitary: true` property indicates this is a collection of potentially unrelated items that don't depend on each other
+
+2. **Folder Structure**
+   Organize content in specific named folders:
+
+   ```
+   module-name/
+     module.yaml        # Contains unitary: true
+     agents/
+     workflows/
+     templates/
+     tools/
+     tasks/
+     prompts/
+   ```
+
+3. **Individual Item Organization**
+   Each item should have its own subfolder:
+   ```text
+   my-custom-stuff/
+     module.yaml
+     agents/
+       larry/larry.agent.md
+       curly/curly.agent.md
+       moe/moe.agent.md
+       moe/moe-sidecar/memories.csv
+   ```
+
+**Future Feature:** Unitary modules will support selective installation, allowing users to pick and choose which specific items to install.
+
+**Note:** Documentation explaining the distinctions between these content types and their specific use cases will be available soon.
+
+## Installation Process
+
+### Prerequisites
+
+Ensure your content follows the proper conventions and includes a `module.yaml` file (only one per top-level folder).
+
+### New Project Installation
+
+When setting up a new BMAD project:
+
+1. The installer will prompt: `Would you like to install a local custom module (this includes custom agents and workflows also)? (y/N)`
+2. Select 'y' to specify the path to your module folder containing `module.yaml`
+
+### Existing Project Modification
+
+To add custom content to an existing BMAD project:
+
+1. Run the installer against your project location
+2. Select `Modify BMAD Installation`
+3. Choose the option to add, modify, or update custom modules
+
+### Upcoming Features
+
+- **Unitary Module Selection:** For modules with `type: unitary` (instead of `type: module`), you'll be able to select specific items to install
+- **Add-on Module Dependencies:** The installer will verify and install dependencies for add-on modules automatically
+
+## Quick Updates
+
+When updates to BMAD Core or core modules (BMM, CIS, etc.) become available, the quick update process will:
+
+1. Apply available updates to core modules
+2. Recompile all agents with customizations from the `_config/agents` folder
+3. Retain your custom content from a cached location
+4. Preserve your existing configurations and customizations
+
+This means you don't need to keep the source module files locally. When updates are available, simply point to the updated module location during the update process.
+
+## Important Considerations
+
+### Module Naming Conflicts
+
+When installing unofficial modules, ensure unique identification to avoid conflicts:
+
+1. **Module Codes:** Each module must have a unique code (e.g., don't use `bmm` for custom modules)
+2. **Module Names:** Avoid using names that conflict with existing modules
+3. **Multiple Custom Modules:** If creating multiple custom modules, use distinct codes for each
+
+**Examples of conflicts to avoid:**
+
+- Don't create a custom module with code `bmm` (already used by BMad Method)
+- Don't name multiple custom modules with the same code like `mca`
+
+### Best Practices
+
+- Use descriptive, unique codes for your modules
+- Document any dependencies your custom modules have
+- Test custom modules in isolation before sharing
+- Consider version numbering for your custom content to track updates

package/docs/custom-content.md

@@ -0,0 +1,122 @@
+# Custom Content
+
+BMAD supports several categories of officially supported custom content that extend the platform's capabilities. Custom content can be created manually or with the recommended assistance of the BMad Builder (BoMB) Module. The BoMB Agent provides workflows and expertise to plan and build any custom content you can imagine.
+
+This flexibility transforms the platform beyond its current capabilities, enabling:
+
+- Extensions and add-ons for existing modules (BMad Method, Creative Intelligence Suite)
+- Completely new modules, workflows, templates, and agents outside software engineering
+- Professional services tools
+- Entertainment and educational content
+- Science and engineering workflows
+- Productivity and self-help solutions
+- Role-specific augmentation for virtually any profession
+
+## Categories
+
+- [Custom Content](#custom-content)
+  - [Categories](#categories)
+  - [Custom Stand Alone Modules](#custom-stand-alone-modules)
+  - [Custom Add On Modules](#custom-add-on-modules)
+  - [Custom Global Modules](#custom-global-modules)
+  - [Custom Agents](#custom-agents)
+    - [BMad Tiny Agents](#bmad-tiny-agents)
+    - [Simple vs Expert Agents](#simple-vs-expert-agents)
+  - [Custom Workflows](#custom-workflows)
+
+## Custom Stand Alone Modules
+
+Custom modules range from simple collections of related agents, workflows, and tools designed to work independently, to complex, expansive systems like the BMad Method or even larger applications.
+
+Custom modules are [installable](./custom-content-installation.md) using the standard BMAD method and support advanced features:
+
+- Optional user information collection during installation/updates
+- Versioning and upgrade paths
+- Custom installer functions with IDE-specific post-installation handling (custom hooks, subagents, or vendor-specific tools)
+- Ability to bundle specific tools such as MCP, skills, execution libraries, and code
+
+## Custom Add On Modules
+
+Custom Add On Modules contain specific agents, tools, or workflows that expand, modify, or customize another module but cannot exist or install independently. These add-ons provide enhanced functionality while leveraging the base module's existing capabilities.
+
+Examples include:
+
+- Alternative implementation workflows for BMad Method agents
+- Framework-specific support for particular use cases
+- Game development expansions that add new genre-specific capabilities without reinventing existing functionality
+
+Add on modules can include:
+
+- Custom agents with awareness of the target module
+- Access to existing module workflows
+- Tool-specific features such as rulesets, hooks, subprocess prompts, subagents, and more
+
+## Custom Global Modules
+
+Similar to Custom Stand Alone Modules, but designed to add functionality that applies across all installed content. These modules provide cross-cutting capabilities that enhance the entire BMAD ecosystem.
+
+Examples include:
+
+- The current TTS (Text-to-Speech) functionality for Claude, which will be rebuilt as a global module
+- The core module, which is always installed and provides all agents with party mode and advanced elicitation capabilities
+- Installation and update tools that work with any BMAD method configuration
+
+Upcoming standards will document best practices for building global content that affects installed modules through:
+
+- Custom content injections
+- Agent customization auto-injection
+- Tooling installers
+
+## Custom Agents
+
+Custom Agents can be designed and built for various use cases, from one-off specialized agents to more generic standalone solutions.
+
+### BMad Tiny Agents
+
+Personal agents designed for highly specific needs that may not be suitable for sharing. For example, a team management agent living in an Obsidian vault that helps with:
+
+- Team coordination and management
+- Understanding team details and requirements
+- Tracking specific tasks with designated tools
+
+These are simple, standalone files that can be scoped to focus on specific data or paths when integrated into an information vault or repository.
+
+### Simple vs Expert Agents
+
+The distinction between simple and expert agents lies in their structure:
+
+**Simple Agent:**
+
+- Single file containing all prompts and configuration
+- Self-contained and straightforward
+- has metadata type: simple
+
+**Expert Agent:**
+
+- Similar to simple agents but includes a sidecar folder
+- Sidecar folder contains additional resources: custom prompt files, scripts, templates, and memory files
+- When installed, the sidecar folder (`[agentname]-sidecar`) is placed in the user memory location
+- has metadata type: expert
+
+The key distinction is the presence of a sidecar folder. As web and consumer agent tools evolve to support common memory mechanisms, storage formats, and MCP, the writable memory files will adapt to support these evolving standards.
+
+Custom agents can be:
+
+- Used within custom modules
+- Designed as standalone tools
+- Integrated with existing workflows and systems, if this is to be the case, should also include a module: <module name> if a specific module is intended for it to require working with
+
+## Custom Workflows
+
+Workflows are powerful, progressively loading sequence engines capable of performing tasks ranging from simple to complex, including:
+
+- User engagements
+- Business processes
+- Content generation (code, documentation, or other output formats)
+
+A custom workflow created outside of a larger module can still be distributed and used without associated agents through:
+
+- Slash commands
+- Manual command/prompt execution when supported by tools
+
+At its core, a custom workflow is a single or series of prompts designed to achieve a specific outcome.