Claude Code plugins

Review Toolkit · Full guide

Everything the reviewer
can do for you

A review loop for pull requests and branches: a reviewer that writes an HTML report, a fixer that resolves what it found, and a publisher that posts the review to GitHub. It works in Claude Code, Cursor, and the other agents the skills CLI supports, and it's MIT-licensed, part of the Humanity Plus Commons.

Install

One command, your choice of lane

Pick one way in. Installing both gives you every skill twice.

Claude Code plugin

A managed bundle, installed from our marketplace. Claude Code only.

claude plugin marketplace add Humanity-Plus/commons
claude plugin install hp-review-toolkit@humanity-plus

Skills carry the plugin's name, so you run /hp-review-toolkit:review-pr. Update with claude plugin marketplace update humanity-plus.

Skills CLI

Editable files for Claude Code, Cursor, Codex, and most other coding agents. You pick the skills and the agents.

npx skills add Humanity-Plus/commons -g

Add --list to see every skill first, or --skill review-pr to take one. The files are yours: nothing updates until you run npx skills update.

What you get

The skills, and how they chain

The reviewer and the fixer at the core, workflows that chain them, and setup skills that teach the toolkit your repo. Each skill is also a slash command: /review-pr from the skills CLI, or /hp-review-toolkit:review-pr from the plugin.

review-prcore
Full review, ending in an HTML report.
resolve-reviewcore
Fixes the findings on your branch and validates each fix.
review-fixworkflow
Review and fix in one pass, before you open a PR.
publish-reviewworkflow
Posts the review to the PR as inline comments.
review-issuesworkflow
Files the leftover nitpicks as grouped issues.
map-primitivessetup
Maps your system's building blocks for the review.
create-verify-skillsetup
Builds a skill that drives your real app to prove a change.
fix-the-classsetup
Turns a repeated mistake into a check that stops it.

How the pieces chain

  1. review-prlenses, verify, arbiter, then findings.json and report.html
  2. resolve-reviewplan, scoped fixes, your CI's checks, a resolution table
  3. publish-reviewinline PR comments and one review body

review-fix runs the first two back to back on your own branch in findings-only mode: the full pipeline, no HTML report.

Configure

Configure it for your repo

The toolkit works out of the box. The files you commit are its real configuration: they turn a generic review into yours.

REVIEW.mdevery lens
Everything a reviewer can't infer from a diff: repo facts (“auth isn't wired yet”, “these paths are generated”), what high severity means here, what CI already enforces, the invariants every change must keep, which stack areas the scorecard grades, and soft style preferences. This is the file that stops repeat false positives.
docs/conventions/conventions lens
Your written rules, one short file per topic. Every conventions finding cites the rule it breaks, and no written rule means no finding. AGENTS.md, CLAUDE.md, and .cursor/rules/ are read too.
docs/primitives.yamlprimitives lens
A map of your system's building blocks: the files that define each one, the invariants it keeps, and what it relates to. It lets a review tell whether a change uses a primitive, extends it, or invents a parallel shape. Generate it with map-primitives.
verify-<app>/experiments and fixes
A generated skill that starts your app, signs in as a seeded test user, uses a feature, and saves the evidence, plus a feature map whose source paths let a change find the features it touched. The one setup file that runs code, so it runs only on your own checkouts. Generate it with create-verify-skill.

REVIEW.md, the shape that works

The lenses look for these headings:

# Review instructions
## What Important means here   ← your severity bar
## Do not report               ← what CI already enforces, generated code
## Always check                ← your invariants, each citing its rule
## Stack                       ← areas the scorecard grades
## Repo facts                  ← what a diff can't tell a reviewer
## Style                       ← soft preferences, never blocking
## Review roles                ← optional model-tier overrides
## Trust                       ← optional: let reviews run collaborators' PRs

Point it at your convention docs (“web UI → react.md”) so each lens reads the right file in full. Copy the skeleton, and see a real one from a production app for what yours grows into.

primitives.yaml, one entry

