gofastr / framework
AGENTS.md24 starsChanged yesterdayMITView on GitHub
App-level helpers worth surfacing to AI agents alongside the batteries. Use this when the prompt mentions: page layout, app shell, "a sidebar app", header and footer, breadcrumbs, a docs site with a table of contents, list on the left / detail on the right, highlight the current nav item, outlet, chrome that persists across navigation — or audit trail / who did what, hot reload, dev server, browser auto-refresh, livereload, run the app while developing, .env loading, live app introspection,…
- Reads credentials
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.
- 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, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 98
Every schema.Image upload produces the configured renditions plus a BlurHash, stores them beside the original, and writes the metadata to …
- Very specific: line 148
Don't: add a separate godotenv.Load() call before NewApp.
≈ “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
framework (root + sub-helpers)
App-level helpers worth surfacing to AI agents alongside the batteries.
Use this when the prompt mentions: page layout, app shell, "a
sidebar app", header and footer, breadcrumbs, a docs site with a table
of contents, list on the left / detail on the right, highlight the
current nav item, outlet, chrome that persists across navigation — or
audit trail / who did what, hot
reload, dev server, browser auto-refresh, livereload, run the app while
developing, .env loading, live app introspection, image uploads that need
thumbnails / responsive sizes / a blur placeholder.
core-ui/app: layouts with outlets — the page-shell primitive
Use this when the prompt mentions: page layout, app shell, "a sidebar app", header and footer, breadcrumbs, a docs site with a table of contents, list on the left / detail on the right, highlight the current nav item, outlet, persistent chrome, master-detail with a shareable URL.
Import: github.com/DonaldMurillo/gofastr/core-ui/app (imported
as uiapp in examples); the components a shell composes come from
github.com/DonaldMurillo/gofastr/framework/ui.
Shape:
toolbar := uiapp.NewOutlet("toolbar") // a named slot of the shell
shell := uiapp.NewLayout("shell", uiapp.LayoutSpec{
Outlets: []*uiapp.Outlet{toolbar}, // filled per route
Areas: []uiapp.AreaSpec{{Name: "crumbs"}}, // re-rendered per route
}, func(ctx context.Context, l *uiapp.LayoutTree) render.HTML {
return html.Div(html.DivConfig{},
siteHeader(ctx), // static chrome
l.RouteArea("crumbs", crumbsArea),
l.Place(toolbar),
l.Primary(), // the route's screen
)
})
site.SetDefaultLayout(shell)
site.RegisterScreen(uiapp.NewScreen("/inbox", &InboxScreen{}).
Fill(toolbar, &InboxToolbar{}), nil) // a screen fills its outletGroup layers nest under the shell and keep a pane across sibling
pages: uiapp.NewScreenGroup("/projects/{project}", layer) keys the
layer on the resolved param, so the issue list survives moving between
one project's issues. A fill whose Load returns uiapp.ErrNoFill
declines (an article without headings leaves the TOC column empty).
Don't reinvent a hand-rolled shell <div> per screen, a per-page
header copy, or a CSS-only chrome. There is no layout constructor in
framework/ui and no ready-made layout export: declare the layout
with uiapp.NewLayout and compose ui.Sidebar, ui.ContentRow and
the app's own header, footer and docs-page packages (copy
examples/acme-site/{siteheader,sitefooter,helpdocs}) in its build
function. The runtime's
active-link sweep marks the current nav item — never read the route in
the static chrome (the layoutfunc lint flags it). The four page
shapes are recipes: gofastr docs ui-composition-recipes; the
primitive: gofastr docs layouts; real apps: examples/tracker,
examples/acme-site.
app.WithAuditLog(cfg): automatic CRUD audit
Use this when the prompt mentions: audit trail, who did what, track changes, compliance log, history of modifications, admin accountability.
// WithAuditLog is a chained *App method, not a NewApp option.
app := framework.NewApp(framework.WithDB(db))
app.WithAuditLog(framework.AuditConfig{
Actor: func(ctx context.Context) string { return currentUserID(ctx) },
Entities: []string{"users", "orders"}, // restrict to non-PHI entities
Redact: nil, // optional func(entityName, row) row to redact JSON diff
})Writes one audit_log row per AfterCreate / AfterUpdate / AfterDelete
inside the same transaction as the change, so audit and write commit
or roll back together. Failed audit insert → write fails.
PHI caveat: the audit row contains a full JSON diff of the
changed row. For entities holding user-content (search history, symptom
logs, etc.) either exclude them via Entities or set Redact to drop
the sensitive keys before serialisation. Don't fold full content into
audit; that defeats the point of audit hygiene.
Don't reinvent a hand-rolled audit_log entity + recordAuditLog
helper for entity CRUD. DO keep custom audit writes for domain actions
(suspend, delete, password.reset). The framework only covers CRUD,
not arbitrary domain events.
framework.WithImagePipeline(d): uploads derive their own renditions
Every schema.Image upload produces the configured renditions plus a
BlurHash, stores them beside the original, and writes the metadata to sibling
columns the entity declares (<field>_blurhash, <field>_variants,
<field>_placeholder). Undeclared columns are skipped, so a column is how you
opt in.
framework.WithFileStorage(store),
framework.WithImagePipeline(imagefield.MustNew(imagefield.Config{
Variants: []image.Variant{{Width: 960, Format: image.FormatJPEG, Quality: 82, Suffix: "md"}},
BlurHashX: 4, BlurHashY: 3,
})),WithImagePipelineFor(entity, field, d) overrides one field; a nil deriver
opts a field out. Render with image.BlurHashDataURL(hash, ...) into
ui.PipelineImage's Placeholder.
Two things to know: the derive is synchronous in the request (~180ms for two
JPEG widths from a 3000px source, ~540ms once WebP is included, because that
encoder runs five passes), and an undecodable upload fails the request rather
than storing a file with no renditions. gofastr docs uploads has the detail.
framework/dev: auto-wired livereload
Develop with gofastr dev, not go run .. It is the only
first-party command that sets GOFASTR_DEV=1, so plain go run . never
hot-reloads. gofastr dev rebuilds the binary on save;
framework.NewApp auto-wires /__livereload + /__livereload.js, and
full HTML documents get the reload client. uihost screens inject it
themselves, and dev middleware splices it into any other response that
declares Content-Type: text/html and contains </body> (static file
serving, widget pages, hand-rolled handlers that set the type). So every
open tab refreshes when the new binary boots. No host code needed.
Disable: GOFASTR_DEV_LIVERELOAD=0 (keeps rebuild loop). Production
is hard-killed by GOFASTR_ENV=production.
See: framework/docs/content/dev-livereload.md.
core/dotenv: automatic .env loading
framework.NewApp reads .env.local, .env.<APP_ENV>, .env in
order (earlier wins) before option callbacks run. Existing os.Environ
always beats file values.
Disable: GOFASTR_DOTENV=off in the real process env.
Don't add a separate godotenv.Load() call before NewApp. It's
already done.
framework.WithMCPIntrospection(): live-app agent debug
Adds app_routes, app_plugins, app_batteries,
app_modules, app_config, app_readiness, app_goroutine_leaks,
app_routines (the registered cron/routine bodies, so "did my routine
body change land" is answerable from the session), app_unmounted (the
unmounted package copies compiled into the binary), so a
connected agent can answer "what routes exist" / "is the app
ready" / "is anything leaking goroutines" without leaving the session.
The embedded framework docs are a separate option, framework.WithMCPTools(mcptools.Register)
from framework/docs/mcptools: it adds framework_docs_list,
framework_docs_get and framework_docs_search. Package framework does not
import the docs corpus, so an app that wants the docs tools on /mcp adds
that option beside WithMCPIntrospection() (the app spec and the examples
do).
It also adds the contract catalog tools contracts_list,
contracts_explain, and contracts_capabilities, so an agent can read what
the framework requires of app code (with the reasoning, the fix, and a
worked example per rule) before writing any, rather than after
gofastr verify rejects it.
In the dev loop (gofastr dev) two more join them: contracts_verify
runs the analyzers over the app's own source tree and returns the
findings as structured diagnostics, and contracts_fix applies one
rule's autofixes and reports which files changed. Both read local
source, and contracts_fix also writes it, so they are registered only
when dev implies the MCP surface. A production /mcp does not gate
them; it does not have them.
framework.WithMCPControl() is the mutating counterpart: adds
app_module_enable / app_module_disable for runtime state control
on trusted /mcp endpoints.
Under gofastr dev the whole surface auto-enables (mount +
introspection + control + battery/log's log_* debug tools) with no
options, livereload for agents. Opt out with GOFASTR_DEV_MCP=0.
Production processes never see GOFASTR_DEV, so the explicit options
stay the only path there.
Use this when the prompt asks about live introspection, debugging
a running server, or "is this app healthy". See the
gofastr-mcp-debug Claude Code skill.
Don't reinvent
- A custom audit log entity:
WithAuditLogfor CRUD; domain actions stay custom. - A livereload SSE handler: framework auto-wires it under
gofastr dev. - A dotenv loader:
NewAppdoes it. - Per-test PG isolation: see
framework/testkit(NewIsolatedDB). - Resize/encode/thumbnail code in an upload handler:
WithImagePipelinedoes it from the field declaration;framework/imageis the manual path. - A JS BlurHash decoder:
image.BlurHashDataURLdecodes server-side andui.PipelineImagepaints it with no JavaScript. - Hand-rolled markup or CSS:
framework/uiships ~100 components; see theuirow of AGENTS.md (.agents/ui.md) andgofastr docs ui-new-components. - A hand-rolled page shell or per-screen chrome:
core-ui/app's tree layouts own the shell (NewLayout+ outlets); see the section above andgofastr docs layouts.
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.

