agentleFS
DonaldMurilloDonaldMurillo/gofastr/framework/agents.md

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

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
  1. Very specific:

    Every schema.Image upload produces the configured renditions plus a BlurHash, stores them beside the original, and writes the metadata to …

    line 98
  2. Very specific:

    Don't: add a separate godotenv.Load() call before NewApp.

    line 148

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

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 outlet

Group 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: WithAuditLog for CRUD; domain actions stay custom.
  • A livereload SSE handler: framework auto-wires it under gofastr dev.
  • A dotenv loader: NewApp does it.
  • Per-test PG isolation: see framework/testkit (NewIsolatedDB).
  • Resize/encode/thumbnail code in an upload handler: WithImagePipeline does it from the field declaration; framework/image is the manual path.
  • A JS BlurHash decoder: image.BlurHashDataURL decodes server-side and ui.PipelineImage paints it with no JavaScript.
  • Hand-rolled markup or CSS: framework/ui ships ~100 components; see the ui row of AGENTS.md (.agents/ui.md) and gofastr 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 and gofastr docs layouts.

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.