bmad-method 5.1.3 → 6.0.0-alpha.1

package/docs/installers-bundlers/ide-injections.md

@@ -0,0 +1,186 @@
+# 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>
+```

package/docs/installers-bundlers/installers-modules-platforms-reference.md

@@ -0,0 +1,327 @@
+# BMAD 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 Core is a modular AI agent framework with intelligent installation, platform-agnostic support, and configuration inheritance.
+
+### Key Features
+
+- **Modular Design**: Core + optional modules (BMB, BMM, CIS)
+- **Smart Installation**: Interactive configuration with dependency resolution
+- **Clean Architecture**: Centralized `bmad/` directory add to project, no source pollution with multiple folders added
+
+## Architecture
+
+### Directory Structure upon installation
+
+```
+project-root/
+├── bmad/                      # Centralized installation
+│   ├── _cfg/                  # Configuration
+│   │   ├── agents/            # Agent configs
+│   │   └── agent-manifest.csv # Agent manifest
+│   ├── core/                  # Core module
+│   │   ├── agents/
+│   │   ├── tasks/
+│   │   └── config.yaml
+│   ├── bmm/                   # BMad Method module
+│   │   ├── agents/
+│   │   ├── tasks/
+│   │   ├── workflows/
+│   │   └── 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. **Installation**: Compile Process and copy files
+5. **Generation**: Create config files with inheritance
+6. **Post-Install**: Run module installers
+7. **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-config.yaml
+├── agents/
+├── tasks/
+├── templates/
+└── sub-modules/            # Platform-specific content
+    └── {platform}/
+        ├── injections.yaml
+        └── sub-agents/
+```
+
+## Configuration System
+
+### Collection Process
+
+Modules define prompts in `install-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-config.yaml
+   ├── agents/
+   └── tasks/
+   ```
+
+2. **Configuration** (`install-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
+```

package/docs/installers-bundlers/web-bundler-usage.md

@@ -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