chore: General and package specific Instructions for AI Code Agents

[RubenSibon]

AI Code Agent Instructions (general and per package)

What

Adds AGENTS.md instruction files across the repository to guide AI code agents when working in the Amsterdam Design System codebase. Also updates human documentation to cover AI-assisted contributions.

New files:

• Root AGENTS.md — cross-cutting priorities, "never do" rules, and general agent behaviour
• packages/css/AGENTS.md — CSS package conventions (BEM, no mixins prematurely, SCSS patterns)
• packages/react/AGENTS.md — React package conventions (props, tests, accessibility)
• packages-proprietary/tokens/AGENTS.md — design token conventions (DTCG format, file structure)
• storybook/AGENTS.md — Storybook conventions (docs, stories, visual regression tests)

Updated files:

• documentation/code-reviews.md — new "AI-assisted contributions" section; guidance on reviewing AI-authored PRs and handling AI-generated review comments; documents the /chromatic test comment trigger
• documentation/definition-of-done.md — added requirement to update AGENTS.md files when conventions, file locations, or tooling change
• .prettierignore / eslint.config.mjs — exclude AGENTS.md files from linting and formatting to avoid confusing prettier-ignore comments in markdown

Why

GitHub Copilot is increasingly used for contributions, code reviews, and PR authoring. Without explicit instructions, AI agents tend to introduce patterns that don't match project conventions — overly broad refactors, incorrect license headers, accessibility regressions, or wrong tooling commands. These instruction files codify existing conventions in a format agents can follow, reducing review friction and improving the quality of AI-assisted contributions.

How

• Each AGENTS.md file is structured as a thin, agent-specific layer that references existing documentation rather than duplicating it.
• The root file covers cross-cutting concerns (priorities, licensing, commit conventions, repo structure), while per-package files cover package-specific conventions.
• AGENTS.md files are excluded from Prettier and ESLint to keep their formatting stable and avoid tool conflicts.
• The code-reviews documentation was extended (not rewritten) to integrate AI-specific guidance naturally into the existing review workflow.

Checklist

• Add or update documentation
• Start the PR title with a Conventional Commit prefix, as explained here.

To do

