bmad-code-org__bmad-method/docs/how-to/upgrade-to-v6.md at feat-set-flag-1663

mirror of https://github.com/bmad-code-org/BMAD-METHOD.git synced 2026-09-19 08:11:52 +08:00

Files

T

Brian 97d32405d0 feat(installer): universal source support for custom module installs (#2233 )

* feat(installer): add plugin resolution strategies for custom URL installs

When installing from a custom GitHub URL, the installer now analyzes
marketplace.json plugin structures to determine how to locate module
registration files (module.yaml, module-help.csv). Five strategies
are tried in cascade:

1. Root module files at the common parent of listed skills
2. A -setup skill with registration files in its assets/
3. Single standalone skill with registration files in assets/
4. Multiple standalone skills, each with their own registration files
5. Fallback: synthesize registration from marketplace.json metadata
   and SKILL.md frontmatter

Also changes the custom URL flow from confirm-all to multiselect,
letting users pick which plugins to install. Already-installed modules
are pre-checked for update; new modules are unchecked for opt-in.

New file: tools/installer/modules/plugin-resolver.js
Modified: custom-module-manager.js, official-modules.js, ui.js

* fix(installer): address PR review findings for plugin resolver

- Guard against path traversal in plugin-resolver.js: skill paths from
  unverified marketplace.json are now constrained to the repo root using
  path.resolve() + startsWith check
- Skip npm install during browsing phase: cloneRepo() accepts
  skipInstall option, used in ui.js before user confirms selection,
  preventing arbitrary lifecycle script execution from untrusted repos
- Add createModuleDirectories() call to installFromResolution() so
  modules with declarative directory config are fully set up
- Fix ESLint: use replaceAll instead of replace with global regex

* fix(installer): pass version and repoUrl to manifest for custom plugins

installFromResolution was passing empty strings for version and repoUrl,
which the manifest stores as null. Now threads the repo URL from ui.js
through resolvePlugin into each ResolvedModule, and passes the plugin
version and URL to the manifest correctly.

* fix(installer): manifest-generator overwrites custom module version/repoUrl

ManifestGenerator rebuilds the entire manifest via getModuleVersionInfo
for every module. For custom modules, this returned null for version and
repoUrl because it only checked _readMarketplaceVersion (which searches
for marketplace.json on disk) and hardcoded repoUrl to null. Now checks
the resolution cache first to get the correct version and repo URL.

* fix(installer): resolve custom modules from disk cache on quick update

When the resolution cache is empty (fresh CLI process, e.g. quick
update), findModuleSourceByCode only matched plugin.name against the
module code. This failed for modules like "sam" and "dw" where the
code comes from module.yaml inside a setup/standalone skill, not from
the plugin name in marketplace.json.

Now runs the PluginResolver on cached repos when the direct name match
fails, finding the correct module source and re-populating the cache
for the install pipeline.

* feat(installer): universal source support for custom modules

Replace GitHub-only custom module installation with support for any Git
host (GitHub, GitLab, Bitbucket, self-hosted) and local file paths.

- Add parseSource() universal input parser (local paths, SSH, HTTPS with
  deep path/subdir extraction for GitHub, GitLab, Gitea)
- Add resolveSource() coordinator: parse -> clone if URL -> detect
  discovery vs direct mode (marketplace.json present or not)
- Clone-first approach eliminates host-specific raw URL fetching
- 3-level cache structure (host/owner/repo) with .bmad-source.json
  metadata for URL reconstruction
- Local paths install directly without caching; localPath persisted in
  manifest for quick-update source lookup
- Direct mode scans target directory for SKILL.md when no marketplace.json
- Fix version display bug where walk-up found parent repo marketplace.json
  and reported wrong version for custom modules

* fix(installer): harden readMarketplaceJsonFromDisk and hoist require

- Add try/catch to readMarketplaceJsonFromDisk so malformed JSON returns
  null instead of throwing an unhandled parse error
- Hoist CustomModuleManager require outside the per-module loop in
  _installOfficialModules

* fix(installer): restore validateGitHubUrl strictness and fix prettier

- Restore original GitHub-only regex in deprecated validateGitHubUrl
  wrapper so existing tests pass (rejects non-GitHub URLs, trailing
  slashes)
- Run prettier to fix formatting in custom-module-manager.js

* feat(installer): add --custom-source CLI flag for non-interactive installs

Allows installing custom modules from Git URLs or local paths directly
from the command line without interactive prompts:

  npx bmad-method install --custom-source /path/to/module
  npx bmad-method install --custom-source https://gitlab.com/org/repo
  npx bmad-method install --custom-source /path/one,https://host/org/repo

Works alongside --modules and --yes flags. All discovered modules from
each source are auto-selected.

* docs: add custom and community module installation guide

New how-to page covering community module browsing, custom sources (any
Git host, local paths), discovery vs direct mode, local development
workflow, and the --custom-source CLI flag. Clarifies that
.claude-plugin/ is a cross-tool convention, not Claude-specific.

Also updates non-interactive installation docs with the new flag and
examples, bumps sidebar ordering, and fixes --custom-source to install
only core + custom modules when --modules is not specified.

2026-04-09 18:44:40 -05:00

3.6 KiB

Raw Permalink Blame History

title, description, sidebar

title

description

sidebar

How to Upgrade to v6

Migrate from BMad v4 to v6

order
4

Use the BMad installer to upgrade from v4 to v6, which includes automatic detection of legacy installations and migration assistance.

When to Use This

You have BMad v4 installed (.bmad-method folder)
You want to migrate to the new v6 architecture
You have existing planning artifacts to preserve

:::note[Prerequisites]

Node.js 20+
Existing BMad v4 installation :::

Steps

1. Run the Installer

Follow the Installer Instructions.

2. Handle Legacy Installation

When v4 is detected, you can:

Allow the installer to back up and remove .bmad-method
Exit and handle cleanup manually

If you named your bmad method folder something else - you will need to manually remove the folder yourself.

3. Clean Up IDE Skills

Manually remove legacy v4 IDE commands/skills - for example if you have Claude Code, look for any nested folders that start with bmad and remove them:

.claude/commands/

The new v6 skills are installed to:

.claude/skills/

4. Migrate Planning Artifacts

If you have planning documents (Brief/PRD/UX/Architecture):

Move them to _bmad-output/planning-artifacts/ with descriptive names:

Include PRD in filename for PRD documents
Include brief, architecture, or ux-design accordingly
Sharded documents can be in named subfolders

If you're mid-planning: Consider restarting with v6 workflows. Use your existing documents as inputs—the new progressive discovery workflows with web search and IDE plan mode produce better results.

5. Migrate In-Progress Development

If you have stories created or implemented:

Complete the v6 installation
Place epics.md or epics/epic*.md in _bmad-output/planning-artifacts/
Run the Developer's bmad-sprint-planning workflow
Tell the agent which epics/stories are already complete

What You Get

v6 unified structure:

your-project/
├── _bmad/               # Single installation folder
│   ├── _config/         # Your customizations
│   │   └── agents/      # Agent customization files
│   ├── core/            # Universal core framework
│   ├── bmm/             # BMad Method module
│   ├── bmb/             # BMad Builder
│   └── cis/             # Creative Intelligence Suite
└── _bmad-output/        # Output folder (was doc folder in v4)

Module Migration

v4 Module	v6 Status
`.bmad-2d-phaser-game-dev`	Integrated into BMGD Module
`.bmad-2d-unity-game-dev`	Integrated into BMGD Module
`.bmad-godot-game-dev`	Integrated into BMGD Module
`.bmad-infrastructure-devops`	Deprecated — new DevOps agent coming soon
`.bmad-creative-writing`	Not adapted — new v6 module coming soon

Key Changes

Concept	v4	v6
Core	`_bmad-core` was actually BMad Method	`_bmad/core/` is universal framework
Method	`_bmad-method`	`_bmad/bmm/`
Config	Modified files directly	`config.yaml` per module
Documents	Sharded or unsharded required setup	Fully flexible, auto-scanned

3.6 KiB Raw Permalink Blame History