ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6b9ab8b201db71ac5e4b1a5a7cc0b471daab6827
BMAD-METHOD/tools/cli/README.md
Brian Madison 940cc15751 cli installer bundler documentation added
2025-10-18 10:20:29 -05:00

19 KiB
Raw Blame History

BMad CLI Tool

The BMad CLI handles installation and web bundling for the BMAD-METHOD framework. It compiles YAML agents into two distinct formats: IDE-integrated agents (filesystem-aware, customizable) and web bundles (self-contained, dependency-embedded).

Table of Contents

Overview

The CLI provides two primary functions:

  1. Installation: Compiles agents from YAML and installs to IDE environments with full customization support
  2. Bundling: Packages agents and dependencies into standalone web-ready XML files

Both use the same YAML→XML compilation engine but produce different outputs optimized for their environments.

Commands

Installation

# Interactive installation
npm run install:bmad

# Direct CLI usage
node tools/cli/bmad-cli.js install --target /path/to/project --modules bmm,bmb --ides codex

# Flags:
#   --target <path>        Target project directory
#   --modules <list>       Comma-separated: bmm, bmb, cis
#   --ides <list>          Comma-separated IDE codes (see IDE Support)
#   --non-interactive      Skip all prompts

Bundling

# Bundle all modules
npm run bundle

# Bundle specific items
node tools/cli/bundlers/bundle-web.js all              # Everything
node tools/cli/bundlers/bundle-web.js module bmm       # One module
node tools/cli/bundlers/bundle-web.js agent bmm pm     # One agent

Utilities

npm run bmad:status              # Installation status
npm run validate:bundles         # Validate web bundles
node tools/cli/regenerate-manifests.js    # Regenerate agent-party.xml files

Installation System

The installer is a multi-stage system that handles agent compilation, IDE integration, module configuration, platform-specific behaviors, and manifest generation.

Installation Flow

1. Collect User Input
   - Target directory, modules, IDEs
   - Custom module configuration (via install-menu-config.yaml)

2. Pre-Installation
   - Validate target, check conflicts, backup existing installations
   - Resolve module dependencies (4-pass system)

3. Install Core + Modules
   - Copy files to {target}/bmad/
   - Compile agents: YAML → Markdown/XML (forWebBundle: false)
   - Merge customize.yaml files if they exist
   - Inject activation blocks based on agent capabilities

4. IDE Integration
   - Initialize selected IDE handlers
   - Generate IDE-specific artifacts (commands/rules/workflows)
   - Execute platform-specific hooks (IDE+module combinations)

5. Generate Manifests
   - manifest.yaml (installation metadata)
   - workflow-manifest.csv (workflow catalog)
   - agent-manifest.csv (agent metadata)
   - task-manifest.csv (legacy)
   - files-manifest.csv (all files with SHA256 hashes)

6. Validate & Finalize
   - Verify file integrity, agent compilation, IDE artifacts
   - Display summary and next steps

Output Structure:

{target}/
├── bmad/
│   ├── core/              # Always installed
│   ├── {module}/          # Selected modules
│   │   ├── agents/        # Compiled .md files
│   │   ├── workflows/
│   │   └── config.yaml
│   └── _cfg/              # Manifests
└── .{ide}/                # IDE-specific artifacts
    └── ...                # Format varies by IDE

IDE Support

The installer supports 14 IDE environments through a base-derived architecture. Each IDE handler extends BaseIDE and implements IDE-specific artifact generation.

Supported IDEs (as of v6-alpha):

Code Name Artifact Location
codex Claude Code .claude/commands/
claude-code Claude Code (alt) .claude/commands/
windsurf Windsurf .windsurf/workflows/
cursor Cursor .cursor/rules/
cline Cline .clinerules/
github-copilot GitHub Copilot .github/copilot/
crush Crush .crush/
auggie Auggie .auggie/
gemini Google Gemini .gemini/
qwen Qwen .qwen/
roo Roo .roo/
trae Trae .trae/
iflow iFlow .iflow/
kilo Kilo .kilo/