• Benchmark these instructions (follow Máni's benchmarking methodology)

Additional notes

• No runtime code changes — this PR is documentation-only, so unit tests, stories, and exports are not applicable.
• The .prettierignore and eslint.config.mjs changes are intentional: AGENTS.md files use specific formatting (inline HTML comments for licenses, structured markdown) that conflicts with auto-formatting rules.
• The AGENTS.md format is the standard convention recognised by GitHub Copilot for repository-level custom instructions.

[magucc]

Other remarks:

• These files will rot if there's no process. Consider adding a note in CONTRIBUTING.md or the definition of done: When changing conventions, update the relevant AGENTS.md.
• The Storybook AGENTS.md references IS_CHROMATIC env var but doesn't explain what it controls beyond "pseudo-states" Agents might misuse it.
• React AGENTS.md code example has /* eslint-disable */ comments that agents might copy literally into generated code. Consider using plain comments instead.
• Root file is 225 lines. It's thorough but on the edge of what agents will reliably process in full. The signal-to-noise goal from the PR description could be tested by seeing if any sections can be replaced with a link to existing docs.

[magucc]

Should be 2.

[magucc]

You might want to add AGENTS.ms to packages-proprietary/tokens as well

[RubenSibon]

Yeah, I was aware that it was missing. I'll see to it.

[magucc]

2 occurrences is a low bar. The classic rule of three exists for a reason. Agents following this literally will create premature abstractions. Consider 3+ or "repeated across multiple components".

[RubenSibon]

Agreed, but we do have this guideline in our docs on Mixins:

We use Sass mixins to extract common patterns, especially if they need more than 1 declaration.

So maybe we should adjust that too. What do you think, @VincentSmedinga?

[VincentSmedinga]

Well, that ‘1 declaration’ refers to the content of the mixin, e.g.

@mixin hyphenation {
  hyphenate-limit-chars: …;
  hyphens: auto;
  overflow-wrap: break-word;
}

has 3 declarations that work together. So that’s something different.

We follow the rule of three. Don’t abstract too early; we might not have the full picture. So yes, at least 3 occurrences.

[RubenSibon]

Shall I add the rule of 3 to our docs for humans? I don't think it exists somewhere. I don't think it's a good idea to add rules to the agent instructions explicitly that do not exist in our docs.

[RubenSibon]

Other remarks:

* These files will rot if there's no process. Consider adding a note in CONTRIBUTING.md or the definition of done: `When changing conventions, update the relevant AGENTS.md.`

* The Storybook AGENTS.md references IS_CHROMATIC env var but doesn't explain what it controls beyond "pseudo-states" Agents might misuse it.

* React AGENTS.md code example has /* eslint-disable */ comments that agents might copy literally into generated code. Consider using plain comments instead.

* Root file is 225 lines. It's thorough but on the edge of what agents will reliably process in full. The signal-to-noise goal from the PR description could be tested by seeing if any sections can be replaced with a link to existing docs.

Thanks for the thourough review!

One point 1: it's a very good point. Updating our documentation regarding AI agents was on my to-do list, but I didn't get to it yet.

On point 3 about eslint-disable. Maybe I should actually prevent the AGENT.md files from being linted.

[Copilot]

Pull request overview

Adds repository-wide and package-specific AGENTS.md instruction files to guide AI code agents, plus documentation and tooling updates to accommodate AI-assisted contributions.

Changes:

• Introduces new AGENTS.md files at the repo root and in key packages (CSS, React, tokens, Storybook).
• Updates contributor documentation to cover AI-assisted PRs and review comment handling (including /chromatic test).
• Excludes AGENTS.md files from ESLint and Prettier to keep their formatting stable.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
AGENTS.md	Adds cross-cutting agent rules, repo structure, licensing, and command guidance.
packages/css/AGENTS.md	Defines CSS-layer conventions for agents (BEM-ish naming, token usage, mixins, etc.).
packages/react/AGENTS.md	Defines React-layer conventions for agents (imports, forwardRef, testing, a11y rules).
packages-proprietary/tokens/AGENTS.md	Defines token-format and workflow rules for agents (DTCG, structure, build info).
storybook/AGENTS.md	Defines Storybook story/docs/testing conventions for agents (Chromatic, play tests, tags).
documentation/code-reviews.md	Adds an “AI-assisted contributions” section and generalizes AI comment handling.
documentation/definition-of-done.md	Adds requirement to update relevant AGENTS.md when conventions/tooling change.
eslint.config.mjs	Ignores **/AGENTS.md in ESLint.
.prettierignore	Ignores AGENTS.md in Prettier.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The blanket rule “Never use npm or yarn” conflicts with existing workspace scripts that invoke npm internally (e.g. packages-proprietary/tokens/package.json build:watch runs npm run build). Consider rephrasing this to “Never run npm/yarn directly for install/run; use pnpm commands from the repo root (some scripts may call npm internally)” or update the underlying scripts to use pnpm so the instruction remains accurate.

Suggested change

	- **Never use npm or yarn** — always use `pnpm` (see commands in [README.md](README.md)).
	- **Never run npm or yarn directly for install or run tasks** — use `pnpm` commands from the repo root (some workspace scripts may call `npm` internally; follow the documented `pnpm` entrypoints in [README.md](README.md)).

[Copilot]

“Never use default exports” is inconsistent with the current codebase and required tooling patterns (e.g. Storybook CSF uses export default meta, and there are existing default exports in packages/react/src and storybook/). This instruction will lead agents to make changes that don’t match established conventions. Suggest scoping it (e.g. “avoid new default exports in library source unless required by the framework”) or removing it to align with existing patterns.

Suggested change

	- **Never use default exports** — use named exports only.
	- **Avoid introducing new default exports in library source unless the framework or existing package convention requires them** — prefer named exports where practical, but follow established patterns such as Storybook CSF.