feat: bmad-installable-entities batch — module builder, workflow convert, path convention fix

.claude-plugin/marketplace.json

@@ -6,17 +6,22 @@
   "license": "MIT",
   "homepage": "https://github.com/bmad-code-org/bmad-builder",
   "repository": "https://github.com/bmad-code-org/bmad-builder",
-  "keywords": ["bmad", "agent-builder", "workflow-builder", "skill-factory", "ai-agents"],
+  "keywords": ["bmad", "agent-builder", "workflow-builder", "module-builder", "skill-factory", "ai-agents"],
   "plugins": [
     {
       "name": "bmad-builder",
       "source": "./",
-      "description": "Build AI agents and workflows from a conversation. Three skills — Agent Builder, Workflow Builder, and Setup — guide you from idea to production-ready skill structure with built-in quality optimization. Part of the BMad Method ecosystem.",
+      "description": "Build AI agents, workflows, and modules from a conversation. Four skills — Agent Builder, Workflow Builder, Module Builder, and Setup — guide you from idea to production-ready skill structure with built-in quality optimization. Part of the BMad Method ecosystem.",
       "version": "1.2.0",
       "author": {
         "name": "Brian (BMad) Madison"
       },
-      "skills": ["./skills/bmad-agent-builder", "./skills/bmad-builder-setup", "./skills/bmad-workflow-builder"]
+      "skills": [
+        "./skills/bmad-agent-builder",
+        "./skills/bmad-builder-setup",
+        "./skills/bmad-module-builder",
+        "./skills/bmad-workflow-builder"
+      ]
     }
   ]
 }

docs/explanation/module-configuration.md

@@ -88,8 +88,8 @@ If these cover your discoverability needs, you can skip the setup skill entirely
 The CSV asset registers the module's capabilities with the help system. Each row describes one capability that users can discover and invoke.
 
 ```csv
-module,agent-name,skill-name,display-name,menu-code,capability,args,description,...
-mymod,,my-skill,My Skill,MS,build-process,,"Does something useful.",...
+module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+mymod,my-skill,My Skill,MS,"Does something useful.",build-process,,anytime,,,false,,
 ```
 
 When the setup skill runs, it merges these rows into the project-wide `_bmad/module-help.csv`, replacing any existing rows for this module. This is how users find your module's commands through the help system.

docs/explanation/skill-authoring-best-practices.md

@@ -33,7 +33,7 @@ Six dimensions to keep in mind during the build phase. The quality scanners chec
 | **Intelligence Placement** | Scripts handle plumbing (fetch, transform, validate). Prompts handle judgment (interpret, classify, decide). If a script contains an `if` that decides what content _means_, intelligence has leaked |
 | **Progressive Disclosure** | SKILL.md stays focused; stage instructions go in `prompts/`, reference data in `resources/`                                                                                                          |
 | **Description Format**     | Two parts: `[5-8 word summary]. [Use when user says 'X' or 'Y'.]` — default to conservative triggering                                                                                               |
-| **Path Construction**      | Never use `{skill-root}`. Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}`                                                        |
+| **Path Construction**      | Never use `{skill-root}`. Use `{project-root}` for any project-scope path, `./` for skill-internal. Config variables used directly — they already contain `{project-root}`                            |
 | **Token Efficiency**       | Remove genuine waste (repetition, defensive padding). Preserve context that enables judgment (domain framing, rationale)                                                                             |
 
 ## Common Patterns

docs/reference/builder-commands.md

@@ -7,10 +7,11 @@ Reference for the three core BMad Builder skills — the Agent Builder (`bmad-ag
 
 ## Capabilities Overview
 
-| Capability           | Menu Code | Agent Builder                         | Workflow Builder                                       |
-| -------------------- | --------- | ------------------------------------- | ------------------------------------------------------ |
-| **Build Process**    | BP        | Build, edit, convert, or fix agents   | Build, edit, convert, or fix workflows and utilities   |
-| **Quality Optimize** | QO        | Validate and optimize existing agents | Validate and optimize existing workflows and utilities |
+| Capability           | Menu Code | Agent Builder                         | Workflow Builder                                                                    |
+| -------------------- | --------- | ------------------------------------- | ----------------------------------------------------------------------------------- |
+| **Build Process**    | BP        | Build, edit, convert, or fix agents   | Build, edit, convert, or fix workflows and utilities                                |
+| **Quality Optimize** | QO        | Validate and optimize existing agents | Validate and optimize existing workflows and utilities                              |
+| **Convert**          | CW        | —                                     | Convert any skill to BMad-compliant, outcome-driven equivalent with comparison report |
 
 Both capabilities support autonomous/headless mode via `--headless` / `-H` flags.
 
