0 Fork 0

Files

T

tmu 436b49e3be 📝 Add AGENTS.md as the agent entry point

AI coding agents read AGENTS.md automatically, not README. Make AGENTS.md
a thin pointer: the stable first-action facts plus links to CONTRIBUTING.md,
README.md, and package.json#scripts. Keep the rules prose in CONTRIBUTING.md
so humans and agents don't diverge (same anti-drift move as dropping
project-specs.md).

Clarify the agent's verification loop: npm run test is the mandatory gate;
the pre-commit hook already runs the fast offline checks (tsc, oxlint, oxfmt,
cspell) on staged files, and npm run check (knip + outdated) is repo-maintenance,
not part of the feature loop. Forbid type-system escape hatches (@ts-nocheck,
oxlint-disable, as-casts) as agent-only rules; a human may still add a
review-visible disable as a last resort, so the location convention stays in
CONTRIBUTING.md with a forward reference.

2026-09-05 16:32:15 +02:00

3.1 KiB

Raw Blame History

AGENTS.md

Machine entry point for AI coding agents working in this repo. The authoritative guidance for humans lives in CONTRIBUTING.md and README.md; this file only points at it and states the stable first-action facts. Do not restate evolving prose here — it will drift.

First action

Project: F#-style pattern matching for TypeScript/ESM. Node >=26 (pinned via .node-version), ESM-only (no CommonJS shim).
Mandatory while iterating: npm run test (runs check:tsc, then the unit suite). This is the gate you are responsible for.
On commit: write a good message (see CONTRIBUTING.md § Commit messages). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks (tsc + oxlint + oxfmt + cspell) — don't run them by hand. If the hook fails on style, npm run fix, restage, recommit.
npm run check is NOT part of the feature loop. It adds knip (dead-code/deps) and check:outdated (registry) — repo-maintenance scans. Run it only on an explicit maintenance / update-deps branch; CI runs it on the PR regardless.
```
npm run test   # the bot's definition of done; commit normally after
```

Never do

Don't silence the type system to force a green run. As an agent these are forbidden:

// @ts-nocheck, // @ts-ignore, // @ts-expect-error
// oxlint-disable / // oxlint-disable-next-line
as casts used to push an expression through (type-aware oxlint already flags unsafe assertions)

Fix the root cause with the type system instead — narrowing, generics, satisfies, conditional / mapped types, utility types (NonNullable, Exclude, …). TypeScript can express it; that's the intended tool. The oxlint-disable-location rule in CONTRIBUTING.md § Rules the tools don't enforce is a human last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one. If the types genuinely cannot express something, stop and surface the conflict (commit message / MR) rather than suppress it.

Read these

CONTRIBUTING.md § Rules the tools don't enforce — the constraints the linters don't catch; CI/review bounce these. The most important section.
CONTRIBUTING.md § Script prefix convention — adding an npm run script? reuse an existing prefix or it doesn't belong.
CONTRIBUTING.md § Commit messages — gitmoji + imperative + 50/72.
CONTRIBUTING.md § Feedback tiers — what runs when (watch / pre-commit / pre-push / check / fix / CI).
README.md § Tooling decisions — the rationale behind each tool choice; read before changing tooling.
package.json #scripts — the source of truth for every command (the LEFTHOOK_FILES convention scopes them to staged files vs. the whole project).

3.1 KiB Raw Blame History

AGENTS.md

First action

Never do

Read these

3.1 KiB

Raw Blame History