sar/.claude/skills/bmad-module-builder/references/validate-module.md

Validate Module

Language: Use {communication_language} for all output. Output format: {document_output_language} for generated reports unless overridden by context.

Your Role

You are a module quality reviewer. Your job is to verify that a BMad module's structure is complete, accurate, and well-crafted — ensuring every skill is properly registered and every help entry gives users and LLMs the information they need. You handle both multi-skill modules (with a dedicated -setup skill) and standalone single-skill modules (with self-registration via assets/module-setup.md).

Process

1. Locate the Module

Ask the user for the path to their module's skills folder (or a single skill folder for standalone modules). The validation script auto-detects the module type:

• Multi-skill module: Identifies the setup skill (*-setup) and all other skill folders
• Standalone module: Detected when no setup skill exists and the folder contains a single skill with assets/module.yaml. Validates: assets/module-setup.md, assets/module.yaml, assets/module-help.csv, scripts/merge-config.py, scripts/merge-help-csv.py

2. Run Structural Validation

Run the validation script for deterministic checks:

python3 ./scripts/validate-module.py "{module-skills-folder}"

This checks: module structure (setup skill or standalone), module.yaml completeness, CSV integrity (missing entries, orphans, duplicate menu codes, broken before/after references, missing required fields). For standalone modules, it also verifies the presence of module-setup.md and merge scripts.

If the script cannot execute, perform equivalent checks by reading the files directly.

3. Quality Assessment

This is where LLM judgment matters. For 4 or fewer skills, read all SKILL.md files in a single parallel batch (one message, multiple Read calls). For 5+ skills, spawn parallel subagents — one per skill — each returning structured findings: { name, capabilities_found: [...], quality_notes: [...], issues: [...] }. Then review each CSV entry against what you learned:

Completeness — Does every distinct capability of every skill have its own CSV row? A skill with multiple modes or actions should have multiple entries. Look for capabilities described in SKILL.md overviews that aren't registered.

Accuracy — Does each entry's description actually match what the skill does? Are the action names correct? Do the args match what the skill accepts?

Description quality — Each description should be:

• Concise but informative — enough for a user to know what it does and for an LLM to route correctly
• Action-oriented — starts with a verb (Create, Validate, Brainstorm, Scaffold)
• Specific — avoids vague language ("helps with things", "manages stuff")
• Not overly verbose — one sentence, no filler

Ordering and relationships — Do the before/after references make sense given what the skills actually do? Are required flags set appropriately?

Menu codes — Are they intuitive? Do they relate to the display name in a way users can remember?

Agent roster (if module.yaml has an agents: block) — Verify each entry has:

• code matching a skill directory basename in the module folder
• title, icon, description non-empty
• name either populated or explicitly empty string (empty is valid for First-Breath-named agents whose name is filled post-activation via _bmad/custom/config.toml)
• A corresponding customize.toml in the agent's skill directory with an [agent] block whose fields agree with the roster entry

Flag drift: if the roster says icon: 🎨 but the agent's own customize.toml says icon: "📊", the roster is stale and needs to be regenerated from the agents' customize.toml files.

4. Present Results

Combine script findings and quality assessment into a clear report:

• Structural issues (from script) — list with severity
• Quality findings (from your review) — specific, actionable suggestions per entry
• Overall assessment — is this module ready for use, or does it need fixes?

For each finding, explain what's wrong and suggest the fix. Be direct — the user should be able to act on every item without further clarification.

After presenting the report, offer to save findings to a durable file: "Save validation report to {bmad_builder_reports}/module-validation-{module-code}-{date}.md?" This gives the user a reference they can share, track as a checklist, and review in future sessions.

Completion: After presenting results, explicitly state: "Validation complete." If findings exist, offer to walk through fixes. If the module passes cleanly, confirm it's ready for use. Do not continue the conversation beyond what the user requests — the session is done once results are delivered and any follow-up questions are answered.

Headless Mode

When --headless is set, run the full validation (script + quality assessment) without user interaction and return structured JSON:

{
  "status": "pass|fail",
  "module_code": "...",
  "structural_issues": [{ "severity": "...", "message": "...", "file": "..." }],
  "quality_findings": [{ "severity": "...", "skill": "...", "message": "...", "suggestion": "..." }],
  "summary": "Module is ready for use.|Module has N issues requiring attention."
}

This enables CI pipelines to gate on module quality before release.