spencerbeggs/okfit

Builds or normalizes the standard shields.io badge block at the top of a package README, preserving custom badges. Use when adding, fixing or refreshing badges ("add badges to this README", "npm version badge", "TypeScript badge", "normalize the badge block").

Detects a repo's shape and metadata (single package, monorepo root, sub-package, website, docs folder) and sets up its Surface concepts under okf/surfaces/. Use when starting docs work in a repo that has no Surface concepts yet, when asked "what shape is this repo", "which docs presets apply", "set up documentation surfaces", or before writing a README or docs page whose shape is unknown.

Rewrites a docs file to remove AI-sounding prose (promotional phrasing, filler, -ing analyses, elegant variation, copula avoidance) without changing facts, code or links. Use when a README or docs page reads machine-written, or as the final pass after rendering a page. Trigger phrases -- "humanize this doc", "make this sound less like AI", "tighten the prose".

Re-renders a published page from the concepts a Publication names, then restamps its digests. Use when a Publication drifts (the publication-drift lint fires), when asked to "re-render", "refresh" or "update the published page" for a Publication, or after a source concept changes.

Gives the section order and skeletons for a package README, a monorepo router README and a docs/ folder with its table of contents. Use when creating or restructuring a README or docs page, adding a page to docs/, or rebuilding a docs TOC ("scaffold a package README", "add a docs page", "update the docs TOC").

Nineteen imperative rules for writing and editing OKF concept files under a config: what is required, what to never touch, the actor and timestamp conventions, and where core's leniency differs from the spec's prose. Use when creating, editing, or reviewing a concept file's frontmatter or body inside an okf/ bundle. Trigger phrases -- "write a new concept", "add frontmatter to this file", "should I set verified", "can I edit index.md", "what actor string do I use", "is generated.at required".

The okfit config file: discovery order, the three project-local locations and the XDG fallback, the TOML schema table by table, lint severities, and what the software-project profile contributes. Use when writing or editing .okfit.toml, okfit.toml or .config/okfit.toml, or explaining why a type, tag, or lint severity behaves the way it does. Trigger phrases -- "add a new type to the config", "change a lint severity", "where does okfit look for its config", "what does software-project add", "set actors.agent".

CLAUDE.md as a thin router into the okf/ bundle, checked against index.md. Use when writing or auditing a CLAUDE.md pointer into the bundle, or when okf-finalize's branch-end sweep needs to verify pointer coverage. Trigger phrases -- "does this CLAUDE.md pointer still work", "check CLAUDE.md against the bundle", "should this go in CLAUDE.md or the bundle".

Branch-end sweep: reconcile every concept the branch's diff touches, run okfit validate and fix what it reports, check CLAUDE.md pointer coverage, and report what changed. Use at the end of a branch of work that touched the okf/ bundle or its context files, before handing off to a human for commit and changeset. Trigger phrases -- "finalize the bundle", "wrap up the okf changes", "reconcile the docs before merging", "sweep the bundle".

OKF v0.2 condensed reference: the conformance floor, the frontmatter field table by family, reserved files, the actor convention, cross-linking rules, and the v0.1-to-v0.2 changes. Use when authoring or reviewing an OKF concept file, deciding which frontmatter fields to set, or checking whether a bundle is conformant. Trigger phrases -- "what fields does OKF support", "is verified required", "what changed from 0.1 to 0.2", "actor convention", "frontmatter reference table", "is this concept conformant".