Caddi for agents

Caddi projects are designed to be operated by coding agents. This page is the conventions agents should know — and the prompt patterns we’ve found work best.

The AGENTS.md contract

Every Caddi template ships an AGENTS.md at the repo root that describes the project’s conventions in agent-friendly language: branch flow, env-var naming, where form endpoints live, where to put new pages. Agents should read it first.

md · AGENTS.md (excerpt)

# AGENTS.md

This is a Caddi template. Conventions:

## Branches
- main: production
- staging: staging
- dev: in-progress work

Open PRs against `dev` unless explicitly told otherwise.

## Forms
The form endpoint URL lives in PUBLIC_CADDI_FORM_URL.
Use @caddi/forms-sdk; don't write a custom POST handler.

## Env vars
Public values are prefixed PUBLIC_*. Secrets are not — and
should never appear in client bundles.

Prompt patterns

Add a new page

prompt

Read AGENTS.md.

Add a new page at /case-studies/[slug] using the existing MDX content
collection. Match the style of /case-studies/index. Wire SEO metadata
from the frontmatter. Open a PR against `dev`.

Add a contact form

prompt

Read AGENTS.md.

Add a contact form at /contact using @caddi/forms-sdk. The endpoint URL
is in PUBLIC_CADDI_FORM_URL. Fields: name, email, company, message.
On submit, redirect to /thanks. Use the existing Button and Input
primitives from components/ui. Open a PR against `dev`.

Promote a release

prompt

I want to promote dev to staging. Open the Caddi promotion screen
for this project, fill in a one-line summary based on the latest
git log, and submit. Don't merge directly — go through the PR.

You don’t need agents to use Caddi — but if you do, the conventions above mean less back-and-forth. The promotion and form endpoints are the highest-leverage pieces to wire up correctly the first time.

What agents should never do

Push directly to main or staging. Always go through a PR.
Hard-code form endpoints. Always read from the env var.
Commit secrets, even temporarily.
Edit env vars on Vercel directly. Use Caddi so changes flow through the audit log.