The Commons

Humanity Plus Commons · Claude Code

The tools we build with,
open to everyone

Claude Code plugins from our own workflow, MIT-licensed. The Review Toolkit reviews code the way a careful senior engineer would. Code Publish ships the result to GitHub with honest attribution and clear writing. Here's what they do, and how to give them the context that makes them good.

hp-review-toolkit

Review Toolkit

A code-review loop built for agent-written code. Independent lenses check a change for bugs, missing tests, risky dependencies, deploy hazards, breaks with your own conventions, and what it reaches beyond the diff. A skeptic pass removes false positives before you see them, and the result is an HTML report with evidence and suggested fixes.

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

Code Publish

Skills for the moment work leaves your machine and lands on GitHub. They say who wrote it and make what was written easy to read, the opposite of skills that make agent output pass as human.

create-pr
Outcome-led titles and problem-first descriptions.
write-clearly
Clarity rules for PR bodies, issues, docs, and reports.
github-comment-attribution
Marks agent-written GitHub comments as such.
Set it up

Install

Add our marketplace, then install

Add our marketplace once and install either plugin, or both. They run in Claude Code in the terminal, the desktop app, and the IDE extensions.

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

Inside a session, use /plugin install with the same names. Skills carry the plugin's name, so you run /hp-review-toolkit:review-pr. New releases arrive with claude plugin marketplace update humanity-plus.

Installed one of them under an earlier name? The release notes list the commands to swap it for the current one.

What you need

  • The GitHub CLI, signed in, for anything that touches a pull request. Reviewing a local branch works without it.
  • Bun, for the Review Toolkit's HTML report.
  • Not on Claude Code? npx skills add Humanity-Plus/commons -g installs the same skills as editable files for Cursor, Codex, and other agents. Pick one route: installing both gives you every skill twice.

Set up · Review Toolkit

Give the reviewer your context

The toolkit works as soon as it's installed. It gets good once it knows your repo. A few files you commit turn a generic review into yours: what to ignore, which rules to cite, which shapes your system already has, and how to run your app.

This is the short version. The full guide covers every skill, argument, and lens.

  1. Brief the reviewer

    • REVIEW.md

    Put everything a reviewer can't learn from a diff at the repo root: what counts as serious here, what CI already enforces, the invariants every change must keep, and facts like “auth isn't wired up yet”. This is the file that stops repeat false positives. Claude Code Review reads the same file, so one brief drives both reviewers.

    # 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

    Start from the skeleton, and see a mature example for what yours grows into.

  2. Write down your conventions

    • docs/conventions/
    • AGENTS.md

    One short file per topic: react.md, typescript.md, testing.md. Every conventions finding cites the rule it breaks, and no written rule means no finding, so the review never turns into a generic style bot. It also reads AGENTS.md, CLAUDE.md, and .cursor/rules/.

    Tag each rule with how hard it is. We use [Rule] for hard gates, [Convention] for defaults, and [Known gap] for debt we already know about, so a review stops re-reporting old debt and blocks new copies of it instead. Name the files in REVIEW.md (“web UI → react.md”) so each lens reads the right one in full.

  3. Map your primitives

    • docs/primitives.md
    • docs/primitives.yaml

    Primitives are your system's building blocks: entities, status enums, lifecycles, API shapes. With a map, the review can tell whether a change uses what exists, extends it, or quietly invents a parallel shape, the most common failure of agent-written code. Generate the map, then read it:

    /hp-review-toolkit:map-primitives

    Each entry lists the files that define a primitive and the invariants it must keep. Run the skill again to refresh the map and report drift, and update the map in the same PR that changes a primitive.

    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]
  4. Teach it to run your app

    • .claude/skills/verify-<app>/

    Reading code predicts behavior. Running it proves it. Generate a skill that knows how to start your app from a fresh checkout, sign in as the test users your seed creates, use a feature, and save the evidence:

    /hp-review-toolkit:create-verify-skill

    It comes with a feature map: one file per feature, listing the source files behind it. When a change touches those files, the review and the fixer use the feature to prove the change works. The skill only runs on your own checkouts, against a local or disposable instance, and it proves itself on one feature before it hands over.

  5. Make it a gate

    • .claude/settings.json

    Optional. A hook that ships with the toolkit blocks gh pr create until a fresh review covers the code being opened. Claude Code runs the hook itself, so an agent can't skip it. Install the hook.

The everyday loop

For a pull request, review it, put the findings on the PR, then fix them. The fix step checks each change with the same checks your CI runs, and tells you about any changed file none of them cover.

/hp-review-toolkit:review-pr 482
/hp-review-toolkit:publish-review
/hp-review-toolkit:resolve-review

On a branch that isn't a PR yet, /hp-review-toolkit:review-fix does the same in one pass.

When a mistake repeats, across the diff or across reviews, or breaks a rule nothing enforces yet, the review marks it as a class. The fixer then does more than patch it: it adds a type, a check, or a test that would have caught it, proves that guard fails on the mistake it just fixed, and records the rule in your AGENTS.md.

Set up · Code Publish

Ship work that says who wrote it

Code Publish needs less setup: its skills read your repo as they work. It takes the PR title convention from your merged PRs, so there's nothing to configure for that. These steps make it fit your team.

  1. Sign in to GitHub

    create-pr and github-comment-attribution post through your own GitHub CLI login. They never read a token or key.

    gh auth login
  2. Write down what a PR needs

    • AGENTS.md
    • CLAUDE.md
    • CONTRIBUTING.md

    Before it files, create-pr checks these files for what a PR must satisfy, such as required checks, a changelog entry, or a decision record, and meets them first. A gate that isn't written down can't be met.

  3. Add the map

    • docs/primitives.yaml

    With the Review Toolkit installed and a primitives map on your base branch, create-pr adds a recap to the description showing which of your system's building blocks the PR touched. Map your primitives once and both plugins use it.

  4. Make attribution a rule

    • AGENTS.md

    The attribution skill loads when Claude posts to GitHub. To make it non-negotiable, say so in your agent instructions:

    Anything you post to GitHub from my account (comments, replies, issues) starts with the attribution header from the github-comment-attribution skill.

What they run and send

Your code stays yours

The plugins collect nothing, and Humanity Plus receives nothing. They run git and gh on your machine, plus bun for the Review Toolkit's report and Code Publish's optional recap, and post to GitHub only through your own login, only when you ask. A review never runs, builds, or installs someone else's pull request unless your REVIEW.md opts in. On your own branches it runs your checks, and a verify skill starts your app locally to prove a change. The plugin privacy notice lists everything that leaves your machine, and each plugin's README has the technical detail: Review Toolkit, Code Publish.