AGENTS.md examples for seven kinds of repository

# AGENTS.md: keeping this repository's AGENTS.md right

This repository's `AGENTS.md` files are instructions for every coding agent that works here. Treat them like code:
they must be correct, short and checked.

## When you change an AGENTS.md
- Use the `agents-md-writer` skill. It has seven worked examples and a lint script.
- Every command in it must exist and work. Run it before you write it down.
- Keep the five parts: what the project is, Commands, Layout, Conventions and Never, Done means.
- Keep each file under 150 lines and the root-to-folder chain under 32 KiB.
- A CLAUDE.md must import `AGENTS.md` with a line `@AGENTS.md`; never put different rules in the two files.

## When the code changes
If you rename a script, move a folder or change the test runner, update the AGENTS.md that mentions it in the same
change, and run the lint again.

## Never
- Write a command you have not run, or one copied from another project
- Put rules in CLAUDE.md, GEMINI.md or Cursor rules that contradict AGENTS.md

## Done means
The lint prints `0 error(s)`, and every warning left is explained in your report.

# CLAUDE.md

@AGENTS.md

## Claude Code notes

- Skills from this loadout live in `.claude/skills/`: `agents-md-writer`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From SetupBay "AGENTS.md examples for seven kinds of repository" v1.0.0 — https://setupbay.com/loadouts/agents-md-examples/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes

- Skills from this loadout live in `.agents/skills/`: `agents-md-writer`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From SetupBay "AGENTS.md examples for seven kinds of repository" v1.0.0 — https://setupbay.com/loadouts/agents-md-examples/ -->

---
name: agents-md-writer
description: Write or fix a repository's AGENTS.md from worked examples, then lint it against what Codex, Claude Code and the others actually load. Use when creating an AGENTS.md, when agents ignore or misread it, when adding a nested AGENTS.md in a monorepo, or when asked for AGENTS.md examples.
---

# Write an AGENTS.md that agents follow

AGENTS.md is read by Codex, Cursor, Copilot, Antigravity CLI and Claude Code (when no CLAUDE.md shadows it). It is
loaded into every session, so every line costs context and every wrong command wastes a run.

## 1. Pick the nearest example
`references/examples/` has seven, each 30–40 lines:

| File | For |
|---|---|
| `web-app.md` | Next.js / TypeScript app with a database |
| `python-library.md` | a published Python package (uv, pytest, ruff, mypy) |
| `monorepo-root.md` + `monorepo-api.md` | a root file plus a nested one for one app |
| `go-cli.md` | a Go command-line tool with golden files |
| `godot-game.md` | a Godot 4 game |
| `infra-opentofu.md` | OpenTofu / Terraform, plan only |

Copy the structure, not the content. Every example has the same five parts: one line on what the project is;
**Commands** (exact, copy-pasteable, including how to run one test); **Layout**; **Conventions** and **Never**;
**Done means**.

## 2. Fill it from the repository, not from memory
- Read `package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`, CI workflows. Use the commands that exist.
  Run each one once; if it fails, fix the command or leave it out.
- Write what an agent would get wrong here: the package manager, the test runner, generated folders, the database
  rule. Leave out what any agent already knows ("write clean code").
- Keep it under 150 lines. Longer procedures belong in skills.
- Monorepo: a short root file with rules for every package, and a nested `AGENTS.md` per app with its commands.
  Codex joins them root first and stops at 32 KiB in total.
- If the repo has a CLAUDE.md, make it import AGENTS.md (a line with `@AGENTS.md`). Otherwise Claude Code reads
  CLAUDE.md only and ignores AGENTS.md.

## 3. Lint it
```bash
python3 .agents/skills/agents-md-writer/scripts/agents_md_lint.py .
```
(Claude Code installs the skill under `.claude/skills/`.) Fix every error: a size over Codex's 32 KiB, a shadowing
CLAUDE.md, an `npm run` / `pnpm` / `make` / `just` command that does not exist. Fix or explain each warning: no
test command, no "Never" section, over 150 lines, a path that does not exist. The `info` lines show which files Codex
joins for each folder.

