BMAD-METHOD/docs/installers-bundlers/ide-injections.md

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:

<!-- 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:

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

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

<agent>
  <persona>...</persona>
  <!-- IDE-INJECT-POINT: pm-agent-instructions -->
  <cmds>...</cmds>
</agent>

Injection Configuration

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

<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