feat: v6.0.0-alpha.0 - the future is now
This commit is contained in:
Brian Madison
196
docs/installers-bundlers/ide-injections.md
Normal file
196
docs/installers-bundlers/ide-injections.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# IDE Content Injection Standard
|
||||
|
||||
## Overview
|
||||
|
||||
This document defines the standard for IDE-specific content injection in BMAD modules. Each IDE can inject its own specific content into BMAD templates during installation without polluting the source files with IDE-specific code. The installation process is interactive, allowing users to choose what IDE-specific features they want to install.
|
||||
|
||||
## Architecture
|
||||
|
||||
### 1. Injection Points
|
||||
|
||||
Files that support IDE-specific content define injection points using HTML comments:
|
||||
|
||||
```xml
|
||||
<!-- IDE-INJECT-POINT: unique-point-name -->
|
||||
```
|
||||
|
||||
### 2. Module Structure
|
||||
|
||||
Each module that needs IDE-specific content creates a sub-module folder:
|
||||
|
||||
```
|
||||
src/modules/{module-name}/sub-modules/{ide-name}/
|
||||
├── injections.yaml # Injection configuration
|
||||
├── sub-agents/ # IDE-specific subagents (if applicable)
|
||||
└── config.yaml # Other IDE-specific config
|
||||
```
|
||||
|
||||
### 3. Injection Configuration Format
|
||||
|
||||
The `injections.yaml` file defines what content to inject where:
|
||||
|
||||
```yaml
|
||||
# injections.yaml structure
|
||||
injections:
|
||||
- file: 'relative/path/to/file.md' # Path relative to installation root
|
||||
point: 'injection-point-name' # Must match IDE-INJECT-POINT name
|
||||
requires: 'subagent-name' # Which subagent must be selected (or "any")
|
||||
content: | # Content to inject (preserves formatting)
|
||||
<llm>
|
||||
<i>Instructions specific to this IDE</i>
|
||||
</llm>
|
||||
|
||||
# Subagents available for installation
|
||||
subagents:
|
||||
source: 'sub-agents' # Source folder relative to this config
|
||||
target: '.claude/agents' # Claude's expected location (don't change)
|
||||
files:
|
||||
- 'agent1.md'
|
||||
- 'agent2.md'
|
||||
```
|
||||
|
||||
### 4. Interactive Installation Process
|
||||
|
||||
For Claude Code specifically, the installer will:
|
||||
|
||||
1. **Detect available subagents** from the module's `injections.yaml`
|
||||
2. **Ask the user** about subagent installation:
|
||||
- Install all subagents (default)
|
||||
- Select specific subagents
|
||||
- Skip subagent installation
|
||||
3. **Ask installation location** (if subagents selected):
|
||||
- Project level: `.claude/agents/`
|
||||
- User level: `~/.claude/agents/`
|
||||
4. **Copy selected subagents** to the chosen location
|
||||
5. **Inject only relevant content** based on selected subagents
|
||||
|
||||
Other IDEs can implement their own installation logic appropriate to their architecture.
|
||||
|
||||
## Implementation
|
||||
|
||||
### IDE Installer Responsibilities
|
||||
|
||||
Each IDE installer (e.g., `claude-code.js`) must:
|
||||
|
||||
1. **Check for sub-modules**: Look for `sub-modules/{ide-name}/` in each installed module
|
||||
2. **Load injection config**: Parse `injections.yaml` if present
|
||||
3. **Process injections**: Replace injection points with configured content
|
||||
4. **Copy additional files**: Handle subagents or other IDE-specific files
|
||||
|
||||
### Example Implementation (Claude Code)
|
||||
|
||||
```javascript
|
||||
async processModuleInjections(projectDir, bmadDir, options) {
|
||||
for (const moduleName of options.selectedModules) {
|
||||
const configPath = path.join(
|
||||
bmadDir, 'src/modules', moduleName,
|
||||
'sub-modules/claude-code/injections.yaml'
|
||||
);
|
||||
|
||||
if (exists(configPath)) {
|
||||
const config = yaml.load(configPath);
|
||||
|
||||
// Interactive: Ask user about subagent installation
|
||||
const choices = await this.promptSubagentInstallation(config.subagents);
|
||||
|
||||
if (choices.install !== 'none') {
|
||||
// Ask where to install
|
||||
const location = await this.promptInstallLocation();
|
||||
|
||||
// Process injections based on selections
|
||||
for (const injection of config.injections) {
|
||||
if (this.shouldInject(injection, choices)) {
|
||||
await this.injectContent(projectDir, injection, choices);
|
||||
}
|
||||
}
|
||||
|
||||
// Copy selected subagents
|
||||
await this.copySelectedSubagents(projectDir, config.subagents, choices, location);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Clean Source Files**: No IDE-specific conditionals in source
|
||||
2. **Modular**: Each IDE manages its own injections
|
||||
3. **Scalable**: Easy to add support for new IDEs
|
||||
4. **Maintainable**: IDE-specific content lives with IDE config
|
||||
5. **Flexible**: Different modules can inject different content
|
||||
|
||||
## Adding Support for a New IDE
|
||||
|
||||
1. Create sub-module folder: `src/modules/{module}/sub-modules/{new-ide}/`
|
||||
2. Add `injections.yaml` with IDE-specific content
|
||||
3. Update IDE installer to process injections using this standard
|
||||
4. Test installation with and without the IDE selected
|
||||
|
||||
## Example: BMM Module with Claude Code
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
src/modules/bmm/
|
||||
├── agents/pm.md # Has injection point
|
||||
├── templates/prd.md # Has multiple injection points
|
||||
└── sub-modules/
|
||||
└── claude-code/
|
||||
├── injections.yaml # Defines what to inject
|
||||
└── sub-agents/ # Claude Code specific subagents
|
||||
├── market-researcher.md
|
||||
├── requirements-analyst.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Injection Point in pm.md
|
||||
|
||||
```xml
|
||||
<agent>
|
||||
<persona>...</persona>
|
||||
<!-- IDE-INJECT-POINT: pm-agent-instructions -->
|
||||
<cmds>...</cmds>
|
||||
</agent>
|
||||
```
|
||||
|
||||
### Injection Configuration
|
||||
|
||||
```yaml
|
||||
injections:
|
||||
- file: 'bmad/bmm/agents/pm.md'
|
||||
point: 'pm-agent-instructions'
|
||||
requires: 'any' # Injected if ANY subagent is selected
|
||||
content: |
|
||||
<llm critical="true">
|
||||
<i>Use 'market-researcher' subagent for analysis</i>
|
||||
</llm>
|
||||
|
||||
- file: 'bmad/bmm/templates/prd.md'
|
||||
point: 'prd-goals-context-delegation'
|
||||
requires: 'market-researcher' # Only if this specific subagent selected
|
||||
content: |
|
||||
<i>DELEGATE: Use 'market-researcher' subagent...</i>
|
||||
```
|
||||
|
||||
### Result After Installation
|
||||
|
||||
```xml
|
||||
<agent>
|
||||
<persona>...</persona>
|
||||
<llm critical="true">
|
||||
<i>Use 'market-researcher' subagent for analysis</i>
|
||||
</llm>
|
||||
<cmds>...</cmds>
|
||||
</agent>
|
||||
```
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] Injection points are properly named and unique
|
||||
- [ ] injections.yaml is valid YAML with correct structure
|
||||
- [ ] Content formatting is preserved after injection
|
||||
- [ ] Installation works without the IDE (injection points removed)
|
||||
- [ ] Installation works with the IDE (content properly injected)
|
||||
- [ ] Subagents/files are copied to correct locations
|
||||
- [ ] No IDE-specific content remains when different IDE selected
|
||||
@@ -0,0 +1,355 @@
|
||||
# BMAD v6 Installation & Module System Reference
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Quick Start](#quick-start)
|
||||
3. [Architecture](#architecture)
|
||||
4. [Modules](#modules)
|
||||
5. [Configuration System](#configuration-system)
|
||||
6. [Platform Integration](#platform-integration)
|
||||
7. [Development Guide](#development-guide)
|
||||
8. [Troubleshooting](#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
|
||||
|
||||
```bash
|
||||
# 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`:
|
||||
|
||||
```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:
|
||||
|
||||
```yaml
|
||||
# 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`)
|
||||
|
||||
```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`)
|
||||
|
||||
```yaml
|
||||
code: mymod
|
||||
name: 'My Module'
|
||||
prompt: 'Welcome message'
|
||||
|
||||
setting_name:
|
||||
prompt: 'Configure X?'
|
||||
default: 'value'
|
||||
```
|
||||
|
||||
3. **Installer** (`installer.js`)
|
||||
```javascript
|
||||
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:
|
||||
|
||||
```xml
|
||||
<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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
bmad bundle --web # Filter for web deployment
|
||||
npm run validate:bundles # Validate bundles
|
||||
```
|
||||
54
docs/installers-bundlers/web-bundler-usage.md
Normal file
54
docs/installers-bundlers/web-bundler-usage.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Web Bundler Usage
|
||||
|
||||
ALPHA NOTE: Bundling of individual agents might work, team bundling is being reworked and will come with Beta release soon.
|
||||
|
||||
The web bundler creates self-contained XML bundles for BMAD agents, packaging all dependencies for web deployment.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Bundle all agents from all modules
|
||||
npm run bundle
|
||||
|
||||
# Clean and rebundle (removes old bundles first)
|
||||
npm run rebundle
|
||||
```
|
||||
|
||||
## Custom Output Directory
|
||||
|
||||
```bash
|
||||
# Bundle to custom directory
|
||||
node tools/cli/bundlers/bundle-web.js all --output ./my-bundles
|
||||
|
||||
# Rebundle to custom directory (auto-cleans first)
|
||||
node tools/cli/bundlers/bundle-web.js rebundle --output /absolute/path/to/custom/directory
|
||||
|
||||
# Bundle specific module to custom directory
|
||||
node tools/cli/bundlers/bundle-web.js module bmm --output ./custom-folder
|
||||
|
||||
# Bundle specific agent to custom directory
|
||||
node tools/cli/bundlers/bundle-web.js agent bmm analyst -o ./custom-folder
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
Bundles are generated in `web-bundles/` directory by default when run from the root of the clones project:
|
||||
|
||||
```
|
||||
web-bundles/
|
||||
├── [module-name]/
|
||||
│ └── agents/
|
||||
│ └── [agent-name].xml
|
||||
```
|
||||
|
||||
## Skipping Agents
|
||||
|
||||
Agents with `bundle="false"` attribute are automatically skipped during bundling.
|
||||
|
||||
## Bundle Contents
|
||||
|
||||
Each bundle includes:
|
||||
|
||||
- Agent definition with web activation
|
||||
- All resolved dependencies
|
||||
- Manifests for agent/team discovery
|
||||
Reference in New Issue
Block a user