ping-mee-self-service-platform/.agents/skills/bmad/references/migrate.md

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.