bmad-loop-setup writes legacy config.yaml/module-help.csv; ignored on BMAD v6.10.0 TOML config layout

[jmsundar]

Summary

The bmad-loop-setup skill's config/help registration targets the legacy per-file YAML layout, but current BMAD-METHOD (v6.10.0) uses a consolidated TOML layout that its own resolver reads exclusively. The scripts write files the runtime never reads.

Environment

• bmad-loop 0.9.0
• BMAD-METHOD v6.10.0 (latest release), bmm + core modules
• macOS, Python via uv

Details

bmad-loop-setup documents and runs:

• merge-config.py → writes _bmad/config.yaml and _bmad/config.user.yaml
• merge-help-csv.py → writes a root _bmad/module-help.csv

But on v6.10.0 the consolidated config is TOML, resolved by _bmad/scripts/resolve_config.py, which uses tomllib and reads only these four layers:
_bmad/config.toml, _bmad/config.user.toml, _bmad/custom/config.toml, _bmad/custom/config.user.toml. It never reads config.yaml. Help is consolidated in _bmad/_config/bmad-help.csv (plus per-module _bmad/<module>/module-help.csv), not a root _bmad/module-help.csv.

Net effect: the merge scripts produce dead / split-brain files. On a stock install the BMAD installer has already registered the module (manifest + per-module config + help CSV), and bmad-loop validate reports BMAD config OK sourced from the TOML layout — so the merge scripts add nothing but confusion. The bmad-loop module's module.yaml also has no prompt variables, so there is nothing to collect.

Suggested fix

• Detect the consolidated TOML layout; when present, no-op config/help registration (the installer already did it) or write TOML.
• Update the skill docs (they reference config.yaml throughout) to the TOML layout.
• Consider skipping the merge entirely for modules with no prompt variables.

[coderabbitai]

🔗 Related PRs

#73 - fix(setup): never delete live core BMAD config/manifest (#64) [merged]
#77 - feat(stories): spec-to-loop engine, adapter, CLI + HITL checkpoints (Phase 2 + 3) [merged]
#86 - feat(resolve): intent-gap patch-restore re-drive + inline-review-layer preflight (re-cut) [merged]
#155 - fix(worktree): survive the renderer-era bmad-dev-auto (BMAD-METHOD #2587/#2588) [open]
#180 - Copy bmad-review into isolated worktrees for merged-reviewer installs [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!

[pbean]

Validated — issue confirmed, with two corrections

Checked every claim against a live BMAD v6.10.1-next.16 install (_bmad/_config/manifest.yaml).

Claim	Verdict	Evidence
resolve_config.py reads TOML only	TRUE	_bmad/scripts/resolve_config.py:156-159 loads exactly config.toml, config.user.toml, custom/config.toml, custom/config.user.toml. Never config.yaml.
Help lives in _config/bmad-help.csv, not root module-help.csv	TRUE	bmad-help/SKILL.md:25 names _bmad/_config/bmad-help.csv as the only catalog — the assembled concat of per-module _bmad/<mod>/module-help.csv (31 + 14 rows → 43 lines).
The files the merge scripts write are dead	TRUE	_bmad/_config/files-manifest.csv tracks config.toml, bmm/config.yaml, core/config.yaml, bmm/module-help.csv, core/module-help.csv — but not root config.yaml or root module-help.csv. Both survive here as orphans: root config.yaml holds a stale bmb: section, root module-help.csv still holds pre-rename BMAD Automator Skills rows.
module.yaml has no prompt variables	TRUE	It is metadata only (code, name, description, module_version, default_selected, module_greeting). Nothing to collect.

Correction 1 — "the installer has already registered the module" doesn't hold universally

On a uv tool install + bmad-loop init project, nothing registers the module: manifest.yaml lists only core + bmm, and there are 0 bmad-loop rows in skill-manifest.csv / bmad-help.csv. bmad-loop init never touches _bmad/. So a plain no-op would leave the module permanently invisible to /bmad-help — the fix has to register into the new layout, not just stop writing the old one.

Correction 2 — validate's "BMAD config OK" does not come from the TOML layout

cli.py:187 → bmadconfig.load_paths → bmadconfig.py:72 reads _bmad/bmm/config.yaml, the per-module YAML, which v6.10.1 still generates and manifest-tracks. The orchestrator runtime is unaffected by this issue. Migrating that read to the four-layer TOML is #154 and stays out of scope here.

Fix — detect the layout, register into what v6.10 actually reads

