Vellum Migration Checklist
Testing & Qualityvellum-migration-checklistVellum Migration Checklist is an Agent Skill for testing & quality published in the vellum-ai/vellum-assistant repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/vellum-ai/vellum-assistant/blob/HEAD/.cursor/skills/vellum-migration-checklist/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/vellum-migration-checklist, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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
migrationStepsarray inassistant/src/persistence/steps.ts. - Update schema modules if the runtime schema changed.
- Add or update a focused
db-*migration*.test.tstest.
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_MIGRATIONSinassistant/src/workspace/migrations/registry.ts. - Make the migration idempotent.
- Add or update a focused
workspace-migration-*.test.tstest.
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.