Skip to content

Fix marketplace.json naming mismatch and improve community module installation experience #30

@masteroleg

Description

@masteroleg

Problem Description
When installing the community module wds (Whiteport Design Studio) from the bmad-method-wds-expansion npm package, the installer displays the same warning 4 times during a single installation:

! Community module 'wds' picked the only plugin in marketplace.json ('bmad-wds') because no name or module_definition match was found. Verify marketplace.json if the install looks wrong.

Root Cause Analysis
Naming mismatch: The marketplace.json file inside bmad-method-wds-expansion npm package contains:

{
  "name": "bmad-wds"
}

The registryApprovedTag: v0.1.0 is misleading — it's the curator-approved version, NOT the actually installed version (which is main branch, newer than v0.3.1).

Suggested Fixes

For BMAD Core Installer

  1. Support module_definition in marketplace.json:
{
  "name": "bmad-wds",
  "module_definition": {
    "code": "wds"
  }
}
  1. Reduce warning frequency: Show the naming mismatch warning once at the beginning of installation, not repeatedly.
  2. Improve auto-detection message: When auto-detecting the only plugin in marketplace.json, make it informational rather than a warning:

ℹ Using plugin 'bmad-wds' from marketplace.json for module 'wds'

  1. Include community modules in status output: bmad-method status should list all installed modules, including community ones.

For manifest.yaml

  1. Rename or clarify registryApprovedTag: Consider renaming to curatorApprovedTag or add a clear comment that this field represents the approved version, not the installed version. Alternatively, add an installedVersion field that reflects the actual installed code version.

For Module Authors (bmad-method-wds-expansion)

  1. Update marketplace.json to include proper module definition:
{
  "name": "bmad-wds",
  "module_definition": {
    "code": "wds",
    "displayName": "Whiteport Design Studio"
  }
}

Environment

  • BMAD Core Version: 6.6.0
  • Installer: npx bmad-method
  • Community Module: wds (bmad-method-wds-expansion)
  • Platform: Windows 10/11
  • Node.js: v24.15.0.
  • Package Manager: npm

Expected Behavior

  1. Clean installation without repeated warnings
  2. bmad-method status shows all installed modules (including community)
  3. Clear version information in manifest.yaml that distinguishes between "approved" and "actually installed"

Additional Context

  • The WDS module repository has tags up to v0.3.1, but the registry shows approved_tag: v0.1.0
  • The actual installed files are from main branch (post-v0.3.1 commits), which includes breaking changes from v0.3.x (removed agents, changed paths, new naming convention)
  • Users may be confused why they're getting "newer" code but the system reports an older "approved" version

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions