Skip to content

fix(setup): stop registering BMAD config; the installer owns it (#258, #259) #297

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pbean merged 1 commit into from
Jul 25, 2026
+204 −1,766
Merged

fix(setup): stop registering BMAD config; the installer owns it (#258, #259) #297

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
{
"name": "bmad-loop",
"source": "./src/bmad_loop/data/skills",
"description": "Automation-mode skills driven by the bmad-loop orchestrator: interactive escalation resolution (bmad-loop-resolve) and deferred-work sweep triage (bmad-loop-sweep) — the inner dev primitive (which self-reviews and commits) is the upstream bmad-dev-auto skill",
"description": "Automation-mode skills driven by the bmad-loop orchestrator: project bootstrap (bmad-loop-setup), interactive escalation resolution (bmad-loop-resolve) and deferred-work sweep triage (bmad-loop-sweep) — the inner dev primitive (which self-reviews and commits) is the upstream bmad-dev-auto skill",
"version": "0.9.0",
"author": {
"name": "pinkyd"
Expand Down
23 changes: 23 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,21 @@ breaking changes may land in a minor release.

### Changed

- **`bmad-loop-setup` stops registering BMAD config; the installer owns it (#258).** The skill
wrote `_bmad/config.yaml`, `_bmad/config.user.yaml` and a root `_bmad/module-help.csv` — the
pre-v6.10 layout, which BMAD's own resolver never reads (it merges four TOML layers, and
`/bmad-help` reads a catalog assembled from per-module `_bmad/<module>/module-help.csv`). Since
v6.10.0 bmad-loop is an installer-installed module, so the BMAD installer already stages
`_bmad/bmad-loop/`, writes the manifests, and rebuilds the help catalog on every run — and
regenerates the central `config.toml` wholesale, discarding anything written there from outside.
The three PEP 723 scripts (`merge-config.py`, `merge-help-csv.py`, `cleanup-legacy.py`) are
**removed**; setup now writes exactly one file under `_bmad/`, the per-module
`_bmad/bmad-loop/module-help.csv`, and otherwise does only what the installer cannot: install
or upgrade the orchestrator tool, run `bmad-loop init`, and preflight with `validate`. It reads
the user's name and language through BMAD's own `resolve_config.py` instead of collecting them.
Dropping the scripts also closes the PEP 723 invocation bug (#259) — no inline-dependency script
is invoked with bare `python3` any more, because none ships.

- **Ctrl+C outside a run now exits `130` cleanly (#241).** A `KeyboardInterrupt` escaping
`main()` outside `engine.run()` (config load, engine construction) now prints a one-line
`interrupted` to stderr and returns the new `ExitCode.INTERRUPTED` (`130` = 128 + SIGINT).
Expand All @@ -65,6 +80,14 @@ breaking changes may land in a minor release.
`subprocess.returncode` sees `130` rather than `-2`). A Ctrl+C _during_ a run is unchanged:
the engine still finalizes it as a resumable `stopped` run (rc `0`).

### Removed

- **The `bmad-auto` → `bmad-loop` rename compatibility is gone.** The rename shipped in 0.8.0 and
no pre-rename installs remain in the wild, so `init` no longer strips `bmad_auto`-marked hooks,
deletes `bmad-auto-*` skill dirs, carries `.automator/policy.toml` over to `.bmad-loop/`, or
prints the leftover-`.automator/` note. `bmad-loop-setup` drops its migration section with them.
A project still on `bmad-auto` should migrate on 0.9.0 before upgrading past it.

Comment on lines +83 to +90

@coderabbitai coderabbitai Bot Jul 25, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Clarify the migration version boundary.

0.9.0 removes the compatibility behavior, but the final sentence tells remaining bmad-auto users to migrate “on 0.9.0.” Say they must migrate on 0.8.x before installing 0.9.0, or document a manual migration path; otherwise those users may upgrade after the cleanup logic is already gone. This follows the release note’s statement that init no longer performs the migration.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CHANGELOG.md` around lines 83 - 90, Update the final migration guidance in
the “Removed” changelog entry to state that projects still using bmad-auto must
migrate on a 0.8.x release before installing 0.9.0. Do not leave the instruction
implying migration can occur after upgrading to 0.9.0 unless a manual migration
path is documented.

### Fixed

- **`validate` requires the review skills your `bmad-dev-auto` actually invokes (#260).** The
Expand Down
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,7 +253,7 @@ The orchestrator drives the upstream `bmad-dev-auto` skill as its inner dev prim
| `bmad-review` | merged lens-based reviewer, supersedes the hunters (**upstream** — bmm prereq, not bundled) |
| `bmad-loop-resolve` | interactive CRITICAL-escalation resolution (`/bmad-loop-resolve <story>`) |
| `bmad-loop-sweep` | deferred-work ledger triage (automation-only) |
| `bmad-loop-setup` | registers the module in `_bmad/` config + help |
| `bmad-loop-setup` | installs the orchestrator tool from Git, then runs `bmad-loop init` + `validate` |

`bmad-loop validate` preflights `bmad-dev-auto` (always) plus the review skills that copy of the skill will actually invoke — read from its `customize.toml` review layers, or from `step-04-review.md` on releases that name their reviewers inline. So a merged-`bmad-review` install needs only `bmad-review`, a v6.10.0 install needs the two hunters it names, and a tree whose configured layers reference a skill it does not have is reported instead of failing on every dev run. Missing skills (or a `bmad-dev-auto` without its `customize.toml`) are reported with bmm-module remediation before any run starts.

Expand All @@ -267,14 +267,14 @@ uv tool install "bmad-loop[tui] @ git+https://github.com/bmad-code-org/bmad-loop
uv tool install "bmad-loop[tui] @ git+https://github.com/bmad-code-org/bmad-loop.git@v0.8.1"

bmad-loop init --project /path/to/project --cli claude # add --cli codex/gemini as needed
claude "/bmad-loop-setup accept all defaults" # registers _bmad/ config + help
claude "/bmad-loop-setup accept all defaults" # installs the tool + wires the project
```

The `[tui]` extra pulls in the dashboard/settings UI (textual); drop it for a headless install. `bmad-loop --version` confirms what you've got. Existing skill dirs are left untouched (`--force-skills` to overwrite a stale copy, `--no-skills` to manage skills yourself).

### Upgrading

**Easiest — let the setup skill do it.** Re-running `/bmad-loop-setup` (or `/bmad-loop-setup upgrade`) on an already-installed project performs the two-step ritual for you: it detects the existing install, upgrades the tool with `--reinstall`, re-lays the per-project skills with `--force-skills`, and re-stamps config — then reports the before → after version.
**Easiest — let the setup skill do it.** Re-running `/bmad-loop-setup` (or `/bmad-loop-setup upgrade`) on an already-installed project performs the two-step ritual for you: it detects the existing install, upgrades the tool with `--reinstall`, and re-lays the per-project skills with `--force-skills` — then reports the before → after version.

```bash
claude "/bmad-loop-setup upgrade"
Expand Down
39 changes: 20 additions & 19 deletions docs/setup-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ an optional extra.
There are two ways the skills land in a project. The orchestrator's wheel **bundles**
the three skills, so the simplest path is **pip + `bmad-loop init`**, which installs them
itself. Alternatively the **BMAD-method installer** copies them. Either way the
`/bmad-loop-setup` skill registers the `_bmad/` config, ensures the tool is installed,
picks which coding CLIs to drive, and bootstraps the project. For the one-page summary,
`/bmad-loop-setup` skill installs the orchestrator tool, picks which coding CLIs to
drive, and bootstraps the project. For the one-page summary,
see the [Installing the skill module](../README.md#installing-the-skill-module) section
of the README.

Expand Down Expand Up @@ -62,19 +62,19 @@ claude "/bmad-loop-setup accept all defaults"

`/bmad-loop-setup` handles both first-time setup and later upgrades — re-run it any time. It:

1. Merges the module's config into `_bmad/config.yaml` (+ personal settings into the
gitignored `_bmad/config.user.yaml`) and registers its help entries in
`_bmad/module-help.csv`.
2. Installs **or upgrades** the `bmad-loop` tool from Git (see
1. Installs **or upgrades** the `bmad-loop` tool from Git (see
[Installing the tool and TUI](#installing-the-tool-and-tui)). On an upgrade it runs
`uv tool upgrade bmad-loop --reinstall`.
3. Asks **which coding CLI(s)** the orchestrator should drive, then runs `bmad-loop init`
2. Asks **which coding CLI(s)** the orchestrator should drive, then runs `bmad-loop init`
to install the `bmad-loop-*` skills + register hooks + write the `.bmad-loop/policy.toml`
template + add gitignore entries (including policy.toml itself — policy is per-machine; repos initialized before this run `git rm --cached .bmad-loop/policy.toml` once if theirs is already committed) (see [Choosing which CLIs to drive](#choosing-which-clis-to-drive)
and [Initializing CLIs other than claude](#initializing-clis-other-than-claude)). On an
upgrade it passes `--force-skills` so the per-project skill copies are refreshed.
4. Runs `bmad-loop validate` as a preflight (see [Verify](#verify)).
5. Cleans up the legacy installer package directories under `_bmad/`, leaving only config.
3. Runs `bmad-loop validate` as a preflight (see [Verify](#verify)).
4. Refreshes `_bmad/bmad-loop/module-help.csv`, the module's help entries. That is the
only file it writes under `_bmad/` — module registration, the central `config.toml`,
and the `/bmad-help` catalog are owned by the BMAD installer, which regenerates them
on every run.

Run `/bmad-loop-setup` with plain prompts if you want to choose interactively — e.g.
`claude "/bmad-loop-setup cli: claude, codex"` to preselect the CLIs.
Expand All @@ -88,7 +88,7 @@ If you are working from a clone of this repo, sync the project env and let
```bash
uv sync --extra tui # the orchestrator tool + TUI
uv run bmad-loop init --project /path/to/project --cli claude # installs skills + hooks + policy
claude "/bmad-loop-setup accept all defaults" # register _bmad/ config + help
claude "/bmad-loop-setup accept all defaults" # install the tool + wire the project
```

Add `--cli codex --cli gemini` to also populate `.agents/skills/`. `init` always
Expand Down Expand Up @@ -307,8 +307,8 @@ lines), then uninstall the tool. There is no `bmad-loop uninstall` command — t
are the documented manual procedure. Work **inside the project root**, and reclaim disk
**before** deleting state so no worktrees or archives are orphaned.

Two paths overlap: every project does steps 1–5 and 7; only projects set up through the
**BMAD-method installer** (i.e. that ran `/bmad-loop-setup`) also need step 6.
Two paths overlap: every project does steps 1–5 and 7; only projects with a `_bmad/` tree
also need step 6.

### 1. Reclaim run disk first

Expand Down Expand Up @@ -370,15 +370,16 @@ entries to strip; leave every other hook in place.
you had run `git rm --cached .bmad-loop/policy.toml` to stop sharing the per-machine policy, the
file is untracked — re-add it (`git add .bmad-loop/policy.toml`) only if you want it back in version control.

### 6. Unregister from `_bmad/` (BMAD-installer projects only)
### 6. Remove the BMAD module (BMAD-installer projects only)

If you ran `/bmad-loop-setup`, it registered the module in your BMAD config. Remove the
bmad-loop (`bmad-loop`) entries from:
There is nothing to hand-unregister: bmad-loop writes no BMAD config. If you installed the
module through the BMAD installer, remove it there — the installer owns `_bmad/bmad-loop/`,
the central `config.toml`, and the `/bmad-help` catalog, and regenerates all three on its
next run.

- `_bmad/config.yaml` and `_bmad/config.user.yaml` — drop the bmad-loop module config block
- `_bmad/module-help.csv` — drop the bmad-loop help rows

uv + `init`-only projects never write to `_bmad/` and can skip this step.
If you only ever ran `/bmad-loop-setup`, delete `_bmad/bmad-loop/module-help.csv` (the one
file it refreshes) — or the whole `_bmad/bmad-loop/` directory if the installer never
created it. uv + `init`-only projects that have no `_bmad/` can skip this step.
Comment on lines +373 to +382

@coderabbitai coderabbitai Bot Jul 25, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Align the step-6 heading with its documented scope.

The preceding rule says every project with a _bmad/ tree needs step 6, and the body explicitly covers /bmad-loop-setup-only projects. BMAD-installer projects only contradicts both and may cause setup-only users to skip cleanup. Rename the heading, for example:

Proposed fix 
-### 6. Remove the BMAD module (BMAD-installer projects only)
+### 6. Remove BMAD files

This follows the scope stated earlier in the guide and the setup-only branch in this section.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
### 6. Remove the BMAD module (BMAD-installer projects only)
If you ran `/bmad-loop-setup`, it registered the module in your BMAD config. Remove the
bmad-loop (`bmad-loop`) entries from:
There is nothing to hand-unregister: bmad-loop writes no BMAD config. If you installed the
module through the BMAD installer, remove it there — the installer owns `_bmad/bmad-loop/`,
the central `config.toml`, and the `/bmad-help` catalog, and regenerates all three on its
next run.
- `_bmad/config.yaml` and `_bmad/config.user.yaml` — drop the bmad-loop module config block
- `_bmad/module-help.csv` — drop the bmad-loop help rows
uv + `init`-only projects never write to `_bmad/` and can skip this step.
If you only ever ran `/bmad-loop-setup`, delete `_bmad/bmad-loop/module-help.csv` (the one
file it refreshes) — or the whole `_bmad/bmad-loop/` directory if the installer never
created it. uv + `init`-only projects that have no `_bmad/` can skip this step.
### 6. Remove BMAD files
There is nothing to hand-unregister: bmad-loop writes no BMAD config. If you installed the
module through the BMAD installer, remove it there — the installer owns `_bmad/bmad-loop/`,
the central `config.toml`, and the `/bmad-help` catalog, and regenerates all three on its
next run.
If you only ever ran `/bmad-loop-setup`, delete `_bmad/bmad-loop/module-help.csv` (the one
file it refreshes) — or the whole `_bmad/bmad-loop/` directory if the installer never
created it. uv + `init`-only projects that have no `_bmad/` can skip this step.
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/setup-guide.md` around lines 373 - 382, Rename the step-6 heading to
cover all projects with a _bmad/ tree, rather than limiting it to BMAD-installer
projects. Keep the existing installer-managed and /bmad-loop-setup-only cleanup
instructions unchanged.


### 7. Uninstall the tool

Expand Down
13 changes: 8 additions & 5 deletions src/bmad_loop/data/skills/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ the table below).
| `bmad-loop` | — (this repo, Git) | the orchestrator: ralph-loop, hooks, tmux adapters, TUI. CLI `bmad-loop`. Installed by `bmad-loop-setup` from Git. |
| `bmad-loop-resolve` | — (bmad-loop-native) | interactive CRITICAL-escalation resolution: a human disambiguates a frozen spec so a paused story can be re-driven (`/bmad-loop-resolve <story>`) |
| `bmad-loop-sweep` | — (bmad-loop-native) | read-only deferred-work ledger triage; owns the canonical `deferred-work-format.md` |
| `bmad-loop-setup` | — (scaffolded) | registers the module in `_bmad/config.yaml` + `module-help.csv`, **installs the orchestrator tool from Git**, runs `bmad-loop init` + `validate` |
| `bmad-loop-setup` | — (scaffolded) | **installs the orchestrator tool from Git**, runs `bmad-loop init` + `validate`, refreshes `_bmad/bmad-loop/module-help.csv` |

The **inner dev primitive is the upstream `bmad-dev-auto` skill** (BMAD-METHOD's
generic unattended dev session). It is **not** owned or bundled here — the
Expand All @@ -35,16 +35,19 @@ down for you:
```bash
uv tool install "bmad-loop[tui] @ git+https://github.com/bmad-code-org/bmad-loop.git"
bmad-loop init --project /path/to/project --cli claude # add --cli codex/gemini as needed
claude "/bmad-loop-setup accept all defaults" # registers _bmad/ config + help
claude "/bmad-loop-setup accept all defaults" # installs the tool + wires the project
```

`bmad-loop init` installs the `bmad-loop-*` skills into `.claude/skills/`
(claude) and/or `.agents/skills/` (codex/gemini), registers hooks, writes
`.bmad-loop/policy.toml`, and gitignores the runs dir. Existing skill dirs are
left untouched (`--force-skills` to overwrite, `--no-skills` to skip).
Comment on lines 37 to 44

@coderabbitai coderabbitai Bot Jul 25, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Document all supported CLI targets.

The examples and .agents/skills/ description mention only codex and gemini, but copilot and antigravity are also supported and use that tree. Include them to avoid incomplete setup guidance. Based on src/bmad_loop/data/skills/bmad-loop-setup/SKILL.md: all four adapters use .agents/skills/.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/bmad_loop/data/skills/README.md` around lines 37 - 44, Update the CLI
examples and installation description in the README to document all supported
`.agents/skills/` targets: codex, gemini, copilot, and antigravity. Keep claude
associated with `.claude/skills/`, and ensure the setup guidance consistently
reflects these adapter mappings.

`bmad-loop-setup` is one-shot for the BMAD-side wiring: it merges config + help
entries, ensures the tool is installed, then runs `bmad-loop init` and
`bmad-loop validate` (preflight).
`bmad-loop-setup` is one-shot for the bootstrap the BMAD installer cannot do: it
ensures the orchestrator tool is installed, then runs `bmad-loop init` and
`bmad-loop validate` (preflight). Module registration — `_bmad/bmad-loop/`, the
central `config.toml`, the `/bmad-help` catalog — belongs to the BMAD installer,
which regenerates it on every run; the only file the skill writes there is
`_bmad/bmad-loop/module-help.csv`.

The skills must be installed **together**: `bmad-loop-sweep` owns the canonical
`deferred-work-format.md` that the ledger normalizes to, and the upstream
Expand Down
Loading