bmad-method 6.0.0-alpha.16 → 6.0.0-alpha.17

package/docs/custom-content-installation.md

@@ -1,245 +1,149 @@
 # Custom Content Installation
 
-This guide explains how to create and install custom BMAD content including agents, workflows, and modules. Custom content allows you to extend BMAD's functionality with your own specialized tools and workflows that can be shared across projects or teams.
+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.
 
-## Types of Custom Content
+For detailed information about the different types of custom content available, see [Custom Content](./custom-content.md).
 
-### 1. Custom Agents and Workflows (Standalone)
+If you download either of the folders within the [Sample Custom Modules](./sample-custom-modules/readme.md) folder
 
-Custom agents and workflows are standalone content packages that can be installed without being part of a full module. These are perfect for:
+## Content Types Overview
 
-- Sharing specialized agents across projects
-- Building a personal Agent powered Notebook vault
-- Distributing workflow templates
-- Creating agent libraries for specific domains
+BMAD Core supports several categories of custom content:
 
-#### Structure
+- Custom Stand Alone Modules
+- Custom Add On Modules
+- Custom Global Modules
+- Custom Agents
+- Custom Workflows
 
-A custom agents and workflows package follows this structure:
+## Making Custom Content Installable
 
-```
-my-custom-agents/
-├── module.yaml          # Package configuration
-├── agents/              # Agent definitions
-│   └── my-agent/
-│       └── agent.md
-└── workflows/           # Workflow definitions
-    └── my-workflow/
-        └── workflow.md
-```
+### Custom Modules
 
-#### Configuration
+To create an installable custom module:
 
-Create a `module.yaml` file in your package root:
+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
 
-```yaml
-code: my-custom-agents
-name: 'My Custom Agents and Workflows'
-default_selected: true
-```
+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
 
-#### Example
+3. **Folder Organization**
+   Follow these conventions for optimal compatibility:
 
-See `/example-custom-content` for a working example of a folder with multiple random custom agents and workflows. Technically its also just a module, but you will be able to further pick and choose from this folders contents of what you do and do not want to include in a destination folder. This way, you can store all custom content source in one location and easily install it to different locations.
+   ```
+   module-code/
+     module.yaml
+     agents/
+     workflows/
+     tools/
+     templates/
+     ...
+   ```
 
-### 2. Custom Modules
+   - `agents/` - Agent definitions
+   - `workflows/` - Workflow definitions
+   - Additional custom folders are supported but following conventions is recommended for agent and workflow discovery
 
-Custom modules are complete BMAD modules that can include their own configuration, documentation, along with agents and workflows that all compliment each other. Additionally they will have their own installation scripts, data, and potentially other tools. Modules can be used for:
+**Note:** Full documentation for global modules and add-on modules will be available as support is finalized.
 
-- Domain-specific functionality (e.g., industry-specific workflows, entertainment, education and training, medical, etc...)
-- Integration with external systems
-- Specialized agent collections
-- Custom tooling and utilities
+### Standalone Content (Agents, Workflows, Tasks, Tools, Templates, Prompts)
 
-#### Structure
+For standalone content that isn't part of a cohesive module collection, follow this structure:
 
-A custom module follows 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
 
-```
-my-module/
-├── _module-installer/
-│   ├── installer.js           # optional, when it exists it will run with module installation
-├── module.yaml                # Module installation configuration with custom question and answer capture
-├── docs/                      # Module documentation
-├── agents/                    # Module-specific agents
-├── workflows/                 # Module-specific workflows
-├── data/                      # csv or other content to power agent intelligence or workflows
-├── tools/                     # Custom tools, hooks, mcp
-└── sub-modules/               # IDE-specific customizations
-    ├── vscode/
-    └── cursor/
-```
+2. **Folder Structure**
+   Organize content in specific named folders:
 
-#### Module Configuration
+   ```
+   module-name/
+     module.yaml        # Contains unitary: true
+     agents/
+     workflows/
+     templates/
+     tools/
+     tasks/
+     prompts/
+   ```
 
