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
|
||||
Reference in New Issue
Block a user