## 4. Report
Show the final file, the lint summary, and each command you ran to check it.

#!/usr/bin/env python3
"""Lint the AGENTS.md files in a repository against what agents actually load.

Usage: python3 agents_md_lint.py [REPO_DIR]     (default: the current folder)

For every AGENTS.md (root and nested; skips node_modules, .git, vendor, dist, build, .venv):
  error  combined size of the AGENTS.md chain is over Codex's default 32 KiB project_doc_max_bytes (the rest is not read)
  error  a CLAUDE.md or CLAUDE.local.md sits beside it without importing it (@AGENTS.md), so Claude Code reads only CLAUDE.md
  error  a referenced script does not exist: `npm run X` / `pnpm X` / `yarn X` (package.json scripts), `make X` (Makefile targets),
         `just X` (justfile recipes)
  warn   no section that tells the agent how to test or check its work
  warn   no "never" / "don't" section (the agent has no boundaries)
  warn   over 150 lines (agents follow short files better; move procedures into skills)
  warn   a backticked path such as `src/lib/` that does not exist
  info   files Codex would read for each nested AGENTS.md, root first
Exit 1 if any error, else 0. Standard library only; read-only.
"""
import json
import os
import re
import sys

SKIP = {"node_modules", ".git", "vendor", "dist", "build", ".venv", "venv", "target", ".next", ".godot", "__pycache__"}
CODEX_MAX = 32 * 1024
TEST_HINT = re.compile(r"^#+.*\b(test|tests|testing|check|checks|verify|done)\b|`[^`]*\b(test|pytest|vitest|jest|check|validate|lint)\b[^`]*`", re.I | re.M)
NEVER_HINT = re.compile(r"^#+\s*(never|don'?t|do not|boundaries|off limits|ask first)\b|^\s*[-*]\s*(never|do not|don'?t)\b", re.I | re.M)
CODE_SPAN = re.compile(r"`([^`\n]+)`")
RUN_SCRIPT = re.compile(r"\b(?:npm run|pnpm(?: run)?|yarn(?: run)?|bun run)\s+([A-Za-z0-9:_-]+)")
PNPM_BUILTINS = {"install", "i", "add", "remove", "exec", "dlx", "turbo", "--filter", "-r", "why", "update", "outdated", "audit", "store", "run", "x", "create", "init"}
MAKE = re.compile(r"^make\s+([A-Za-z0-9_.-]+)")
JUST = re.compile(r"^just\s+([A-Za-z0-9_-]+)")
PATHLIKE = re.compile(r"^((?:\.?[A-Za-z0-9_-]+/)+(?:[A-Za-z0-9_.-]+)?)$")
GENERATED = (".next/", "dist/", "build/", "node_modules/", ".godot/", "target/", ".venv/", "coverage/")


def find_agents(root):
    for d, dirs, files in os.walk(root):
        dirs[:] = sorted(x for x in dirs if x not in SKIP and not x.startswith(".") or x in (".github",))
        if "AGENTS.md" in files:
            yield os.path.join(d, "AGENTS.md")


def nearest(start, root, name):
    d = start
    while True:
        p = os.path.join(d, name)
        if os.path.isfile(p):
            return p
        if os.path.abspath(d) == os.path.abspath(root):
            return None
        d = os.path.dirname(d)


def scripts_for(dirpath, root):
    pj = nearest(dirpath, root, "package.json")
    if not pj:
        return None, None
    try:
        return set(json.load(open(pj)).get("scripts", {})), pj
    except ValueError:
        return set(), pj


def make_targets(dirpath, root):
    mk = nearest(dirpath, root, "Makefile")
    if not mk:
        return None
    return set(re.findall(r"^([A-Za-z0-9_.-]+)\s*:(?!=)", open(mk).read(), re.M))


def just_recipes(dirpath, root):
    jf = nearest(dirpath, root, "justfile") or nearest(dirpath, root, "Justfile")
    if not jf:
        return None
    return set(re.findall(r"^@?([A-Za-z0-9_-]+)[^:\n]*:(?!=)", open(jf).read(), re.M))


