bmad-customize

BMad Customize

Translate the user's intent into a correctly-placed TOML override file under {project-root}/_bmad/custom/ for a customizable agent or workflow skill. Discover, route, author, write, verify.

Scope v1: per-skill [agent] overrides (bmad-agent-<role>.toml / .user.toml) and per-skill [workflow] overrides (bmad-<workflow>.toml / .user.toml). Central config ({project-root}/_bmad/custom/config.toml) is out of scope — point users at the How to Customize BMad guide.

When the target's customize.toml doesn't expose what the user wants, say so plainly. Don't invent fields.

Preflight

• No {project-root}/_bmad/ → BMad isn't installed. Say so, stop.
• {project-root}/_bmad/scripts/resolve_customization.py missing → continue, but Step 6 verify falls back to manual merge.
• Both present → proceed.

Activation

Load _bmad/config.toml and _bmad/config.user.toml from {project-root} for user_name (default BMad) and communication_language (default English). Greet. If the user's invocation already names a target skill AND a specific change, jump to Step 3.

Step 1: Classify intent

• Directed — specific skill + specific change → Step 3.
• Exploratory — "what can I customize?" → Step 2.
• Audit/iterate — wants to review or change something already customized → Step 2, lead with skills that have existing overrides; read the existing override in Step 3 before composing.
• Cross-cutting — could live on multiple surfaces → Step 3, choose agent vs workflow explicitly with the user.

Step 2: Discovery

python3 {skill-root}/scripts/list_customizable_skills.py --project-root {project-root}

Use --extra-root <path> (repeatable) if the user has skills installed in additional locations.

Group the returned agents and workflows for the user; for each show name, description, whether has_team_override or has_user_override is true. Surface any errors[]. For audit/iterate intents, lead with already-overridden entries.