Notes

Reviewer Framework

last modified: orginally published: 4 min read

Update (Mar 2026): Anthropic recently shipped Code Review - a hosted GitHub App that dispatches parallel agents on every PR, verifies findings, and ranks by severity. It feels good to be validated.

The reviewer plugin started as a single slash command that loaded every guidance file and reviewed everything in one pass. That ran into context bloat - too much loaded up front, often forcing a compaction that wiped out whatever had already been reviewed. Moving the review into a subagent freed up the main context, but the subagent hit most of the same problems with a longer runway and still missed simple mistakes. Splitting into one subagent per concern caught more issues but a full review now needed multiple commands. To keep each agent from loading every AGENTS.md, I copied the relevant guidance into the agents directly, which then had to be updated alongside the originals every time guidance changed. I started on an orchestrator slash command to launch the subagents and hold the shared rubric, but the Sonnet 4.5 release dropped before I finished and I gave up in favor of just having Codex use its own /review command. I came back to it after Opus 4.5, since Claude Code had started converting slash commands into skills. After trying similar approaches in a few projects, I extracted the common parts as the foundation of the plugin framework.

The result is a layered framework with project-local extension points, plus a companion plugin with extra review types that I often use.

Architecture

The three layers fell out of that iteration process:

  • reviewer-framework holds the shared rubric - severity levels, a 0-100 confidence scale, and the output template that every review type emits findings against.
  • Core review types are one skill per concern: review-logic, review-patterns, review-documentation, and review-skill. Each ships its own default rules and supports a project-local override hook.
  • self-review is the orchestrator: it picks the scope, assigns the right model to each review type, fans out, and coalesces findings.

Local customization

The defaults ship to everyone so they have to stay deliberately generic. Project-specific rules like naming conventions, specific business model domains, and internal libraries belong in the project repo. The plugin gives four extension points:

  • customize-core-review - project-specific rules for a built-in type, extending or overriding the defaults.
  • extend-self-review - orchestrator config: which types run, agent per type, confidence threshold, and pre/post steps.
  • add-core-review - entirely new review categories (e.g. security, performance, accessibility, domain-specific checks).
  • create-reviewer-agent - custom model and tool combos, such as a Haiku fast-reviewer or an agent with Bash for running linters.

The reviewer-init skill composes all four into an interactive wizard that can be used to add the framework to a new repo.

Reviewer extras

The core plugin holds the framework itself - rubric, review types, orchestrator, and the customization skills. reviewer-extras holds anything beyond that. Today it has two skills, both review types that lean on other plugins:

Plugins can’t declare dependencies on each other, so each of these extras checks for its required plugin at the start of its skill and short-circuits with a CRITICAL finding if it’s missing.

Since all the skills in the plugins are compatible with the Agent Skills specification, Codex can actually leverage the exact same skills to run its own parallel self-review.

Custom orchestrators

One of the benefits of the architecture is that it’s pretty simple to add other entry points or orchestrators. For example, a simple ci-review might look like:

---
name: ci-review
description: Run reviewer-framework reviews on a PR and post findings as GitHub comments.
allowed-tools: Read, Glob, Grep, Skill, Task, Bash, mcp__github_inline_comment__create_inline_comment
argument-hint: "[repo] [pr-number]"
---

1. Resolve scope: parse `$ARGUMENTS` for `<repo> <pr-number>`, then `gh pr diff <pr-number> --name-only` for changed files.
2. Run the `self-review` skill against those files.
3. Provide detailed feedback on the findings from step 2 using inline comments for specific issues.

Then you can replace prompt: in the Anthropic Claude Code Action solutions doc’s PR review example with /ci-review ${{ github.repository }} ${{ github.event.pull_request.number }}.

It probably isn’t a good idea to wrap self-review directly but it does work for a simple example. In reality, you’d probably want to copy the language of the self-review skill and edit it for your needs (remove the local extension, just merge that content directly, etc.) In most of my projects I use the review-codex skill which obviously wouldn’t work in the Claude Code GitHub Action. Writing a fully custom ci-review skill makes it easy to exclude it.

Graph View

Backlinks

Recent Notes