def chain(path, root):
    """AGENTS.md files Codex concatenates when started in path's folder: root first."""
    out, d = [], os.path.dirname(path)
    while True:
        p = os.path.join(d, "AGENTS.md")
        o = os.path.join(d, "AGENTS.override.md")
        if os.path.isfile(o):
            out.append(o)
        elif os.path.isfile(p):
            out.append(p)
        if os.path.abspath(d) == os.path.abspath(root):
            break
        d = os.path.dirname(d)
    return list(reversed(out))


def main(argv):
    root = argv[0] if argv else "."
    files = list(find_agents(root))
    if not files:
        print("agents-md-lint: no AGENTS.md found")
        return 1
    errors = warns = 0

    def report(level, path, msg):
        nonlocal errors, warns
        errors += level == "error"
        warns += level == "warn"
        print(f"{level:5} {os.path.relpath(path, root)}: {msg}")

    for path in files:
        d = os.path.dirname(path)
        text = open(path, encoding="utf-8").read()
        lines = text.count("\n") + 1
        ch = chain(path, root)
        size = sum(os.path.getsize(p) for p in ch)
        if size > CODEX_MAX:
            report("error", path, f"AGENTS.md chain is {size} bytes; Codex stops reading at {CODEX_MAX} (project_doc_max_bytes)")
        for cname in ("CLAUDE.md", "CLAUDE.local.md"):
            c = os.path.join(d, cname)
            if os.path.isfile(c) and not re.search(r"^\s*@(\./)?AGENTS\.md\s*$", open(c).read(), re.M):
                report("error", path, f"{cname} next to it does not import it with @AGENTS.md, so Claude Code reads {cname} only")
        scripts, pj = scripts_for(d, root)
        spans = [m.group(1).strip() for m in CODE_SPAN.finditer(text)]
        cmds = [c for sp in spans for c in re.split(r"\s*(?:&&|\|\||;|\bthen\b)\s*", sp)]
        for m in (x for c in cmds for x in RUN_SCRIPT.finditer(c)):
            name = m.group(1)
            if name in PNPM_BUILTINS or name.startswith("-"):
                continue
            if scripts is None:
                report("warn", path, f"mentions script '{name}' but no package.json was found")
            elif name not in scripts:
                report("error", path, f"script '{name}' is not in {os.path.relpath(pj, root)} scripts")
        targets = make_targets(d, root)
        for m in (x for c in cmds for x in [MAKE.match(c)] if x):
            if targets is not None and m.group(1) not in targets:
                report("error", path, f"make target '{m.group(1)}' is not in the Makefile")
        recipes = just_recipes(d, root)
        for m in (x for c in cmds for x in [JUST.match(c)] if x):
            if recipes is not None and m.group(1) not in recipes:
                report("error", path, f"just recipe '{m.group(1)}' is not in the justfile")
        if not TEST_HINT.search(text):
            report("warn", path, "nothing says how to test or check work (add the exact test command and what done means)")
        if not NEVER_HINT.search(text):
            report("warn", path, "no 'Never' section; list what the agent must not touch or run")
        if lines > 150:
            report("warn", path, f"{lines} lines; keep it short and move procedures into skills")
        for m in (x for sp in spans for x in [PATHLIKE.match(sp)] if x):
            rel = m.group(1)
            if "<" in rel or "*" in rel or rel.startswith(("http", "~", "/")) or rel.startswith(GENERATED):
                continue
            if not (os.path.exists(os.path.join(d, rel)) or os.path.exists(os.path.join(root, rel))):
                report("warn", path, f"path `{rel}` does not exist")
        print(f"info  {os.path.relpath(path, root)}: {lines} lines, {len(text.encode())} bytes; Codex reads: {' + '.join(os.path.relpath(p, root) for p in ch)}")
    print(f"agents-md-lint: {len(files)} file(s), {errors} error(s), {warns} warning(s)")
    return 1 if errors else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

