Initialize Neon Postgres

Walks the user through installing Neon Postgres from the Vercel Marketplace with branch-per-environment enabled so Vercel auto-injects a separate DATABASE_URL per environment, which apps/worker/src/infra/runtime-env.ts requires at boot.

AI Workflow uses Postgres as its run registry and its store for workflow definitions, approvals and telemetry: tracking active workflow runs per ticket, deduplicating dispatch, and locking concurrent cron cycles. Tables are created automatically; migrations run during every deploy's build step (apps/worker/scripts/db-migrate.ts).

Canonical reference: SETUP.md section 4 holds the facts and constraints for the database. This skill is the procedure; when the two disagree, SETUP.md wins and this skill gets updated.

If you want full project setup (Jira + VCS + Agent + Slack + Neon + deploy), invoke init-env instead. This skill only handles Neon.

Precondition

apps/worker/.vercel/project.json must exist: the worker is linked from apps/worker (SETUP.md section 3), and this skill's commands run there. If missing:

ERROR: no Vercel project linked. Run `vercel link` first, or invoke `init-env`
for the full first-time setup.

Halt.

State detection

1. vercel env ls | grep DATABASE_URL: if present for all three environments, skip install and go to verification.
2. If missing: walk the user through the Marketplace install below.

Step 1: Marketplace install

Walk the user through these steps (Vercel dashboard install is faster than CLI):

1. Open https://vercel.com/marketplace/neon and click Install.
2. Select the team and connect it to the ai-workflow Vercel project.
3. Critical: enable branch per environment (development / preview / production) when configuring the integration. Each environment's DATABASE_URL must point at its own Neon branch. The build fails with an env_marker error if two environments share one branch: that guard protects the production run registry from preview deployments. The one exception is an engine canary that declares its owner with DATABASE_SHARED_WITH=production (SETUP.md section 4); a new deployment has none.
4. Confirm the install. Vercel auto-injects DATABASE_URL for all three environments.

CLI alternative: vercel integration add neon

Step 2: Confirm the key landed

Tell the user to confirm in Vercel → Project Settings → Environment Variables that they see DATABASE_URL scoped to all three environments (Production, Preview, Development).

CLI alternative (faster from a terminal):

vercel env ls | grep DATABASE_URL

Success: DATABASE_URL appears for each of the three environments, with different values (distinct ep-… endpoint hosts confirm branch isolation; ignore any -pooler suffix when comparing hosts, because pooled and direct URLs of the same branch differ textually).

If DATABASE_URL is missing or the same value appears across environments, the branch-per-environment option wasn't enabled during install. Recovery paths:

• Easier: disconnect the Neon integration (Project → Storage → Neon → Disconnect), reinstall with branch-per-environment enabled.
• Manual fix: in the Neon console, create separate branches per environment and update each environment's DATABASE_URL in Vercel manually. Works but the integration won't keep them in sync automatically.

Verification (all must pass)

1. vercel env ls shows DATABASE_URL for development, preview, and production.
2. Branch isolation: pull each environment's value and confirm the hosts differ (vercel env pull --environment=production .env.prod etc., compare the ep-… endpoint hosts; ignore any -pooler suffix when comparing hosts, because pooled and direct URLs of the same branch differ textually). Identical hosts across environments mean the build's env_marker guard will fail: fix the integration's branch settings.
3. Migrations: cd apps/worker && vercel env pull .env.local && pnpm db:migrate against the development branch: expect "[db-migrate] OK: branch claimed by 'development'." (The script loads .env.local then .env via dotenv; vars already set in the shell env are never overridden.)

Step 3: Done

No paste-template needed: DATABASE_URL is auto-injected by Vercel. The init-env Step 8 validator (apps/worker/src/infra/runtime-env.ts) confirms it made it.

If invoked from init-env, return control. If standalone, end.

Troubleshooting

• Build fails with [db-migrate] FATAL: this Neon branch is already claimed by VERCEL_ENV='production', but this build is VERCEL_ENV='…': two environments share one Neon branch (the env_marker guard). Reconfigure the integration for branch-per-environment, redeploy.
• DATABASE_URL undefined at build: integration not connected to this project, or env var scoped to the wrong environments.
• Stale run registry for one ticket (e.g. after a bad deploy or smoke test): run /ai-workflow redis inspect <KEY> in Slack to see its entries, then /ai-workflow redis reset <KEY> to clear them (integrations/slack/commands.ts). Reset does not cancel a live run; cancel it first with /ai-workflow cancel <KEY> or MCP runs.cancel.

Don'ts

• Don't manually create a Neon database outside the Marketplace. You'd lose the auto-injection benefit and have to manage DATABASE_URL by hand. The Marketplace integration is the preferred path.
• Don't share one Neon branch across environments unless the sharing environment declares DATABASE_SHARED_WITH (only the engine canary does). The env_marker build guard will fail: it protects the production run registry from preview deployments polluting it.
• Don't skip branch isolation. A preview deploy writing to the production Neon branch corrupts the run registry and can orphan live sandboxes.