diff --git a/src/core-skills/bmad-module/SKILL.md b/src/core-skills/bmad-module/SKILL.md index 690bb8251..64a67feec 100644 --- a/src/core-skills/bmad-module/SKILL.md +++ b/src/core-skills/bmad-module/SKILL.md @@ -5,9 +5,9 @@ description: Install, update, remove, or list community BMAD modules. Use when t # bmad-module -Manage community BMAD modules — installable packages of skills, agents, and supporting assets that ship as standalone GitHub repos. Modules are staged under `_bmad//` and tracked in the existing manifests. On `install`, `update`, and `remove`, the script then distributes (or prunes) the module's skills to **every coding assistant the user selected when they ran `bmad install`** — read from the `ides:` list in `_bmad/_config/manifest.yaml` — so a community module lands in Claude Code, Cursor, Copilot, etc. exactly like an official module. As with official modules, the canonical end state is skills living in the IDE directories (e.g. `.claude/skills//`), not in `_bmad/`. The same artifact is also loadable as a Claude Code plugin via its `.claude-plugin/plugin.json` manifest. +Manage community BMAD modules — installable packages of skills, agents, and supporting assets that ship as standalone GitHub repos. Modules are staged under `_bmad//` and tracked in the existing manifests. On `install`, `update`, and `remove`, the script distributes (or prunes) the module's skills to **every coding assistant the user selected at `bmad install`** — read from the `ides:` list in `_bmad/_config/manifest.yaml` — so the module lands in Claude Code, Cursor, Copilot, etc. The canonical end state is skills living in the IDE directories (e.g. `.claude/skills//`), not in `_bmad/`. The same artifact also loads as a Claude Code plugin via its `.claude-plugin/plugin.json` manifest. -To match the full `bmad install` for custom modules, the script also completes the install in place: it installs npm dependencies when the module ships a `package.json` (opt out with `bmad.install.skipNpm: true`), generates the module's `[modules.]` / `[agents.]` blocks in `_bmad/config.toml` and `config.user.toml` from its `module.yaml` (defaults, overridable with `--set`), creates the working directories the module declares under `directories:`, and rebuilds the merged `_bmad/_config/bmad-help.csv` so the module's skills show up in `bmad-help`. These steps are best-effort — a failure in any of them is reported as a warning, not a failed install. Interactive config refinement remains the job of the module's `postInstallSkill`, if it declares one. +The script also completes the install in place, best-effort: it runs `npm install` when the module ships a `package.json` (skip with `bmad.install.skipNpm: true`), generates the module's `[modules.]` / `[agents.]` config blocks from its `module.yaml` (overridable with `--set`), creates the working directories it declares under `directories:`, and rebuilds `_bmad/_config/bmad-help.csv` so its skills appear in `bmad-help`. A failure in any of these is reported as a warning, not a failed install. Interactive config refinement remains the job of the module's `postInstallSkill`, if it declares one. ## CRITICAL RULES @@ -34,7 +34,7 @@ If the verb is ambiguous (e.g. the user says "manage modules"), ASK which verb t ### Step 2 — Parse the args - **install:** the user supplies `` — `owner/repo` (GitHub short), a full git URL (`https://…` or `git@…`), or a local path. Optional flags: `--ref `, `--channel `, `--set .=` (override a module config answer; repeatable), `--dry-run`. -- **update:** the user supplies `` (the `_bmad//` folder name) or asks for "all"; in that case use `--all`. Optional `--ref`, `--set .=`. +- **update:** the user supplies `` (the `_bmad//` folder name) or asks for "all"; in that case use `--all`. Optional `--ref`, `--channel `, `--set .=`. - **remove:** the user supplies ``. Use `--purge` only if they explicitly say "also remove customizations" or "purge". - **list:** no args. Use `--json` if the user asks for machine-readable. @@ -59,7 +59,7 @@ Run from the project root (the dir containing `_bmad/`): node /scripts/bmad-module.mjs [args...] ``` -`` is this skill's own directory — the script ships alongside this `SKILL.md`, so it lives wherever `bmad install` distributed skills for the coding assistant you're running under. That's `/bmad-module/` (e.g. `.claude/skills/bmad-module/` for Claude Code, `.agents/skills/bmad-module/` for Cursor/Copilot/etc.), making the script `/bmad-module/scripts/bmad-module.mjs`. During development in this repo it's `src/core-skills/bmad-module/scripts/bmad-module.mjs`. Resolve it relative to this `SKILL.md` rather than assuming a fixed path. If the script isn't found next to it, the skill's bundled runtime is missing — that's the exit-code-5 case (see CRITICAL RULES and EXIT CODES): relay the "reinstall the skill" guidance rather than guessing another location. +`` is this skill's own directory: the script ships alongside this `SKILL.md`, so resolve it relative to this file rather than assuming a fixed path — `/scripts/bmad-module.mjs` (e.g. `.claude/skills/bmad-module/scripts/bmad-module.mjs` once distributed, or `src/core-skills/bmad-module/scripts/bmad-module.mjs` during development in this repo). If the script isn't found next to this `SKILL.md`, the skill's bundled runtime is missing — that's the exit-code-5 case (see CRITICAL RULES and EXIT CODES): relay the "reinstall the skill" guidance rather than guessing another location. Stream stdout and stderr verbatim. Do NOT silence or rewrite them — the script's own messages are designed for end-user consumption. @@ -76,21 +76,16 @@ On non-zero exit: print the exit code, the stderr message, and stop. Do not sugg ## EXIT CODES -| Code | Meaning | -| ---- | ------------------------------------------------------------------------------------------------------------- | -| 0 | success | -| 2 | usage error (bad/missing args or flags) | -| 5 | skill runtime files missing/corrupt — reinstall the skill (a setup/packaging problem, NOT a module rejection) | -| 10 | no `_bmad/` directory in project — run `bmad install` first | -| 20 | missing or invalid `.claude-plugin/plugin.json` in source | -| 21 | module uses a reserved `bmad.code` | -| 30 | prefix collision with an already-installed module | -| 40 | module would write outside its `_bmad//` root | -| 50 | filesystem commit (atomic swap) failed | -| 60 | network or `git clone` failed | -| 70 | path traversal detected in manifest | -| 80 | update aborted: locally modified files would be overwritten | -| 90 | no such installed module (for `update`/`remove`) | +The script's stderr always names the condition, so for most non-zero exits you just relay it (see CRITICAL RULES). These few change what you tell the user next: + +| Code | Meaning | What to tell the user | +| ---- | ------------------------------------------------------------------- | ----------------------------------------------------------------- | +| 5 | skill runtime files missing/corrupt — NOT a module rejection | reinstall the skill (relay the script's guidance) | +| 10 | no `_bmad/` directory in project | run `bmad install` first | +| 80 | update aborted: locally modified files would be overwritten | move overrides into `_bmad/custom//`, then retry | +| 90 | no such installed module (for `update`/`remove`) | check the code, or run `list` to see what's installed | + +Any other non-zero exit: report the code and stderr verbatim and stop — stderr names the condition. For the full list of codes, run the script with `--help`. ## EXAMPLES diff --git a/src/core-skills/bmad-module/scripts/cli.mjs b/src/core-skills/bmad-module/scripts/cli.mjs index 1293a3b7d..531e78d5e 100644 --- a/src/core-skills/bmad-module/scripts/cli.mjs +++ b/src/core-skills/bmad-module/scripts/cli.mjs @@ -174,7 +174,6 @@ EXIT CODES 20 missing or invalid plugin.json 21 reserved bmad.code 30 prefix collision with existing module - 40 file overlap outside the module root 50 filesystem commit failed 60 network/git clone failed 70 path traversal in manifest diff --git a/src/core-skills/bmad-module/scripts/lib/exit.mjs b/src/core-skills/bmad-module/scripts/lib/exit.mjs index 7a8a00c7d..89f43d7d0 100644 --- a/src/core-skills/bmad-module/scripts/lib/exit.mjs +++ b/src/core-skills/bmad-module/scripts/lib/exit.mjs @@ -13,7 +13,6 @@ export const EXIT = { BAD_MANIFEST: 20, RESERVED_PREFIX: 21, PREFIX_COLLISION: 30, - FILE_OVERLAP: 40, COMMIT_FAILURE: 50, NETWORK_FAILURE: 60, PATH_TRAVERSAL: 70,