Engineering Playbook

Canonical build-and-deploy conventions for our projects: trunk-based, AI-assisted, preview-per-PR, gates-before-merge. One source of truth that every repo — new or being converted — points at, so the way we work doesn't drift from project to project.

This is the same workflow the Team Flow learning app teaches, written down here for machines to enforce and humans to skim.

What's here

File	Audience	Purpose
`AGENTS.md`	AI build sessions	The machine-facing contract. Vendored into each repo; an AI coding session reads it and conforms.
`HANDBOOK.md`	Everyone	The one-page human quick-reference to keep open while you work.
`CONVERSION.md`	Whoever migrates a repo	Checklist to bring an existing project onto this model.
`ci/gates.yml`	Every project	The pre-merge gates workflow (lint / type / validate / build). Copy in as-is.
`ci/deploy-image.yml`	Container-image projects	Build → scan → push → deploy pipeline for the container-image class.

The one idea that organises everything: deploy class, not deploy vendor

Pick your host and it falls into one of two classes. The methodology is written per class; the named vendors are just instances, and any other host in the same class inherits the same rules.

Container-image class — build once, scan the artefact, the platform pulls it. CI builds a Docker image, scans it, pushes it to a registry (GHCR); the host pulls that exact tag. Instances: Coolify, DigitalOcean (App Platform image mode or a Droplet+Docker), Render, Fly.io, Railway, Kamal.
Managed-source class — the platform builds from your repo. Git integration gives per-PR previews and trunk→production automatically; there is no image, so image-scanning is replaced by source/dependency scanning. Instances: Vercel, Cloudflare (via OpenNext), Netlify.

New host not listed? Classify it with one question: does CI hand the platform a built image, or does the platform build from source? Then apply that class's section of AGENTS.md. That's the whole point of organising by class.

How a project adopts this

Copy AGENTS.md to the project root. Keep a one-line CLAUDE.md that points at it (Claude Code reads CLAUDE.md; other tools read AGENTS.md).
Set the two-line project header in that copy (DEPLOY TARGET / DEPLOY CLASS).
Copy ci/gates.yml into .github/workflows/. Container-image projects also copy ci/deploy-image.yml.
Follow CONVERSION.md for the rest (branch protection, .env.example, lockfile, previews, secrets).

Keep this repo the source of truth; re-vendor AGENTS.md into a project when it changes (stamp the version/commit in the project's copy so drift is visible).