# AGENTS.md template

The file the agent reads first. Copy to your repo root, replace the brackets, delete what you don't enforce. A rule you won't enforce is worse than no rule; agents learn from what's tolerated. Template from tokenstoagents.ai/kit.

---

# AGENTS.md

Canonical agent instructions for this repository. Read this first. Detailed procedures live in [skills folder / linked docs] and load on demand.

## What this is

[Two sentences: what this project is and who it serves. Write it so a fresh agent could not mistake this repo for a different kind of project.]

Source-of-truth documents:
- [path]: design tokens (DTCG). The only place visual values live.
- [path]: component contracts. Props, variants, and applied tokens, as data.
- [path]: specs for in-flight work.
- [path]: the design guidance that explains the reasoning.

## Standing rules, always apply

- Every visual value comes from a token. Never hardcode a value a token should own.
- Build from semantic tokens. Primitives never appear in application code.
- Semantic roles are law: [your danger token] is for destructive actions and errors only. When unsure which token applies, read its $description before guessing.
- Components are used through their contracts. If a prop or variant isn't in the contract, it doesn't exist; propose a contract change instead of improvising.
- New behavior starts from a spec in [path]. If no spec exists, write one first using the EARS patterns in [path].
- [Your equivalent of a house style rule. Ours: never use em dashes or en dashes, anywhere.]

## Where detail lives

Keep this file lean; load detail on demand.
- [skill or doc]: how we author and compile tokens.
- [skill or doc]: how we write component contracts.
- [skill or doc]: how we write and verify specs.

## Drift alarms, self-correct when you catch these

[The mistakes agents (and humans) actually make here, stated as patterns to catch. Examples to adapt:]
- A hex value or pixel number in application code. Route it through a token.
- A primitive token referenced outside the token files. Use the semantic tier.
- [Danger color] used decoratively. It means danger, nowhere else.
- A new component prop invented mid-task. Contracts change by proposal, not improvisation.

## Quality floor, no exceptions

[The non-negotiables you actually hold. Examples:] Semantic HTML. Visible keyboard focus. AA contrast. Responsive to [breakpoint]. Honored without being asked.

---

## Notes on using this template (delete after adapting)

Keep it to one page. The always-on file is a context budget; spend it on rules that prevent expensive mistakes, and push everything else into on-demand detail. Update it when a rule changes, in the same commit; a stale AGENTS.md teaches agents that the file lies. And test it: open a fresh agent session, ask "what are the rules here?", and check the answer against this file. That round trip is your delivery layer working, or not.