Handler Architecture:

  • Base class: tools/cli/installers/lib/ide/_base-ide.js
  • Handler implementations: tools/cli/installers/lib/ide/{ide-code}.js
  • Dynamic discovery: IDE manager scans directory and auto-registers handlers
  • Each handler implements: setup(), createArtifacts(), cleanup(), getAgentsFromBmad()

Adding New IDE Support:

  1. Create handler file: tools/cli/installers/lib/ide/your-ide.js
  2. Extend BaseIDE, set ideCode, ideName, artifactType
  3. Implement artifact generation methods
  4. IDE auto-discovered on next run

Custom Module Configuration

Modules define interactive configuration menus via install-menu-config.yaml files in their _module-installer/ directories.

Config File Location:

  • Core: src/core/_module-installer/install-menu-config.yaml
  • Modules: src/modules/{module}/_module-installer/install-menu-config.yaml

Configuration Types:

  • select: Radio button choices
  • multiselect: Checkboxes
  • input: Text input with validation
  • confirm: Yes/no

Variable Substitution:

  • {project-root} → Absolute target path
  • {directory_name} → Project directory basename
  • {module} → Current module name
  • {value:config_id} → Reference another config value

Config Persistence:

  • Values saved to module's config.yaml
  • Existing values detected on reinstall
  • User prompted: "Use existing or change?"

Processor: tools/cli/installers/lib/core/config-collector.js

Platform Specifics

Platform specifics are IDE+module combination hooks that execute custom logic when specific IDE and module are installed together.

Two-Layer Architecture:

  1. Module-Level: src/modules/{module}/_module-installer/platform-specifics/{ide}.js

    • Module provides custom behavior for specific IDEs
    • Example: BMM creates subagents when installed with Claude Code

  2. IDE-Level: Embedded in IDE handler's createArtifacts() method

    • IDE provides custom handling for specific modules
    • Example: Windsurf configures cascade workflows for BMM

Execution Timing: After standard installation, before validation

Common Use Cases:

  • Creating subagent variations (PM-technical, PM-market)
  • Configuring IDE-specific workflow integrations
  • Adding custom commands or rules based on module features
  • Adjusting UI/UX for module-specific patterns

Platform Registry: tools/cli/installers/lib/ide/shared/platform-codes.js

Manifest System

The installer generates 5 manifest files in {target}/bmad/_cfg/:

1. Installation Manifest (manifest.yaml)

  • Installation metadata: version, timestamps, target directory
  • Installed modules and versions
  • Integrated IDEs and their configurations
  • User configuration values

2. Workflow Manifest (workflow-manifest.csv)

  • Columns: module, workflow_path, workflow_name, description, scale_level
  • Used by workflow command generators
  • RFC 4180 compliant CSV format

3. Agent Manifest (agent-manifest.csv)

  • Columns: module, agent_path, agent_name, role, identity_summary, communication_style, expertise, approach, responsibilities, workflows
  • 10-column metadata for each agent
  • Used by IDE integrations and documentation

4. Task Manifest (task-manifest.csv)

  • Legacy compatibility (deprecated in v6)
  • Columns: module, task_path, task_name, objective, agent

5. Files Manifest (files-manifest.csv)

  • Complete file tracking with SHA256 hashes
  • Columns: file_path, file_type, module, hash
  • Enables integrity validation and change detection

Generator: tools/cli/installers/lib/core/manifest-generator.js

Use Cases:

  • Update detection (compare current vs manifest hashes)
  • Workflow command generation for IDEs
  • Installation validation and integrity checks
  • Rollback capability

Advanced Features

Dependency Resolution (4-Pass System):

  • Pass 1: Explicit dependencies from module metadata
  • Pass 2: Template references in workflows
  • Pass 3: Cross-module workflow/agent references
  • Pass 4: Transitive dependencies

Agent Activation Injection:

  • Detects which handlers each agent uses (workflow, exec, tmpl, data, action)
  • Injects only needed handler fragments from src/utility/models/fragments/
  • Keeps compiled agents lean and purpose-built

Module Injection System:

  • Conditional content injection based on user config
  • Can inject menu items, text blocks, workflow steps
  • File: tools/cli/installers/lib/ide/shared/module-injections.js

