A directory table, a command list, and four short convention sections. Most subsystem detail is delegated to per-app instruction files and to a set of named skills.
Quoted passages are verbatim. Open one to see it in the source.
01 / From this file
A rule about the repository being public
PR descriptions, issues and code comments are identified as world-readable, and three categories are excluded from them: absolute production metrics, internal decision detail such as vendor or pricing discussions, and competitor names. Percentages and ratios are given as the permitted substitute for absolute figures, and the internal tracker is named as where that context belongs.
Source excerpt starting at line 59.
59**Public surfaces** — this repo is public: PR descriptions, issues, and code comments are world-readable. Keep internal content out of them: absolute production metrics (event counts, user counts, revenue figures: state percentages, ratios, or relative change instead), internal decision detail (vendor, legal, pricing, or strategy discussions), and competitor names (protocol identifiers such as user-agent strings are fine). Put that context in the Linear issue and link it.
02 / Router files
Skills mapped to when they apply
Nine skills are listed, each with the trigger that should load it: user-facing text anywhere in the monorepo, anything under the docs app, code that builds SQL against user databases, any form code. The file states that the skills, not itself, are the source of truth for those conventions.
Source excerpt starting at line 63.
63The skills in `.agents/skills/` are the source of truth for conventions — load the relevant ones before working, don't guess:
03 / Ratchets
A lint warning count that may not increase
Lint rules run at warning severity across all apps, and a ratchet check on the Studio app fails if the warning count goes up. The rule is enforced by a path-filtered CI job rather than by review.
04 / Generated file guards
Generated paths listed explicitly
Eight path patterns are named as never hand-edited, including API types, a route tree, generated docs content and database types. One entry carries the command that regenerates it.
05 / From this file
One component named as the default
The conventions section states which button component is the standard, and notes that a raw shadcn variant also exists but is rarely the right choice. Checking the package index before creating a new primitive is given as the rule.
Put it to work
Borrow this for your repo
01If your repository is public, state what may not go into PR descriptions, issues and comments, and where that content belongs instead.
02When two similarly named components exist, say which is the default and what the other one is for.
03A warning count that may not increase turns a long tail of lint debt into a one-way door.
Supabase's file tells an agent how the codebase works. It cannot tell it which bug three customers hit this week. Modem keeps that context current and attaches it to the work.