@@ -111,7 +112,7 @@ Before completing the build, both builders run deterministic validation.
 
 | Script                   | What It Checks                                                                            |
 | ------------------------ | ----------------------------------------------------------------------------------------- |
-| `scan-path-standards.py` | Path conventions — no `{skill-root}`, `{project-root}` only for `_bmad`, no double-prefix |
+| `scan-path-standards.py` | Path conventions — no `{skill-root}`, `{project-root}` for project-scope, `./` for skill-internal, no double-prefix |
 | `scan-scripts.py`        | Script portability, PEP 723 metadata, agentic design, unit test presence                  |
 
 Critical issues block completion. Warnings are noted but don't block.
@@ -179,6 +180,50 @@ Not every suggestion should be applied. The optimizer communicates these decisio
 - **Prefer scripting** for deterministic operations; **prefer prompting** for creative or judgment-based tasks
 - **Reject changes** that flatten personality unless a neutral tone is explicitly wanted
 
+## Convert (CW)
+
+One-command conversion of any existing skill into a BMad-compliant, outcome-driven equivalent. This is the fastest path for taking a non-conformant skill — whether it's bloated, poorly structured, or just doesn't follow BMad best practices — and producing a clean version that does. Unlike the Build Process's edit/rebuild modes, `--convert` always runs headless and produces a visual comparison report.
+
+### Usage
+
+```
+--convert <path-or-url> [-H]
+```
+
+The `--convert` flag implies headless mode. Accepts a local skill path or a URL (not limited to remote — local file paths work too).
+
+### Process
+
+| Step | What Happens |
+| ---- | ------------ |
+| **1. Capture** | Fetch or read the original skill, save a copy for comparison |
+| **2. Rebuild** | Full headless rebuild from intent — extract what the skill achieves, apply BMad outcome-driven best practices |
+| **3. Report** | Measure both versions, categorize what changed and why, generate an interactive HTML comparison report |
+
+### Comparison Report
+
+The HTML report includes:
+
+| Section | Content |
+| ------- | ------- |
+| **Hero banner** | Overall token reduction percentage |
+| **Metrics table** | Lines, words, characters, sections, files, estimated tokens — with visual bars |
+| **What changed** | Categorized differences — bloat removal, structural reorganization, best-practice alignment — with severity and examples |
+| **What survived** | Content that earns its place — instructions the LLM wouldn't follow correctly without being told |
+| **Verdict** | One-sentence summary of the conversion |
+
+Reports are saved to `{bmad_builder_reports}/convert-{skill-name}/`.
+
+### When to Use Convert vs Build Process
+
+| Scenario | Use |
+| -------- | --- |
+| You have any non-BMad-compliant skill and want it converted fast | `--convert` |
+| You have a bloated skill and want a lean replacement with a comparison report | `--convert` |
+| You want to interactively discuss what to change | Build Process (Edit mode) |
+| You want to rethink a skill from scratch with full discovery | Build Process (Rebuild mode) |
+| You want a detailed quality analysis without rebuilding | Quality Optimize |
+
 ## Module Builder
 
 The Module Builder (`bmad-module-builder`) handles module-level planning, scaffolding, and validation. It operates at a higher level than the Agent and Workflow Builders — it orchestrates what those builders produce into a cohesive, installable module.
@@ -275,6 +320,7 @@ Verifies that a module's setup skill is complete and accurate. Combines a determ
 | Edit      | "edit/modify/update a workflow/skill"                   | Workflow | `prompts/build-process.md`        |
 | Convert   | "convert this to a BMad agent"                          | Agent    | `prompts/build-process.md`        |
 | Convert   | "convert this to a BMad skill"                          | Workflow | `prompts/build-process.md`        |