Conflict Resolution:

  • Detects existing installations
  • Options: Update (preserve customizations), Backup (timestamp), Cancel
  • Auto-backup to .bmad-backup-{timestamp} if selected

Workflow Command Auto-Generation:

  • Reads workflow-manifest.csv
  • Generates IDE commands for each workflow
  • IDE-specific formatting (Claude Code .md, Windsurf YAML, etc.)

Validation & Integrity:

  • Verifies all manifest files exist
  • Validates file hashes against files-manifest.csv
  • Checks agent compilation completeness
  • Confirms IDE artifacts created

Bundling System

Web bundling creates self-contained XML packages with all dependencies embedded for web deployment.

Bundling Flow

1. Discover modules and agents from src/modules/
2. For each agent:
   - Compile with YamlXmlBuilder (forWebBundle: true)
   - Use web-bundle-activation-steps.xml fragment
   - Resolve ALL dependencies recursively:
     - Scan menu items for workflow references
     - Load workflows → extract web_bundle section
     - Find all file references (templates, data, sub-workflows)
     - Wrap each in <file id="path"><![CDATA[...]]></file>
   - Build consolidated bundle: agent + all deps
3. Output to: web-bundles/{module}/agents/{name}.xml

Key Differences from Installation:

  • No customize.yaml merging (base agents only)
  • No metadata (reduces file size)
  • All dependencies bundled inline (no filesystem access)
  • Uses web-specific activation fragment
  • Output: Standalone XML files

Output Structure:

web-bundles/
├── bmm/
│   ├── agents/
│   │   ├── pm.xml
│   │   ├── architect.xml
│   │   ├── sm.xml
│   │   └── dev.xml
│   └── teams/
│       └── dev-team.xml
├── bmb/
│   └── agents/
│       └── bmad-builder.xml
└── cis/
    └── agents/
        └── creative-director.xml

Bundler: tools/cli/bundlers/web-bundler.js

Agent Compilation

Both installation and bundling use the same YAML→XML compiler with different configurations.

Compilation Engine

Core File: tools/cli/lib/yaml-xml-builder.js

Process:

  1. Load YAML agent definition
  2. Merge with customize.yaml (installation only)
  3. Analyze agent to detect required handlers
  4. Build activation block:
    • IDE: Uses activation-steps.xml (filesystem-aware)
    • Web: Uses web-bundle-activation-steps.xml (bundled files)
  5. Convert to XML structure
  6. Output as markdown (IDE) or standalone XML (web)

Key Option Flags:

  • forWebBundle: true - Use web activation, omit metadata
  • includeMetadata: true - Include build hash (IDE only)
  • skipActivation: true - Omit activation (team bundles)

Fragment System

Reusable XML fragments in src/utility/models/fragments/:

  • activation-steps.xml - IDE activation (loads config.yaml at runtime)
  • web-bundle-activation-steps.xml - Web activation (uses bundled files)
  • activation-rules.xml - Validation rules (IDE only)
  • menu-handlers.xml - Menu handler wrapper
  • handler-workflow.xml - Workflow handler
  • handler-exec.xml - Exec command handler
  • handler-tmpl.xml - Template handler
  • handler-data.xml - Data handler
  • handler-action.xml - Action handler

Dynamic Injection: Agent analyzer detects which handlers are used, activation builder injects only those fragments.

Input: Agent YAML

agent:
  metadata:
    id: 'bmad/bmm/agents/pm.md'
    name: 'PM'
    title: 'Product Manager'
  persona:
    role: 'Product Manager'
    identity: 'You are an experienced PM...'
  menu:
    - trigger: '*create-brief'
      workflow: '{project-root}/bmad/bmm/workflows/.../workflow.yaml'

Output: IDE (Markdown with XML)

<!-- Powered by BMAD-CORE™ -->

# Product Manager

```xml
<agent id="..." name="PM">
  <activation critical="MANDATORY">
    <step n="2">Load {project-root}/bmad/bmm/config.yaml at runtime</step>
    ...
  </activation>
  <persona>...</persona>
  <menu>...</menu>
</agent>
```


### Output: Web (Standalone XML)

