AGENTS.md · diff

git:20260829.bc9434a to git:20260911.61ebbad

4 added, 5 removed. Audit B to B.

# Agent Instructions

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

- Run `make check` before declaring any change done (validation, lint,

format check, tests). `make list` 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/`, `scripts/hooks/`, `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`

- (new/resolve/list/show/validate/index/baseline/migrate/migrate-resolved) —

- the CLI is the only interface in Copilot, pi and CI, and the only one for

- `baseline`, `migrate` and `migrate-resolved`, which no tool wraps.

- `commands/_conventions.md` maps every operation to both.

+ 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.

Never hand-edit `INDEX.md` or `resolved.jsonl`.

- 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.

- 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` and

owned in `.github/CODEOWNERS`.

- 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 (`make 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.