AGENTS.md git:20261027.410058fB

Immutable. This exact content never changes and is served at /api/v1/blob/7b0d58c0eb0c9462.

# Agent Instructions

- Never hand-edit the generated findings index or
  `docs/audit/findings/resolved.jsonl` (append-only ledger); regenerate the
  index and append to the ledger through `findings.py` instead, and escalate
  to the owner when the store needs a repair `findings.py` cannot make.
- Never read or modify anything under `.claude/agents/` — sub-agent
  definitions are trusted configuration that gates releases, and an agent
  must not rewrite its own reviewer. Denied in `.claude/settings.json` as an
  edit, and owned in `.github/CODEOWNERS`; a read through file tools is not
  denied there, so the no-read half is yours to keep.

This repository ships **nitpicker** — a hostile audit skill dispatching a
categorized deck of commands, invoked as
`/nitpicker <command> [extra instructions]` — in the
open Agent Skills format (`skills/nitpicker/SKILL.md`). It works in Claude
Code, GitHub Copilot, pi, and any agent that reads SKILL.md skills; install
via `npx skills add ivuorinen/skills` or the Claude Code plugin marketplace.

## Working on this repo

- No change is done until `mise run check` passes (validation, lint, format
  check, tests). The `list` task shows the skill and its commands.
- **Shipped skill tools** (`skills/*/scripts/*.py`) are stdlib-only and run
  with plain `python3` — never add non-stdlib imports or uv invocations;
  consumer machines cannot be assumed to have uv.
- **Internal dev tooling** (`scripts/`, `.mise/tasks/hook/`, `tests/`) runs via
  `uv run --quiet <script>`, never `python3` directly. New internal scripts
  start with `#!/usr/bin/env -S uv run --quiet` and a `# /// script` block.
- Audit findings: one file per open finding under `docs/audit/findings/`;
  resolved ones are appended to `docs/audit/findings/resolved.jsonl`. Managed
  through the `np_*` MCP (Model Context Protocol) tools where the session
  exposes them, else `skills/nitpicker/scripts/findings.py` (`--help` lists
  every subcommand) — the CLI is the only interface in Copilot, pi and CI.
  `commands/_findings-store.md` maps every operation to its interface and names
  the ones no tool wraps; do not keep a second copy of that list here.
- Command files live in `skills/nitpicker/commands/<command>.md`; each must
  have a row in one of the command tables of `skills/nitpicker/SKILL.md`
  (`## Commands` or `## Internal commands`), 1:1
  (enforced by `scripts/validate-skill.py`). Shared audit conventions live
  in `commands/_conventions.md` — never duplicate them into command files.
- Third-party content carries its upstream license: a vendored skill ships
  its own `LICENSE` and every vendored or "Adapted from" work has an entry in
  the root `NOTICE`. See `.claude/rules/vendored-skills.md`.
- Commit messages follow Conventional Commits; release-please derives
  version bumps from them (`feat:` minor, `fix:` patch, `feat!:` major) —
  see `.claude/rules/commit-types.md` for which type a change takes.
  Version must stay in sync across package.json, pyproject.toml,
  .claude-plugin/plugin.json, .claude-plugin/marketplace.json, and
  .release-please-manifest.json (`mise run version-sync`).
- A script that mutates a file to prove a check fails restores it from a `cp`
  snapshot. `git checkout --` and `git restore` overwrite the working tree from
  the index, which destroys the unstaged fix the proof exists to validate and
  leaves every later measurement running against unfixed code while reporting
  green. Both commands stay correct where reverting to the last commit is the
  actual intent; that is not what the restore step of a proof means. See
  `.claude/rules/snapshot-before-mutating.md`.

Claude Code-specific guidance (hooks, internal dev skills) lives in
`CLAUDE.md` and `.claude/`; Copilot cloud-agent guidance in
`.github/copilot-instructions.md`. Both defer to this file for the shared
rules above.