code-quality-atlas

A composable suite of code-review skills, built from first principles — map everything that factors into code quality, then distill it into focused, single-purpose review lenses an AI coding agent can run.

It ships as a Claude Code plugin, but the skills are plain SKILL.md files with no Claude-specific dependencies, so the suite also runs in any coding agent that supports the SKILL.md format (Cursor, Windsurf, Copilot, …). The plugin wrapper — commands, hooks, marketplace metadata — is additive.

Jump to: Install · Wire it into your repo · Use it · Automate PR review · How it was built

What you get

44 review skills, generated from a researched taxonomy and refined against eval scenarios:

• 41 review lenses — each a narrow, self-contained reviewer (correctness, naming & readability, module design, concurrency, migrations & data safety, security, performance, tests, API contracts, data transformations & data contracts, accessibility & i18n, observability, LLM-integration, agentic & tool-use safety, resilience, install/upgrade experience, plus repo-shaped audits for architecture, dependencies, config/build, docs, compliance, infrastructure-as-code, decision-record currency, data-pipeline health, deployment/trust-boundary security, a decision-time lens, and an artifact lens that reviews authored artifacts like SKILL.md against their own standard, plus the first two Cluster VII lenses — usability & interaction quality and product-outcome instrumentation — and 12 more). Each leads with a one-line tagline, runs on its own, and carries its full checklist in reference/heuristics.md (the artifact lens uses artifact-specific rubric files instead); the narrowly-scoped lenses add an explicit Skip when… clause so the router knows when not to run them.
• choosing-review-lenses — a router that ranks a change's relevant lenses and runs the top few by default, with triage and comprehensive depth modes for fewer or all of them, so you don't have to know the catalog.
• grounding-review-in-tool-output — a pre-pass that runs the deterministic linters, type checkers, and scanners the reviewed repo already configures, scoped to what's under review, and hands each lens their hits as evidence to confirm, contextualize, or dismiss. It never introduces a tool the repo hasn't adopted, and a clean run clears nothing.
• synthesizing-review-findings — merges multiple lenses (and any other reviewer) into one deduplicated, severity-ranked, single-verdict report.

The catalog lives in skills/manifest.yaml. For Claude Code, the plugin also adds slash commands, a side-effect-free SessionStart routing hook, opt-in self-improvement telemetry hooks (off by default), and routing templates.

The point of the suite is to supersede the generic built-in /code-review (and framework reviews like BMAD) as the primary review path — with deeper, research-derived coverage — while still folding their findings in through the synthesizer rather than picking only one.

Install

Both paths install the same skills; the Claude Code plugin adds commands and hooks on top. Update mechanics, web-session setup, and keeping current are in docs/install.md.

Any SKILL.md agent — via Skulto (recommended cross-platform path; syncs to Claude Code, Cursor, Windsurf, Copilot, and 25+ more):

brew install asteroid-belt/tap/skulto
skulto add brandondees/code-quality-atlas
skulto install brandondees/code-quality-atlas -y

Claude Code (plugin):

/plugin marketplace add brandondees/code-quality-atlas
/plugin install code-quality-atlas@code-quality-atlas

