Ship

Deterministic deployment workflow. Reads the project's DEPLOY.md and executes it. If none exists, infers the shape from project files and offers to write one.

The goal: stop burning cycles re-discovering "where does this deploy / how do migrations apply / what can the agent actually run" every session.

Workflow

1. Find the project root + DEPLOY.md

From the current directory or the file under discussion, walk up to the nearest package.json, pyproject.toml, Cargo.toml, or .git/. That's the project root.

Look for DEPLOY.md at the project root.

• Present → use it as the source of truth. Don't second-guess it. If something looks stale, flag it but follow the stated workflow until corrected.
• Missing → go to step 2.

2. Infer + offer to scaffold (only if DEPLOY.md missing)

Read these in parallel to infer the deploy shape:

• package.json (scripts, dependencies — next, astro, @sveltejs/kit, etc.)
• wrangler.toml / wrangler.jsonc → Cloudflare Workers/Pages
• vercel.json / vercel.ts → Vercel
• supabase/config.toml → Supabase project ref
• .github/workflows/*.yml → CI-triggered deploys
• netlify.toml, fly.toml, railway.toml, render.yaml
• git remote -v → where pushes go

Offer to scaffold a DEPLOY.md from template.md, pre-filled with what you inferred. Show the inferred values; ask the user to confirm or correct before writing. (This is the one place to ask — getting this wrong contaminates every future ship.)

3. Preflight (before any deploy action)

Run these checks. Report any that fail; ask before proceeding.

• git status — uncommitted or unpushed work? Naming the branch you're on matters; deploys to main vs preview behave differently.
• Pending migrations? Check the project's migration directory against what's deployed (if the manifest specifies a check command, run it).
• Required env vars present in the target environment? The manifest should list them; if it doesn't, name what you'd expect based on the code and stop.

4. Trigger the deploy

Follow the manifest. Most common shapes:

• Push-to-deploy (Vercel / Cloudflare Pages / Netlify with GitHub integration): git push and report the expected build URL. Do not run the platform CLI to "redeploy" unless the manifest says to — push-triggered builds are the canonical path; CLI re-deploys can race.
• Manual CLI deploy: run the exact command in the manifest. Don't substitute flags.
• CI-gated: push and link to the workflow run.

Never assume push-to-deploy is wired. A Cloudflare Pages project, a Vercel project, or a Netlify site can all exist without the git integration enabled — in which case git push does nothing and you have to run the platform CLI yourself. The integration is configured in the dashboard, not the repo, so you cannot infer it from the codebase alone.

Signals that push-to-deploy IS wired (any one is sufficient):

• The manifest says so (canonical source — trust it).
• A .github/workflows/*.yml file deploys on push.
• A .vercel/project.json exists AND project is linked AND user has confirmed it deploys on push (the file alone doesn't prove the integration is active).

If none of those are true, treat the project as manual-CLI-deploy. Don't push and wait. Don't poll Pages dashboards "in case it picks up." Run the CLI command, or ask the user which mode this project uses.

5. Verify

After triggering, do whatever the manifest's verify step says. If no verify step is specified:

• Curl the prod URL's health endpoint if one exists
• Report the expected build URL and an estimated build time
• Name the runtime errors that could appear if a step was skipped (e.g., "the deploy will succeed, but route X will 500 because the migration hasn't run")

End with a status sentence, not a question.

Authority limits — things the agent CANNOT run

These fail silently or hit auth walls. Don't waste a turn trying; instead, hand the exact command to the user OR use the documented fallback.

When you hit one of these, stop. Don't retry with different flags. State the limit, give the user the exact command to run, and continue with whatever can be done without that step.

Common platform shorthand

For when the manifest is terse and you need to fill in standard behavior. All "X-linked" notes below require evidence — see step 4. Don't assume linkage from repo files alone.

• Cloudflare Pages, GitHub-linked: push to main triggers production build; PR branches trigger preview builds at <branch>.<project>.pages.dev. Build runs in CF's environment.
• Cloudflare Pages, manual (standalone project): requires npm run build (or framework equivalent) THEN wrangler pages deploy <build-output-dir>. SvelteKit + adapter-cloudflare outputs to .svelte-kit/cloudflare. Astro outputs to dist. Next.js via Cloudflare adapter outputs to .vercel/output/static. The wrangler CLI usually works in the agent shell because wrangler login persists to ~/.wrangler/config/.
• Vercel, GitHub-linked: push to production branch (usually main) triggers prod build. Preview URL per branch + per PR.
• Vercel, manual: vercel deploy --prod. Requires VERCEL_TOKEN or interactive login the agent can't do — usually hand off to user.
• Supabase migrations: files in supabase/migrations/ apply in filename order. The dashboard SQL Editor always works for the agent; supabase db push usually doesn't (see authority limits).
• GitHub Actions deploys: the workflow is the source of truth; trigger conditions are in on:. Don't run deploy scripts manually if a workflow exists for the same step — you'll desync.

When the user says "deploy this"

1. Read DEPLOY.md (or scaffold one).
2. Preflight: git status, list any pending migrations.
3. State what you're about to do in one sentence.
4. Do it.
5. Report what's happening, what could go wrong, and end with a status sentence.

Don't ask permission for each step inside an already-authorized ship.