Deploy

Deploy — Safe Deployment Pipeline

<!-- ============================================================
     TEMPLATE: Customize this skill for your deployment pipeline.
     Replace every [PLACEHOLDER] and every commented "CUSTOMIZE"
     block with your actual commands. Delete the patterns you
     don't use (shadow/canary is optional). The structure —
     discover → gate → deploy → report — is the part worth keeping.
     ============================================================ -->

Pipeline shape: discover targets → fail-stop gate → deploy → report-only checks. The default scope is the whole project; module-level targeting is optional (see Target Discovery).

Input

/deploy [target(s)...] [--all] [--skip-tests]

• target(s) (optional) — specific services/functions/apps to deploy. Omit to auto-detect from the git diff.
• --all — deploy every target affected by the current diff.
• --skip-tests — skip the pre-deploy test gate (use only when tests were just run).

<!-- CUSTOMIZE: list your valid deploy targets, or delete this line if your repo has a single deploy target -->

Valid targets: [YOUR_TARGET_1], [YOUR_TARGET_2], ...

Target Discovery

The pipeline finds what to deploy by scanning for capability-marker files — the file that signals "this directory is independently deployable." Discover targets instead of hardcoding them, so a newly-added target works without editing this skill.

<!-- CUSTOMIZE: pick the marker file(s) for your stack and the directory layout.
     One project per repo: usually there is a single marker at the repo root,
     and "discovery" just confirms it exists. Use module-level markers only if
     your repo genuinely ships more than one independently-deployable unit. -->

# Scan for the capability marker. Default to the whole project (repo root).
# Examples of marker files (pick ONE for your stack):
#   <!-- e.g. fly.toml | vercel.json | wrangler.toml | serverless.yml
#         | Dockerfile | Procfile | package.json with a "deploy" script -->
find . -maxdepth 2 -name '[YOUR_MARKER_FILE]' -not -path '*/node_modules/*'

If a marker is found at the repo root → the deploy target is the whole project (the common case). If markers exist in multiple subdirectories → each is an independent target; map the diff to the affected one(s).

Resolving deploy config (fallback hierarchy)

Read deploy config (app id, account/project identifier, region — whatever your provider needs) from the first source that exists:

1. Committed config — a tracked file checked into the repo (canonical, worktree-safe).

   <!-- CUSTOMIZE: e.g. fly.toml `app =`, vercel.json, a `.deploy-target` file you commit -->

2. CLI-managed temp/state — whatever your provider's CLI writes after link/login (often gitignored).

   <!-- CUSTOMIZE: e.g. `.vercel/project.json`, a CLI cache under the project's temp dir -->

3. Heuristic — derive from a convention (directory name, repo name, an env var).

   <!-- CUSTOMIZE: e.g. app name == repo name; region from an env var -->

If none resolve, STOP with an actionable message: No deploy config for [target]. Run '[YOUR_LINK_COMMAND]', or create '[YOUR_COMMITTED_CONFIG_FILE]'.

Detect what changed

If no target was passed explicitly, map the diff to targets:

git diff --name-only HEAD
git diff --name-only --cached

<!-- CUSTOMIZE: map changed paths → affected target(s). With a single target this
     reduces to "is anything deployable changed?" -->

Shared-code dependency awareness

If the diff touches shared/library code that other deployable units import, those importers must be redeployed too — they bundle the changed code.

<!-- CUSTOMIZE: point this at your shared dir and your import syntax.
     The pattern: find direct importers, then recurse once for transitive importers. -->

# Direct importers of the changed shared file:
grep -rl "[CHANGED_SHARED_PATH]" [YOUR_SOURCE_GLOB]

# Transitive: a shared file that imports the changed shared file is itself
# "changed" — repeat the grep for it, then add its importers. Recurse until
# the set stops growing (usually one extra pass is enough).

Each affected target then runs through the full deploy pipeline below.

Pipeline

Step 1 — Preflight

1. Resolve target(s), the deploy list, and deploy config.
2. Print a summary so the operator can sanity-check before anything ships:

   Repo:    <path>
   Branch:  <name> @ <short-sha>
   Targets: <list>

   <!-- CUSTOMIZE: if you work on feature branches, also show `git log main..HEAD --oneline` -->

3. Classify each target as new vs. existing in production (see Step 3 — the two branches differ).

   <!-- CUSTOMIZE: how to ask your provider "does this already exist live?"
        e.g. `flyctl status`, `vercel ls`, `wrangler deployments list`, an API call -->

Step 2 — Pre-deploy gate (FAIL-STOP)

These run before anything goes live. A failure here means nothing is deployed — the live target is untouched.

<!-- CUSTOMIZE: replace with your test command. Discover it if you can
     (e.g. a "test" script in package.json) and skip cleanly if none exists. -->

[YOUR_TEST_COMMAND]

• Non-zero exit → STOP. Report which suite failed, pass/fail counts. Deploy nothing.
• Skipped only when --skip-tests is set or no test command is discovered.

Step 3 — Deploy

Deploy targets one at a time. If one fails, stop and report — do not continue to the remaining targets.

3a. New target (does not yet exist in production)

Nothing live to protect, so deploy directly:

[YOUR_DEPLOY_COMMAND] [target]

• Then run the smoke probe (see below). A hard failure (target won't boot / not routable) → STOP and report. There is no previous version to fall back to; the operator inspects.

3b. Existing target — optional Shadow/Canary, then swap

<!-- OPTIONAL PATTERN. Skip this whole sub-step if your provider already does
     atomic, instant rollback (most PaaS do — keep a previous-release id instead,
     see "Rollback" below). Use shadow/canary when a bad deploy would otherwise
     be served to users before you can verify it. -->

Deploy a staging variant alongside the live one, probe it, and only swap if it passes. The live target keeps serving the old code until the swap.

1. Shadow-deploy a parallel variant (a separate slug / preview URL / canary slice):

   [YOUR_SHADOW_DEPLOY_COMMAND]      # deploy as <target>-shadow / a preview / N% canary

   <!-- CUSTOMIZE per provider, e.g.:
        Vercel:      vercel deploy            (preview URL, not --prod)
        Fly.io:      flyctl deploy --strategy canary
        AWS Lambda:  publish a new version + weighted alias
        Cloudflare:  wrangler deploy --name <target>-shadow   (separate Worker) -->

   • Shadow deploy fails → run Cleanup helper on the shadow, STOP. Live target untouched.

2. Smoke-probe gate (FAIL-STOP) — probe the shadow URL:

   [YOUR_SHADOW_SMOKE_PROBE]

   • Fail → run Cleanup helper on the shadow, STOP. Live target untouched.

3. Swap — promote the verified bundle to the live target:

   [YOUR_SWAP_COMMAND]               # promote shadow → live / shift 100% traffic

   <!-- CUSTOMIZE per provider, e.g.:
        Vercel:      vercel promote <deployment-url>
        Fly.io:      shift traffic to the canary release
        AWS Lambda:  point the alias at the new version
        Cloudflare:  deploy the verified bundle to the live Worker name -->

   • Swap fails → see Retry-once in Error handling. The live target may be mid-state; do NOT touch git.

4. Post-swap probe (REPORT-ONLY) — probe the live URL. See Step 4. On failure, report and keep the shadow live for inspection — do not roll back automatically.

5. Cleanup — on success, remove the shadow (see Cleanup helper).