Travis Herbranson 86797abb99 Initial a-review skill: model-agnostic independent code review

Skill that sends git diffs to an independent AI model (Gemini CLI, Ollama)
for security, bug, performance, and convention review. Assembles a context
packet from CLAUDE.md + session notes + expanded diff so the reviewer
evaluates intent vs. implementation.

Includes context assembler script, structured review prompt template,
and review-ready CLAUDE.md with key patterns documented.

2026-04-27 20:32:56 -04:00

2.5 KiB

Raw Blame History

a-review — Agent Code Review Skill

Claude Code skill that sends code changes to an independent AI model for review. Model-agnostic — supports Gemini CLI, Ollama, or any text-in/text-out backend.

Architecture

a-review-skill/
  a-review/
    SKILL.md                      — Skill definition (triggers, workflow)
    references/
      review-prompt.md            — Prompt template sent to the reviewer
    scripts/
      assemble_context.py         — Builds context packet from project files

Key Patterns

Context packet. The reviewer gets four pieces of information assembled by scripts/assemble_context.py: CLAUDE.md (architecture + conventions), latest session notes (intent), expanded diff (changes in surrounding context), and diff stat (scope summary). This mirrors how a human reviewer works — read the PR description, understand conventions, then evaluate the diff.

Model-agnostic backend. The skill doesn't call the reviewer directly. It builds the context packet and pipes it to whatever backend is configured. Gemini CLI uses gemini -p with --approval-mode plan (read-only). Ollama uses the HTTP generate API. New backends only need a way to accept text in and return text out.

Read-only reviewer. The reviewer model runs in plan/read-only mode. It cannot modify files. Its job is to produce findings, not fixes. The authoring agent (Claude Code) decides what to act on.

Complements zero-check, doesn't replace it. zero-check is deterministic (lint, SAST, tests, deps). a-review is subjective (security patterns, logic gaps, convention violations, intent-vs-implementation). They run in sequence: zero-check first, a-review after.

Development

# Test the context assembler
cd /path/to/any/git/project
python /path/to/a-review-skill/a-review/scripts/assemble_context.py

# Run a review manually with Gemini
python scripts/assemble_context.py | \
  GEMINI_CLI_TRUST_WORKSPACE=true gemini -p "$(cat references/review-prompt.md)" \
  --approval-mode plan

# Package as .skill file
cd a-review && zip -r ../a-review.skill SKILL.md references/ scripts/

Session Notes

After each coding session, append a session entry to sessions/a-review-skill.md in this project folder. See that file for the format convention and existing entries.

Granularity: one entry per logical change. A new function, a new route, a new template, a new config setting, or a bug fix each get their own entry. Don't combine multiple changes into one entry. If it would be a separate item in a code review, it's a separate entry here.