BMAD-METHOD/docs/custom-content-installation.md

# 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).

If you download either of the folders within the [Sample Custom Modules](./sample-custom-modules/readme.md) folder

## 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