TOML layout detected by _bmad/config.toml existing; the legacy YAML path is kept intact for pre-6.10 projects.

• Config → write [modules.bmad-loop] into _bmad/custom/config.toml, the layer BMAD documents as "never touched by the installer". Core values are deliberately not written there — the custom layer wins over the installer layer, so a pinned user_name would override every future installer answer. Implemented as a surgical text edit (that file is human-authored and comment-bearing), with no new dependency: there is no stdlib TOML writer, and tomli-w would deepen bmad-loop-setup docs invoke PEP 723 scripts with python3; merge-config.py fails without uv run #259.
• Help → write _bmad/bmad-loop/module-help.csv (the installer's per-module location) and anti-zombie-merge our rows into _bmad/_config/bmad-help.csv, so /bmad-help lists the skills for the first time. A BMAD installer re-run regenerates the catalog and drops the rows; re-running /bmad-loop-setup restores them — documented.
• Orphans → the inert root config.yaml / config.user.yaml / module-help.csv are reported in the script JSON and the skill's Confirm step, never deleted (the bmad-loop-setup deletes core BMAD config/manifest (_bmad/core/config.yaml, _bmad/_config/) in multi-module projects #64 never-delete-live-config doctrine).

Out of scope, tracked separately: #154 (runtime bmadconfig TOML read) and #259 (python3 vs uv run for the PEP 723 scripts — not bundled, so the python3 prefix stays as-is here).

Plan — 3 phases, one branch fix/setup-toml-config-layout-258, one PR closing this issue

• P1 — merge-config.py: --bmad-dir, layout detection, TOML branch writing [modules.bmad-loop] into custom/config.toml via surgical upsert, orphan reporting, YAML branch untouched + tests
• P2 — merge-help-csv.py: per-module CSV + anti-zombie merge into the assembled catalog, orphan reporting, stale HEADER constant fix (after/before → preceded-by/followed-by), YAML branch untouched + tests
• P3 — SKILL.md rewritten for both layouts, docs/setup-guide.md / README.md / data/skills/README.md, CHANGELOG, end-to-end proof via BMAD's own resolve_config.py, PR

[pbean]

Phase 1 of 3 complete — merge-config.py (e03d579 on fix/setup-toml-config-layout-258)

merge-config.py now detects the config layout from --bmad-dir and registers into
whatever the project actually reads. No PR yet — phases 2 (help CSV) and 3 (docs) land on
the same branch first.

What changed

• New --bmad-dir (required), added to reject_unresolved_paths so an unresolved
  {project-root} token still fails loudly. --config-path / --user-config-path are now
  optional (legacy layout only) and the YAML branch errors clearly when they are missing.
• detect_layout() — "toml" iff <bmad-dir>/config.toml exists. Pure Path.exists(),
  no parsing, no imports.
• TOML branch writes [modules.bmad-loop] into _bmad/custom/config.toml and nothing
  else. No config.yaml, no config.user.yaml, no core values — the custom layer wins
  over the installer layer, so pinning user_name there would override every future
  installer answer. Payload is exactly extract_module_metadata(): name / description /
  version / default_selected.
• Surgical text edit, not parse-and-re-emit. There is no stdlib TOML writer and no new
  dependency was added (tomli-w deliberately avoided — that would deepen bmad-loop-setup docs invoke PEP 723 scripts with python3; merge-config.py fails without uv run #259).
  emit_module_table() hand-emits the table; upsert_module_table() replaces the existing
  table's span in place, so every comment and unrelated table in that human-authored file
  comes back byte-identical. Blank/comment lines directly above the next table header are
  treated as that table's preamble and left alone. The result is validated by parsing it back
  with tomllib (lazy import; toml_validated: false + a stderr note if unavailable).
• detect_orphans() reports inert root config.yaml / config.user.yaml /
  module-help.csv as {"path", "has_module_entries"}. Reported, never deleted (bmad-loop-setup deletes core BMAD config/manifest (_bmad/core/config.yaml, _bmad/_config/) in multi-module projects #64
  doctrine — legacy_configs_deleted stays []). Reads are fully defensive: a malformed
  leftover is still listed, just with has_module_entries: false.
• Result JSON gains layout, table_replaced, toml_validated, orphans_detected.
  The YAML branch keeps every key it emitted before, plus "layout": "yaml" and
  "orphans_detected": [].

Proof — BMAD's own resolver reads it back

A throwaway v6.10 fixture with a hand-written custom/config.toml, then the script, then
BMAD's unmodified _bmad/scripts/resolve_config.py as the oracle:

$ resolve_config.py --project-root <fixture> --key modules.bmad-loop
{
  "modules.bmad-loop": {
    "name": "BMAD Loop Skills",
    "description": "Automation-mode skills driven by the bmad-loop orchestrator: ...",
    "version": "0.9.0",
    "default_selected": false
  }
}

The pre-existing # my own overrides — keep me comment and unrelated [modules.other]
table survived verbatim; a second run reported table_replaced: true and left exactly one
[modules.bmad-loop]; _bmad/ gained no config.yaml.

Tests

8 new tests in tests/test_setup_cleanup_scripts.py behind a _v610_bmad fixture (adds
config.toml, config.user.toml, a comment-bearing custom/config.toml): custom-table
write, comment/unrelated-table preservation (append and replace-with-a-neighbour-below),
no YAML written, no core values leaked, upsert idempotence incl. a version bump, orphans
reported-not-deleted, and the legacy YAML branch unchanged + its missing-path error.

uv run pytest tests/test_setup_cleanup_scripts.py -q   18 passed
uv run pytest -q                                       2936 passed, 7 skipped
trunk check                                            No issues

Next

• P2 — merge-help-csv.py: per-module CSV + anti-zombie merge into _config/bmad-help.csv.
• P3 — SKILL.md / docs / CHANGELOG, then the PR closing this issue.

#259 (the python3 invocation prefix) and #154 (the runtime's _bmad/bmm/config.yaml read)
remain deliberately out of scope.

[pbean]

Phase 2 of 3 complete — merge-help-csv.py (606f76a on fix/setup-toml-config-layout-258)

merge-help-csv.py now detects the layout the same way merge-config.py does and, on
BMAD v6.10+, registers the skills where /bmad-help actually looks. No PR yet —
phase 3 (docs + CHANGELOG) lands on the same branch first.

What changed

• New --bmad-dir (required), added to reject_unresolved_paths. --target is now
  optional (legacy layout only); --module-code becomes required on the TOML branch — it
  names the per-module CSV directory. Each branch fails loudly with the layout-specific
  argument it is missing.
• detect_layout() / detect_orphans() — its own copies, not imports: both scripts
  ship standalone into user projects. One difference forced by the PEP 723 header: this
  script declares zero dependencies and must stay that way, so where merge-config.py
  parses orphan YAML with pyyaml, this one uses a conservative unindented-key: line scan.
  Verified below that the two agree row-for-row on the same tree.
• TOML branch writes two files.
  • _bmad/<module-code>/module-help.csv — the installer's per-module location. The whole
    file is ours, so it is a full overwrite (source header + source rows). Side effect worth
    having: cleanup-legacy.py's _CONFIG_MARKERS lists module-help.csv, so this makes
    _bmad/bmad-loop/ cleanup-protected.
  • _bmad/_config/bmad-help.csv — the assembled catalog, shared with every other module,
    so rows are merged anti-zombie (drop every row whose module column matches a source
    module code, append fresh) and the catalog's own header is preserved. Created from
    the source header when absent.
• Root _bmad/module-help.csv is never written on this branch — it is manifest-untracked
  and read by nothing. A pre-existing one is reported in orphans_detected and left
  byte-identical (bmad-loop-setup deletes core BMAD config/manifest (_bmad/core/config.yaml, _bmad/_config/) in multi-module projects #64 doctrine; legacy_csvs_deleted stays []).
• Stale HEADER constant fixed — it read after / before; every real CSV
  (_bmad/_config/bmad-help.csv, _bmad/bmm/module-help.csv, our own
  assets/module-help.csv) uses preceded-by / followed-by. It is only a last-resort
  fallback: an existing target's header still wins.
• Result JSON — TOML branch: layout, module_help_path, catalog_path,
  catalog_existed, module_codes, rows_removed, rows_added, total_rows,
  legacy_csvs_deleted, orphans_detected. YAML branch keeps every key it emitted before
  (target_path / target_existed included) plus "layout": "yaml" and
  "orphans_detected": [].

Proof — a v6.10 fixture, both scripts, BMAD's own resolver as oracle

$ merge-help-csv.py --bmad-dir <fixture>/_bmad --source assets/module-help.csv --module-code bmad-loop
{
  "status": "success",
  "layout": "toml",
  "module_help_path": ".../_bmad/bmad-loop/module-help.csv",
  "catalog_path": ".../_bmad/_config/bmad-help.csv",
  "catalog_existed": true,
  "module_codes": ["BMAD Loop Skills"],
  "rows_removed": 0,
  "rows_added": 2,
  "total_rows": 5,
  "legacy_csvs_deleted": [],
  "orphans_detected": [
    {"path": ".../_bmad/config.yaml", "has_module_entries": true},
    {"path": ".../_bmad/module-help.csv", "has_module_entries": true}
  ]
}

# second run — anti-zombie replaces rather than duplicates
{"rows_removed": 2, "rows_added": 2, "total_rows": 5, "catalog_existed": true}

merge-config.py (pyyaml) and merge-help-csv.py (stdlib line scan) produced identical
orphans_detected lists on this tree.

_bmad/_config/bmad-help.csv after two consecutive runs — one block of our rows, every
pre-existing row intact, catalog header preserved:

module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
BMad Method,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
BMad Method,bmad-brainstorming,Brainstorm Project,BP,...,,,1-analysis,,,false,planning_artifacts,brainstorming session
BMad Method,bmad-market-research,Market Research,MR,...,,,1-analysis,,,false,planning_artifacts|project-knowledge,research documents
BMAD Loop Skills,bmad-loop-setup,Setup Loop Module,SA,...,configure,{-H: headless mode},anytime,,,false,{project-root}/_bmad,config.yaml entries
BMAD Loop Skills,bmad-loop-sweep,Sweep Triage,ST,...,triage,{--feedback path},anytime,,,false,implementation_artifacts,result.json triage plan

_bmad/bmad-loop/module-help.csv holds the source header + exactly our two rows. The inert
_bmad/module-help.csv and _bmad/config.yaml came back byte-identical.

And BMAD's unmodified resolver still reads phase 1's registration back out of the same tree:

$ uv run --no-project --python 3.11 <fixture>/_bmad/scripts/resolve_config.py \
    --project-root <fixture> --key modules.bmad-loop
{
  "modules.bmad-loop": {
    "name": "BMAD Loop Skills",
    "description": "Automation-mode skills driven by the bmad-loop orchestrator: ...",
    "version": "0.9.0",
    "default_selected": false
  }
}

Tests

8 new tests in tests/test_setup_cleanup_scripts.py; _v610_bmad now also seeds a realistic
_config/bmad-help.csv (BMad Method + Core rows, real v6.10 columns). Coverage: per-module
CSV contents + header, catalog merge preserving other modules and the target header, merge
idempotence (second run's rows_removed == rows_added, one contiguous block), catalog
creation when absent, root CSV never written / reported-not-deleted, pre-rename row
behavior, the YAML branch unchanged, and both missing-argument errors.

uv run pytest tests/test_setup_cleanup_scripts.py -q   26 passed
uv run pytest -q                                       2944 passed, 7 skipped
trunk check                                            No issues

Three notes for phase 3

1. test_merge_help_toml_strips_pre_rename_rows asserts the opposite of its name, on
   purpose. The anti-zombie filter keys on source module codes (BMAD Loop Skills), so
   leftover BMAD Automator Skills rows never match and survive. SKILL.md:53 already
   documents that manual-deletion step for the root CSV — phase 3 must extend it to
   _bmad/_config/bmad-help.csv.
2. SKILL.md's script commands are now stale for both scripts: neither passes
   --bmad-dir (required since P1/P2) and merge-help-csv.py needs --module-code on the
   TOML branch. Phase 3 closes that seam. The python3 prefix stays as-is (bmad-loop-setup docs invoke PEP 723 scripts with python3; merge-config.py fails without uv run #259).
3. Error JSON goes to stdout in this script, matching its own pre-existing
   reject_unresolved_paths and cleanup-legacy.py, whereas merge-config.py uses stderr.
   Left as-is deliberately — no unrequested behavior change — but worth a follow-up to unify.

Also worth recording: run the resolver proof with uv run --no-project. Plain
uv run --python 3.11 … from inside the repo tears down and rebuilds the project .venv
at 3.11; recovery is uv sync --all-extras.

Next

• P3 — SKILL.md two-layout rewrite, docs/setup-guide.md, README.md,
  data/skills/README.md, CHANGELOG, then the PR closing this issue.

#259 (the python3 invocation prefix) and #154 (the runtime's _bmad/bmm/config.yaml read)
remain deliberately out of scope.

[pbean]

Phase 3 of 3 complete — docs + CHANGELOG → PR #285 (fff4c6b)

The three-phase program is done. #285 is
open ready for review and closes this issue.

What changed in this phase (docs only — no behavior changes)

• bmad-loop-setup/SKILL.md — the main rewrite. The overview is now a two-layout
  explanation (TOML on v6.10+ / legacy YAML before, detected by _bmad/config.toml), naming
  the three files the TOML branch writes and stating plainly that no core values are
  written to the custom layer and why. The fresh-install-vs-upgrade tells, the bauto
  rename-migration steps, Collect Configuration (module.yaml declares zero prompt variables ⇒
  nothing to collect on TOML), Create Output Directories, and the Confirm step were all
  updated per layout.
• Confirm step rewritten against the scripts' real result-JSON keys — layout,
  table_replaced, toml_validated, module_help_path, catalog_path, catalog_existed,
  orphans_detected — read out of the code, not the plan. It now instructs the skill to tell
  the user that orphans_detected files are inert leftovers, safe to delete by hand, and that
  bmad-loop never deletes them; and to state the installer-regenerates-the-catalog caveat
  every time.
• The stale command lines are fixed. After P1/P2 neither SKILL.md command passed the
  now-required --bmad-dir. Both now do, and they carry the legacy-only arguments too, so
  one command line works on both layouts (ignored on the TOML branch). The python3
  prefix is untouched — that is bmad-loop-setup docs invoke PEP 723 scripts with python3; merge-config.py fails without uv run #259.
• docs/setup-guide.md (what setup does + the uninstall "Unregister from _bmad/" step),
  README.md, data/skills/README.md, and a ### Fixed CHANGELOG entry.
• One drive-by content fix: assets/module-help.csv's outputs cell for bmad-loop-setup
  read config.yaml entries, wrong on v6.10 — now the layout-neutral
  module config + help entries. No test asserted the old string.

End-to-end proof

A throwaway v6.10 fixture, both scripts run twice, then BMAD's unmodified
resolve_config.py as the oracle:

$ uv run --no-project --python 3.11 <fixture>/_bmad/scripts/resolve_config.py \
    --project-root <fixture> --key modules.bmad-loop
{
  "modules.bmad-loop": {
    "name": "BMAD Loop Skills",
    "description": "Automation-mode skills driven by the bmad-loop orchestrator: ...",
    "version": "0.9.0",
    "default_selected": false
  }
}

• _config/bmad-help.csv holds exactly one block of BMAD Loop Skills rows after two runs
  (2 rows, matching the source), with both pre-existing BMad Method / Core rows intact.
  Run 1: table_replaced: false, rows_removed: 0 / rows_added: 2 / total_rows: 4.
  Run 2: table_replaced: true, rows_removed: 2 / rows_added: 2 / total_rows: 4.
  toml_validated: true on both.
• No root config.yaml / config.user.yaml / module-help.csv was created.
• The pre-existing comments and the unrelated [agents.bmad-agent-pm] table in
  custom/config.toml survived verbatim.
• On a second fixture pre-seeded with pre-6.10 leftovers, all three were reported in
  orphans_detected (with correct has_module_entries) and survived byte-identical;
  legacy_configs_deleted: [].

Full output is pasted in the PR body.

uv run pytest -q     2944 passed, 7 skipped
trunk check          No issues

#259 (the python3 invocation prefix) and #154 (the runtime's _bmad/bmm/config.yaml
read) remain deliberately out of scope and stay open.

[pbean]

Triage: still open and still valid. Filed under #287 with the rest of the v6.10 TOML adoption work.

For the record, since a PR came and went: PR #285 was closed unmerged. The fix had outgrown the
defect — it is not that the bug was found to be wrong. The bug report above is unchanged and
unfixed on main.

The prior work survives on origin/fix/setup-toml-config-layout-258 (tip fe2b95f) for whoever
picks this up; the validated v6.10 layout research in it is worth reading even if the code is not
reused. Two traps found the hard way and worth carrying forward:

• A corrupt custom/config.toml is swallowed by BMAD's own resolver at exit 0, silently
  dropping the user's own overrides with no error. Any fix must verify the layout it is about to
  write into before writing, not after.
• os.replace onto a symlinked config replaces the symlink, not its target. Config files in
  this layout are plausibly symlinked in shared setups.

A narrow fix — detect the consolidated TOML layout and no-op config/help registration when the
installer has already done the work — is very likely the right altitude here.