# AGENTS.md

Next.js 16 (App Router) + TypeScript strict + Postgres via Drizzle. pnpm only.

## Commands
- Install: `pnpm install --frozen-lockfile`
- Dev server: `pnpm dev` (http://localhost:3000; reuse a running one, check `.next/dev/lock`)
- Type check: `pnpm typecheck`
- Lint and format: `pnpm lint` then `pnpm format`
- Unit tests: `pnpm test` · one file: `pnpm test src/lib/price.test.ts`
- End-to-end: `pnpm e2e` (needs the dev server)
- DB migration: `pnpm db:generate` writes SQL to `drizzle/`; never run `db:push` against a shared database

## Layout
- `app/` routes; server components by default, `"use client"` only for interactivity
- `src/lib/` pure logic with unit tests next to it; `src/db/` schema and queries; `src/components/` UI

## Conventions
- Server actions validate input with zod and return `{ ok, error }`; never throw to the client
- Money is integer pence; dates are UTC `Date` objects, formatted only in components
- New UI uses the existing components in `src/components/ui/`; no new UI libraries

## Never
- Commit `.env*` files or print secrets; add new variables to `.env.example` with a dummy value
- Edit `drizzle/` migrations that are already merged; write a new one
- Disable a lint rule or a test to get green

## Done means
`pnpm typecheck && pnpm lint && pnpm test` pass, the changed page was opened in the browser and works, and the
PR description says what you checked by hand.

# AGENTS.md

`tidyparse`: a pure-Python library for parsing messy CSV exports. Supports Python 3.11 and later. Published to PyPI.

## Commands
- Set up: `uv sync`
- Tests: `uv run pytest -q` · one test: `uv run pytest -q tests/test_dates.py::test_iso_week`
- Lint and format: `uv run ruff check --fix` then `uv run ruff format`
- Types: `uv run mypy src`
- Docs preview: `uv run mkdocs serve`

## Layout
- `src/tidyparse/` the package; public API is exactly what `__init__.py` exports
- `tests/` mirrors `src/`; fixtures (sample CSVs) in `tests/data/`

## Conventions
- No new runtime dependencies without asking; dev dependencies go in the `dev` group
- Every public function has type hints and a docstring with one example
- Changes to public behaviour get a line in `CHANGELOG.md` under "Unreleased"
- Keep Python 3.11 compatible: no `type` statements or 3.12+ only syntax

## Never
- Change the public API (names, arguments, return types) without saying so first; it breaks users
- Bump the version or publish; releases are done by a maintainer
- Edit `tests/data/` files to make a test pass

## Done means
`uv run pytest -q`, `uv run ruff check` and `uv run mypy src` pass, new behaviour has a test, and `CHANGELOG.md` is updated.

# AGENTS.md (repository root)

Monorepo: `apps/web` (React + Vite), `apps/api` (Fastify), `packages/shared` (types and zod schemas). Turborepo + pnpm workspaces.
Each app has its own `AGENTS.md` with its commands; read the one nearest to the files you change.

## Commands (from the root)
- Install: `pnpm install --frozen-lockfile`
- Everything: `pnpm turbo run build test lint`
- One package: `pnpm --filter @acme/api test`

## Rules for every package
- Shared types live in `packages/shared`; never copy a type into an app
- A change to `packages/shared` must build and test every app that depends on it: `pnpm turbo run test --filter=...@acme/shared`
- Add dependencies to the package that uses them, never to the root `package.json`
- One concern per pull request; do not mix a refactor with a feature

## Never
- Edit generated files (`**/dist/`, `apps/api/src/generated/`)
- Change CI (`.github/`) or Turborepo config without asking

# AGENTS.md (apps/api)

Fastify 5 API on Node 24. Postgres via Kysely. Read the root `AGENTS.md` first; this file adds API rules.

## Commands (from apps/api)
- Dev: `pnpm dev` (port 4000) · tests: `pnpm test` · one: `pnpm test src/routes/orders.test.ts`
- Migrations: `pnpm migrate:new <name>` creates a file in `migrations/`; `pnpm migrate:up` runs them locally only

## Rules
- Every route declares a zod schema from `@acme/shared` for body, params and response
- Handlers stay thin: validation and HTTP in `src/routes/`, logic in `src/services/` with unit tests
- Errors use `httpErrors` from `@fastify/sensible`; never leak stack traces or SQL to clients
- Queries are parameterised through Kysely; no string-built SQL

## Never
- Run migrations against anything but your local database
- Return database rows straight to clients; map them to the shared response schema

## Done means
`pnpm test` passes here and in `apps/web` if you changed a shared schema, and you called the changed route locally
with a real request and saw the expected response.

# AGENTS.md

`shipctl`: a Go 1.27 command-line tool for managing deploy manifests. Single binary, no CGO.

## Commands
- Build: `go build ./...` · run: `go run ./cmd/shipctl --help`
- Tests: `go test ./...` · race: `go test -race ./...` · one: `go test ./internal/manifest -run TestMerge`
- Lint: `golangci-lint run`
- Golden files: `go test ./internal/render -update` rewrites `testdata/*.golden`; only after reading the diff

## Layout
- `cmd/shipctl/` flags and wiring only; `internal/` everything else; no pkg folder
- `testdata/` inputs and golden outputs for table-driven tests

## Conventions
- Errors wrap with context: `fmt.Errorf("load %s: %w", path, err)`; no panics outside `main`
- Flags are kebab-case and documented in `--help`; any new flag is added to `docs/cli.md`
- Output: human text by default, `--json` for machines; never change existing JSON field names
- Standard library first; ask before adding a module

## Never
- Accept updated golden files without reading the diff
- Change exit codes (0 ok, 1 error, 2 usage); scripts depend on them

## Done means
`go test -race ./...` and `golangci-lint run` pass, and you ran the changed command for real and pasted its output.

# AGENTS.md

A 2D platformer in **Godot 4.7** (GDScript 2.0). Not Godot 3: no `yield`, `export var`, `onready`, `KinematicBody2D`.

## Commands
- Check one script: `godot --headless --path . --check-only --script res://scenes/player/player.gd`
- Run headless for errors: `godot --headless --path . --quit-after 300`
- Tests (GUT): `godot --headless --path . -s addons/gut/gut_cmdln.gd -gexit`

## Layout
- `scenes/<thing>/` with the `.tscn` next to its `.gd`; `autoload/` for the few global singletons; `assets/` imported files

## Conventions
- Static types everywhere; `@export` for values a designer tunes; signals up, calls down
- Input actions from the Input Map (`move_left`, `jump`), never raw key codes

## Never
- Hand-edit `.tscn` files beyond small property changes; never edit `.godot/`
- Add plugins to `addons/` without asking

## Done means
No `SCRIPT ERROR` from `--check-only` or the headless run, tests pass, and you told the human what to try in the game.

# AGENTS.md

OpenTofu 1.13 modules and environments for AWS. Agents **plan only**; humans apply.

## Commands
- Format: `tofu fmt -recursive`
- Validate a module: `cd modules/<name> && tofu init -backend=false && tofu validate`
- Plan an environment: `cd envs/staging && tofu init && tofu plan -out=plan.bin` (read-only credentials)
- Policy scan: `checkov -d modules --quiet`

## Layout
- `modules/` reusable modules with `variables.tf`, `outputs.tf`, `README.md`; `envs/<env>/` one root per environment

## Rules
- Pin providers with `~>` in `versions.tf`; commit `.terraform.lock.hcl`
- Every new variable has a type, a description and validation where it can be wrong
- Tag every resource through the module's `tags` variable

## Never
- Run `tofu apply`, `tofu destroy`, `tofu state` or `tofu import`; ask the human
- Put secrets in `.tf` or `.tfvars` files; use the secrets manager data source
- Edit `envs/production/` unless the task names it

## Done means
`tofu fmt -check`, `tofu validate` and `checkov` pass, and the plan output for the changed environment is in your
report with every create, change and destroy listed.