Pre-Deploy Safety Gate

claude-predeploy

The pre-deploy gate that proves your Claude Code deploy won't silently drop what's already live.

A pre-deploy safety gate for Claude Code. Its headline check verifies that your deploy candidate is a git-descendant of what's actually running in production — so an agent (or you) can't quietly revert a route, a feature, or another branch's work by shipping the wrong tree — and it proves your rollback path actually works before it lets you ship.

It's the anti-"AI shipped a regression to prod" tool — not another code auditor. The checks that decide "would this deploy break prod?" are deterministic Node scripts with fixed exit codes, run as one consolidated PASS / BLOCK report that refuses the deploy until every check passes and a human gives an explicit "ship it."

Why this, not another code-audit tool

Plenty of tools review your code. claude-predeploy gates your deploy. Two things set it apart:

• The load-bearing checks are deterministic, not LLM opinions. The gates that decide whether the deploy is safe are plain Node scripts with exit codes (0=PASS / 1=BLOCK / 2=ERROR) — reproducible, CI-chainable, and immune to a model having an off day. AI agents add judgment (code review, security, visual/SEO regressions) on top of the gate, never underneath it.
• Nobody else gates on deploy-lineage or a tested rollback. The two differentiating checks — "is this candidate a descendant of the live SHA?" and "does the documented rollback actually restore the last-good version?" — catch the exact failures that turn a routine deploy into an outage, and they're precisely the two nothing else verifies before you ship.

The problem it solves

Deploys go wrong in boringly predictable ways:

• You deploy a feature branch that isn't a descendant of what's live, silently reverting work that shipped on another branch.
• You delete a route/page and only find the 404 in production.
• A dev/demo/auth bypass flag or a server-only secret leaks into a production build.
• A "green" build ships but a critical path 404s and nobody notices until a customer does.
• You need to roll back and discover the rollback path was never actually tested.

Each of these is cheap to catch mechanically before the deploy and expensive to discover after. claude-predeploy turns that catch into a repeatable gate.

The checks

Deterministic scripts (scripts/*.mjs, no LLM, exit 0=PASS / 1=BLOCK / 2=ERROR):

Judgment agents (agents/*.md, dispatched by the /predeploy skill):

• db-safety — schema changes are additive/backward-compatible and nothing the live frontend still references gets dropped.
• rollback-verify — a specific previous-good version exists and the restore path is real, not assumed.
• visual-parity (public sites) — screenshot-diffs key pages live vs candidate for layout/content regressions.
• seo-guard (public sites) — titles/canonical/hreflang/sitemap/robots/redirects preserved (a site-wide noindex is an instant block).
• perf-check (public sites, optional) — Core Web Vitals + bundle-size regressions.

Plus your own code-review and security-audit agents on the deploy diff, if you have them.

Tiers

Install

claude-predeploy is a set of Claude Code skills + agents + standalone Node scripts.

1. Clone this repo somewhere stable (e.g. ~/tools/claude-predeploy).

2. Make the skills & agents discoverable by Claude Code. Point Claude Code at them (symlink or copy) so the skills and agents resolve:

   # user-level Claude Code config
   ln -s ~/tools/claude-predeploy/skills/predeploy    ~/.claude/skills/predeploy
   ln -s ~/tools/claude-predeploy/skills/deploy-guard ~/.claude/skills/deploy-guard
   ln -s ~/tools/claude-predeploy/skills/shot         ~/.claude/skills/shot
   for a in ~/tools/claude-predeploy/agents/*.md; do ln -s "$a" ~/.claude/agents/; done

   Copy to clipboard

   (Or wire them in as a plugin/marketplace entry — the layout mirrors the standard skills/ + agents/ plugin structure.)

3. Create your registry. Copy the example and edit it for your projects:

   cp examples/registry.example.json registry.json   # gitignored

   Copy to clipboard

   The scripts read registry.json from the repo root by default, or from $PREDEPLOY_REGISTRY.

Requirements: Node 18+, git, curl. vercel CLI is used opportunistically for the prod-env check if your deployMethod starts with vercel (skipped gracefully if not present).

Usage

Run any script directly:

node scripts/regression-guard.mjs  --project=example-project
node scripts/config-env-check.mjs  --project=example-project
node scripts/build-test.mjs        --project=example-project [--build-only|--skip-tests]
node scripts/post-deploy-verify.mjs --project=example-project --marker='/checkout=Buy Now'

Each prints a final PREDEPLOY_RESULT {...} line and exits 0 (PASS) / 1 (BLOCK) / 2 (ERROR), so you can chain them in CI or a git hook.

Or run the whole gate through Claude Code:

/predeploy example-project

The /predeploy skill runs the scripts, dispatches the judgment agents, consolidates one PASS/BLOCK table, and only clears the deploy when every check passes and you give an explicit ship-it that turn. The skill never deploys anything itself — the deploy stays a separate, human-gated step.

The registry

One entry per deployable project describes everything the checks need. See examples/registry.example.json — every field is documented inline in its _fieldDocs block. A trimmed entry:

{
  "slug": "example-project",
  "repo": "/absolute/path/to/your/project",
  "prodBranch": "main",
  "deployMethod": "vercel-git",
  "isPublic": true,
  "liveUrl": "https://example.com",
  "criticalPaths": ["/", "/pricing", "/login", "/sitemap.xml"],
  "requiredEnv": ["NEXT_PUBLIC_API_URL", "SERVICE_ROLE_KEY", "CRON_SECRET"],
  "devBypassFlags": ["NEXT_PUBLIC_ADMIN_BYPASS", "NEXT_PUBLIC_DEMO_MODE", "LOCAL_AUTH"],
  "serverOnlySecrets": ["SERVICE_ROLE_KEY", "CRON_SECRET"],
  "rollbackMethod": "Vercel dashboard -> promote the previous READY production deployment."
}

The pipeline is opinionated toward Next.js / Vite apps on Vercel (route-file detection, NEXT_PUBLIC_* secret checks, vercel env ls), but the registry and scripts are plain enough to adapt to other stacks — see the field docs and adjust deployMethod / route roots as needed.

Roadmap

v1 is the deterministic gate + judgment agents + the registry + the human ship-it — shipped and usable today. Everything below is where v1 is heading; it's planned, not done. Contributions and issues are welcome.

• GitHub Action + pre-push hook — run the gate in any CI or on git push, not only inside Claude Code. Widest reach: the same PASS/BLOCK exit codes, wired into the pipeline you already have.
• claude-predeploy init — auto-detect a project's framework, routes, env vars, and prod branch, then scaffold its registry entry for you instead of hand-writing one.
• Entropy-based secret scanning — replace the naive pattern checks with a real detector that flags high-entropy strings, not just known key shapes.
• Deeper descendant-of-live guard (the headline check) — go beyond dropped route files to catch dropped API endpoints, exported functions, env vars, and DB columns the live app still references. The question it answers: "what does live depend on that this branch removes?"
• Visual before/after diff — screenshot each critical path candidate-vs-live and attach the image diff straight into the report.

Further out: DB-migration shadow dry-runs against a throwaway branch (Supabase/Neon branching), one-command tested rollback, bundle/perf budget gates, and a self-tuning memory that learns which false positives to stop flagging.

Found a deploy failure the gate should have caught? Open an issue or PR — real-world near-misses are the best roadmap input.

License

MIT — see LICENSE.