agentleFS
DonaldMurilloDonaldMurillo/gofastr/AGENTS.md

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).

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
  1. Distinctive:

    Read before you start:

    line 12
  2. Very specific:

    No pagination, sort or filter math in JS: runtime/no-list-math-in-js.

    line 39

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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-docs skill. Docs ship in the same commit, in framework/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.

  1. In-page state stays on its route: uihost/in-page-state-stays-on-its-route.
  2. No pagination, sort or filter math in JS: runtime/no-list-math-in-js.
  3. SSE is push-only, on the one bus: runtime/sse-is-push-only.
  4. No location.href or full reloads as a fix: runtime/no-hard-navigation.
  5. A new data-cui-* attribute is documented and tested: runtime/attributes-are-documented.
  6. Per-user data under auto-CRUD sets Scope.OwnerField: crud.scope/per-user-entity-is-scoped.
  7. One styling surface, zero bespoke CSS: ui.styling/one-styling-surface.
  8. Survey framework/ui and core-ui before building: ui/survey-before-building.
  9. Judge UI by screenshots of examples/meridian, never by DOM probes: the on_change line of ui.
  10. Triage every review thread before merging: ./scripts/pr-review-findings.sh <N> --gate.
  11. Prove a guard: break it, watch its test fail, put it back.
  12. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.