mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-17 09:45:25 +00:00
150 lines
5.2 KiB
Markdown
150 lines
5.2 KiB
Markdown
# 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
|