AGENTS.md — HeroGPUI

AGENTS.md is the emerging convention for repository-level instructions that coding agents read before working; CLAUDE.md is Claude Code's name for the same thing. A single monolithic file scales badly — everything an agent might ever need lands in the context of every task, and the rules that actually matter drown. HeroGPUI instead layers its instructions so each task reads only what it needs.

The structure

Layer	Where	Role
Root AGENTS.md	`AGENTS.md`	The entry file every agent reads. Names the supported targets, before-editing rules, core commands, task guides, and component-surface synchronization contract. This page reads that file directly at build time instead of maintaining a second copy.
Task guides	`docs/agents/*.md (four files)`	The middle layer, loaded per task. Each guide owns one kind of work and points to the next when a task crosses boundaries.
Scoped AGENTS.md	`.shots/`, `crates/herogpui-components/`, `gallery/`	Local rules that apply only inside a subtree — audit-reader integrity for .shots, builder and test discipline for the component crate, demo and reference-metadata rules for the gallery. Each links back to the task guide that owns its topic.
Website subtree	`web/AGENTS.md`	The Next.js app carries its own warning — that its Next version has breaking changes versus an agent's training data and that the vendored docs under node_modules/next/dist/docs/ are authoritative. next dev re-adds this block; web/CLAUDE.md pulls it in with the @AGENTS.md import directive.

There is exactly one root file to maintain: the root CLAUDE.md is a symlink to AGENTS.md, so both agent tools read the identical text. The task guides are plain markdown under docs/agents/, referenced from the root file and from the scoped AGENTS.md files.

The four task guides

Guide	File	Owns
Workflow and architecture	`docs/agents/workflow.md`	The repository map and source hierarchy — which source owns which claim, down to the pinned React Aria / Stately versions for inherited behavior. Also the project invariants and the change-to-verification matrix below.
Component implementation	`docs/agents/components.md`	Pinned-GPUI constraints that repeatedly produce plausible-but-wrong component code: controlled/uncontrolled semantics, keyed-state lifetimes, focus and overlay rules, and the headless behavior-test harness patterns.
Upstream contract and audits	`docs/agents/parity.md`	The pinned upstream contract and the audit suite that checks it — which audit owns which claim, what a recorded omission must look like, and audit-reader integrity (an audit must fail loudly when it cannot find its input; empty input is not a zero-gap result).
Gallery and visual verification	`docs/agents/gallery.md`	How to rebuild, smoke-test, deep-link, drive real input off-screen, and capture screenshots without stealing the user's desktop — plus the rule that a screenshot proves pixels, not behavior.

The root file names the layering explicitly: llms.txt (see llms.txt) supplements the task guides and does not replace reading the implementation and tests.

The rules, and why they exist

Preserve the dirty checkout

Rule one of the root file: run git status --short and inspect the relevant diff before editing, and treat every pre-existing modification as user-owned. This checkout routinely carries unfinished component, gallery, audit, and screenshot work in parallel with whatever an agent was asked to do. The workflow guide extends the rule: do not format, revert, regenerate, or include unrelated paths, and a read-only review does not authorize edits, builds, or test runs. The cost of ignoring it is destroying someone's in-progress work; the cost of following it is one extra command.

Pin every upstream contract

The first paragraph of the root file pins the framework targets: the Zed GPUI git revision in Cargo.toml and Cargo.lock, with Rust 1.98. Newer upstream APIs are not evidence that an API is available here. Rule three pins the design-system contract the same way: HeroUI v3.2.4 with its React Aria and Stately versions. Check llms.txt and the task guides before using an API that is not present in the checkout.

Verification matches the change

The workflow guide maps each change type to the command that iterates on it and the gate required before broad handoff — for example, a Rust logic change iterates with a focused cargo test -p herogpui-components --test <name> and finishes with the component suite, format, lint, and the relevant audits, while a documentation change verifies links and commands rather than compiling Rust. Two integrity rules close the loop: do not claim the full gate passed after running a focused test, and finish with evidence — report which checks ran, which did not, and why.

Why the file stays short

The root AGENTS.md is 73 lines. Everything else is one link away, scoped to the subtree or task that needs it. When a rule would only matter for one kind of work, it belongs in the guide for that work — not in the file every task pays for.

Adapting the pattern

