# Migrating a project between versions of a module

A module ships a migration as `migration-<n>.toml` beside its `bmod.toml`, where `<n>` is a whole number that sets the order of the module's migrations. The file has a `[migration]` table: `module` (the record's code), `from`, `to`, `title`, `summary`, `detect`, `guide`, and a `checklist` array, plus any other prose keys the migration defines. `knowledge.py` lists only a file that has all of those. The file holds the rules. This skill finds it, checks whether it applies, and follows it; it adds no rules of its own.

1. **Find.** Run `uv run {skill-root}/scripts/knowledge.py` with one `--root` per active root. `migrations` lists every migration installed modules ship: `module`, `from`, `to`, `title`, `file`. A `migration` problem names a file that could not be used; relay it. No migrations: say that no installed module ships one, and stop.
2. **Match.** A module or a version the user named narrows the candidates; it never skips the check. Read each remaining candidate's `detect` and check its signals against the project, reading only; list the ones whose signals are present with `title`, `from`, and `to`, in the order `migrations` gives, and let the user choose. None present: say the project already looks like the `to` version and stop; the user may still name one and say to run it anyway, and that override is recorded in the plan.
3. **Follow the file.** Read the chosen file whole and do what `guide` says, in its order, with `precautions` and `target` when it has them. The migration decides what is inventoried, planned, shown, approved, moved, and written; a plan is shown and approved by the user before anything changes. Never change `_bmad/` beyond what the file names under its configuration and workspace rules; `bmad setup` owns the rest. Never delete a file outside version control; a removal the file's own steps offer is a commit the user chooses. Never push.
4. **Verify.** Run every item of `checklist`, record its result where the file says, fix or report each failure, and give the user the summary the file asks for. Several migrations chosen, of one module or several: run them one at a time in that order, each verified before the next. After each one, check the `detect` of that module's later migrations again, since the one just run can make them apply, and offer any that now match.