gofastr-docs
Skill24 starsChanged yesterdayMITView on GitHub
Auto-loads when adding, changing, or removing any GoFastr feature or exported API. Encodes the doc topology (README + ARCHITECTURE + framework/docs/content/*.md) and the change→doc mapping. Docs are embedded in the gofastr binary at build time; `gofastr docs` browses them and the MCP `framework_docs_*` tools expose them to agents. Triggers on edits to framework/*.go, core/, battery/, cmd/, kiln/, core-ui/, and on phrases like "add", "implement", "build", "refactor", "rename", "remove", "deprecate", "new feature", "new endpoint", "new field type", "API change", "expose", "wire up". Goal: docs ship in the same commit as the code, not "later".
- Commits and pushes
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- framework/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adversarial-testsSkill
- app-introspectSkill
- chaos-testSkill
- component-buildSkill
- eval-reportSkill
- gofastr-hostSkill
- gofastr-mcp-debugSkill
- gofastr-uiSkill
- log-debugSkill
- plain-wordsSkill
- primitives-sweepSkill
- review-gateSkill
- twin-sweepSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 6 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
If you are about to add, rename, remove, or refactor anything that an external user (or a future Claude) would discover from the docs, this …
- Very specific: line 46
If the new symbol is referenced from a JSON entity declaration: framework/docs/content/entity-declarations.md
- Very specific: line 105
If you added a new data-cui-* attribute: update the runtime test suite as well (rule from AGENTS.md)
- Distinctive: line 130
Don't leave dangling code samples
- Very specific: line 161
If the release adds host-facing surface (a new battery, uihost option, or CLI capability a host-app agent should reach for): …
- Very specific: line 166
Publish the GitHub Release: a pushed tag is NOT a release: After the PR merges, tag the merge commit AND run gh release create vX.Y.Z …
- Distinctive: line 178
Doc updates ship in the same commit as the code change: Not a follow-up PR, not a TODO.
- Distinctive: line 182
Don't invent documentation for code that doesn't exist yet: Read the actual implementation before writing the doc.
- Distinctive: line 195
One canonical example per concept: If a snippet exists in the README, the reference page should link to or extend it, not re-state a …
- Distinctive: line 210
Run this mental check:
- Very specific: line 222
Surfaces drift: If the README advertises a behaviour, a page in framework/docs/content/ should cover it.
- Very specific: line 225
Keep it accurate: when an item ships, delete it from the roadmap and move per-feature truth into framework/docs/content/<feature>.md.
- Very specific: line 242
Read AGENTS.md, README.md, and core-ui/ARCHITECTURE.md if you have not yet this session.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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
GoFastr docs: load this before changing the public surface
If you are about to add, rename, remove, or refactor anything that an external user (or a future Claude) would discover from the docs, this skill applies. Docs are part of the change, not a follow-up.
Doc topology: know what lives where
| File | Role | Update when |
README.md | Canonical entry point. The quickstart, the "The code you don't write" table (auto-generated entity behaviour), and the "The repo in 60 seconds" table (batteries, CLI) are the source of truth for what the framework advertises. | A new auto-generated entity behaviour is added/renamed/removed. A battery or CLI subcommand is added/renamed/removed. |
framework/docs/content/README.md | The curated docs index: it links most reference pages, not all of them. | A file in framework/docs/content/ is added, renamed or removed. |
core-ui/ARCHITECTURE.md | UI/runtime contract. Authoritative for SSR/hydration/island/SSE model. | Any change to core-ui/, framework/ui/, framework/uihost/, runtime.js, or the data-cui-* attribute set. |
framework/docs/content/entity-declarations.md | JSON + Go entity declaration reference. | New field type, new option in EntityConfig, new declaration loader, new validator. |
framework/docs/content/query-dsl.md | Query DSL parser surface. | New operator, new clause, new column type, change to DSL grammar. |
framework/docs/content/migrations.md | SQL-file migrate directives + CLI subcommands. | New directive, new CLI subcommand, dialect change. |
framework/docs/content/search.md | battery/search interface + backends. | New backend, interface change, new query option. |
framework/docs/content/security.md | Default middleware stack + security headers. | New default middleware, header change, new policy primitive. |
framework/docs/content/widgets.md | core-ui/widget builder API. | New widget, new preset, new theme hook. |
framework/docs/content/reactivity.md | The reactivity ladder (client signals → RPC → poll → SSE push) + the stateless-interactive-layer contract. | Any change to signals, polling, the SSE bus, session tokens, WithSecret, or which rung a surface should use. |
framework/docs/content/contracts.md | gofastr verify: the rule catalog, capabilities, config/suppression, baselines, semantic coverage, and the machine-readable output. | A rule is added/renamed/retired, a capability changes, a verify flag or exit code changes, the JSON/SARIF shape changes, or a contract MCP tool is added. |
examples/site/docs_catalog.go | The public docs site's curated catalog. Every embedded topic must appear here or /docs/<slug> 404s. | Any new file in framework/docs/content/; there is a test for this, and it is the one people forget. |
examples/*/README.md | Per-example walkthrough. | When the example's behaviour or wiring changes. |
The public API is documented via README's "The code you don't write"
table + the per-feature reference pages in framework/docs/content/ + the
framework/doc.go package doc. Keep these consistent. The repo-root
docs/ holds agent notes, proposals and reviews, not reference pages.
The change→doc mapping (use this as a checklist)
For each kind of change, the listed docs MUST be revisited in the same commit. "Revisited" means: open the file, decide whether it needs a change, and either edit it or note in the commit message why no edit was needed.
You added a new exported func/type/const in framework/:
- README "The code you don't write" table or per-feature section
- The matching
framework/docs/content/<feature>.md(or create it if the surface is new enough to warrant its own page) - If the new symbol is referenced from a JSON entity declaration:
framework/docs/content/entity-declarations.md
You added a new entity field type (e.g. schema.JSON, schema.Money):
framework/docs/content/entity-declarations.md: field type table- README "The code you don't write"
app.Entityexample if it changes the canonical shape framework/entity/column.gocolumn constructors, same PR
You added a new auto-generated route or endpoint pattern
(e.g. _batch, _events, _search):
- README's "The code you don't write" table
- A page under
framework/docs/content/updated in the same change; a reference page of its own if the surface has its own semantics examples/api-tour/main.goshould exercise it; update the example README
You added a new EntityConfig option (e.g. SoftDelete, MCP,
CursorField, Endpoints):
framework/docs/content/entity-declarations.md- README "The code you don't write"
app.Entityexample if it changes the default story
You changed the query DSL grammar or operator set:
framework/docs/content/query-dsl.mdframework/dsl/dsl.goparser table, same PR
You added a contract rule, or changed gofastr verify:
framework/contracts/catalog.go: the rule is data; ID, Why, Fix, and a bad/good example pair are all required, and a malformed entry panics at init rather than shipping half-documentedframework/docs/content/contracts.md: the capability table and any behaviour a reader would be surprised by- An analyzer claiming a rule that is not in the catalog panics at init.
The reverse, a catalog rule no analyzer emits, is caught by
TestEveryCatalogRuleHasAnAnalyzerin the analyzers package (it has to live there: the catalog deliberately does not import its analyzers, so the same test inframework/contractscould only ever skip) - The catalog is checked against itself: no rule may fire on its own good
example, and a rule's bad example must produce it. An example that needs
more context than one file can express goes in
examplesNeedingMoreContextWITH the reason README.mdquotes the rule count.TestAdvertisedRuleCountMatchesTheCatalogfails the build until it matches, so adding a rule updates that number. A release entry in CHANGELOG.md states the count at that release and is never rewritten
You added ANY file to framework/docs/content/:
examples/site/docs_catalog.go: add the slug to an intent group, or the site's A–Z index links a page that 404s.TestEveryEmbeddedDocIsInCatalogcatches it, but only in the slowexamples/sitesuite, so it is easy to miss locally
You changed migration directives or the migrate CLI:
framework/docs/content/migrations.mdcmd/gofastr/internal/migratecmd/migrate_cmd.go(+migrate_generate.go), same PR
You changed core-ui/ or framework/uihost/:
core-ui/ARCHITECTURE.md: this is mandatory; the doc is the contract- If you added a new
data-cui-*attribute: update the runtime test suite as well (rule fromAGENTS.md)
You added/changed a battery package (anything under battery/):
- The battery's existing reference page in
framework/docs/content/(find it through the docs index; create<battery>.mdonly when the battery has no page yet) - README "The repo in 60 seconds"
battery/row if the package list changed
You added a new CLI subcommand:
framework/docs/content/cli.md, which maps every subcommand to its doc- README "The repo in 60 seconds"
cmd/gofastrrow - A reference page under
framework/docs/content/if non-trivial
You ran an architecture review / security review:
- Findings become fixes with pinning tests in the same pass; the keep/flip/delete rationale goes in the commit message and a comment beside the surviving test. No review-log or ledger files; git history is the record.
You removed or renamed an exported symbol:
- grep the docs for the old name and replace
git grep '<OldName>' README.md docs/ framework/docs/content/ examples/(docs/public-api.mdlists exported symbols and their stability tiers)- Don't leave dangling code samples
You landed a BREAKING change / you're cutting a release:
- CHANGELOG.md entry (BREAKING items called out explicitly). Keep it to what changed and what a reader must do, in a few lines, and link the PR or docs page for the rest.
- A v0.N0.0 release moves the ten minor versions before it out of
CHANGELOG.md into
changelog/v0.A0-v0.A9.md, unchanged except that repo-relative links gain../, and links the new file from CHANGELOG.md's header (TestChangelogArchiveLayout). internal/upgrade/: every release PR bumpsthroughinregistry.yml; a release with BREAKING or migration-relevant changes also addsreleases/<version>.yml(one-line guidance, afindblock of typed matchers, or a one-linenodetectreason when no spelling differs; the parser has no block scalars).TestThroughMatchesChangeloggates it against the CHANGELOG's latest heading. Between releases a feature PR may add the note to a pendingreleases/<next version>.ymlabovethrough: exactly one such file, its version the next patch, minor or major ofthrough(TestThroughCoversNewestEntry); the release PR keeps or renames it to the version that ships, and every file at or belowthroughmust name a CHANGELOG release. The dev-mode retired-markup table (internal/retired/retired_table.gen.go) copies every kit class or attribute (ui-*,fui-*,data-cui-*,data-fui-*,data-hui-*) a breaking note names, with the note's version and change text. Rungo generate ./internal/retiredafter adding or dropping such a name, editing the change text of a note that names one, or renaming a release file that holds one (including the pending file the release PR renames).TestTableIsCurrentnames the command when the table is out of date.- SECURITY.md "Supported versions": the latest-minor line
- If the release adds host-facing surface (a new battery, uihost
option, or CLI capability a host-app agent should reach for):
.claude/skills/gofastr-host/SKILL.mdrecipe table + trigger phrases, then copy tocmd/gofastr/internal/agentscmd/embedded/gofastr-host-skill.md(TestEmbeddedHostSkillMatchesRepopins the sync) - Publish the GitHub Release: a pushed tag is NOT a release. After
the PR merges, tag the merge commit AND run
gh release create vX.Y.Z --title "…" --notes-file <the CHANGELOG section>.git push origin vX.Y.Zonly creates a tag object; the repo's Releases page (and anyone watching for releases) shows nothing until the Release object exists. The release is not "done" at the tag; it's done whengh release view vX.Y.Zsucceeds and it readsLatest. (v0.27.0 and v0.28.0 are tag-only for exactly this reason; backfill them if the Releases page needs to be complete.)
Hard rules
- Doc updates ship in the same commit as the code change. Not a follow-up PR, not a TODO. If the PR is rejected for doc reasons it gets fixed in place, not deferred.
- Don't invent documentation for code that doesn't exist yet. Read the actual implementation before writing the doc. Stale or wrong docs are worse than missing ones.
- Don't document private implementation details. The reference
pages describe the public surface a user touches: exported types,
exported funcs, HTTP routes, CLI flags, JSON declaration fields,
data-cui-*attributes. Skip internal helpers. - No time estimates, no roadmaps in reference docs. Status ("pre-alpha") goes in the README only, once. Reference pages describe what is true now.
- One canonical example per concept. If a snippet exists in the README, the reference page should link to or extend it, not re-state a different version that will drift.
- Stub pages are a defect. A 22-line doc that just shows one code snippet is not a reference page. Either flesh it out with: full API surface + every option + at least one failure mode, or fold it into the README and delete the stub.
- Don't claim coverage you can't show. "Production-ready" / "battle-tested" / "fully-featured": never. State what the code does, in present tense, with no marketing.
When you are unsure whether a doc needs updating
Run this mental check:
- Could a user of this library reach the thing I just changed by reading the docs and following the obvious path? If yes → doc.
- Did I add a new HTTP route, CLI subcommand, JSON field, env var, middleware, hook point, or auto-generated artifact? → doc.
- Did I only change internals that nobody outside the package would touch? → no doc, but make sure no existing doc contradicts the new behaviour.
Anti-patterns observed in this repo (don't repeat them)
- Surfaces drift. If the README advertises a behaviour, a page in
framework/docs/content/should cover it. - Roadmap drift. Forward-looking work lives in
ROADMAP.md. Keep it accurate: when an item ships, delete it from the roadmap and move per-feature truth intoframework/docs/content/<feature>.md.
Definition of done for a doc-touching PR
- Every doc listed in the change→doc mapping above has been opened
- README "The code you don't write" and "The repo in 60 seconds" tables reflect reality
- No dangling references to removed symbols (
git grepclean) - No new TODO in docs that aren't tracked elsewhere
- If you created a new
framework/docs/content/<name>.md, it has at least: a one-paragraph intro, a code sample that runs as-is against the current code, the full option/parameter table, and one "common mistake" callout - If you renamed/removed something, the old name does not appear in any doc
Read AGENTS.md, README.md, and core-ui/ARCHITECTURE.md if you
have not yet this session. They are the source of truth.
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.

