Run Vercel-specific deployment operations for linked web/fullstack projects: preview deploys, direct production deploys, staged deploy + promote flows, aliases/domains, environment-variable sync, and rollback response. Use when the request is specifically about operating a project on Vercel after the provider is already chosen — especially when someone needs a preview URL, stable alias, custom domain, env-scope fix, production cutover, or rollback on Vercel. Triggers on: Vercel deploy, Vercel preview URL, vercel promote, vercel alias, Vercel domain, Vercel env, Vercel rollback, and Vercel CLI deployment. Route provider-neutral release strategy to `deployment-automation`, CI/workflow authoring to `workflow-automation`, and local install/auth/bootstrap work to `system-environment-setup`.
Run Vercel-specific deployment operations for linked web/fullstack projects: preview deploys, direct production deploys, staged deploy + promote flows, aliases/domains, environment-variable sync, and rollback response. Use when the request is specifically about operating a project on Vercel after the provider is already chosen — especially when someone needs a preview URL, stable alias, custom domain, env-scope fix, production cutover, or rollback on Vercel. Triggers on: Vercel deploy, Vercel preview URL, vercel promote, vercel alias, Vercel domain, Vercel env, Vercel rollback, and Vercel CLI deployment. Route provider-neutral release strategy to `deployment-automation`, CI/workflow authoring to `workflow-automation`, and local install/auth/bootstrap work to `system-environment-setup`.
allowed-tools
Bash Read Write Edit Glob Grep
compatibility
Best when a repository already targets Vercel and either has the Vercel CLI available or can follow dashboard-backed Vercel workflows. Assumes the agent can inspect repo config and run Vercel commands if authenticated.
preview-deploy — create or refresh a testable Vercel preview
production-deploy — run a direct fresh production deployment
promote-preview — verify an existing deployment, then make it current
alias-domain — apply/verify a stable preview alias or custom domain
env-sync — fix environment-variable scope or stale local/project env state
rollback-response — move production back to a known-good deployment and verify recovery
If the request contains multiple goals, pick the one that owns the first answer and route the rest explicitly.
Step 2: Gather only the minimum truthful evidence
Do not guess from the framework name alone. Confirm the smallest credible set first:
Is the project already linked to Vercel (vercel link, .vercel/project.json, or dashboard evidence)?
Is the target really preview, production, or a custom/development environment?
Is the deploy path source-based or prebuilt?
Does the user care about the generated deployment URL, a stable alias, or a custom domain?
Is this actually a deploy/cutover problem, or an env/config mismatch that still needs redeploy?
What proof is expected: URL only, smoke check, health + logs, DNS verification, or rollback verification?
If one item is unknown, state the assumption instead of pretending the mode is fully known.
Step 3: Use the matching operator path
Do not dump every command at once. Pick the reference packet that matches the mode.
A. preview-deploy
Use when the deliverable is a testable preview deployment.
Prefer linked-project CLI or dashboard-backed preview flows.
Return the generated deployment URL plus any stable alias plan.
If the goal is a stable demo URL, carry the result into alias-domain rather than mixing everything into one blob.
Use packet: references/preview-production-command-packets.md#preview-deploy-packet
B. production-deploy
Use when the user explicitly wants a fresh production deployment now.
Say whether the deployment is source-build or prebuilt.
Report the production URL/domain reached.
Separate deploy success from post-deploy verification.
Use packet: references/preview-production-command-packets.md#direct-production-deploy-packet
C. promote-preview
Use when a deployment already exists and the job is to cut over safely.
Verify the exact deployment URL/commit before promotion.
Treat promotion as a release operation, not a magical pointer flip.
Note team-scope or domain caveats when they matter.
Report production verification separately from the promote command itself.
Use packet: references/preview-production-command-packets.md#staged-production--promote-packet
D. alias-domain
Use when the stable URL is the real deliverable.
Distinguish generated URL vs stable preview alias vs production custom domain.
Report DNS/manual verification status separately from CLI success.
Keep the raw deployment URL available as fallback evidence.
Use packet: references/env-domain-rollback-troubleshooting.md#aliases-and-domains
E. env-sync
Use when preview/prod behavior differs because variables are missing, stale, or scoped incorrectly.
Check the intended environment first.
Call out that env-var changes apply to new deployments, not old ones.
Distinguish Vercel env scope from app-level canonical URL/config expectations.
Use packet: references/env-domain-rollback-troubleshooting.md#environment-variables
F. rollback-response
Use when production traffic must revert quickly.
Identify the currently bad deployment and the exact rollback target.
Call out stale-config / cron / plan-limit caveats before claiming recovery.
Re-check production logs/health after rollback.
Use packet: references/env-domain-rollback-troubleshooting.md#rollback
Step 4: Keep boundaries clean while answering
Use this route-out table whenever the request drifts.
If the request sounds like...
Use
“Design the release gates, canary policy, or rollback strategy across providers”
deployment-automation
“Rewrite the GitHub Actions workflow that runs Vercel commands”
workflow-automation
“Install Vercel CLI, auth, Node, or link local credentials”
system-environment-setup
“The build crashes before deploy succeeds”
debugging or a framework-specific skill
“Set up dashboards, alerts, or long-lived post-release monitoring”
monitoring-observability
“Inspect, deploy, promote, alias, domain-manage, env-sync, or roll back on Vercel”
vercel-deploy
Step 5: Mention the legacy claimable deploy helper only if the environment explicitly depends on it
This directory still ships scripts/deploy.sh, a claimable-preview helper that packages a tarball and returns preview/claim URLs. Treat it as a legacy environment-specific shortcut, not the default Vercel operating model.
Use it only when all of these are true:
the runtime explicitly expects the claimable deploy endpoint
the job is just creating a claimable preview URL
linked-project, promotion, alias/domain, env-sync, and rollback operations are out of scope
Otherwise prefer the official Vercel CLI / dashboard model described above.
Output format
Return a mode-specific packet instead of a loose command dump.
