TL-M0-17 · AGENTS.md: the guide every coding agent reads

Why: Every coding agent reads AGENTS.md first; Claude Code reads CLAUDE.md, which points to it. It holds the map and the rules, and points at the register. Turborepo's own block stays at the end, because turbo writes it back if it is removed.

ID TL-M0-17 · Level L0 · Run order row 17

Goal

The root AGENTS.md, under 100 lines, starts with Opleet's guide and ends with Turborepo's block.

Before

TL-M0-16 is Done.

Run

1 · A branch, then write the guide above Turborepo's block

git switch -c repo/agents-md
cat > AGENTS.top.md <<'EOF'
# Opleet v2: guide for coding agents

Read this file, then the register, before you change anything. Keep this file under 100 lines.

## Where decisions live

- [Register] v2 decisions and working rules, in the Opleet Wiki, outranks this file, every other doc and anything said in a chat:
  https://docs.google.com/document/d/1rXKFmIFa1nY3ZViF_Ojo2kCSSOfc0gutjiSHlQ6iGBs/edit
- Cite decisions by ID (D4, D11) in commit messages and comments that depend on them.
- Work is written as runbook steps: [Runbook] v2 timeline (the order of all work), [Runbook] v2 backend and [Runbook] v2 frontend.
- What v2 does is written in apps/docs as rules with IDs, before any test (D27). Start from the rules for your area; contributing/rules.md defines the format.

## Human first

- zuki runs every operational step by hand first. You never run anything against staging or production.
- Never ask for, print or commit a secret. Secrets appear in steps only as placeholders such as <STAGING_DB_PASSWORD>.
- A step is done when zuki has logged a clean run, not when it is written.
- You push only to the agent fork, opleet-agents under zuki's account: a branch, then a pull request inside the fork with green checks. zuki opens the pull request into the repository and merges it (D27).

## Map

- apps/web: the Next.js 16 app. Frontend Engineer.
- apps/docs: Astro Starlight. The source of truth for what v2 does: rules with IDs, written before tests (D27). Docs Engineer. Pages under reference/ are generated; never edit them.
- packages/db-types: the generated database types and nothing else (D22). Never edit by hand.
- supabase/: migrations, pgTAP tests, seed and config.toml. Backend Engineer. Not a package.
- tools/: database and migration scripts, outside the pnpm workspace. Backend Engineer.

## Where logic lives (D3)

- Business rules, multi-step actions and access control live in Postgres: constraints, triggers, security-definer functions and RLS.
- apps/web composes pages, forms and labels. Reads go through PostgREST under the user's session; writes that change status, money or numbers call RPC.

## Rules the repository enforces

- The schema changes only through supabase/migrations (D4). Until cutover the files may be edited in place (D11).
- apps/web never connects to Postgres directly, and there is no ORM (D4). Biome blocks pg, postgres and drizzle-orm outside tools/.
- pnpm only: package.json pins pnpm 12 and .node-version pins Node 24. Build scripts run only for packages listed under allowBuilds in pnpm-workspace.yaml.
- Conventional Commits; scopes are web, docs, db-types, supabase and tools; repo-wide changes take no scope (D6). Pull request titles are checked.
- Every new database rule or business action gets pgTAP tests in the same change (D19), and every refusal raises a stable error key (D10).
- Order of work: the rule in apps/docs, then a test whose description starts with the rule's ID, then the code (D27). pnpm docs:rules checks the link in CI.

## Commands

- pnpm install · pnpm dev · pnpm build · pnpm typecheck · pnpm lint · pnpm format · pnpm docs:rules
- pnpm supabase start · pnpm supabase db reset · pnpm supabase test db · pnpm supabase stop
EOF
cat AGENTS.md >> AGENTS.top.md
mv AGENTS.top.md AGENTS.md
echo "@AGENTS.md" > CLAUDE.md
wc -l AGENTS.md

2 · Commit, open the pull request, merge

git add -A
git commit -m "docs: add the guide for coding agents"
git push -u origin repo/agents-md
gh pr create --fill
gh pr checks --watch
gh pr merge --squash --delete-branch
git pull

Expect

• Block 1: wc prints about 58.
• Block 2: checks pass and the pull request merges.

Check

head -1 AGENTS.md
tail -1 AGENTS.md

“# Opleet v2: guide for coding agents”, then Turborepo's END marker.

If it fails

wc prints more than 100: AGENTS.md held more than Turborepo's block before this step. Paste the output of git diff HEAD -- AGENTS.md.

Undo

Revert it with a new pull request.

Runs

Done 2026-10-06 (zuki)