菜单
Runbook for shipping prumo to production — promoting dev to main, Railway deploy mechanics (Wait-for-CI, SKIPPED-SHA recovery), Supabase auth/storage migration deploys, env-var rotation, and rollback. Invoke manually with /deploy-release when deploying, promoting, or recovering a stuck deploy.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
prumo's visual language — the *what it should look like* layer (Plane/Linear/WorkOS aesthetic). Use when deciding layout structure, density, header height, sidebar behaviour, hover affordances, empty states, loading patterns, or any "how should this screen feel" question for frontend/ pages and components. The sibling ui-styling skill is the *how* layer underneath (Tailwind/shadcn/Radix mechanics) — read this one first when designing, that one when implementing classes.
Use this when writing or modifying anything under `backend/app/` — FastAPI endpoints, SQLAlchemy 2.0 async models or queries, Alembic migrations, Celery tasks in `backend/app/worker/`, Pydantic v2 schemas, Supabase RLS policies in `supabase/migrations/`, or `pytest` tests. Covers prumo's HITL stack (extraction + quality assessment), project-membership auth, structlog observability, and the migration split between Alembic (app schema) and Supabase CLI (auth/storage). Trigger on requests like "add endpoint", "create migration", "write a Celery task", "fix RLS", "new SQLAlchemy model", or anything touching `extraction_*` tables or `/api/v1/runs/...` / `/api/v1/hitl/sessions`.
Use whenever writing, debugging, or designing tests for prumo — Playwright E2E (with a11y + visual), Vitest unit/component, pytest backend integration, MSW v2 network mocks, or whenever a test is flaky. Pulls in the right tool, the right fixture pattern, and the project rule that integration beats heavy mocking. Trigger on "test", "spec", "flaky", "Playwright", "Vitest", "pytest", "MSW", "axe", "snapshot", "visual regression", "test strategy", "mock the database", "test fixture", "CI test".
Use when writing or modifying the STRUCTURE of anything under `frontend/` — where code lives, data flow, and state. Covers components/{domain} organization, TanStack Query hooks + key factories, `services/*Service.ts` via the typed apiClient, Zustand stores vs React Context, react-hook-form + Zod forms, generated `types/api/schema.d.ts`, ErrorResult boundaries, and the React Compiler constraints. Trigger on "add a page", "add a data hook", "add a mutation", "wire a form", "new store", "fetch data", or anything about how the frontend is organized. NOT for visual language (use `frontend-ux`) or Tailwind/shadcn class mechanics (use `ui-styling`).
Use BEFORE claiming done, before writing a PR body, when receiving review feedback (especially unclear or technically questionable), when requesting review, or after completing a feature/bugfix. Enforces technical rigor over performative agreement, evidence-based completion claims, and a prumo-specific review checklist tuned to recurring incident classes (BOLA, run-state TOCTOU, error swallowing, schema drift, ApiResponse envelope drift, stale TanStack cache). Triggers on phrases "looks good", "should be fine", "I'll fix it", "ready to merge", "tests pass", "done", "complete", "fixed", "ready for review", "let me draft the PR". Be pushy about running it.
prumo's visual feedback loop — render the screen, screenshot it, compare to the Plane/Linear target, list the diffs, fix, re-screenshot, confirm. Use BEFORE claiming any frontend screen or component "done", and whenever the ask is "does this look right", "match Linear/Plane", "tighten this screen", "iterate on the UI", "why does this look off / generic / AI-made", or after any non-trivial layout, density, spacing, or theme change. The `/design-review` command runs this loop on a route. Siblings: `frontend-ux` sets the visual language (what it should look like), `ui-styling` is the Tailwind/shadcn mechanics (how to wire the classes); this skill is the *did it actually end up that way* layer that closes the loop with your eyes, not the diff.
| name | deploy-release |
| description | Runbook for shipping prumo to production — promoting dev to main, Railway deploy mechanics (Wait-for-CI, SKIPPED-SHA recovery), Supabase auth/storage migration deploys, env-var rotation, and rollback. Invoke manually with /deploy-release when deploying, promoting, or recovering a stuck deploy. |
| disable-model-invocation | true |
Production topology: Railway (FastAPI web + Celery worker + Redis,
deploys from main) · Vercel (frontend, deploys from main,
VITE_API_URL → Railway web) · Supabase (Postgres + Auth +
Storage). Prod URLs: backend https://web-production-48b398.up.railway.app,
frontend https://prumoai.vercel.app.
Everything lands on dev via squash-merged PRs behind the 8
required checks.
Pre-deploy gate: run /preflight (read-only; probes Vercel,
Supabase advisors, Railway health).
Promote via a merge-commit PR — dev → main cannot fast-forward
(main carries the Merge pull request #NNN from raphaelfh/dev
commits dev lacks, so git push origin dev:main is rejected as
non-fast-forward):
gh pr create --base main --head dev --title "Promote dev to main"
gh pr merge <n> --auto --merge # merge commit — NOT squash, NOT fast-forward
main branch protection requires the 8 check contexts green on the
head before the merge completes; the dev HEAD already carries them.
Railway (GitHub App) waits for the full Actions suite — CI and
docs-ci — on the main push, then builds web + worker. The web
container runs alembic upgrade head before gunicorn, so app-schema
migrations deploy atomically with code.
Vercel builds the frontend from main independently.
Post-deploy: the post-deploy-smoke workflow (push-triggered +
hourly) checks /health, the frontend, and a CORS preflight from
the prod origin. A failure emails the owner.
Only Alembic runs on deploy. supabase/migrations/*.sql must be
pushed explicitly:
cd supabase && supabase db push # links to the remote project
Never apply them via the Supabase MCP apply_migration (records a
non-matching version → a later db push re-runs and errors). This is
hook- and permission-enforced, not just convention.
If a workflow on the main push reports SKIPPED (e.g. path-filtered docs-ci), Railway's Wait-for-CI can wedge — and it does not self-heal when you re-run the job. Recovery, in order:
main (empty commit is fine:
git commit --allow-empty -m "chore: nudge railway wait-for-ci").railway up from the repo root. The
backend --path-as-root form documented in older notes is broken
(also blocked by the bash-guard hook).Detection: the post-deploy-smoke workflow catches the symptom (stale prod while CI is green).
git revert the offending commit on main and let the
pipeline redeploy.docs/reference/deployment.md. Env files are
gitignored — nothing to commit.${{shared.X}} resolved empty — known gotcha).VITE_* copies, so key rotation requires a
manual VITE_* update + prod rebuild. Never widen envPrefix
(would leak service-role/JWT/POSTGRES_PASSWORD into the bundle).railway logs --service worker (look for "Connected to
redis://").