gofastr
AGENTS.md24 starsChanged yesterdayMITView on GitHub
Before changing a file, run go run ./cmd/primitives for <path>. It prints the primitives that own the file with their invariants (each naming the test or analyzer that enforces it) and decisions. The registry lives in primitives/, one primitive.yml per primitive, format in primitives/README.md; go run ./cmd/primitives lint checks it and gen writes the import tests it declares. A rule or a "why" that would have gone into a comment or into this file goes there instead (the primitives-sweep skill).
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository16 other files it gives its agents.
- framework/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adversarial-testsSkill
- app-introspectSkill
- chaos-testSkill
- component-buildSkill
- eval-reportSkill
- gofastr-docsSkill
- gofastr-hostSkill
- gofastr-mcp-debugSkill
- gofastr-uiSkill
- log-debugSkill
- plain-wordsSkill
- primitives-sweepSkill
- review-gateSkill
- twin-sweepSkill
The file
We split this AGENTS.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Read before you start:
- Very specific: line 39
No pagination, sort or filter math in JS: runtime/no-list-math-in-js.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Claude / agent instructions for the GoFastr repo
Before changing a file, run go run ./cmd/primitives for <path>. It
prints the primitives that own the file with their invariants (each
naming the test or analyzer that enforces it) and decisions. The registry
lives in primitives/, one primitive.yml per primitive, format in
primitives/README.md; go run ./cmd/primitives lint checks it and gen writes
the import tests it declares. A rule or a "why" that would have gone
into a comment or into this file goes there instead (the primitives-sweep
skill).
Read before you start:
- UI, the runtime,
framework/uihost, or anything that emits markup or CSS (the app generator, batteries):core-ui/ARCHITECTURE.md. - Adding, moving or extracting anything under
framework/:framework/ARCHITECTURE.md. - An exported API, route, CLI subcommand, JSON field or generated
artifact changes: the
gofastr-docsskill. Docs ship in the same commit, inframework/docs/content/*.md. - Commands (build, test, analyzers, red probes, dupl), the full text of
the process rules, and where each kind of code lives:
docs/contributing.md.
TL;DR of the architecture
SSR first, then hydration, never a re-render. Cross-page navigation is
client-side; in-page state is an island or the query string. Passive
freshness polls (data-cui-poll); SSE on the one /__gofastr/sse bus is
the last resort. Server state lives in the DB or the client signal store,
never in server RAM; sessions are signed tokens. The full ladder is
framework/docs/content/reactivity.md.
Hard rules
Code cites these by number. Each code rule's full text, and what enforces it, is its registry entry.
- In-page state stays on its route:
uihost/in-page-state-stays-on-its-route. - No pagination, sort or filter math in JS:
runtime/no-list-math-in-js. - SSE is push-only, on the one bus:
runtime/sse-is-push-only. - No
location.hrefor full reloads as a fix:runtime/no-hard-navigation. - A new
data-cui-*attribute is documented and tested:runtime/attributes-are-documented. - Per-user data under auto-CRUD sets
Scope.OwnerField:crud.scope/per-user-entity-is-scoped. - One styling surface, zero bespoke CSS:
ui.styling/one-styling-surface. - Survey
framework/uiandcore-uibefore building:ui/survey-before-building. - Judge UI by screenshots of
examples/meridian, never by DOM probes: theon_changeline ofui. - Triage every review thread before merging:
./scripts/pr-review-findings.sh <N> --gate. - Prove a guard: break it, watch its test fail, put it back.
- Watch every PR you open (
subscribe_pr_activity); merge main in on a conflict, never force-push.
Rules 10 to 12, and 7 to 9 at length, are in docs/contributing.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