primitives:
  - id: order
    area: data
    name: Order
    sources: [src/db/schema.ts, src/orders/]
    invariants:
      - Status only moves forward; cancel is a status, not a delete.
      - Totals are derived on write, never recomputed in the UI.
    relates_to: [customer, invoice]

sources maps changed files onto primitives, and a directory matches everything under it. List the files that define the shape, its values, and the guards that enforce it, not the files that only use it. Keep ids stable, and update the map in the PR that changes a primitive.

How a review runs

How a review runs

One orchestrator, several independent perspectives, then skepticism and calibration.

  1. Phase 1triagefeature areas, a risk map, the interfaces, and whether to shard
  2. Phase 2lensesparallel subagents, sharded on large diffs, plus any optional passes
  3. Phase 3verifyone skeptic check per finding: refute, confirm, or downgrade
  4. Phase 3.5arbiterregrade, group repeats, fold what's past the report budget
  5. Phase 4rendermark mistake classes, then write findings.json and report.html

Lenses

triagealways, first
What changed, grouped by feature area and risk?
first-fivealways
The five things automated changes get wrong: errors, input, external calls, mutations, and dependencies.
conventionswith convention docs
Your written rules, stack idioms, and sibling precedent, with a scorecard per area.
warmnew dependencies
Is each new or upgraded package Worth it, Alive, Right-sized, and Maintained?
zombiesalways
Which high-value tests are missing: Zero, One, Many, Boundaries, Interface, Exceptions, Simple?
preflightalways
What has to happen for this to deploy safely?
intentwith a spec source
Does the diff do what the PR body, linked issues, or spec files say it does?
seamswhen areas share contracts
Do both sides of every contract the diff crosses still fit together?
primitiveswith a primitives map
Does the change compose, extend, or add to your primitives, and does it invent shapes outside the map?
blast-radiusmedium tier and up
What does the change reach beyond the diff: other readers of the same data, the library at its pinned version, the path production runs, timing, rollback? It names the one safety fact the change rests on, says how far that fact is proven, and writes the probe that settles it.

Adaptive sharding

Above shard-threshold changed lines (400 by default), first-five, zombies, and conventions split into one subagent per feature area. The other lenses keep the whole diff. Small PRs are untouched.

Severity arbiter

After verify, the arbiter grades severity against the whole review, collapses repeats of one defect into a single card with every location, and folds findings past the budget (15 by default) into a collapsed section. Nothing is dropped.

Mistake classes

A finding becomes a class when it has several sites in the diff, breaks a rule nothing enforces yet, or repeats a defect an earlier review or an open review-debt issue recorded. The report shows a Classes card, and the fixer hardens each class instead of only patching it.

Role-based models

Subagents fill roles (triage, lens, seams, blast radius, adversary, verify, arbiter, holistic) mapped to fast, balanced, or strongest tiers, resolved against what your tool offers. No model ids are hardcoded. Override them in REVIEW.md under ## Review roles.

Optional passes

holistic runs one whole-diff generalist beside the lenses and reports where they overlap, so you can see what the lens split misses. interrogate adds adversaries that try to break the change by running it, each in its own scratch copy of the repo. A finding survives only when a fresh rerun reproduces it, and the report shows what each adversary found and kept. Interrogation runs code, so it works on your own checkouts, or on collaborators' PRs when REVIEW.md opts in under ## Trust.

Skill reference

Every skill, every argument

Run a skill as /hp-review-toolkit:<skill> with the plugin, or /<skill> with the skills CLI. Whatever you type after the name is its argument. In agents without slash commands, ask for the skill by name.

review-pr

read-only

The full review. It writes review-report/findings.json, the source of truth, and report.html: a verdict, the severity mix, a risk heatmap by area, the safety fact the change rests on and how well it's proven, the mistake classes it found, a conventions scorecard, a test-gap matrix, and a deploy checklist. On your own branch it first runs the checks your CI runs, picked from the workflow itself, and notes any changed file none of them cover. It ends with a short summary in chat.

