A command reference, a map of where to find each subsystem, and a set of core principles. Three of its sections are about how code and comments are written rather than what they do.
Quoted passages are verbatim. Open one to see it in the source.
01 / House vocabulary
Named words that may not be used
A section headed in block capitals asks for plain language over jargon, shows two renamed examples, and then lists thirteen individual metaphorical words that may not appear: load-bearing, pin, bite, sharp, arm, guard, bless, wedge, retire, retarget, answer, settle, carry, land. Inventing terms where a common domain equivalent exists is ruled out in the same paragraph.
Source excerpt starting at line 140.
140No-one knows what the hell a bootstrap-safe statement is. Everyone knows what "a statement that needs a table" is. Do141not use metaphorical language, such as the following terms: load-bearing, pin, bite, sharp, arm, guard, bless, wedge,142retire, retarget, answer, settle, carry, land. Do not make up terms if they have equivalents that are commonly used in the domain.
02 / Behavioral framing
A named debugging shortcut, ruled out
Tests failing after a change are defined as that change's regressions, to be debugged directly. Stashing or reverting to check whether they also fail on main is described as a waste of time and prohibited by name.
Source excerpt starting at line 122.
1225. **Own your regressions.** If tests fail after your change, they are your regressions. Debug them directly. Never stash/revert to "check if they fail on main" — that wastes time and is categorically banned.
03 / From this file
Reading order fixed top to bottom
A file should read from the top without jumping ahead: callers come first, callees follow, and a new helper goes below the functions that call it rather than at the end of the file. A three-line example shows the ordering.
04 / Hard prohibitions
Comments ruled out entirely
A two-line section states that comments are not to be added, and directs the effort into making the code expressive instead. It is the most absolute position on comments in the directory, where other files ask for comments that explain why.
Source excerpt starting at line 161.
161- Do not add comments. Instead, focus on making your code expressive.
05 / From this file
A test harness chosen by narrowness
Nine test directories are listed with what each is for, under a default: add coverage to the narrowest existing harness that can express the bug, and extend an existing file rather than create one. Imported upstream golden tests are marked as not to be modified for local behavior changes.
06 / From this file
A note about running inside CI
A closing section tells the agent it may be running in a GitHub Action with a turn limit, that pushing work in progress and continuing in another run is acceptable, and to avoid rabbit holes.
Put it to work
Borrow this for your repo
01If reviewers keep rewriting the same vague phrasing, list the words rather than describing the tone.
02Name the debugging shortcuts that waste time in your codebase, such as reverting to check whether a failure predates the change.
03State which test directory a new test belongs in, and which are off limits.
04If agents run in CI with a turn limit, tell them what to do when they hit it.
Turso'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.
