tmu
3d0fe18d6a
A project-local Agent Skill (.agents/skills/verify/SKILL.md) wraps the correctness ladder as an on-demand procedure: run npm run test, recover by fixing the root cause in the types (not by suppressing them), optionally run whole-project npm run check, and commit through the hook. Exposed as /skill:verify for pi, and read by any Agent-Skills harness from .agents/skills/. It is a procedure, not a doc fork: it links AGENTS.md / CONTRIBUTING.md / package.json instead of restating the rules, so there is no drift. Agents must not start `npm run watch` -- it never returns and blocks the turn. The skill's ladder drops watch and calls it out under "What not to run here"; AGENTS.md gains a matching guardrail.
47 lines
4.2 KiB
Markdown
47 lines
4.2 KiB
Markdown
# AGENTS.md
|
|
|
|
Machine entry point for AI coding agents working in this repo. The authoritative
|
|
guidance for humans lives in [CONTRIBUTING.md](./CONTRIBUTING.md) and
|
|
[README.md](./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](./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.
|
|
- **Optional final gate:** `npm run check` (the fast, offline, whole-project correctness ladder: `tsc → oxlint → oxfmt → cspell`). Safe to run whenever you want a project-wide confirmation; pre-commit already covers staged files.
|
|
- **`npm run maintain` is NOT part of the feature loop.** `maintain:knip` (dead-code/deps) and `maintain:outdated` (registry) are advisory maintenance scans. Run them only on an explicit maintenance / update-deps branch; CI surfaces them via a non-blocking job, never as a gate.
|
|
|
|
```sh
|
|
npm run test # mandatory gate
|
|
npm run check # optional project-wide confirmation
|
|
```
|
|
|
|
The bot's definition of done: `npm run test` green, commit normally after.
|
|
|
|
- A project skill wraps this loop as an on-demand procedure: `/skill:verify` → [`.agents/skills/verify/SKILL.md`](./.agents/skills/verify/SKILL.md).
|
|
|
|
## 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](./CONTRIBUTING.md#rules-the-tools-dont-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.
|
|
|
|
The same applies to the checks themselves: **never `git commit --no-verify`** (or otherwise skip a pre-commit / pre-push hook). The checks are fast and offline, so a redundant run is fine — bypassing a hook to get green is the identical anti-pattern. If a commit already skipped a hook, redo it through one: `git reset --soft HEAD~1 && git commit -C <skipped-sha>`.
|
|
|
|
Never start a long-lived / blocking process such as `npm run watch`. It runs until a human stops it with Ctrl-C, so in an agent turn it hangs forever and floods the context with continuous output. Reach for a one-shot command instead — `npm run test` (or `npm run check`) — to get feedback.
|
|
|
|
## Read these
|
|
|
|
- [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) — the constraints the linters don't catch; CI/review bounce these. **The most important section.**
|
|
- [CONTRIBUTING.md § Script prefix convention](./CONTRIBUTING.md#script-prefix-convention) — adding an `npm run` script? reuse an existing prefix or it doesn't belong.
|
|
- [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages) — gitmoji + imperative + 50/72.
|
|
- [CONTRIBUTING.md § Feedback tiers](./CONTRIBUTING.md#feedback-tiers) — what runs when (`watch` / pre-commit / pre-push / `check` / `fix` / CI).
|
|
- [README.md § Tooling decisions](./README.md#tooling-decisions) — the rationale behind each tool choice; read before changing tooling.
|
|
- [package.json `#scripts`](./package.json) — the source of truth for every command (the `LEFTHOOK_FILES` convention scopes them to staged files vs. the whole project).
|