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):
_bmad/config.toml (installer team)_bmad/config.user.toml (installer user — machine defaults)~/.bmad/config/config.user.toml (global user preferences)_bmad/custom/config.toml (custom team)_bmad/custom/config.user.toml (custom user)
resolve_customization.py (4 layers):
{skill}/customize.toml (skill defaults)~/.bmad/config/{skill}.user.toml (global user preferences)_bmad/custom/{skill}.toml (project team)_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:
--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- 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.
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):_bmad/config.toml(installer team)_bmad/config.user.toml(installer user — machine defaults)~/.bmad/config/config.user.toml(global user preferences)_bmad/custom/config.toml(custom team)_bmad/custom/config.user.toml(custom user)resolve_customization.py(4 layers):{skill}/customize.toml(skill defaults)~/.bmad/config/{skill}.user.toml(global user preferences)_bmad/custom/{skill}.toml(project team)_bmad/custom/{skill}.user.toml(project user)Why this order
_bmad/config.user.toml) contain machine defaults (OS username, "English", "intermediate") — not the user's actual preferences~/.bmad/config/) is hand-authored — it should override those machine defaults_bmad/custom/) is also hand-authored but project-specific — it should override everythingFiles changed
src/scripts/resolve_config.pysrc/scripts/resolve_customization.pytest/test-config-resolution.jsNo 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:--global-user-configflag on the installer — reuses existing prompt logic to write answers into~/.bmad/config/config.user.tomlinstead of the project-local filebmad-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.