Schema / Type Migration
Plan and execute a multi-file schema or type migration safely — changing a data model, type definition, or interface across the codebase while keeping everything compiling and consistent. Plans the migration FIRST — the before/after shape, every call-site and file touched, the ordering that never leaves the tree broken, and the backout — then applies the change file-by-file, then a reviewer verifies the tree still builds and nothing referencing the old shape remains. Covers find-all-references, safe edit ordering, backward-compatibility shims, codemod-style changes, and compile/test-green verification.
Steps
Entry step: plan. Each step names the specialist role it wants; the full working prompt is expandable.
- Plan the migrationplannerentry
lock before/after, touched files, ordering, backout
Show working prompt
Plan the migration before changing a line. Step 1: Document the BEFORE shape and the exact AFTER shape (fields, types, names) of the thing being migrated. Step 2: Find every reference: search the codebase for all call-sites, definitions, and files that touch the old shape, and list them. Step 3: Decide the edit ordering that keeps the tree compiling at each step (e.g. add-new-alongside-old → migrate call-sites → remove-old), and whether a temporary compatibility shim is needed. Step 4: Note the backout/rollback approach. Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'the project compiles after the migration', 'no reference to the old shape remains', 'existing tests still pass', 'behavior is unchanged'). `write_task_note` the plan (with the file list) + checklist and write the same to the produces path.
- Apply the migrationdeveloper
edit each touched file in the planned order
Show working prompt
Execute the migration following the planned ordering. Step 1: Apply the change file-by-file in the order that keeps the tree compiling, using the file list from the plan as a checklist. Step 2: Update every call-site to the new shape; remove the old shape (and any shim) only once nothing references it. Step 3: After each batch, confirm the project still compiles/type-checks. Step 4: Do a final search to prove no reference to the old shape remains. Capture the migration summary (files changed, references updated) to the produces path. On a loop-back, fix only the files the reviewer flagged. `write_task_note` the summary and which criteria now pass.
- Verify the treereviewer
confirm it compiles, tests pass, old shape is gone
Show working prompt
Verify the migration is complete and clean. Step 1: Run the build/type-check and confirm it passes with no errors. Step 2: Run the existing test suite and confirm it is still green (behavior preserved). Step 3: Search the whole codebase for any lingering reference to the old shape/name and confirm there are none. Step 4: Spot-check a couple of migrated call-sites for correctness. Write a verification note with the build/test result and the search result to the produces path.
- Evaluatereviewer
Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.
Show working prompt
Build the project and run the tests. For EACH acceptance criterion: confirm the project compiles/type-checks cleanly, confirm the test suite is green, confirm a codebase search finds NO reference to the old shape, and confirm behavior is unchanged. Write PASS/FAIL per criterion; any lingering old-shape reference or build break is a FAIL. Then route — this is the whole point of the loop: - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`. - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "migrate" })` to loop back. The builder fixes exactly those gaps. Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in. - Finishdeveloper
All acceptance criteria met. Stamp a short summary and report DONE.
Show working prompt
Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.
Triggers
Phrases that suggest this craftbook to a crew.
- migrate a schema
- change a type everywhere
- multi-file migration
- rename a model across the codebase
- type migration
Source
View this craftbook on GitHub · MIT license