Imported from timothyjordan/a14y (AGENTS.md). Install upstream with npx skills add timothyjordan/a14y. Copyright stays with the author.

AGENTS.md — a14y (Agent Readability)

Machine-readable invariants for coding agents working in this repo (Claude Code, Codex, Cursor, OpenCode, etc.). For the longer human-readable version, see CONTRIBUTING.md.

Hard invariants

1. Published scorecards are an immutable contract. Once a scorecard version ships, it never changes — every consumer pinned to that version must keep getting the same score forever. This means:
   • Never modify packages/core/src/scorecard/v0_*.ts.
   • Never mutate an existing '1.x.x' entry under a check's implementations map. To change behavior, add a new entry ('1.1.0') and pin it in draft.ts.
   • The contribution surface is packages/core/src/scorecard/draft.ts plus new implementations entries — never the past.
2. Never hand-edit a README.md. All user-facing READMEs are generated from docs/templates/ and docs/fragments/. Edit the sources and run npm run docs.
3. Never commit directly to main. Branch as feature/..., fix/..., refactor/..., docs/..., or chore/....
4. Use Conventional Commits. The release pipeline reads commit prefixes to decide version bumps. chore:, docs:, ci:, test: do not trigger a release.
5. Frontmatter id in src/content/checks/<id>.md must equal the filename and the pin in draft.ts. The coverage gate fails the build otherwise.
6. If your change touches draft.ts, the refresh-draft-diff workflow reconciles draft-changes.json after you merge. That JSON holds the attribution data the docs site reads to render each diff entry on /scorecards/draft/ and /scorecards/draft/changes/. The workflow runs on push to main (i.e. after your PR merges), not on the PR branch, because an auto-commit-back to the contributor branch is structurally broken for fork PRs (read-only GITHUB_TOKEN). It regenerates the JSON against the live net diff and opens a separate follow-up PR (chore/refresh-draft-diff) that attributes new entries to the PR that triggered it; a maintainer reviews and merges that follow-up like any other change (there is no auto-merge). You do not need to run anything on your own PR. To preview the would-be JSON before merging, run node scripts/refresh-draft-diff.mjs --local and eyeball that it reflects the net diff. If the post-merge run fails for infra reasons, trigger a catch-up from Actions → Refresh draft diff → Run workflow.
7. Non-trivial scorecard changes ship docs-first. Split into two PRs: a spec PR (the check's .md page + the draft.ts pin, plus a stub '1.1.0' implementation copying the prior version when updating an existing check, so the pin resolves and tests stay green) lands and merges first; an implementation PR then replaces the stub with the real '1.1.0' handler. Rationale: prevents the spec PR and impl PR from pulling against each other while reviewers negotiate the contract. See CONTRIBUTING → Docs-first for scorecard changes.

Canonical commands

npm install
npm run build
npm test                           # every workspace + readme builder
npm test --workspace @a14y/core    # registry + check engine
npm test --workspace @a14y/docs    # mirror integration + coverage gate
npm run docs                       # regenerate READMEs from docs/

Use the space form (--workspace @a14y/core), not the = form, to match the rest of the repo.

Where things live

Adding a new check (recipe)

For non-trivial additions, split into spec + impl PRs (see invariant #7). The steps below are the impl PR.

1. Add packages/core/src/checks/{site,page}/<file>.ts with an implementations map keyed by '1.0.0'. The file name is camelCase; the check ids inside it are kebab-case and scoped (e.g. llms-txt.exists).
2. Import it in packages/core/src/scorecard/_imports.ts.
3. Pin it in packages/core/src/scorecard/draft.ts.
4. Add packages/apps/docs/src/content/checks/<id>.md with required frontmatter (id, title, group, scope, why).
5. Run npm test --workspace @a14y/core and npm test --workspace @a14y/docs.

Updating an existing check (recipe)

For non-trivial bumps, split into spec + impl PRs (see invariant #7). The steps below are the impl PR — the spec PR already shipped the .md page, the draft.ts pin bump, and a stub '1.1.0' copy of the prior handler; here you replace that stub with real logic.

1. In packages/core/src/checks/{site,page}/<file>.ts, add a new '1.1.0' (or higher) entry to implementations. Leave the existing '1.0.0' entry untouched — frozen scorecards reference it by version.
2. Bump the pin in packages/core/src/scorecard/draft.ts.
3. Update packages/apps/docs/src/content/checks/<id>.md if behavior changed.
4. Run the same test commands as above.

Definition of done

Before opening a PR, confirm:

• Affected workspace tests pass.
• No v0_*.ts file was modified.
• If a check changed: draft.ts pin, content file, and _imports.ts are all consistent.
• If .astro or global CSS changed: class-name audit diff is empty or intentional (see CONTRIBUTING → "Visual / design parity").
• If anything under docs/templates/ or docs/fragments/ changed: npm run docs was run and the regenerated READMEs are committed.
• If draft.ts changed: you previewed the reconciled packages/core/src/scorecard/draft-changes.json with node scripts/refresh-draft-diff.mjs --local and it reflects the net diff. The refresh-draft-diff workflow opens the attributed follow-up PR after this PR merges to main. See CONTRIBUTING → Diff refresh workflow.
• If non-trivial rubric change: docs-first split was used — the spec PR landed before this impl PR (see invariant #7).
• Commits follow Conventional Commits.

Further reading

• CONTRIBUTING.md — full contribution guide.
• RELEASING.md — release flow, Conventional Commits scopes, release-please mechanics.
• TESTING.md — manual smoke-test recipes for the CLI, Chrome extension, and docs site.