-The `module.yaml` file defines how your module is installed:
+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
+   ```
 
-```yaml
-# Module metadata
-code: my-module
-name: 'My Custom Module'
-default_selected: false
+**Future Feature:** Unitary modules will support selective installation, allowing users to pick and choose which specific items to install.
 
-header: 'My Custom Module'
-subheader: 'Description of what this module does'
-
-# Configuration prompts
-my_setting:
-  prompt: 'Configure your module setting'
-  default: 'default-value'
-  result: '{value}'
-```
-
-#### Example
-
-See `/example-custom-module` for a complete example:
+**Note:** Documentation explaining the distinctions between these content types and their specific use cases will be available soon.
 
 ## Installation Process
 
-### Step 1: Running the Installer
-
-When you run the existing normal BMAD installer - either from the cloned repo, OR via NPX, it will ask about custom content:
-
-```
-? Do you have custom content to install?
-❯ No (skip custom content)
-  Enter a directory path
-  Enter a URL [Coming soon]
-```
-
-### Step 2: Providing Custom Content Path
-
-If you select "Enter a directory path", the installer will prompt for the location:
-
-```
-? Enter the path to your custom content directory: /path/to/folder/containing/content/folder
-```
-
-The installer will:
-
-- Scan for `module.yaml` files (modules)
-- Display an indication of how many installable folders it has found. Note that a project with stand along agents and workflows all under a single folder like the example will just list the count as 1 for that directory.
-
-### Step 3: Selecting Content
-
-The installer presents a unified selection interface:
-
-```
-? Select modules and custom content to install:
-[── Custom Content ──]
- ◉ My Custom Agents and Workflows (/path/to/custom)
-[── Official Content ──]
- ◯ BMM: Business Method & Management
- ◯ CIS: Creativity & Innovation Suite
-```
-
-## Agent Sidecar Support
+### Prerequisites
 
-Agents with sidecar content can store personal data, memories, and working files outside of the `.bmad` directory. This separation keeps personal content separate from BMAD's core files.
+Ensure your content follows the proper conventions and includes a `module.yaml` file (only one per top-level folder).
 
-### What is Sidecar Content?
+### New Project Installation
 
-Sidecar content includes:
+When setting up a new BMAD project:
 
-- Agent memories and learning data
-- Personal working files
-- Temporary data
-- User-specific configurations
+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`
 
-### Sidecar Configuration
+### Existing Project Modification
 
-The sidecar folder location is configured during BMAD core installation:
+To add custom content to an existing BMAD project:
 
-```
-? Where should users' agent sidecar memory folders be stored?
-❯ .bmad-user-memory
-```
+1. Run the installer against your project location
+2. Select `Modify BMAD Installation`
+3. Choose the option to add, modify, or update custom modules
 
-### How It Works
+### Upcoming Features
 
-1. **Agent Declaration**: Agents declare `hasSidecar: true` in their metadata
-2. **Sidecar Detection**: The installer automatically detects folders with "sidecar" in the name
-3. **Installation**: Sidecar content is copied to the configured location
-4. **Path Replacement**: The `{agent_sidecar_folder}` placeholder in agent configurations is replaced with the actual path to the installed instance of the sidecar folder. Now when you use the agent, depending on its design, will use the content in sidecar to record interactions, remember things you tell it, or serve a host of many other issues.
+- **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
 
-### Example Structure
+## Quick Updates
 
-```
-my-agent/
-├── agent.md              # Agent definition
-└── my-agent-sidecar/     # Sidecar content folder
-    ├── memories/
-    ├── working/
-    └── config/
-```
+When updates to BMAD Core or core modules (BMM, CIS, etc.) become available, the quick update process will:
 
-### Git Integration
+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
 
-Since sidecar content is stored outside the `.bmad` directory (and typically outside version control), users can:
+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.
 
-- Add the sidecar folder to `.gitignore` to exclude personal data
-- Share agent definitions without exposing personal content
-- Maintain separate configurations for different projects
+## Important Considerations
 
-Example `.gitignore` entry:
+### Module Naming Conflicts
 
