BMAD-METHOD/src/core-skills/bmad-module

bmad-module

The core BMAD skill for installing, updating, removing, and listing community BMAD modules. Modules are standalone GitHub repos that conform to the BMAD Module Manifest Spec.

How it fits

• Authors publish a single repo with .claude-plugin/plugin.json that works in both Claude Code's plugin marketplace and BMAD-METHOD.
• Users install via this skill — no CLI required. Modules are staged under _bmad/<bmad.code>/, then their skills are distributed to the coding assistants the user chose at bmad install time (the ides: list in _bmad/_config/manifest.yaml), exactly like official modules.
• BMAD-METHOD treats community-installed modules as a new source: 'community' row in manifest.yaml; re-running bmad install preserves them (manifest-generator.js carries source: 'community' rows through regeneration).

Verbs

bmad-module install <source> [--ref <r>] [--channel <c>] [--dry-run]
bmad-module update  <code|--all> [--ref <r>] [--channel <c>]
bmad-module remove  <code> [--purge]
bmad-module list    [--json]

<source> accepts owner/repo, a full git URL, or a local path.

Behavior notes

• Source of truth for what was installed is _bmad/_config/files-manifest.csv (per-file hashes) and _bmad/_config/skill-manifest.csv (one row per shipped skill). manifest.yaml carries the source/version/sha tuple.
• update refuses to overwrite locally-modified files (hash mismatch against the recorded hash). Move overrides into _bmad/custom/<code>/ and retry.
• remove without --purge preserves _bmad/custom/<code>/ so a re-install picks the customizations back up. --purge deletes them. Remove also prunes the module's skills from every configured IDE.
• IDE distribution runs after every install/update/remove via a self-contained bundle of BMAD's real IDE engine, shipped at lib/vendor/ide-sync.mjs (built from tools/installer/ide/* by lib/vendor/build-ide-sync.mjs, gated by vendor:check). The skill execs it locally — no npx, no network. The same engine also backs the bmad ide-sync CLI command and the full installer's IDE setup, so all three stay in lockstep. If the bundle is unreachable on an older install, the skill says so and points the user at bmad ide-sync.
• Hooks / MCP / LSP / Claude subagents declared in the module manifest are copied but NOT auto-activated by this skill (they are Claude Code plugin surfaces, not skills). Use Claude Code's plugin manager to wire them up.

Implementation

The skill itself is a thin verb router (SKILL.md). scripts/bmad-module.mjs is a zero-import launcher that guards the import graph (a missing/corrupt runtime file becomes a documented exit code, not a raw stack trace); the verb dispatcher lives in scripts/cli.mjs and all filesystem work happens in the lib/ modules. These carry no registry dependencies — important because the installer copies the skill into the IDE skills directories (e.g. .claude/skills/bmad-module/) without node_modules and never runs npm install there:

• manifest.yaml is read/written with a vendored copy of the real yaml library (lib/vendor/yaml.mjs, regenerated by lib/vendor/build-vendor.mjs) so it stays byte-identical to BMAD core's writer.
• semver validity/range checks use a small node:-only helper (lib/semver-lite.mjs).

Exit codes

See SKILL.md for the full table. The script's stderr always names the condition; the codes are stable so tooling can branch.

Tests

Integration tests live in tests/integration.test.sh and run end-to-end on a fresh BMAD install. Fixtures for negative cases (collisions, path traversal, reserved codes) are under tests/fixtures/.