BMAD-METHOD/docs/installers-bundlers/installers-modules-platforms-reference.md

BMAD v6 Installation & Module System Reference

Table of Contents

1. Overview
2. Quick Start
3. Architecture
4. Modules
5. Configuration System
6. Platform Integration
7. Development Guide
8. Troubleshooting

Overview

BMAD v6 is a modular AI agent framework with intelligent installation, platform-agnostic support, and configuration inheritance.

Key Features

• Modular Design: Core + optional modules (BMM, CIS)
• Smart Installation: Interactive configuration with dependency resolution
• Multi-Platform: Supports 15+ AI coding platforms
• Clean Architecture: Centralized bmad/ directory, no source pollution

Quick Start

# Interactive installation (recommended)
bmad install

# Install specific modules
bmad install -m bmm cis

# Full installation
bmad install -f

# Check status
bmad status

Installation Options

• -d <path>: Target directory (default: current)
• -m <modules...>: Specific modules (bmm, cis)
• -f: Full installation
• -c: Core only
• -i <ide...>: Configure specific IDEs
• --skip-ide: Skip IDE configuration
• -v: Verbose output

Architecture

Directory Structure

project-root/
├── bmad/                    # Centralized installation
│   ├── _cfg/               # Configuration
│   │   ├── agents/         # Agent configs
│   │   └── agent-party.xml # Agent manifest
│   ├── core/               # Core module
│   │   ├── agents/
│   │   ├── tasks/
│   │   └── config.yaml
│   ├── bmm/                # BMad Method module
│   │   ├── agents/
│   │   ├── tasks/
│   │   ├── templates/
│   │   └── config.yaml
│   └── cis/                # Creative Innovation Studio
│       └── ...
└── .claude/                # Platform-specific (example)
    └── agents/

Installation Flow

1. Detection: Check existing installation
2. Selection: Choose modules interactively or via CLI
3. Configuration: Collect module-specific settings
4. Platform Setup: Configure AI coding platforms
5. Installation: Process and copy files
6. Generation: Create config files with inheritance
7. Post-Install: Run module installers
8. Manifest: Track installed components

Key Exclusions

• _module-installer/ directories are never copied to destination
• localskip="true" agents are filtered out
• Source config.yaml templates are replaced with generated configs

Modules

Core Module (Required)

Foundation framework with C.O.R.E. (Collaboration Optimized Reflection Engine)

• Components: Base agents, activation system, advanced elicitation
• Config: user_name, communication_language

BMM Module

BMad Method for software development workflows

• Components: PM agent, dev tasks, PRD templates, story generation
• Config: project_name, tech_docs, output_folder, story_location
• Dependencies: Core

CIS Module

Creative Innovation Studio for design workflows

• Components: Design agents, creative tasks
• Config: output_folder, design preferences
• Dependencies: Core

Module Structure

src/modules/{module}/
├── _module-installer/       # Not copied to destination
│   ├── installer.js        # Post-install logic
│   └── install-menu-config.yaml
├── agents/
├── tasks/
├── templates/
└── sub-modules/            # Platform-specific content
    └── {platform}/
        ├── injections.yaml
        └── sub-agents/

Configuration System

Collection Process

Modules define prompts in install-menu-config.yaml:

project_name:
  prompt: 'Project title?'
  default: 'My Project'
  result: '{value}'

output_folder:
  prompt: 'Output location?'
  default: 'docs'
  result: '{project-root}/{value}'

tools:
  prompt: 'Select tools:'
  multi-select:
    - 'Tool A'
    - 'Tool B'

Configuration Inheritance

Core values cascade to ALL modules automatically:

# core/config.yaml
user_name: "Jane"
communication_language: "English"

# bmm/config.yaml (generated)
project_name: "My App"
tech_docs: "/path/to/docs"
# Core Configuration Values (inherited)
user_name: "Jane"
communication_language: "English"

Reserved Keys: Core configuration keys cannot be redefined by other modules.

Path Placeholders

• {project-root}: Project directory path
• {value}: User input
• {module}: Module name
• {core:field}: Reference core config value

Config Generation Rules

1. ALL installed modules get a config.yaml (even without prompts)
2. Core values are ALWAYS included in module configs
3. Module-specific values come first, core values appended
4. Source templates are never copied, only generated configs

Platform Integration

Supported Platforms

Preferred (Full Integration):

• Claude Code
• Cursor
• Windsurf

Additional: Cline, Roo, Auggie, GitHub Copilot, Codex, Gemini, Qwen, Trae, Kilo, Crush, iFlow

Platform Features

1. Setup Handler (tools/cli/installers/lib/ide/{platform}.js)

   • Directory creation
   • Configuration generation
   • Agent processing

2. Content Injection (sub-modules/{platform}/injections.yaml)

   injections:
     - file: 'bmad/bmm/agents/pm.md'
       point: 'pm-agent-instructions'
       content: |
         <i>Platform-specific instruction</i>
   
   subagents:
     source: 'sub-agents'
     target: '.claude/agents'
     files: ['agent.md']
   

3. Interactive Config

   • Subagent selection
   • Installation scope (project/user)
   • Feature toggles

Injection System

Platform-specific content without source modification:

• Inject points marked in source: <!-- IDE-INJECT-POINT:name -->
• Content added during installation only
• Source files remain clean

Development Guide

Creating a Module

1. Structure

   src/modules/mymod/
   ├── _module-installer/
   │   ├── installer.js
   │   └── install-menu-config.yaml
   ├── agents/
   └── tasks/
   

2. Configuration (install-menu-config.yaml)

   code: mymod
   name: 'My Module'
   prompt: 'Welcome message'
   
   setting_name:
     prompt: 'Configure X?'
     default: 'value'
   

3. Installer (installer.js)

   async function install(options) {
     const { projectRoot, config, installedIDEs, logger } = options;
     // Custom logic
     return true;
   }
   module.exports = { install };
   

Adding Platform Support

1. Create handler: tools/cli/installers/lib/ide/myplatform.js
2. Extend BaseIdeSetup class
3. Add sub-module: src/modules/{mod}/sub-modules/myplatform/
4. Define injections and platform agents

Agent Configuration

Extractable config nodes:

<agent>
  <setting agentConfig="true">
    Default value
  </setting>
</agent>

Generated in: bmad/_cfg/agents/{module}-{agent}.md

Troubleshooting

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

Debug Commands

bmad install -v     # Verbose installation
bmad status -v      # Detailed status

Best Practices

1. Run from project root
2. Backup bmad/_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

Technical Notes

Dependency Resolution

• Direct dependencies (module → module)
• Agent references (cross-module)
• Template dependencies
• Partial module installation (only required files)

File Processing

• Filters localskip="true" agents
• Excludes _module-installer/ directories
• Replaces path placeholders at runtime
• Injects activation blocks

Web Bundling

bmad bundle --web           # Filter for web deployment
npm run validate:bundles    # Validate bundles