Build & Ship — the one-pager

Keep this open while you work. The full machine-readable rules are in AGENTS.md; this is the human version.

The loop (six steps)

1. Branch. Pull the latest main, make a short-lived branch yourinitials/what-you-re-doing. Never work on main.
2. Build. Make your change — with your AI tools. Keep it small.
3. Commit little and often. Let the AI write the message.
4. Open a PR early — the same day you branched. A preview link appears.
5. Review on the preview. A teammate looks; the automated checks go green.
6. Merge & delete. Merge into main, delete the branch. Round again.

The five golden rules

1. Never commit straight to main — always branch first.
2. Keep changes small — a branch lives hours, not days.
3. Open a PR early — don't wait until it's "finished".
4. Never merge when the checks are red — red means stop.
5. Delete your branch after merging — keep the place tidy.

Before you push — checklist

• Formatter + linter clean
• Type-check passes (tsc --noEmit)
• Tests pass (and content/schema validation, if the project has it)
• It builds
• No secrets in the code — keys/tokens live in the env store, never in a file
• The diff is small enough that a human can actually review it

When AI writes the code

AI is fast, not careful. It can produce code that looks fine but is bloated, insecure, or subtly wrong. The workflow is the safety net: small PRs, a human glance, and automated checks. A passing formatter tells you nothing about safety — you also need linting/types (bugs) and security scanning (leaked secrets, dodgy dependencies).

What a preview does and doesn't tell you

A preview shows the experience — layout, copy, the click-through. Judge that with confidence. It hides secrets left in code, security holes, and logic that breaks off the happy path. Those are for the checks and an engineer.

If Git looks scary — stop

You'll never be blamed for asking. You can cause real damage running a command you don't understand — especially something an AI suggested to "fix" a broken state. Stop, screenshot, ask an engineer.

Deploying — which world am I in?

Two classes; your project's AGENTS.md header says which.

• Container-image (Coolify, DigitalOcean, a VPS, Render/Fly/Railway): CI builds one image, scans it, pushes it to the registry, and the host pulls that exact image. One container, a /health route, secrets in the platform, database as a separate service.
• Managed-source (Vercel, Cloudflare, Netlify): push a branch → you get a preview URL; merge to main → it goes to production. The platform builds from your repo. Set the framework preset explicitly; scan dependencies (there's no image to scan); env vars go in the platform dashboard per environment.

Feature flags (if the project uses them)

A flag lets you merge unfinished work switched off, or kill a feature instantly. One flag, one purpose — and delete it the moment the rollout is done. Stale flags are how accidents happen.