bmad-builder-setup

Module Setup

Overview

Installs and configures a BMad module into a project. Module identity (name, code, version) comes from assets/module.yaml. Collects user preferences and writes them to three files:

• {project-root}/_bmad/config.yaml — shared project config: core settings at root (e.g. output_folder, document_output_language) plus a section per module with metadata and module-specific values. User-only keys (user_name, communication_language) are never written here.
• {project-root}/_bmad/config.user.yaml — personal settings intended to be gitignored: user_name, communication_language, and any module variable marked user_setting: true in assets/module.yaml. These values live exclusively here.
• {project-root}/_bmad/module-help.csv — registers module capabilities for the help system.

Both config scripts use an anti-zombie pattern — existing entries for this module are removed before writing fresh ones, so stale values never persist.

{project-root} is a literal token in config values — never substitute it with an actual path. It signals to the consuming LLM that the value is relative to the project root, not the skill root.

On Activation

1. Read ./assets/module.yaml for module metadata and variable definitions (the code field is the module identifier)
2. Check if {project-root}/_bmad/config.yaml exists — if a section matching the module's code is already present, inform the user this is an update
3. Check for legacy configuration at {project-root}/_bmad/{module-code}/config.yaml and {project-root}/_bmad/core/config.yaml. If either file exists, inform the user that legacy values will be migrated and the old files removed after setup

If the user provides arguments (e.g. accept all defaults, --headless, or inline values like user name is BMad, I speak Swahili), map any provided values to config keys, use defaults for the rest, and skip interactive prompting. Still display the full confirmation summary at the end.

Collect Configuration

Ask the user for values. Show defaults in brackets. Present all values together so the user can respond once with only the values they want to change (e.g. "change language to Swahili, rest are fine"). Use a structured question tool if available. Never tell the user to "press enter" or "leave blank" — in a chat interface they must type something to respond.

Default priority (highest wins): existing new config values > legacy config values > assets/module.yaml defaults. When legacy configs exist, read them and use matching values as defaults instead of module.yaml defaults. Only keys that match the current schema are carried forward — changed or removed keys are ignored.

Core config (only if no core keys exist yet): user_name (default: BMad), communication_language (default: English), document_output_language (default: English), output_folder (default: {project-root}/_bmad-output). Of these, user_name and communication_language are written exclusively to config.user.yaml. The rest go to config.yaml at root and are shared across all modules.

Module config: Read each variable in assets/module.yaml that has a prompt field. Ask using that prompt with its default value (or legacy value if available).

Write Files

Write a temp JSON file with the collected answers structured as {"core": {...}, "module": {...}} (omit core if it already exists). Then run both scripts — they can run in parallel since they write to different files:

python3 ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml assets/module.yaml --answers {temp-file} --legacy-dir "{project-root}/_bmad"
python3 ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source assets/module-help.csv --legacy-dir "{project-root}/_bmad" --module-code {module-code}

Both scripts output JSON to stdout with results. If either exits non-zero, surface the error and stop. The scripts automatically read legacy config values as fallback defaults, then delete the legacy files after a successful merge. Check legacy_configs_deleted and legacy_csvs_deleted in the output to confirm cleanup.

Run ./scripts/merge-config.py --help or scripts/merge-help-csv.py --help for full usage.

Confirm

Use the script JSON output to display what was written — config values set (written to config.yaml at root for core, module section for module values), user settings written to config.user.yaml (user_keys in result), help entries added, fresh install vs update. If legacy files were deleted, mention the migration. Then display the module_greeting from assets/module.yaml to the user.

Outcome

Once the user's user_name and communication_language are known (from collected input, arguments, or existing config), use them consistently for the remainder of the session: address the user by their configured name and communicate in their configured communication_language.