No argument
The current branch against main.
482
That pull request, fetched with gh.
github.com/…/pull/482
A pull request URL.
feature/wbs-tree
A branch against its base.
shard-threshold=250
Shard earlier than the default 400 changed lines.
budget=20
Keep more findings above the fold.
holistic
Also run the whole-diff generalist and compare.
interrogate=3
Also run three adversaries that break the change by running it. Your own checkouts, or under ## Trust.
context=docs/review.md
Use another context file.
repo=../other-checkout
Review a pull request in a different checkout than the one you're in.
no-report
Findings only: the full pipeline and findings.json, no HTML and no fixing. Fix later with resolve-review.

resolve-review

writes code

The fixer, run on its own after a review. It plans the fixes by severity, makes one scoped edit per finding on your own branch (every site of a grouped finding), checks each one with the checks your CI runs, and reverts any fix that breaks them. A finding marked as a class gets hardened with fix-the-class after its sites are fixed, and any sibling outside the branch's scope is named by file and line. After the fixes it re-runs the review's safety-fact probe, and with a verify skill it drives the features the review touched. Deploy steps and PR-text issues come back as a list for you.

No argument
Verified findings at medium severity and up.
high
Only high severity and up.
conventions
Only one lens, feature area, or set of finding ids.

review-fix

writes code

The fast local loop, and the one to point agents at. It runs the full review in findings-only mode, then fixes what it can on the current branch and reports a resolution table in chat, with a list of what only you can close. It never commits.

No argument
The current branch against main, fixed in place.
feature/x
Review and fix that branch.

publish-review

posts to GitHub

Posts a finished pull-request review as one real GitHub review. Findings anchored in the diff become inline comments, and the rest folds into the review body, which opens with the safety fact and the mistake classes. It always shows you a dry run first and posts nothing until you confirm.

No argument
Inline comments for every finding that can anchor.
gist
Also host the report as a secret gist and link it. Public repos only.
pages owner/name
Host the report through a repo that publishes GitHub Pages instead, the private-repo route.
recap
Add the system recap: to the description of your own PR, or to the review body on anyone else's.
medium
Inline comments for medium and up only.
body-only
One summary comment, no inline comments.
https://…/report.html
Link a report you host yourself as the full report.

review-issues

posts to GitHub

Files the review's non-blocking findings, such as readability, naming, and soft conventions, as GitHub issues so they get fixed later instead of dying with the report. One issue per defect class, never per nitpick, deduplicated across runs and labeled review-debt for a scheduled fixer to drain. It asks before creating anything.

No argument
File low and nitpick findings from the latest review.
medium
Widen the band to medium and below.
category=Readability
Only one category.
path=review-report/findings-pr41.json
File from an archived findings file instead of the latest review.
yes
Skip the confirmation, for routines that already carry consent.

map-primitives

writes docs

Maps your system's primitives into docs/primitives.md and primitives.yaml across data, API, auth, workflows, agent tools, UI, and infrastructure, and reports drift: the same concept declared in several shapes. It writes down loose ends honestly instead of quietly fixing them, so consolidation lands as its own PRs.

No argument
Bootstrap a map when there is none, or refresh it against the code and report new drift.

create-verify-skill

writes a skill

Generates a repo-local verify-<app> skill and its feature map, or refreshes them. It interviews the repo (how it runs, its seed data and test users, its test harness), writes the skill, maps your main features with the source files behind each, and drives one feature end to end before it hands over. Refresh checks every feature against the code and one live run, and leaves only proven corrections. It never touches product code.

No argument
Bootstrap, or refresh when a verify skill already exists.
refresh
Refresh only. Stops if there is no verify skill yet.

fix-the-class

changes the repo

For a mistake the repo has seen before. It finds the mistake classes in the repo's own record (reverts, review findings, review-debt issues, notes in AGENTS.md, workaround comments) and makes each one impossible at the highest level that works: architecture, types, a check whose error names the fix, a test, and prose only as a last resort. Every new check has to fail on a real past instance before it counts. It keeps a table in AGENTS.md of each rule and what enforces it. It runs only when you invoke it by name; resolve-review follows the same steps for a review's class findings.