The plugin and the .claude/settings.json marketplace snippet are CLI-local — they do not load in Claude Code web/cloud sessions (the cloud runtime doesn't run the plugin-install step). For cloud, enable the suite as account skills on claude.ai or vendor .claude/skills/ into the repo — see docs/distribution.md.

Wire it into your repo

Installing the suite makes it available; it doesn't guarantee an agent reaches for it. On a plain "review this," the shorter-named built-in code-review can win the keyword race. The deterministic fix is a routing block in the repo's CLAUDE.md / AGENTS.md — agents read it at session start, and it outranks keyword matching.

In a Claude Code session inside the repo you want reviewed:

/code-quality-atlas:atlas-init

It writes an idempotent routing block into both CLAUDE.md and AGENTS.md (different agents read different files), telling them to prefer the atlas suite over /code-review and framework reviews — combined non-exclusively. Not on Claude Code? Paste templates/agents-routing-snippet.md by hand.

The plugin also ships a SessionStart hook that nudges agents toward the suite each session — a backstop for when skill descriptions get budgeted out of context — plus a pair of opt-in, off-by-default hooks that feed the suite's self-improvement loop when a repo turns them on. Details in docs/install.md.

Use it

Most of the time you want one command. Built a feature and want it reviewed? Run /atlas-review-pr <pr> if it's a pull request, or /atlas-code-review for local or pushed-branch changes with no PR. That's the whole happy path — the command picks the lenses your change actually needs — a few by default, or every relevant one in comprehensive mode — and merges their findings into one ranked verdict for you. You don't pick lenses by hand or run the synthesizer yourself; reach for an individual lens (the rows below) only when you already know which one you want. If you ran a command and got useful feedback, you used it right.

Situation	Reach for
A whole PR	/atlas-review-pr
Local changes with no PR (working tree, or a pushed branch)	/atlas-code-review
By hand, unsure which lenses apply	choosing-review-lenses (ranks the change's relevant lenses; top few by default)
The relevant lens is obvious	call it directly (async change → reviewing-concurrency-and-async)
You ran more than one lens	finish with synthesizing-review-findings
Many repos at once	the multi-repo audit runbook

Every lens runs on its own; its SKILL.md is self-sufficient for a first pass and reference/heuristics.md holds the full checklist.

Automate PR review

The plugin turns the suite into a hands-off pull-request loop on Claude Code on the web: a GitHub-event reviewer that re-reviews each push and quiets down as it converges, plus a scheduled poller that rebases stale PRs and pokes conflicts (the gap GitHub webhooks don't cover). Convergence rules — a severity floor that settles at Major, comments only for genuinely-new findings, approve-on-clean, and a round cap — keep the reviewer and a build/auto-fix session from ping-ponging forever.

The commands ship with the plugin; the routines are account-side config you create once. Step-by-step setup: docs/runbooks/pr-review-automation.md. Copy templates/REVIEW.md into the reviewed repo to tune the convergence policy.

How it was built

Built fresh from first principles, treating existing skills, linters, and review tools as prior art to learn from — not constraints. Docs are the source of truth; skills are generated from skills/manifest.yaml with provenance hashes, a drift-checker, and eval-first refinement. The underlying map is a broad, layered taxonomy — clusters of quality categories, each decomposed into concrete factors — that every skill traces back to. Ongoing work is the compounding loop: critique the research, let drift flag affected skills, regenerate, re-gate.

• Project intent, scope, phases, principles → docs/overview.md
• The master map → docs/taxonomy.md; per-cluster research → docs/research/
• Architecture & generation → docs/phase-2-skill-suite-design.md; regenerating skills
• Decisions & history → docs/open-questions.md; docs/session-log.md; structural gaps → docs/map-gaps.md
• Prior art surveyed → docs/prior-art.md
• Contributor system map (what a change hits) → docs/map/CLAUDE.md

Repo layout

Path	What's in it
skills/	The 41 lenses + the three composition skills: choosing-review-lenses (router), grounding-review-in-tool-output (tool-grounding pre-pass), synthesizing-review-findings (synthesizer). Per skill, SKILL.md/reference/*.md are generated from skills/manifest.yaml + docs/research/; examples.md/evals/eval.json are hand-authored
collapsed/	Generated 4-entrypoint form of the suite for cloud / account-skill installs; each entrypoint bundles its shape's lenses and loads them on demand
commands/	Slash commands: /atlas-review-pr, /atlas-code-review, /atlas-init, /atlas-rebase-stale, /atlas-poll-and-review, /atlas-propose-preferences
hooks/	SessionStart routing hook (side-effect-free); opt-in, off-by-default PostToolUse/SessionEnd self-improvement telemetry hooks
templates/	REVIEW.md convergence policy + agents-routing-snippet.md routing block + preferences-template.md team-preferences bootstrap
tooling/	The pipeline: generator, drift-checker, eval validator, cross-model runner

License

Dual-licensed by content type: the research atlas and skills (docs/, skills/, collapsed/, commands/, templates/, this README) are CC BY 4.0 — reuse freely with attribution; the pipeline code (tooling/, hooks/, tests/, CI/config) is MIT. Details in LICENSE.