Task guides
Four guides under docs/agents/ carry the per-task detail behind AGENTS.md. An agent loads the guide for the work at hand.
The root AGENTS.md names the rules every task shares. The guides hold the detail that only some tasks need, so each task reads the root file plus the guide for its kind of work. Scoped AGENTS.md files under .shots/, crates/herogpui-components/, and gallery/ add local rules and link back to the guide that owns their topic.
The four guides
| Guide | File | When to load | Owns |
|---|---|---|---|
| Workflow and architecture | docs/agents/workflow.md | Read this guide for every implementation task. | Repository map, source hierarchy, scope discipline, project invariants, and the change-to-verification matrix below. Start here for every implementation task. |
| Component implementation | docs/agents/components.md | Read this guide before changing crates/herogpui-components. | Component model and controlled state, state lifetime, events and focus, overlays, layout and animation, virtual collections, and the headless behavior-test harness. |
| Upstream contract and audits | docs/agents/parity.md | Read this guide when changing a public builder, documented behavior, styling, tokens, motion, component anatomy, demos, reference metadata, or an audit. | Pinned upstream contract, the audit suite and which audit owns which claim, API ownership and omission rules, and audit-reader integrity. |
| Gallery and visual verification | docs/agents/gallery.md | Read this guide before changing gallery, capturing screenshots, driving a component, or running route smoke. | Rebuild and smoke scripts, off-screen and foreground input drivers, deep links and environment controls, screenshot integrity, and behavioral proof. |
Verification matches the change
The workflow guide maps each change type to the command to iterate with and the gate required before broad handoff:
| Change | Iterate with | Before broad handoff |
|---|---|---|
| Rust logic in one component | Focused cargo test -p herogpui-components --test <name> | Component suite, format, lint, relevant audits |
| Public builder/API | Focused tests plus api_audit.py, extra_audit.py, write_only.py | All audits and package checks when release-facing |
| Tokens or component metrics | token_audit.py, design_audit.py, focused screenshots | Format, lint, affected behavior tests, visual check |
| Interaction, focus, overlay, or state | Focused behavior binary | Gallery drive for the real path, then component suite |
| Gallery demo or reference metadata | Gallery tests and relevant demo/reference audit | Rebuild, route smoke, focused capture |
| Audit parser or mapping | Run the changed audit against known-positive and known-negative input | Run every *audit.py as CI does |
| Documentation only | Check links, commands, and current file names | No Rust build unless the documentation changes code generation |
Normal tests run once. Do not claim the full gate passed after a focused test, and finish with evidence: report which checks ran, which did not, and why. A screenshot proves pixels, a headless behavior test proves the exercised event path, and an audit proves only its mapped surface.
llms.txt carries the component API reference and supplements these guides. How the layers fit together is described on the repository guide page.