```xml
<agent id="..." name="PM">
  <activation critical="MANDATORY">
    <step n="2">All dependencies bundled inline below</step>
    ...
  </activation>
  <persona>...</persona>
  <menu>...</menu>
  <bundled-files>
    <file id="bmad/bmm/config.yaml"><![CDATA[...]]></file>
    <file id="bmad/bmm/workflows/.../workflow.yaml"><![CDATA[...]]></file>
    ...
  </bundled-files>
</agent>

Architecture

Directory Structure

tools/cli/
├── bmad-cli.js                 # Main CLI entry
├── commands/                   # CLI command handlers
│   ├── install.js
│   ├── status.js
│   ├── list.js
│   ├── update.js
│   └── uninstall.js
├── bundlers/                   # Web bundling
│   ├── bundle-web.js          # CLI entry
│   └── web-bundler.js         # WebBundler class
├── installers/
│   └── lib/
│       ├── core/              # Core installer logic
│       │   ├── installer.js
│       │   ├── manifest-generator.js
│       │   ├── manifest.js
│       │   ├── dependency-resolver.js
│       │   ├── config-collector.js
│       │   └── csv-parser.js
│       ├── modules/           # Module processing
│       │   └── manager.js
│       └── ide/               # IDE integrations
│           ├── _base-ide.js
│           ├── {14 IDE handlers}.js
│           ├── manager.js
│           └── shared/
│               ├── bmad-artifacts.js
│               ├── platform-codes.js
│               ├── module-injections.js
│               └── workflow-command-generator.js
├── lib/                       # Shared compilation
│   ├── yaml-xml-builder.js   # YAML→XML compiler
│   ├── activation-builder.js # Activation generator
│   ├── agent-analyzer.js     # Handler detection
│   ├── xml-handler.js        # Builder wrapper
│   └── paths.js
├── regenerate-manifests.js
└── test-yaml-builder.js

Fragment Library

src/utility/models/fragments/
├── activation-steps.xml
├── web-bundle-activation-steps.xml
├── activation-rules.xml
├── menu-handlers.xml
└── handler-*.xml              # 5 handler types

Key Differences: Installation vs Bundling

Aspect Installation (IDE) Bundling (Web)
Trigger npm run install:bmad npm run bundle
Entry Point commands/install.js bundlers/bundle-web.js
Compiler Flag forWebBundle: false forWebBundle: true
Output Format Markdown .md Standalone XML .xml
Output Location {target}/bmad/ + IDE dirs web-bundles/
Customization Merges customize.yaml Base agents only
Dependencies Referenced by path Bundled inline (CDATA)
Activation Fragment activation-steps.xml web-bundle-activation-steps.xml
Filesystem Access Required Not needed
Build Metadata Included (hash) Excluded
Path Format {project-root} placeholders Stripped, wrapped as <file>
Use Case Local IDE development Web deployment

Activation Differences:

  • IDE: Loads config.yaml at runtime from filesystem
  • Web: Accesses bundled content via <file id> references

Development Workflows

Testing Compilation

# Test YAML→XML compiler
node tools/cli/test-yaml-builder.js

# Test installation
node tools/cli/bmad-cli.js install --target ./test-project --modules bmm --ides codex

# Test bundling
node tools/cli/bundlers/bundle-web.js agent bmm pm

# Validate bundles
npm run validate:bundles

Adding New Menu Handlers

To add a new handler type (e.g., validate-workflow):

  1. Create fragment: src/utility/models/fragments/handler-validate-workflow.xml
  2. Update agent-analyzer.js to detect the new attribute
  3. Update activation-builder.js to load/inject the fragment
  4. Test with an agent using the handler

Regenerating Manifests

# Regenerate agent-party.xml for all modules
node tools/cli/regenerate-manifests.js

# Location: src/modules/{module}/agents/agent-party.xml

Related Documentation

  • Project Guide: CLAUDE.md
  • BMM Workflows: src/modules/bmm/workflows/README.md
  • Module Structure: src/modules/bmb/workflows/create-module/module-structure.md
  • Agent Creation: src/modules/bmb/workflows/create-agent/README.md

Support