specs/button/index.md, it gets a closed contract instead of needing to guess. The spec tells the agent which tokens to bind, which ARIA attributes to add, which interaction states to implement, and exactly which files to open. There is nothing to infer.
The agent reading order
Follow these steps every time you ask an agent to write or modify a component: Step 1 — Open the spec. Navigate tospecs/<component>/index.md. The YAML frontmatter is the machine-readable contract. The prose below it is the human explanation. Read the frontmatter first.
Step 2 — Check status.
Trust AI-Ready. Question In progress — the spec may be incomplete. Refuse Draft — the spec is not ready for code generation.
Step 3 — Read token_contract.
This is a closed list. Every token the component may use appears here. Anything outside this list is forbidden, even if it looks correct. If the value you need is not in the list, extend the token system — do not inline a value.
Step 4 — Read required_aria and interaction_states.
Both fields are fully enumerated. Implement every ARIA attribute in required_aria. Implement every state in interaction_states. Skipping either is a contract violation.
Step 5 — Open the code.
sources.code.path in the frontmatter points at the component’s TSX file. The code is an implementation of the spec, not the source of truth. If code and spec conflict, the spec wins.
What agents must NOT do
- Bind a hex value directly (e.g.
color: '#2563eb'). Use the token. - Invent a token that does not exist in
tokens.json(e.g.color.brand.primary). Check the contract first. - Skip an interaction state because it seemed obvious or low-priority. Every state in
interaction_statesmust be implemented. - Drop an ARIA attribute because the visual works without it. Accessibility is part of the contract.
- Change the spec to match code you have already written. The spec is the contract; code follows from it.
Using the agentic-spec CLI in your agent workflow
Run the validator before making any edits to a component. A failing spec is telling you the component is not in the state it claims to be in — do not write code against it.--json for programmatic output in CI pipelines or agent toolchains that need structured data:
init:
specs/<name>/index.md (status: Draft) and specs/<name>/tokens.json with stubs. Fill in semantic_parts and interaction_states before writing any code.
Supported tools
Any agent that can read files from the repository works with this system. Tested workflows include:
The system does not require a special plugin or integration. The contract is in plain markdown and YAML files. Any agent that can read a file can use it.