No argument
Harden the class behind the correction you just gave, or, with no fresh correction, every class the record shows.

Agent automation

Make agents review first

Ways to make agents run the review loop before they open a pull request, from a request to a hard gate.

  1. Advisory

    A rule in AGENTS.md

    One line works in Claude Code, Cursor, and cloud sessions: “Before creating any PR, run review-fix and include the resolution summary in the PR body.” A long session can still drift past it.

  2. Prompt

    Routine prompts

    For scheduled cloud agents, put the instruction in the routine's own prompt. The prompt is the reliable channel there: don't count on a routine noticing a file mid-run.

  3. Hard gate

    A Claude Code hook

    The pre-PR hook blocks gh pr create until findings.json exists and is newer than the last commit. Claude Code enforces it, so the agent can't skip it.

Claude Code and other agents

Claude Code

Every skill is a slash command. Anything you type after it becomes its argument, and the hook can make the review a hard gate.

Cursor, Codex, and others

The skills CLI installs the same skills. Agents load most skills when they look relevant, so asking for one by name (“use review-pr on PR 482”) is the reliable path. fix-the-class runs only when named.

The workflow skills are thin: the logic lives in review-pr and resolve-review. If an agent says one of those isn't available, reinstall (npx skills add Humanity-Plus/commons -g, or the hp-review-toolkit plugin) and restart the app.

Example scenarios

Which skill, when

Everyday situations, and which skill to reach for.

“I'm about to open a PR. Check my work first.”

You, on your own feature branch, before pushing.

  1. Run review-fix.
  2. The agent reviews the branch against main through the full pipeline, then fixes the verified findings in place: a missed null check, a convention break with the rule it cites, a couple of missing edge-case tests.
  3. Read the resolution table, skim git diff, and commit what you agree with.

Outcome: The obvious review comments are resolved before a teammate sees the PR. No HTML report: this is the quick loop.

“Review this PR properly before we merge it.”

You, reviewing a teammate's pull request.

  1. Run review-pr 482, or paste the PR URL.
  2. The lenses run as parallel subagents, a skeptic check verifies every finding, and the arbiter calibrates the report.
  3. Open review-report/report.html: the verdict up top, risk by feature area, and findings written like short teaching articles with diffs and diagrams.
  4. Run publish-review gist. After a dry run and your confirmation, the findings land on the PR as inline comments and one summary review that links the full report.

Outcome: One evidence-based GitHub review instead of a wall of bot comments. Nothing on the PR branch is run or edited unless REVIEW.md deliberately opts collaborators' PRs in.

“The review found 14 things. Fix the important ones.”

You, after a review of your own branch.

  1. Run resolve-review high for high severity and up, or resolve-review conventions for just the craft findings.
  2. It fixes them in severity order, checks each fix with your CI's checks, and reverts and marks as failed anything that breaks them.
  3. A repeated mistake gets a guard as well as a fix: a type, check, or test that fails on the instance it just fixed.
  4. Deploy steps, PR-description mismatches, and folded findings come back as a list for you instead of being guessed at.

Outcome: A ledger of exactly what changed and what still needs a human. You stay in control of the commit.

“Make the agent refuse to open a PR without a review.”

You, wiring Claude Code so the loop can't be skipped.

  1. Add the pre-PR rule to the project's AGENTS.md.
  2. Install the pre-PR hook, for the project or globally. Plugins don't ship hooks, so this step is yours.
  3. When an agent runs gh pr create without a fresh review, the hook blocks it and tells the agent to run review-fix first.

Outcome: Every PR that goes out has been through review and fix against the commit being filed.

“Prove the change actually works.”

You, on your own branch, with a verify skill in the repo.

  1. Run create-verify-skill once. It writes the skill and proves it on one feature.
  2. From then on, a review on your own branch can run its experiments through the app, and the safety fact gets a probe that settles it by running.
  3. After its fixes, resolve-review drives the features the change touched and records what it saw.

Outcome: Claims about behavior arrive proven or contradicted, not predicted from reading code.

Safety

Safe by default

What the toolkit refuses to do, and why.