feat(module-builder): default to root manifests, bundle as opt-in by bmadcode · Pull Request #81 · bmad-code-org/bmad-builder

bmadcode · 2026-04-27T03:38:19Z

Summary

bmad-create-module now always writes module.yaml, module-help.csv, and .claude-plugin/marketplace.json at the module root. This is the canonical layout the BMad installer expects and matches the docs landed in docs(modules): lead with root placement for module manifests #80.
Setup skill (multi-skill) and self-registering single-skill bundles become opt-in add-ons for direct-download distribution. They duplicate the same root manifests inside a skill so users can register the module manually without running npx bmad-method install.
bmad-validate-module now recognizes three layouts in installer priority order: root, setup-skill bundle, self-registering bundle. Root placement is treated as canonical; bundles are validated as additional infrastructure when present alongside root manifests.
Headless mode in create-module gains a --bundle flag (none / setup / standalone / auto). Default is none (root only), so existing CI/automation gets the cleaner default behavior.

Files changed

references/create-module.md (workflow restructure: step 7 always-root, step 7.5 optional bundling, headless mode rewrite)
scripts/validate-module.py (recognize root layout; treat bundles as additive)
scripts/tests/test-validate-module.py (4 new test cases for root layout; 2 existing tests updated for renamed info-dict keys)
scripts/scaffold-setup-skill.py, scripts/scaffold-standalone-module.py (docstring updates clarifying their new role as additive bundlers)

Test plan

test-validate-module.py: 18/18 pass (14 existing + 4 new for root layout)
test-scaffold-setup-skill.py: 7/7 pass (no behavior change)
test-scaffold-standalone-module.py: 8/9 (1 pre-existing failure on `main`, not caused by this PR)
Smoke test: validator correctly identifies `bmad-bmm/main/src/bmm-skills` and `bmad-cis/main/src` as canonical-source root layouts

Known follow-ups (out of scope)

`find_skill_folders` only looks at direct children. `bmm` and `cis` nest skills under phase folders, so the validator currently produces false-positive orphan-entry warnings for those modules. Recursive skill discovery is a separate enhancement.
Pre-existing `test_marketplace_json_content` failure in `test-scaffold-standalone-module.py` is on `main` and untouched by this PR.

bmad-create-module now always writes module.yaml, module-help.csv, and .claude-plugin/marketplace.json at the module root. This is the canonical layout the BMad installer expects. The setup skill (multi- skill) and self-registering single-skill bundles become opt-in add- ons for direct-download distribution; they duplicate the same root manifests so users can register the module manually. bmad-validate-module now recognizes three layouts in installer priority order: root, setup-skill bundle, self-registering bundle. Root placement is treated as canonical; bundles are validated as additional infrastructure when present alongside root manifests. Adds four new test cases covering root layout and root+bundle combinations. Headless mode in create-module gains a --bundle flag (none/setup/ standalone/auto) so callers can opt into direct-download bundling explicitly. Default is none (root only).

coderabbitai · 2026-04-27T03:38:26Z

Warning

Rate limit exceeded

@bmadcode has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 36 minutes and 31 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8c17b709-6a62-45ae-bd9f-05a69ce4d8f2

📥 Commits

Reviewing files that changed from the base of the PR and between 86033fc and c6a4a97.

📒 Files selected for processing (5)

skills/bmad-module-builder/references/create-module.md
skills/bmad-module-builder/scripts/scaffold-setup-skill.py
skills/bmad-module-builder/scripts/scaffold-standalone-module.py
skills/bmad-module-builder/scripts/tests/test-validate-module.py
skills/bmad-module-builder/scripts/validate-module.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch builder-root-default

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

augmentcode · 2026-04-27T03:41:28Z

🤖 Augment PR Summary

Summary: This PR updates the module builder to treat root-level manifests as canonical and makes direct-download “bundle” layouts opt-in.

Changes:

Restructures the create-module reference so module.yaml, module-help.csv, and .claude-plugin/marketplace.json are always written at the module root, regardless of skill count.
Adds an optional post-step for bundling: either a {code}-setup setup-skill bundle (multi-skill) or a self-registering bundle inside a single skill.
Extends scripts/validate-module.py to detect three layouts (root → setup bundle → self-registering bundle), report a canonical_source, and validate bundles as additive infra when root exists.
Updates and expands validator tests with new root-layout scenarios and revised info keys.
Updates scaffold script docstrings to clarify they are bundlers for direct-download distribution.

