feat: add bmad-method installer over the skills CLI

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run check
+      - run: npm test

.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+      - run: npm ci
+      - run: npm test
+      - run: npm publish --provenance --access public --tag next

README.md

@@ -1,5 +1,121 @@
-# bmad-installer
+# bmad-method
 
-Installs and updates BMad Method modules. A thin wrapper around `npx skills`.
+## What it does
 
-Published to npm as `bmad-method`. Run it with `npx bmad-method`.
+`bmad-method` installs BMad modules into a project as agent skills. It asks which modules you want, runs the Vercel skills CLI (the `skills` npm package, shipped as a dependency) to install them, then reads the install with the `bmad` skill's setup script and prints a report. It copies no files itself, keeps no state of its own, and never removes anything.
+
+## Install commands
+
+Needs Node 22 or newer and [uv](https://docs.astral.sh/uv/getting-started/installation/) on your PATH.
+
+```
+npx bmad-method            install into the current directory
+npx bmad-method install    the same thing
+npx bmad-method update     update the BMad skills already installed
+npx bmad-method status     show what is installed and what is still missing
+```
+
+## Example
+
+Interactive, in a terminal:
+
+```
+npx bmad-method
+```
+
+It asks where to install, which modules and which parts of each module you want. The first skills install then hands over to the skills CLI, which shows its own agent picker if it finds none or several coding agents in the project. Later installs in the same run reuse that pick. The closing message names the directory and tells you to run `bmad setup` in your coding agent.
+
+Headless, for scripts and CI:
+
+```
+npx bmad-method install -d ./my-app -m method:planning+build,cis -t claude-code,codex -y
+```
+
+## Where it can run
+
+An interactive run needs a real terminal. It refuses to start inside a coding agent such as Claude Code or Codex, because the prompts cannot be answered there. Add `--yes` to run without prompts anywhere. `update` and `status` never prompt.
+
+## Choosing coding agents
+
+The installer keeps no list of coding agents. Agent ids and detection come from the skills CLI.
+
+- Interactive without `--tools`: the skills CLI detects agents and shows its picker when it needs a choice. The pick is reused for the rest of the run.
+- `--tools <ids>`: every install goes to those agents and the picker never shows. The [skills CLI README](https://github.com/vercel-labs/skills#supported-agents) lists the valid ids.
+- `--yes` without `--tools`: the skills CLI chooses from the agents it detects.
+
+## Where skills land
+
+The skills CLI decides. With one agent it copies the skills into that agent's folder, for example `.claude/skills`. With several agents it writes them once to `.agents/skills` and links each agent's folder to them. `npx bmad-method status` reads the real locations with `npx skills list`.
+
+## Flags
+
+| Flag | What it does |
+| --- | --- |
+| `-d, --directory <path>` | Project directory, default the current one |
+| `-m, --modules <spec>` | Modules to install, e.g. `method:planning+build,cis` |
+| `-t, --tools <ids>` | Comma-separated skills CLI agent ids to install to |
+| `-y, --yes` | Take the defaults and ask nothing |
+| `--action <name>` | `install`, `update` or `quick-update`. Kept so scripts written for the 6.12 installer still work |
+| `--no-telemetry` | Turn off skills CLI telemetry and the skills.sh install counts |
+| `--copy` | Copy skills instead of linking, if symlinks fail on your system |
+| `--debug` | Print every child command, its cwd and its output to stderr |
+| `-h, --help` | Show the help |
+| `-v, --version` | Show the version |
+
+`--modules` takes module codes. `method` (alias `bmm`) has the bundles `planning`, `build`, `agents` and `extras`; `cis` has none. A module named without `:` takes its default bundles. The core tools module installs on every run.
+
+A 6.12 flag this installer dropped prints one line about it, then exits without installing.
+
+## What the closing message tells you
+
+The closing message names the directory BMad went into and asks you to open your coding agent there and tell it to run `bmad setup`. Setup asks the configuration questions and finishes the install. Configuration and customization belong to the `bmad` skill from then on; this installer never asks those questions.
+
+## Updating
+
+Three routes: ask the `bmad` skill, run `npx bmad-method update`, or run `npx skills update`.
+
+`npx bmad-method update` runs the skills CLI update over the project's skills, then prints the status report and any migrations for the version jump.
+
+After adding or updating any skill by any route, ask the `bmad` skill to update. Only it reconciles what is installed.
+
+## Removing
+
+`npx skills remove` removes skills. This installer has no uninstall command and never removes anything.
+
+## Installing with the skills CLI directly
+
+If you install with the skills CLI directly, a module is its `bmod-<code>` record skill plus the skills that record lists. A record without its skills, or skills without their record, is a partial install: the `bmad` skill cannot see or run it. `npx bmad-method status` lists missing records and unmet requirements.
+
+## Troubleshooting
+
+- `status` and `update` take 5 to 10 seconds. The `bmad` skill's setup script reads each module's record from GitHub on every call.
+- `npx skills update` currently skips the `bmad` skill because BMAD-METHOD ships a second `bmad` SKILL.md in a test fixture.
+- `npx skills update` re-adds skills without the agent list, which can change where they land. `npx bmad-method update` has the same limit.
+- Symlink errors on Windows: add `--copy`.
+- `--debug` prints every child command with its output.
+
+## Telemetry
+
+The installer sends nothing. The skills CLI it runs sends two GET requests to `add-skill.vercel.sh`: an audit call to `https://add-skill.vercel.sh/audit` before an install, carrying the `owner/repo` and the skill names, and an install event to `https://add-skill.vercel.sh/t` after it, carrying the source, the skill names, the agent ids and the CLI version. The install event goes out only for a public GitHub repo. The audit call is not gated on repo visibility: it goes out for a private GitHub repo too. A local path sends neither. No file contents leave the machine. The install event carries the metadata this installer attaches: `{"installer":"bmad-method","version":"<installer version>"}`.
+
+`--no-telemetry` sets `DO_NOT_TRACK=1` in every skills CLI process the installer starts. That also removes those installs from the install counts on skills.sh.
+
+`DO_NOT_TRACK` or `DISABLE_TELEMETRY` set in your own environment turns telemetry off for every skills command, including the ones you run yourself.
+
+## Reproducible installs
+
+The skills CLI writes `skills-lock.json` in the project. Commit it. `npx skills experimental_install` restores the skills recorded there.
+
+## Testing
+
+`npm test` runs the unit tests with `node --test`. `npm run check` runs `tsc` over `bin`, `src` and `test`.
+
+`npm run e2e` runs the end-to-end install. It skips itself unless `BMAD_INSTALLER_E2E_SOURCE` points at a local BMAD-METHOD checkout. The test passes that path to the child run as `BMAD_INSTALLER_SOURCE_OVERRIDE`, which makes module loading replace every module's source with it. Set `BMAD_INSTALLER_E2E_DEBUG` to log every child command. `BMAD_INSTALLER_SOURCE_OVERRIDE` exists for this test; do not set it for a real install.
+
+## Releasing
+
+See [tools/release.md](tools/release.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

bin/bmad-method.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js'
+
+process.exitCode = await main(process.argv.slice(2))

messages.yaml

@@ -0,0 +1,174 @@
+intro: |-
+  BMad Installer installs BMad modules as agent skills.
+  It is free and open source.
+  Installs run through the skills CLI (npx skills). You need uv installed.
+
+  Docs     https://docs.bmad-method.org
+  GitHub   https://github.com/bmad-code-org/BMAD-METHOD
+  Discord  https://discord.gg/gk8jAdXWmj
+  YouTube  https://www.youtube.com/@BMadCode
+  X        https://x.com/BMadCode
+
+  Support: star the repo, https://buymeacoffee.com/bmad
+  Contact: contact@bmadcode.com
+
+updateAvailable: |-
+  You are using version {current} but {latest} is available.
+  To update, exit and first run:
+  npm cache clean --force && npx bmad-method@{tag} install
+
+nodeTooOld: |-
+  Node {version} is too old. This installer needs Node 22 or newer.
+  Install Node 22, then run this again.
+
+nodeBelowSkillsFloor: |-
+  Node {version} is below the 22.20.0 the skills CLI asks for.
+  Installs usually still work. Upgrade Node if you hit errors.
+
+uvMissing: |-
+  uv is not installed. The BMad scripts need it.
+  Install it with:
+  {installCommand}
+  More ways: https://docs.astral.sh/uv/getting-started/installation/
+
+uvInstall:
+  darwin: "curl -LsSf https://astral.sh/uv/install.sh | sh"
+  linux: "curl -LsSf https://astral.sh/uv/install.sh | sh"
+  win32: 'powershell -c "irm https://astral.sh/uv/install.ps1 | iex"'
+
+wslWindowsNode: |-
+  This is Windows Node.js started from a WSL shell.
+  Install Node inside WSL and run this again from the WSL terminal.
+
+needsTerminal: |-
+  This installer needs an interactive terminal.
+  Run it in a terminal, or add --yes to install without prompts.
+
+insideAgent: |-
+  This is running inside {agent}.
+  Run the installer in a terminal, or add --yes to install without prompts.
+
+directoryPrompt: "Where should BMad be installed?"
+
+directoryCreateConfirm: "{directory} does not exist. Create it?"
+
+directoryConfirm: "Install into {directory}?"
+
+legacyManifest: |-
+  Found an older BMad install at _bmad/_config/manifest.yaml.
+  This installer leaves it alone.
+
+existingInstallPrompt: "BMad is already installed here. What do you want to do?"
+
+existingInstallModify: "Add or change modules"
+
+existingInstallUpdate: "Update what is installed"
+
+foundModules: "Found these modules:"
+
+installedSuffix: "(installed {version})"
+
+installedSuffixNoVersion: "(installed)"
+
+modulesPrompt: "Which modules do you want?"
+
+bundlesPrompt: "Which parts of {module} do you want?"
+
+deprecatedModule: "{module} is deprecated. {reason}"
+
+beforeSkillsPicker: |-
+  The skills CLI takes over for the first install.
+  Pick the coding agents to install to.
+  If it asks for a scope, keep Project.
+  If it asks for a method, keep Symlink.
+  Confirm, and this installer picks up again when it is done.
+
+firstInstallNotInProject: |-
+  The skills CLI did not install into {directory}.
+  Nothing was added to this project.
+  If you picked Global scope, the skills went to the global skills dir.
+  Run the installer again and keep the Project scope.
+
+bundleSkillUnknown: "Skipped skills that {module} no longer lists: {skills}"
+
+installingSpinner: "Installing {what}"
+
+statusSpinner: "Reading the BMad install"
+
+nothingToUpdate: "No BMad install here to update. Run npx bmad-method install first."
+
+nothingInstalled: "There is no BMad install here. Run npx bmad-method install first."
+
+updateSpinnerDone: "Update finished"
+
+migrationsAvailable: "Migrations are available for this upgrade:"
+
+migrationLine: "{title} ({module}, {from} to {to})"
+
+reportTitle: "BMad install"
+
+reportCurrent: "Everything the modules ask for is in place."
+
+reportNotCurrent: "Not finished yet. Next: {next}"
+
+reportModule: "{name} {version}, {count} skills installed"
+
+reportAlsoAvailable: "  Also in {code}: {skills}"
+
+reportMissingRecord: "  Missing module record. Install it with: {install}"
+
+reportUnmet: "  {skill} needs {requires} {minimum} ({state}). Install it with: {install}"
+
+reportPendingQuestions: "{count} setup questions are still unanswered."
+
+reportProblem: "Problem: {message}"
+
+reportLegacy: "Left over from an older install: {path}"
+
+reportFailure: "Failed to install {skill}: {error}"
+
+closing: |-
+  BMad is installed in:
+  {directory}
+  Open your coding agent in this directory.
+
+  Ask it to run: bmad setup
+  Setup asks the configuration questions and finishes the install.
+  Configuration and customization are its job from now on.
+
+  Three ways to change this install later:
+    ask the bmad skill
+    npx bmad-method update
+    npx skills update
+
+  npx skills remove removes skills. This installer never removes anything.
+
+  Going direct with the skills CLI: a module is its bmod-<code> record
+  skill plus the skills it requires.
+  A partial install is one the bmad skill cannot see or run.
+
+  After adding or updating any skill by any route,
+  ask the bmad skill to update. Only it reconciles what is installed.
+
+cancelled: "Cancelled. Anything already installed is still there."
+
+droppedFlags:
+  custom-source: "--custom-source is gone. Install those with npx skills add <source>."
+  set: "--set is gone. The bmad setup skill asks these questions."
+  list-options: "--list-options is gone. The bmad setup skill asks these questions."
+  user-name: "--user-name is gone. The bmad setup skill asks these questions."
+  communication-language: "--communication-language is gone. The bmad setup skill asks these questions."
+  document-output-language: "--document-output-language is gone. The bmad setup skill asks these questions."
+  output-folder: "--output-folder is gone. The bmad setup skill asks these questions."
+  channel: "--channel is gone. Modules install from each repo's main branch."
+  all-stable: "--all-stable is gone. Modules install from each repo's main branch."
+  all-next: "--all-next is gone. Modules install from each repo's main branch."
+  next: "--next is gone. Modules install from each repo's main branch."
+  pin: "--pin is gone. Modules install from each repo's main branch."
+  shims: "--shims is gone. Shims are no longer shipped."
+  no-shims: "--no-shims is gone. Shims are no longer shipped."
+  list-tools: "--list-tools is gone. Tool ids are the skills CLI --agent ids; a wrong one lists the valid ones."
+
+droppedUninstall: |-
+  This installer does not remove anything.
+  Remove skills with npx skills remove.

modules.yaml

@@ -0,0 +1,45 @@
+modules:
+  - code: core-tools
+    name: BMad Core Tools
+    description: Brainstorming, research, review, party mode, customization
+    source: bmad-code-org/BMAD-METHOD
+    record: bmod-core-tools
+    always: true
+
+  - code: method
+    aliases: [bmm]
+    name: BMad Method
+    description: Plan, spec and build software with agile AI agents
+    source: bmad-code-org/BMAD-METHOD
+    record: bmod-method
+    default: true
+    message: |
+      BMad Method is installed.
+      Once setup is done, ask the `bmad` skill what to do next.
+    bundles:
+      - code: planning
+        name: Planning
+        description: Brief, PRD, UX, architecture, spec
+        default: true
+        skills: [bmad-product-brief, bmad-prfaq, bmad-prd, bmad-ux, bmad-architecture, bmad-spec, bmad-project-context]
+      - code: build
+        name: Build
+        description: Epics and stories, sprint planning, build, review, course correction, retrospective
+        default: true
+        skills: [bmad-create-epics-and-stories, bmad-sprint-planning, bmad-build, bmad-build-auto, bmad-code-review, bmad-correct-course, bmad-retrospective, bmad-qa-generate-e2e-tests]
+      - code: agents
+        name: Agent personas
+        description: Analyst, architect, developer, PM and UX designer agents
+        default: true
+        skills: [bmad-agent-analyst, bmad-agent-architect, bmad-agent-dev, bmad-agent-pm, bmad-agent-ux-designer]
+      - code: extras
+        name: Extras
+        description: Preview ticketing and the walkthrough
+        default: false
+        skills: [bmad-preview-ticketing, bmad-walkthrough]
+
+  - code: cis
+    name: BMad Creative Intelligence Suite
+    description: Innovation, brainstorming, problem-solving
+    source: bmad-code-org/bmad-module-creative-intelligence-suite
+    record: bmod-cis