| name | vellum-migration-checklist |
| description | Validate Vellum Assistant database and workspace migrations. Use when adding, editing, reviewing, or testing migrations, release-note migrations, persisted schemas, workspace file formats, or data backfills. |
Vellum Migration Checklist
When A Migration Is Required
Use a migration for shipped interfaces and persisted data:
- DB schema changes, indexes, backfills, or persisted row shape changes.
- Workspace file renames, moves, format changes, or namespace changes.
- Stored config or data that existing installs must keep reading.
Do not delete migration files. Migrations are append-only, even when their logic becomes obsolete.
DB Migrations
For DB migrations:
- Add a new file under
assistant/src/persistence/migrations/.
- Make it idempotent and safe to retry after interruption.
- Register it in the
migrationSteps array in assistant/src/persistence/steps.ts.
- Update schema modules if the runtime schema changed.
- Add or update a focused
db-*migration*.test.ts test.
Check for ordering drift and never reorder existing migrations.
Workspace Migrations
For workspace migrations:
- Add a new numbered file under
assistant/src/workspace/migrations/.
- Append it to
WORKSPACE_MIGRATIONS in assistant/src/workspace/migrations/registry.ts.
- Make the migration idempotent.
- Add or update a focused
workspace-migration-*.test.ts test.
Never reuse or reorder existing migration IDs.
Release Notes Migrations
There is currently no release-note surfacing mechanism. The update-bulletin feature (workspace migrations appending to a workspace bulletin file, processed by a background conversation at daemon startup) was removed. Do not add new 0XX-release-notes-* workspace migrations — the historical set is frozen by workspace-release-notes-feature-flag-guard.test.ts. If a release needs user-facing notes, design an explicit on-demand surfacing mechanism first.
Verification
Run the focused migration test first. Add package typecheck when migration exports, schema types, or registry wiring changed:
cd assistant && bun test src/__tests__/workspace-migration-example.test.ts
cd assistant && bun test src/__tests__/db-example-migrations.test.ts
cd assistant && bunx tsc --noEmit
Replace example paths with the actual test files related to the change.