+| Convert   | `--convert <path-or-url>`                               | Workflow | `./references/convert-process.md` |
 | Optimize  | "quality check/validate/optimize/review agent"          | Agent    | `prompts/quality-optimizer.md`    |
 | Optimize  | "quality check/validate/optimize/review workflow/skill" | Workflow | `prompts/quality-optimizer.md`    |
 | Ideate    | "ideate module/plan a module/brainstorm a module"       | Module   | `./references/ideate-module.md`   |

skills/bmad-agent-builder/build-process.md

@@ -68,7 +68,7 @@ Key structural context:
 **Path conventions (CRITICAL):**
 
 - Memory: `{project-root}/_bmad/memory/{skillName}-sidecar/`
-- Project artifacts: `{project-root}/_bmad/...`
+- Project-scope paths: `{project-root}/...` (any path relative to project root)
 - Skill-internal: `./references/`, `./scripts/`
 - Config variables used directly — they already contain full paths (no `{project-root}` prefix)
 

skills/bmad-agent-builder/references/quality-dimensions.md

@@ -45,7 +45,7 @@ Default to conservative triggering. See `./references/standard-fields.md` for fu
 
 ## 6. Path Construction
 
-Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}`.
+Use `{project-root}` for any project-scope path. Use `./` for skill-internal paths. Config variables used directly — they already contain `{project-root}`.
 
 See `./references/standard-fields.md` for correct/incorrect patterns.
 

skills/bmad-agent-builder/references/script-opportunities-reference.md

@@ -118,7 +118,7 @@ All scripts use PEP 723 and `--help`. When a skill's prompt needs to invoke a sc
 - ## Read Access section exists
 - ## Write Access section exists
 - ## Deny Zones section exists (can be empty)
-- Paths use placeholders correctly ({project-root} for _bmad paths, relative for skill-internal)
+- Paths use placeholders correctly ({project-root} for project-scope paths, ./ for skill-internal)
 ```
 
 **Output:** Structured JSON of read/write/deny zones

skills/bmad-agent-builder/references/standard-fields.md