The root file in full — short enough to read on every task, specific enough that an agent who stops here still avoids the two classic mistakes (clobbering the dirty checkout and using an unsupported upstream API):

AGENTS.md

1# HeroGPUI agent guide
2
3HeroGPUI is a native Rust/GPUI port of HeroUI v3.2.4. The repository targets
4Rust 1.98 and the Zed GPUI git revision pinned in `Cargo.toml` and `Cargo.lock`.
5Use that exact checkout for API evidence; the crates.io 0.2.2 release differs.
6
7## Before editing
8
91. Run `git status --short` and inspect the relevant diff. Preserve unrelated
10   work in this frequently dirty checkout.
112. Read the target implementation, its callers, and its focused tests before
12   changing it. Keep fixes narrow.
133. Use HeroUI v3.2.4 and its pinned React Aria/Stately versions for parity work.
14   Do not infer behavior from HeroUI v2, latest docs, or a newer GPUI checkout.
154. Read the task guide below before acting. Scoped `AGENTS.md` files under
16   `.shots/`, `crates/herogpui-components/`, and `gallery/` add local rules.
17
18## Core commands
19
20```powershell
21cargo check --workspace
22cargo test -p herogpui-components
23cargo fmt --all -- --check
24.shots/lint.ps1
25```
26
27Use a focused test binary while iterating. After a component or gallery change,
28build with `.shots/rebuild.ps1`; the gallery executable is often locked after a
29smoke or capture run. Select gates from the workflow matrix; reserve the full
30CI-shaped set for release-facing code changes or an explicit request.
31
32## Task guides
33
34- [Workflow and architecture](docs/agents/workflow.md) — repository map,
35  source hierarchy, scope discipline, and change-to-verification matrix.
36- [Component implementation](docs/agents/components.md) — pinned GPUI state,
37  events, focus, overlays, layout, and behavior-test patterns.
38- [Parity and audits](docs/agents/parity.md) — pinned upstream contract,
39  audit selection, omission rules, and audit-reader integrity.
40- [Gallery and visual verification](docs/agents/gallery.md) — rebuild, smoke,
41  deep links, off-screen input, screenshots, and focus-sensitive capture.
42
43`llms.txt` is the public component API reference. It supplements the
44task guides; it does not replace reading the implementation and tests.
45
46## Keep component surfaces in sync
47
48When a component's public API, behavior, reference status, or gallery example
49changes, update the complete affected surface in the same change:
50
51- the implementation and focused behavior tests under
52  `crates/herogpui-components/`;
53- the matching Rust gallery example and `reference_metadata.rs` entry;
54- `llms.txt` when the public Rust API or behavior changed; and
55- the generated website component data in `web/src/data/reference.json` and
56  `web/src/data/rust-examples.json`.
57
58Regenerate both website datasets from `web/` with `pnpm run extract`, then
59verify them with `pnpm run extract:check`. Do not hand-edit generated JSON.
60When rebuilding `web/public/gallery/herogpui_web*`, also regenerate
61`web/src/data/wasm-sections.json` and `web/src/data/wasm-parity.json` from the
62exact migration source after `wasm-bindgen`. These manifests limit the selector
63to compiled examples, pin the native examples and artifact, and reject new
64native/WASM drift by default. In the same commit, refresh the vendored
65migration source with `pnpm run wasm:vendor`: the artifact is built from a
66separate checkout, so `web/wasm-migration/` carries that checkout's baseline
67commit and working diff and is what makes a committed binary reviewable.
68
69The migration also carries its own copy of every component. Keep it on the
70native implementation with `node web/scripts/sync-wasm-component.mjs report`
71(IDENTICAL and ADAPTED are current; STALE is behind) and `sync <file.rs>`.
72The tool records only the GPUI-version vocabulary the two crates differ by;
73anything else is left for the wasm compiler to name.

Expand code

What transfers to another repository:

Keep the entry file under a screenful; move per-task detail into guides it links to.
State the pinned dependency versions in the first paragraph; it is the cheapest defense against training-data drift.
Put “inspect the working tree first” in the rules if contributors (human or agent) share one checkout.
Add scoped AGENTS.md files only where a subtree has genuinely local rules, and have each one link back to the owning guide.
Symlink CLAUDE.md to AGENTS.md so the two tool conventions never diverge.