austere-axi
AGENTS.md8 starsChanged 4 days agoMITView on GitHub
austere-axi is a CLI, a local review server, and a browser runtime for agent review artifacts written in OpenUI Lang. This file keeps only the rules that apply to almost every change.
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 33,315 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 repository5 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-componentSkill
- review-changeSkill
- austere-setupSkill
- austereSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 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.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
Adding or changing a component: follow .agents/skills/add-component/SKILL.md.
- Very specific: line 13
Reviewing a change before committing: follow .agents/skills/review-change/SKILL.md.
- Very specific: line 46
Only dist, skills, README.md and LICENSE are published (package.json files).
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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
AGENTS.md
austere-axi is a CLI, a local review server, and a browser runtime for agent review artifacts written in OpenUI Lang. This file keeps only the rules that apply to almost every change.
Where things are owned
- User-facing contract: the guides in
docs/(docs/README.mdlists them).README.mdis the product page for people who do not read flags: what it is, how to use it, how to start. Keep it plain and put reference detail indocs/. - What agents are told while using the tool: CLI output:
--help(src/cli/main.ts), andspec(generated fromsrc/runtime/prompt.ts, the component files andsrc/runtime/stock.ts). - Shipped skills:
skills/austere/SKILL.mdstays a stub that points at the CLI, so don't copy CLI guidance into it. The one exception is its line that the agent must not open, screenshot or inspect the page unless asked: it has to override a harness's "verify UI visually" rule before the agent reads the CLI.skills/austere-setup/SKILL.mdwalks an agent through setup; keep its commands in step with the CLI. - MCP server and Claude Code plugin:
austere-axi mcp(src/cli/mcp.ts) runs the CLI as a child process for each tool call and returns its output; keep logic in the CLI commands, not there. A new tool argument maps to an existing CLI flag..claude-plugin/holds the marketplace and plugin manifests; it lives in git, not in the npm package. - Review loop v2 (projects, inbox, attach, history, dashboard, wiki):
docs/review-loop-v2.mdis the contract for RLM-332 to RLM-367: its decisions, data model, CLI changes and security rules. Change the note first when a build issue departs from it. - Adding or changing a component: follow
.agents/skills/add-component/SKILL.md. - Reviewing a change before committing: follow
.agents/skills/review-change/SKILL.md. It runs the checks and the agents in.agents/agents/(change-reviewer, visual-qa, cold-start-author).
Commands
npm run build # dist/: runtime, packs, pack-kit, spec.json, prompt.md, catalog.json, chrome, cli.mjs
npm test # rebuilds spec first; unit, server loop, and library guards
npm run typecheck # tsc over every source, script and test (strict)
npm run test:browser # real review loop in headless Chrome (one hover check also in Firefox): render checks + every part annotatable
npm run signatures # record new component signatures (refuses breaking changes)
npm run gallery # .dev/gallery.html with every custom component's example
npm run shot -- <page> [--width 390] [--full] [--parts] # needs Chrome or CHROME_PATH
npm run site # _site/: landing page + example gallery for GitHub Pages; needs Chrome or CHROME_PATH
npm run bench # austere-axi vs lavish-axi benchmark (model keys from env); see docs/benchmark.md
npm run demo # re-record docs/demo.{gif,mp4,webm} (after build; needs Chrome and ffmpeg)
npm run social # re-render docs/social-preview.png, 1200x630 (after build; needs Chrome)Rules
- Released component props are positional and append-only (
test/fixtures/signatures.json). - Third-party packs build against
src/runtime/pack-api.ts(whataustere-axi/packexports) and the catalog format insrc/shared/catalog.ts. Change either additively; a breaking change bumpsPACK_APIorCATALOG_FORMAT. - austere-cloud builds against
austere-axi/sync(src/shared/sync.ts, typed bytypes/sync.d.ts). Change it additively and bumpSYNC_VERSION, by the rules indocs/hosted-share-links.md("Versioning and compatibility"). Keep it free of Node APIs; the chrome and the Worker run it too. - The component reference has a token budget (
test/library.test.ts). Raise it only deliberately. - The served artifact must equal the file on disk, except for the runtime
<script>tag. - The server binds to loopback, plus the Tailscale IP when Tailscale is up, and never to
0.0.0.0./api/*answers loopback callers only, and only with the owner key (x-austere-key), except/api/health.- Loopback is not the owner; the owner key (header) or the cookie derived from it is. Never put the key on a command line, in printed output, or in a cookie; browsers sign in with a single-use login code.
- Browser POST routes reject a foreign
Origin. - Artifact files are served from the artifact's own directory only, with no dotfiles.
- The frame's subresources send no cookie (opaque origin), so the frame's URL carries a per-viewer token,
/s/:id/a/<token>/<file>(assetTokeninsrc/cli/server.ts). It opens only what that route already serves; keepallow-same-originout of the sandbox.exportreads sibling images through the sameresolveSiblingrules (src/cli/assets.ts).
- Tests that start the server, or read packs or the hub, set
AUSTERE_AXI_STATE_DIRand use an ephemeral port. - Nothing an installed pack ships runs in the CLI or the server; its code runs only in the sandboxed artifact frame. (
components builddoes load the pack being built, in Node, to read its components.) - Only
dist,skills,README.mdandLICENSEare published (package.jsonfiles)..agents/,.dev/,bench/,scripts/andtest/are maintainer-only.docs/holds the user guides, read on GitHub and not shipped in the npm package. - The website lives in
site/(hand-written) andexamples/(gallery source), built to_site/byscripts/site.tsand deployed by.github/workflows/pages.yml. Keep links relative (the site is served under/austere-axi/) and keepsite/out ofpackage.jsonfiles. - The playground (
site/play/) runssrc/shared/check-program.ts,src/shared/feedback.tsandsrc/shared/statements.tsin the browser, and the artifact frame over the review bridge insrc/runtime/index.tsx. Keep those shared modules free of Node APIs; if a bridge message changes, changesite/play/play.tswith it. - Sources are strict TypeScript (
tsconfig.json;npm run typecheck): noany; only erasable syntax (Node runs.tsdirectly), so noenum,namespaceor parameter properties; relative imports name the.ts/.tsxfile; type-only imports useimport type.
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.

