← turboflow.online
~/your-repo — AGENTS.md template · free

AGENTS.md — the constitution file your AI coding agents actually read

What is AGENTS.md? It's a markdown file at the root of your repository that AI coding agents read before they touch anything — the instructions layer between "a model with tools" and "an engineer that works in your repo". Rules, project context, how to build and test, and the non-negotiables. This page gives you the working template from rig-lite — the one that pairs the file with a gate that enforces it.

Published Oct 8, 2026 · Updated Oct 8, 2026

AGENTS.md vs CLAUDE.md

Same idea, different namespace. CLAUDE.md is Claude Code's instruction file; AGENTS.md is the vendor-neutral name that Codex reads natively and every harness can read. The failure mode of having both is drift — two copies of the truth that disagree within a month. The pattern rig-lite's init-repo.sh installs:

# one source of truth, every harness:
AGENTS.md          # the real file — constitution pointer + project cheat-sheet
CLAUDE.md -> AGENTS.md   # symlink: Claude reads it, never a second copy

Codex reads AGENTS.md directly; Claude Code follows the symlink; ZCode, Gemini and Grok read whatever markdown you point them at. One file, zero drift.

The template (from rig-lite's constitution)

A constitution is only real if it's enforced — the file states the laws, gate.sh gives them teeth. The four laws, ready to paste:

1. Builder ≠ reviewer. Every change is reviewed read-only by an agent from a
   different model family than the one that wrote it. Same-family
   self-review does not count as review.
2. Agents never merge. No agent force-pushes, merges, or pushes to the
   mainline. Humans hold the merge button. Always.
3. Parallel writers get isolated worktrees. Two agents never write the
   same checkout. One writer per worktree, one lane per branch.
4. Secrets never touch git. Credentials live in the OS keychain or a
   gitignored env file — never in code, commits, logs, or issue bodies.

Plus the operating rules that make the laws cheap: deterministic before expensive (lint, tests, type-check run first — paid model review only after the free checks pass), verdicts are parseable or they don't exist (VERDICT: APPROVED or VERDICT: REVISE on the final line — ambiguity is REVISE, fail-closed), memory is versioned, not vibes (one fact per file in git, not chat transcripts), and state on disk, not in chat — specs, memory and runbooks are files in the repo.

Your repo in 30 seconds

# from any repo you want to govern:
bash /path/to/turbo-flow/rig-lite/init-repo.sh "My Project"
# writes the thin AGENTS.md (never clobbers an existing one),
# symlinks CLAUDE.md, installs the deletion-guard pre-commit hook,
# and points the constitution somewhere every clone can resolve.

The generated AGENTS.md is deliberately thin — a constitution pointer plus a five-line project cheat-sheet (stack, test command, run command, deploy, gotchas) that your agent reads every session:

# My Project — agent instructions

Read and follow the constitution: rig-constitution.md
(gate every PR, agents never merge, state on disk).

## Project cheat-sheet (fill in, one line each)
- Stack:
- Run tests:
- Run locally:
- Deploy:
- Gotchas:

Why a file is not enough

An instruction file is a promise, and models break promises under pressure — the v4 era of this very project proved that volume without governance doesn't ship. That's why the template ships as a pair: the constitution says builder ≠ reviewer, and the gate refuses the merge when the reviewer came from the builder's family. The laws are lines in a file; the teeth are a script. Both are open source.

More on the pattern