Skip to content
helixui

AGENTS.md (generic agents)

AGENTS.md is a vendor-neutral convention: a single AGENTS.md at the repo root that any AI coding tool can pick up. Aider, OpenHands, Sweep, Devin, and a growing list of agents read it.

Drop the template below at your repo root.

AGENTS.md

# AGENTS.md — conventions for AI coding agents


This project uses the **helixui** design system (`@helixui/core` + friends).
helixui is AI-native: every component owns a colocated `spec.md` with a
machine-readable frontmatter, and every token comes from a single DTCG
JSON manifest.


## Setup


\`\`\`bash
pnpm install
pnpm build:tokens
pnpm dev
\`\`\`


## Run tests


\`\`\`bash
pnpm test          # all packages
pnpm typecheck     # cross-workspace
pnpm format:check  # prettier
\`\`\`


## Build


\`\`\`bash
pnpm build:all     # tokens → docs → site → llms.txt → manifests
\`\`\`


## Conventions


| Topic | Rule |
|-------|------|
| Imports | Use `@helixui/core` for components and `@helixui/icons` for icons. Never reinvent a primitive that ships in helixui. |
| Styling | Use CSS variables (`--helixui-color-*`, `--helixui-space-*`, `--helixui-radius-*`). Never hex / px / inline font names. |
| Theming | Wrap themed regions in `<HelixUIDNAProvider dna={…}>`. Use `@helixui/dna`'s `compose` to breed new themes. |
| A11y | Every interactive element keyboard-reachable. Icon-only buttons need `aria-label`. Don't remove focus rings. |
| Specs | When you modify a component, update its sibling `spec.md` in the same commit. |


## Where things live


- Components: `packages/core/src/components/<name>/`
- Specs: `packages/core/src/components/<name>/spec.md`
- Tokens: `packages/tokens/tokens/*.json` (source of truth — DTCG JSON)
- Generated CSS: `packages/tokens/dist/css/*.css` (build output — do not edit)
- AI manifests: `apps/site/dist/llms.txt`, `llms-full.txt`,
  `components-manifest.json`, `tokens-manifest.json`
- Showcases (examples to copy from): `apps/site/src/pages/showcase/`


## What NOT to do


- Don't add new dependencies without a one-line justification in the
  PR.
- Don't write CSS-in-JS — use plain CSS files with CSS variables.
- Don't introduce new hex codes; use tokens.
- Don't bypass `prepack` / `prebuild` hooks. They guarantee `dist/`
  is fresh.


## When unsure


- Read `DESIGN.md` at the repo root for a one-file summary of the
  system.
- Read `MANIFESTO.md` for the eight non-negotiable principles.
- Read `llms-full.txt` (~80 KB) for the full prose snapshot.
- Read `packages/core/src/components/<name>/spec.md` for a specific
  component's contract.
- Use `helixui.search` via the MCP server (`@helixui/mcp`) if your tool
  speaks MCP.


## Pull request conventions


- Branch from `main`.
- One logical change per PR.
- Update `spec.md` in the same commit as component code changes.
- Add a `.changeset/` file for any user-facing change to a published
  package.
- `pnpm typecheck && pnpm format:check && pnpm test` must pass.

Why this works

AGENTS.md is the lowest-common-denominator instruction file. It works with:

  • Aider (reads AGENTS.md automatically when present).
  • OpenHands / Devin / Smol Developer (read root markdown files).
  • GitHub Copilot Workspace (treats it like a project README).
  • Any tool that runs cat AGENTS.md as part of its startup probe.

If you also have .cursorrules (Cursor) or CLAUDE.md (Claude Code), the per-tool file overrides this generic one for that specific tool.

Naming clash

You might already have an AGENTS.md from another tool. helixui’s template plays nicely as a section:

AGENTS.md
## Project setup
...


## Design system (helixui)
[everything from the template above]


## Other rules
...

The order doesn’t matter; agents read the whole file.