Technical Notes: Validator now fails on any high/critical findings; root manifests win as the read source when present.

_{🤖 Was this summary useful? React with 👍 or 👎}

augmentcode

Review completed. 4 suggestions posted.

Comment augment review to trigger a new review at any time.

augmentcode · 2026-04-27T03:41:29Z

+        return {"status": "fail", "findings": findings, "info": info}
+
+    # Partial root layout: one of the two manifests exists but not both
+    if has_root and not (root_yaml and root_csv):


skills/bmad-module-builder/scripts/validate-module.py:137 — The “partial root layout” check looks unreachable because has_root is defined as bool(root_yaml and root_csv), so has_root and not (root_yaml and root_csv) can never be true. This likely prevents emitting the intended specific error when only one of the two root manifests exists.

Severity: low

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augmentcode · 2026-04-27T03:41:29Z

+        yaml_path = setup_dir / "assets" / "module.yaml"
+        csv_path = setup_dir / "assets" / "module-help.csv"
+        # Verify bundle files exist
+        for label, path in [


skills/bmad-module-builder/scripts/validate-module.py:155 — For the setup-skill bundle path, the validator only checks SKILL.md and the two manifest files, but not the rest of the bundle infrastructure (e.g., merge scripts) that direct-download registration depends on. As-is, an incomplete/non-runnable setup bundle could still validate successfully if those three files exist.

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augmentcode · 2026-04-27T03:41:29Z

-    """Find the setup skill folder (*-setup)."""
+    """Find the setup skill folder (*-setup) used for multi-skill direct-download bundling."""
    for d in module_dir.iterdir():
        if d.is_dir() and d.name.endswith("-setup"):


skills/bmad-module-builder/scripts/validate-module.py:53 — find_setup_skill() treats any directory ending in -setup as a bundle, which can cause root-layout modules to fail validation if they contain a normal skill with that suffix (since the bundle checks will be enforced and the folder is excluded from skill_folders). If -setup isn’t guaranteed to be reserved for module bundling, this can introduce false negatives.

Severity: medium

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augmentcode · 2026-04-27T03:41:29Z

+Before running this script, the LLM must duplicate the root manifests into
+`<skill>/assets/module.yaml` and `<skill>/assets/module-help.csv`. The script
+then copies template files (module-setup.md, merge scripts) into the skill
+directory and (re)generates a .claude-plugin/marketplace.json for distribution.


skills/bmad-module-builder/scripts/scaffold-standalone-module.py:16 — This script “(re)generates” marketplace.json, but the implementation overwrites the file rather than merging/preserving existing fields and other plugin entries. With the updated create-module flow emphasizing merging into an existing root .claude-plugin/marketplace.json, running this bundler can clobber previously populated metadata or other modules’ entries.

Severity: high

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augmentcode Bot reviewed Apr 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(module-builder): default to root manifests, bundle as opt-in#81

feat(module-builder): default to root manifests, bundle as opt-in#81
bmadcode wants to merge 1 commit intomainfrom
builder-root-default

bmadcode commented Apr 27, 2026

Uh oh!

coderabbitai Bot commented Apr 27, 2026

Rate limit exceeded

Uh oh!

augmentcode Bot commented Apr 27, 2026

Uh oh!

augmentcode Bot left a comment

Uh oh!

augmentcode Bot Apr 27, 2026 •

edited

Loading

Uh oh!

augmentcode Bot Apr 27, 2026 •

edited

Loading

Uh oh!

augmentcode Bot Apr 27, 2026 •

edited

Loading

Uh oh!

augmentcode Bot Apr 27, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

bmadcode commented Apr 27, 2026

Summary

Files changed

Test plan

Known follow-ups (out of scope)

Related

Uh oh!

coderabbitai Bot commented Apr 27, 2026

Rate limit exceeded

Uh oh!

augmentcode Bot commented Apr 27, 2026

Uh oh!

augmentcode Bot left a comment

Choose a reason for hiding this comment

Uh oh!

augmentcode Bot Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

augmentcode Bot Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

augmentcode Bot Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

augmentcode Bot Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

augmentcode Bot Apr 27, 2026 •

edited

Loading

augmentcode Bot Apr 27, 2026 •

edited

Loading

augmentcode Bot Apr 27, 2026 •

edited

Loading

augmentcode Bot Apr 27, 2026 •

edited

Loading