-```
-# Exclude agent personal data
-.bmad-user-memory/
-```
+When installing unofficial modules, ensure unique identification to avoid conflicts:
 
-## Creating Custom Content with BMAD Builder
+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
 
-The BMAD Builder provides workflows that will guide you to produce your own custom content:
+**Examples of conflicts to avoid:**
 
-1. **Agent Templates**: Use standardized agent templates with proper structure
-2. **Workflow Templates**: Create workflows using proven patterns
-3. **Validation Tools**: Validate your content before distribution
-4. **Package Generation**: Generate properly structured packages
+- 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
 
-1. **Use Clear Naming**: Make your content codes and names descriptive
-2. **Provide Documentation**: Include clear setup and usage instructions
-3. **Test Installation**: Test your content in a clean environment
-4. **Version Management**: Use semantic versioning for updates
-5. **Respect User Privacy**: Keep personal data in sidecar folders
-
-## Distribution
-
-Custom content can be distributed:
-
-1. **File System**: Copy folders directly to users
-2. **Git Repositories**: Clone or download from version control
-3. **Package Managers**: [Coming soon] npm package support
-4. **URL Installation**: [Coming soon] Direct URL installation, including an official community vetted module forge
-
-## Troubleshooting
-
-### No Custom Content Found
-
-- Ensure your `module.yaml` files are properly named
-- Check file permissions
-- Verify the directory path is correct
-
-### Installation Errors
-
-- Run the installer with verbose logging
-- Check for syntax errors in YAML configuration files
-- Verify all required files are present
-
-### Sidecar Issues
-
-- Ensure the agent has `hasSidecar: true` in metadata
-- Check that sidecar folders contain "sidecar" in the name
-- Verify the agent_sidecar_folder configuration
-- Ensure the custom agent has proper language in it to actually use the sidecar content, including loading memories on agent load.
-
-## Support
-
-For help with custom content creation or installation:
-
-1. Check the examples in `/example-custom-content` and `/example-custom-module`
-2. Review the BMAD documentation
-3. Create an issue in the BMAD repository
-4. Join the BMAD community discussions on discord
+- 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.

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/{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/{module}/agents/{agent-name}`
+2. **Include Entire Module**: Use `@_bmad/{module}`
+3. **Reference Index**: Use `@_bmad/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/core/agents/dev - Activate dev agent
+@_bmad/bmm/agents/architect - Activate architect agent
+@_bmad/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/core/agents/dev @_bmad/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/agents/` or `_bmad/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/agents/core-dev - Activate dev agent
+/_bmad/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/bmm/workflows/workflow-init - Activate the workflow-init command
 ```
 
 ### Notes

package/docs/ide-info/rovo-dev.md

@@ -55,7 +55,7 @@ project-root/
 │   ├── config.yml          (Rovo Dev configuration)
 │   ├── prompts.yml         (Optional: reusable prompts)
 │   └── ...
-├── .bmad/                  (BMAD installation directory)
+├── _bmad/                  (BMAD installation directory)
 └── ...
 ```
 

package/docs/index.md

@@ -53,7 +53,7 @@ The flagship module for agile AI-driven development.
 
 Build your own agents, workflows, and modules.
 
-- **[BMB Module README](../src/modules/bmb/README.md)** - Module overview and capabilities
+- **[BMB Module README](../src/modules/bmb/docs/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
@@ -141,7 +141,7 @@ Instructions for loading agents and running workflows in your development enviro
 
 ### Path 5: Building Custom Solutions
 
-1. [BMB Module README](../src/modules/bmb/README.md) - Understand capabilities
+1. [BMB Module README](../src/modules/bmb/docs/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
 

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

@@ -158,7 +158,7 @@ src/modules/bmm/
 
 ```yaml
 injections:
-  - file: '.bmad/bmm/agents/pm.md'
+  - file: '_bmad/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/bmm/templates/prd.md'
     point: 'prd-goals-context-delegation'
     requires: 'market-researcher' # Only if this specific subagent selected
     content: |