skills

Nitpicker — a hostile audit toolkit for coding agents. One skill, one entry point, a full deck of audit commands:

/nitpicker <command> [extra instructions]

Assumes the code is incorrect until proven otherwise. Every command files findings with evidence and a concrete fix — no compliments, no hedging.

Works in Claude Code, GitHub Copilot, pi, and any agent that reads the open Agent Skills format.

The bundled tools (skills/nitpicker/scripts/*.py) are stdlib-only and run with plain python3 — no uv, no package installs on the consumer machine.

/nitpicker                       # exhaustive whole-repo audit (default)
/nitpicker security              # run the security scanners, consolidate findings
/nitpicker tests inline          # audit the test suite; findings in the response only
/nitpicker cr fix only critical  # implement PR review comments, scoped by your words
/nitpicker release-gate          # fail if any open finding ≥ High
/nitpicker help                  # print the command table

The first word after /nitpicker picks the command (old 1.x skill names still work as aliases); everything after it is free-text instructions for that run. The modifiers inline (nothing written to disk) and changed-files (scope to modified files) work with every command.

Full command instructions: skills/nitpicker/commands/, shared conventions in commands/_conventions.md.

Open findings live one file each; resolving one appends to an append-only ledger and deletes the file, so audits scale, parallel worktrees never conflict on a counter, and PR review is never buried under resolved-finding files:

docs/audit/findings/
  INDEX.md                      # generated summary — never hand-edited
  resolved.jsonl                # append-only ledger of fixed/invalid findings
  .gitattributes                # marks the store linguist-generated (self-written)
  <auditor>/open/<id>.md        # one open finding per file

IDs are content-hashed (security-1a2b3c4d). The store is managed by the bundled CLI:

python3 skills/nitpicker/scripts/findings.py list --status open
python3 skills/nitpicker/scripts/findings.py resolve <id> --status fixed --notes "…"
python3 skills/nitpicker/scripts/findings.py validate
python3 skills/nitpicker/scripts/findings.py index

1.x wrote one docs/audit/<skill>-findings.md per skill. Run /nitpicker x-findings-migrator (nitpicker also detects the old files itself and asks before migrating — never mid-PR without your consent), or convert manually:

python3 skills/nitpicker/scripts/findings.py migrate docs/audit/*-findings.md
git rm docs/audit/*-findings.md

Legacy IDs (N-042) stay valid. All 1.x skill invocations (/security-auditor, /test-auditor, …) map to /nitpicker <command> aliases — the ## Commands tables in skills/nitpicker/SKILL.md list every alias next to its command.

Installing the plugin registers a stdlib-only stdio MCP server (nitpicker) that exposes skill introspection (np_list_skills, np_read_skill, np_read_command, np_list_commands) and findings management (np_list_findings, np_show_finding, np_findings_index, np_validate_store, np_new_finding, np_resolve_finding). Every tool is prefixed np_ and publishes MCP annotations, so a client can tell the eight read-only tools from np_resolve_finding, the one irreversible call. See the "MCP server" section of skills/nitpicker/SKILL.md for scope and the non-interactive mutate contract.

make check     # validate skill + commands, rules, version sync, findings store, findings index, lint, format, typecheck, tests, pre-commit
make list      # list the skill and its commands
make test      # pytest suite for the tooling

Repo conventions for agents working on this codebase: AGENTS.md (shared), CLAUDE.md (Claude Code), .github/copilot-instructions.md (Copilot).

Versioning is SemVer automated with release-please from Conventional Commits (feat: minor, fix: patch, feat!: major).

• /nitpicker plan and /nitpicker execute-plan adapt the brainstorm → plan → gated-execution model from obra/superpowers — the separation of planning from implementation, with explicit human sign-off before code is written. plan hardens the plan with nitpicker's own adversarial audit lenses; execute-plan carries out its executing-plans skill — load-and-review, per-task verification, stop-when-blocked, never-build-on-main, gated finish.
• /nitpicker teach adapts the stateful teaching-workspace model from mattpocock/skills — mission-grounded learning, spaced retrieval-practice lessons, and learning records as ADRs — rewritten to this repo's command conventions with lessons under docs/lessons/.

This repo redistributes work by other authors: the vendored graphify skill under .claude/skills/graphify/, and command files adapted from obra/superpowers, DietrichGebert/ponytail, and mattpocock/skills. All four are MIT. NOTICE carries each upstream's copyright and permission notice, repository, author, and SPDX identifier; the vendored skill also ships its upstream license at .claude/skills/graphify/LICENSE.

MIT © Ismo Vuorinen

Portions of this software are derived from third-party works; see NOTICE.