# 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

```bash
# 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.