---
base_skill: new
base_skill_version: 4.28.0
mode: extend
---

# new — migration-gate overlay (example)

> Drop this into your repo at `.baldart/overlays/new.md` (it is shared by `/new`
> **and** `new2`) to teach the **Migration Gate** how *your* project applies a DB
> schema change. The gate runs **before** the batch (/new Phase 0 step 1b · new2
> Step 3.5): when an epic card declares a `migration_plan`, the skill front-loads
> the migration interactively so downstream cards verify against the **live**
> schema instead of one deferred to the end of the batch.
>
> Two layers cooperate:
> 1. **The epic card** declares *that* a migration is needed + the artifacts
>    (`migration_plan` block — see `epic-template.yml`).
> 2. **This overlay** declares *how* this project applies migrations (the
>    `## Migration modalities` section below). The gate merges the epic's
>    `apply_modalities` with these, de-duped by `id`, and adds the built-in
>    `["Già applicata — prosegui", "Abort"]` tail.
>
> Adapt the commands to your stack (Supabase / Prisma / Drizzle / raw SQL / …).

## Migration modalities

These are offered (via `AskUserQuestion`) whenever an epic declares
`migration_plan.required: true` and its `artifacts` exist on disk. The skill runs
the chosen `command` in the main repo (`$MAIN`), captures output to
`/tmp/migration-<first-card>.log`, surfaces only the exit code, and — when the
`migration_plan.verify` probe is present — requires it green too. A command is
**never** run without the user selecting it.

- **id: `remote-push`** — applica al DB remoto/condiviso (owner-gated; eseguito
  dalla skill SOLO su tua approvazione esplicita).
  - command: `npx supabase db push`
  - When to pick: dev DB condiviso o staging dove le card verificano contro il
    DB reale.
- **id: `local`** — applica a un DB locale/shadow; la prod resta un deploy
  manuale post-merge (Phase 7 lo riporta come item manuale).
  - command: `npx supabase db reset --local` *(oppure `npx prisma migrate dev`)*
  - When to pick: il batch verifica contro un DB locale effimero.
- **id: `prisma-deploy`** — esempio Prisma per uno stack diverso.
  - command: `npx prisma migrate deploy`

> Verifica post-apply consigliata (referenziata da `migration_plan.verify`
> nell'epic): rigenera i tipi dal DB così `tsc` downstream è onesto, es.
> `npx supabase gen types typescript --local > src/types/db.ts` oppure
> `npx prisma generate`.

## Notes

- Se l'epic NON dichiara `migration_plan` (o `required: false`), il gate è un
  **no-op silenzioso** — nessun prompt aggiuntivo, comportamento identico a oggi.
- Se gli `artifacts` non esistono ancora su disco, il gate **degrada**: non
  applica nulla e la migrazione segue il path owner-gated di fine batch (nessuna
  regressione). La migrazione va autorata prima per essere front-loaddata.
- Le modalità possono anche arrivare dalla **memoria di progetto** (oltre che da
  questo overlay e dal blocco epic): la skill le unisce tutte.
