feat: standalone self-registering modules + v1.4.0#50
Merged
Conversation
Remove bmad-builder-setup — modules with a single skill no longer need a dedicated setup skill. The module builder now detects single-skill vs multi-skill input and offers the appropriate approach: - Single skill: embeds self-registration via assets/module-setup.md - Multiple skills: generates a -setup skill (existing behavior) New files: - standalone-module-template/ with module-setup.md and merge scripts - scaffold-standalone-module.py for standalone scaffolding - test-scaffold-standalone-module.py (9 tests) Updated: - validate-module.py auto-detects standalone modules - create-module.md with standalone flow (step 1.5 confirm, step 7/8 branches) - validate-module.md and SKILL.md for standalone awareness - marketplace.json: removed setup skill, bumped to 1.3.0
Adds standalone self-registering module infrastructure to the dream-weaver sample — module.yaml, module-help.csv, module-setup.md, and merge scripts. Fixes SKILL.md menu codes to match reference file frontmatter (DC→DL, PA→PD) and adds missing dream-query capability. Restructures both sample skills to use references/ subdirectories. Adds bmad-bmb-setup skill and updates module-help.csv.
Agents with sidecar memory already detect first run (sidecar missing). The module registration now hooks into that existing flow instead of being a separate activation check, giving users a unified first-run experience that handles both module setup and skill initialization.
Overhaul documentation to reflect the new standalone self-registering module pattern alongside the existing multi-skill setup skill approach. Quick Start (index.md): - Replace placeholder with real 3-step guide: register, build, use - Add bmad-bmb-setup registration instruction for first use - Add guidance on using skills without module packaging — just copy the folder to your tool's skills directory for personal use - Note that single-skill modules self-register on first run Module Configuration (module-configuration.md): - Reframe from setup-skill-only to two registration paths - Add "Why Register with the Help System?" explaining bmad-help integration: dependency graphs, completion detection, routing - Add full 13-column CSV guide with column-by-column purpose table - Add "How bmad-help Uses These Entries" with real example row - Document both multi-skill and standalone Create Module workflows - Incorporate user edits on standalone pattern flexibility and richer help entry benefits What Are Modules (what-are-modules.md): - Add "Distribution: Plugins and Marketplaces" section explaining .claude-plugin/ convention, single plugin vs marketplace structure, cross-platform reach (43+ skills platforms, Vercel NPX, Anthropic), and remote URL skill composition - Update component table to compare multi-skill vs standalone - Note that registration enables bmad-help discovery - Update Module Builder description for both packaging approaches Tutorial (build-your-first-module.md): - Update prerequisites to reference bmad-bmb-setup - Replace single-pattern Understanding Modules with comparison table - Split Step 3 into multi-skill and standalone subsections with separate folder structures and marketplace.json mention - Update FAQ on single-skill modules to describe auto-detection - Update Key Takeaways for both patterns Builder Commands Reference (builder-commands.md): - Update Create Module (CM): auto-detection, both output paths - Update Validate Module (VM): handles both module types - Update capabilities overview table Marketplace (marketplace.json): - Bump version to 1.4.0 - Add bmad-bmb-setup to skills list (4 skills total)
Sync package.json version with marketplace.json (1.4.0) for the installer's version detection. Remove release:* scripts and publishConfig — npm releases are no longer used.
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (4)
📒 Files selected for processing (43)
WalkthroughThe pull request restructures the BMad module architecture to support two registration models: multi-skill modules with dedicated setup skills and single-skill standalone modules with self-registration. The Changes
Sequence DiagramsequenceDiagram
participant User
participant Skill as Skill (Single/Multi)
participant Setup as Setup Registration
participant ConfigMerge as merge-config.py
participant HelpMerge as merge-help-csv.py
participant BmadHelp as bmad-help System
participant Config as _bmad/config.yaml
User->>Skill: Trigger setup/configure/install
Skill->>Setup: Load module-setup.md
Setup->>User: Prompt for configuration (if needed)
User-->>Setup: Provide answers
Setup->>ConfigMerge: Pass module.yaml + answers
ConfigMerge->>Config: Merge/update config (anti-zombie)
ConfigMerge->>ConfigMerge: Apply result templates
Setup->>HelpMerge: Pass module-help.csv
HelpMerge->>BmadHelp: Update capability registry
HelpMerge->>BmadHelp: Remove stale entries (anti-zombie)
Setup->>User: Display post-install summary
Setup->>Skill: Resume main activation flow
User->>BmadHelp: Request help
BmadHelp-->>User: Show registered capabilities
Estimated code review effort🎯 4 (Complex) | ⏱️ ~65 minutes Possibly related PRs
Poem
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
🤖 Augment PR SummarySummary: This PR introduces standalone self-registering modules and bumps BMad Builder to v1.4.0. Changes:
Technical Notes: Standalone packaging relies on a first-run/arg-triggered 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| module_answers = apply_result_templates( | ||
| module_yaml, answers.get("module", {}), verbose | ||
| ) | ||
| module_section.update(module_answers) |
There was a problem hiding this comment.
skills/bmad-bmb-setup/scripts/merge-config.py:285 — module_section.update(module_answers) will also write variables marked user_setting: true into shared _bmad/config.yaml, even though the setup docs say those values should live exclusively in config.user.yaml.
This can unintentionally leak user-specific preferences into the project-shared config.
Severity: medium
Other Locations
skills/bmad-module-builder/assets/standalone-module-template/merge-config.py:285samples/bmad-agent-dream-weaver/scripts/merge-config.py:285
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| for var_name, var_def in module_yaml.items(): | ||
| if isinstance(var_def, dict) and var_def.get("user_setting") is True: | ||
| if var_name in module_answers: | ||
| user_settings[var_name] = module_answers[var_name] |
There was a problem hiding this comment.
skills/bmad-bmb-setup/scripts/merge-config.py:319 — extract_user_settings() copies user_setting values from raw answers without applying the variable’s result template, which can make config.user.yaml disagree with the templated values written into config.yaml.
If any user-setting variable uses result for normalization (paths, tokens), this would store inconsistent values.
Severity: medium
Other Locations
skills/bmad-module-builder/assets/standalone-module-template/merge-config.py:319samples/bmad-agent-dream-weaver/scripts/merge-config.py:319
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| ) | ||
| return 2 | ||
|
|
||
| if not (skill_dir / "assets" / "module.yaml").is_file(): |
There was a problem hiding this comment.
skills/bmad-module-builder/scripts/scaffold-standalone-module.py:81 — the script validates assets/module.yaml exists but doesn’t check for assets/module-help.csv, even though assets/module-setup.md/merge-help-csv.py assume it’s present.
This can produce a “successful” scaffold that later fails during registration.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| @@ -1,644 +0,0 @@ | |||
| #!/usr/bin/env python3 | |||
There was a problem hiding this comment.
skills/bmad-builder-setup/scripts/tests/test-merge-config.py:1 — the merge/cleanup unit tests were removed, but equivalent coverage doesn’t appear to exist for the new skills/bmad-bmb-setup/scripts/* copies.
Given these scripts mutate (and delete) legacy config, losing test coverage increases regression risk.
Severity: low
Other Locations
skills/bmad-builder-setup/scripts/tests/test-cleanup-legacy.py:1skills/bmad-builder-setup/scripts/tests/test-merge-help-csv.py:1
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| - **Validate Module (VM)** — Checks that a module's structure is complete and correct — every skill has its capabilities registered, entries are accurate and well-crafted, and structural integrity is sound. Handles both multi-skill and standalone modules. Supports `--headless` / `-H`. | ||
|
|
||
| **Args:** Accepts `--headless` / `-H` for CM and VM paths, an initial description for IM, or a path to a skills folder for CM/VM. | ||
| **Args:** Accepts `--headless` / `-H` for CM and VM paths, an initial description for IM, or a path to a skills folder or single SKILL.md file for CM/VM. |
There was a problem hiding this comment.
skills/bmad-module-builder/SKILL.md:16 — after renaming the setup skill to bmad-bmb-setup, this skill still tells users to run bmad-builder-setup when config is missing (see skills/bmad-module-builder/SKILL.md:20).
That reference will point to a non-existent skill in v1.4.0 installs.
Severity: medium
Other Locations
skills/bmad-agent-builder/SKILL.md:22skills/bmad-workflow-builder/SKILL.md:22
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
This was referenced Apr 4, 2026
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
-setupskill. The Module Builder detects single vs multi-skill input and embeds registration directly into the skill viaassets/module-setup.mdbmad-builder-setup: Regenerated asbmad-bmb-setupby the Module Builder itself, proving the tooling works end-to-endpackage.jsonandmarketplace.json, removed npm release scriptsNew Files
standalone-module-template/— template withmodule-setup.mdand merge scriptsscaffold-standalone-module.py— scaffold script for standalone modules (9 tests)validate-module.pyupdated — auto-detects standalone modules (5 new tests, 14 total)Test Plan
🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes
New Features
Documentation
Refactor
Chores