@@ -75,6 +75,13 @@ Always use `{project-root}` prefix: `{project-root}/_bmad/memory/{skillName}-sid
 
 The sidecar `index.md` is the single entry point to the agent's memory system — it tells the agent what else to load (boundaries, logs, references, etc.). Load it once on activation; don't duplicate load instructions for individual memory files.
 
+### Project-Scope Paths
+
+Use `{project-root}/...` for any path relative to the project root:
+
+- `{project-root}/_bmad/planning/prd.md`
+- `{project-root}/docs/report.md`
+
 ### Config Variables
 
 Use directly — they already contain `{project-root}` in their resolved values:

skills/bmad-agent-builder/scripts/scan-path-standards.py

@@ -2,9 +2,9 @@
 """Deterministic path standards scanner for BMad skills.
 
 Validates all .md and .json files against BMad path conventions:
-1. {project-root} only valid before /_bmad
+1. {project-root} for any project-scope path (not just _bmad)
 2. Bare _bmad references must have {project-root} prefix
-3. Config variables used directly (no double-prefix)
+3. Config variables used directly — no double-prefix with {project-root}
 4. Skill-internal paths must use ./ prefix (references/, scripts/, assets/)
 5. No ../ parent directory references
 6. No absolute paths
@@ -28,8 +28,8 @@
 
 
 # Patterns to detect
-# {project-root} NOT followed by /_bmad
-PROJECT_ROOT_NOT_BMAD_RE = re.compile(r'\{project-root\}/(?!_bmad)')
+# Double-prefix: {project-root}/{config-variable} — config vars already contain project-root
+DOUBLE_PREFIX_RE = re.compile(r'\{project-root\}/\{[^}]+\}')
 # Bare _bmad without {project-root} prefix — match _bmad at word boundary
 # but not when preceded by {project-root}/
 BARE_BMAD_RE = re.compile(r'(?<!\{project-root\}/)_bmad[/\s]')
@@ -142,8 +142,8 @@ def scan_file(filepath: Path, skip_fenced: bool = True) -> list[dict]:
     rel_path = filepath.name
 
     checks = [
-        (PROJECT_ROOT_NOT_BMAD_RE, 'project-root-not-bmad', 'critical',
-         '{project-root} used for non-_bmad path — only valid use is {project-root}/_bmad/...'),
+        (DOUBLE_PREFIX_RE, 'double-prefix', 'critical',
+         'Double-prefix: {project-root}/{variable} — config variables already contain {project-root} at runtime'),
         (ABSOLUTE_PATH_RE, 'absolute-path', 'high',
          'Absolute path found — not portable across machines'),
         (HOME_PATH_RE, 'absolute-path', 'high',
@@ -259,9 +259,8 @@ def scan_skill(skill_path: Path, skip_fenced: bool = True) -> dict:
     # Build summary
     by_severity = {'critical': 0, 'high': 0, 'medium': 0, 'low': 0}
     by_category = {
-        'project_root_not_bmad': 0,
-        'bare_bmad': 0,
         'double_prefix': 0,
+        'bare_bmad': 0,
         'absolute_path': 0,
         'relative_prefix': 0,
         'bare_internal_path': 0,
@@ -281,7 +280,7 @@ def scan_skill(skill_path: Path, skip_fenced: bool = True) -> dict:
     return {
         'scanner': 'path-standards',
         'script': 'scan-path-standards.py',
-        'version': '2.0.0',
+        'version': '2.1.0',
         'skill_path': str(skill_path),
         'timestamp': datetime.now(timezone.utc).isoformat(),
         'files_scanned': files_scanned,

skills/bmad-builder-setup/assets/module-help.csv

@@ -4,6 +4,7 @@ BMad Builder,bmad-agent-builder,Build an Agent,BA,"Create, edit, convert, or fix
 BMad Builder,bmad-agent-builder,Optimize an Agent,OA,Validate and optimize an existing agent skill. Produces a quality report.,quality-optimizer,[-H] [path],anytime,bmad-agent-builder:build-process,,false,bmad_builder_reports,quality report
 BMad Builder,bmad-workflow-builder,Build a Workflow,BW,"Create, edit, convert, or fix a workflow or utility skill.",build-process,"[-H] [description | path]",anytime,,bmad-workflow-builder:quality-optimizer,false,output_folder,workflow skill
 BMad Builder,bmad-workflow-builder,Optimize a Workflow,OW,Validate and optimize an existing workflow or utility skill. Produces a quality report.,quality-optimizer,[-H] [path],anytime,bmad-workflow-builder:build-process,,false,bmad_builder_reports,quality report
+BMad Builder,bmad-workflow-builder,Convert a Skill,CW,"Convert any skill to BMad-compliant, outcome-driven equivalent with before/after HTML comparison report.",convert-process,"--convert <path-or-url> [-H]",anytime,,,false,bmad_builder_reports,converted skill + comparison report
 BMad Builder,bmad-module-builder,Ideate Module,IM,"Brainstorm and plan a BMad module — explore ideas, decide architecture, and produce a build plan.",ideate-module,,anytime,,bmad-module-builder:create-module,false,bmad_builder_reports,module plan
 BMad Builder,bmad-module-builder,Create Module,CM,"Scaffold a setup skill into an existing folder of built skills, making it an installable BMad module.",create-module,"[-H] [path]",anytime,bmad-module-builder:ideate-module,,false,bmad_builder_output_folder,setup skill
 BMad Builder,bmad-module-builder,Validate Module,VM,"Check that a module's setup skill is complete, accurate, and all capabilities are properly registered.",validate-module,[path],anytime,bmad-module-builder:create-module,,false,bmad_builder_reports,validation report

skills/bmad-builder-setup/scripts/merge-help-csv.py

@@ -26,20 +26,18 @@
 # CSV header for module-help.csv
 HEADER = [
     "module",
-    "agent-name",
-    "skill-name",
+    "skill",
     "display-name",
     "menu-code",
-    "capability",
-    "args",
     "description",
+    "action",
+    "args",
     "phase",
     "after",
     "before",
     "required",
     "output-location",
     "outputs",
-    "",  # trailing empty column from trailing comma
 ]