diff --git a/.agents/skills/verify/SKILL.md b/.agents/skills/verify/SKILL.md new file mode 100644 index 0000000..035d77f --- /dev/null +++ b/.agents/skills/verify/SKILL.md @@ -0,0 +1,40 @@ +--- +name: verify +description: Run tiny-pattern-ts's fast, offline correctness gates — `npm run test` (mandatory type check + unit suite), then an optional whole-project `npm run check` — and recover from failures without suppressing the type system. Use when verifying TypeScript/ESM changes before committing, when asked to check or run tests, or when a pre-commit hook fails. +--- + +# Verify (tiny-pattern-ts) + +The repo's correctness ladder. `test` is the gate you are responsible for; `check` is a +whole-project confirmation; both are fast and offline. Do not pull repo-maintenance scans +into the feature loop. + +## Procedure + +1. `npm run test` — type check + unit suite. This is the gate. +2. If it fails: read the error, then fix the **root cause in the types/code**. Do not + silence it with `@ts-nocheck` / `@ts-ignore` / `oxlint-disable` / an `as` cast (see + [AGENTS.md § Never do](../../../AGENTS.md#never-do)). Re-run. +3. Optional whole-project pass: `npm run check` (`tsc → oxlint → oxfmt → cspell`). + Pre-commit already runs these on staged files; `check` confirms the entire tree. +4. If `check` flags style or format: `npm run fix`, then repeat from step 1. +5. Commit normally — the pre-commit hook re-runs the staged-file checks. Never bypass a + hook with `git commit --no-verify`. + +## What not to run here + +- `npm run maintain` (`maintain:knip` + `maintain:outdated`) — advisory scans, not + correctness. Feature work must not gate on a stale dependency or an unused export; CI + runs it as a non-blocking job. Run it only on an explicit maintenance / update-deps branch. +- `npm run build` — emit is exercised by the CI publish job, not the dev loop. +- `npm run watch` — a persistent, never-returning process (`--watch`) meant for a + human dev loop (stop with Ctrl-C). Never run it as an agent: it blocks the turn + and streams continuous output. Use `npm run test` for feedback instead. + +## The ladder (fastest → most thorough) + +pre-commit (~1.3s, staged files) → `npm run test` (~3.5s) → `npm run check` (~3s, +whole project). + +Source of truth for every command: [`package.json#scripts`](../../../package.json). +Why each tier exists: [CONTRIBUTING.md § Feedback tiers](../../../CONTRIBUTING.md#feedback-tiers). diff --git a/AGENTS.md b/AGENTS.md index a8e64f8..0ae623b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,8 @@ first-action facts. Do not restate evolving prose here — it will drift. 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: @@ -32,6 +34,8 @@ Fix the root cause with the type system instead — narrowing, generics, `satisf 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 `. +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.**