Per-user global config not shared across git worktrees

[jrevillard]

Problem

Users working across multiple git worktrees or cloned repos must re-enter personal settings (user_name, communication_language, user_skill_level) in every project's _bmad/config.user.toml. The installer writes defaults (e.g. OS username) into this file, but these are machine-generated — the user's actual preferences are lost across projects.

Solution

A global user layer at ~/.bmad/config/ that overrides installer defaults but is still overridden by hand-authored project customizations.

Priority order (lowest → highest)

resolve_config.py (5 layers):

1. _bmad/config.toml (installer team)
2. _bmad/config.user.toml (installer user — machine defaults)
3. ~/.bmad/config/config.user.toml (global user preferences)
4. _bmad/custom/config.toml (custom team)
5. _bmad/custom/config.user.toml (custom user)

resolve_customization.py (4 layers):

1. {skill}/customize.toml (skill defaults)
2. ~/.bmad/config/{skill}.user.toml (global user preferences)
3. _bmad/custom/{skill}.toml (project team)
4. _bmad/custom/{skill}.user.toml (project user)

Why this order

• Installer-generated files (_bmad/config.user.toml) contain machine defaults (OS username, "English", "intermediate") — not the user's actual preferences
• Global user config (~/.bmad/config/) is hand-authored — it should override those machine defaults
• Custom project config (_bmad/custom/) is also hand-authored but project-specific — it should override everything

Files changed

File	Change
src/scripts/resolve_config.py	Add global user layer between installer layers and custom layers
src/scripts/resolve_customization.py	Add global user layer between skill defaults and project layers
test/test-config-resolution.js	New — 14 unit tests for both scripts

No installer changes needed — the scripts are copied to _bmad/scripts/ via _installSharedScripts.

Follow-up: Setup UX

No guided setup exists yet for ~/.bmad/config/. Users must create it manually. Two options considered:

1. --global-user-config flag on the installer — reuses existing prompt logic to write answers into ~/.bmad/config/config.user.toml instead of the project-local file
2. Dedicated skill (e.g. bmad-setup-global-config) — interactive guided setup, could also handle global skill customizations ({skill}.user.toml)

Leaving this for a future iteration — input welcome on which approach (or both) to pursue.

[coderabbitai]

🔗 Related PRs

#1520 - feat: add non-interactive installation support [merged]
#1698 - fix: change default Codex install location from global to project [merged]
#1735 - fix(installer): refuse install when ancestor dir has BMAD commands [merged]
#2282 - feat(skills): YAML-based agent customization with Python resolver [merged]
#2289 - feat(core-skills): add bmad-customize — guided authoring for _bmad/custom overrides [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[jrevillard]

Implementation (PR incoming)

Implemented the global user layer in ~/.bmad/config/ for both resolution scripts:

• resolve_config.py: 5-layer merge (global user → base team → base user → custom team → custom user)
• resolve_customization.py: 4-layer merge (global user → skill defaults → project team → project user)
• ~/.bmad/config/config.user.toml for central config, ~/.bmad/config/{skill}.user.toml for skill customization
• 14 new tests, all 327 tests pass

Follow-up: Setup UX

No guided setup exists yet for ~/.bmad/config/. Users must create it manually. Two options considered:

1. --global-user-config flag on the installer — reuses existing prompt logic to write answers into ~/.bmad/config/config.user.toml instead of the project-local file
2. Dedicated skill (e.g. bmad-setup-global-config) — interactive guided setup, could also handle global skill customizations ({skill}.user.toml)

Leaving this for a future iteration — input welcome on which approach (or both) to pursue.

[jrevillard]

Scope note: only BMM & Core skills updated so far

The PR (#2339) currently updates skills in BMM (src/bmm-skills/) and Core (src/core-skills/) to use resolve_config.py instead of reading config.yaml directly.

The following modules still have skills/workflows that may reference config.yaml directly and need the same treatment:

Module	Repo / Location	Status
BMad Builder (BMB)	external module	needs audit
Test Architect (TEA)	external module	needs audit
Game Dev Studio (BMGD)	external module	needs audit
Creative Intelligence Suite (CIS)	external module	needs audit
Module Template	external module	needs audit

These external modules live in ~/.bmad/cache/external-modules/ and are not part of this repo. Each will need a separate pass to update their skill files to call resolve_config.py.