# a-review-skill

A Claude Code skill that runs an **independent AI code review** after a
coding session. The reviewer is a *different* model from the one that
wrote the code — Gemini CLI, a local Ollama, or any text-in/text-out
backend — and runs read-only so it can produce findings but never edits
files.

This complements [zero-check](../zero-check-pipeline) rather than
replacing it:

- **zero-check** = deterministic gauntlet (lint, SAST, deps, tests).
- **a-review** = subjective second opinion ("did you miss something a
  linter wouldn't catch?").

Run zero-check first, a-review after.

## How it works

1. Assembles a **context packet** from the project: `CLAUDE.md` (so the
   reviewer knows the architecture + conventions), the latest session
   notes (so the reviewer knows the intent), `git diff -U10 HEAD~1`
   (the change in surrounding context), and `git diff --stat HEAD~1`
   (scope summary).
2. Pipes the packet plus the prompt template at
   `a-review/references/review-prompt.md` to whichever backend is
   configured.
3. Saves the reviewer's output to `reviews/a-review-YYYY-MM-DD.md` in
   the project, with a header noting the model + diff scope.
4. Surfaces the findings to you — grouped by severity if the reviewer
   used severity labels, with anything critical or security-related
   highlighted.

## Install

The skill is packaged as `a-review.skill` (a zip of `SKILL.md`,
`references/`, and `scripts/`). Two install paths:

**From the packaged `.skill`** (preferred for sharing):

```bash
# Drop the file into your Claude Code skills dir
cp a-review.skill ~/.claude/skills/
```

**From the source tree** (for development):

```bash
# Symlink (or copy) the unpacked dir
ln -s "$(pwd)/a-review" ~/.claude/skills/a-review
```

After install, the skill triggers on:

- `/a-review` slash command
- Phrases like "review my changes", "get a second opinion",
  "run a-review", or "check this with gemini/ollama"
- Automatically after a coding session with substantive changes (per
  the skill description)

## Backends

| Backend | How it's invoked | Notes |
|---------|------------------|-------|
| **Gemini CLI** (default) | `gemini -p "$(cat references/review-prompt.md)" --approval-mode plan` | `--approval-mode plan` is required — keeps the reviewer read-only. |
| **Ollama** | HTTP `POST /api/generate` against `http://localhost:11434` | Pick a code-tuned local model (`codellama`, `deepseek-coder`, etc.). |
| **Anything else** | Pipe the assembled context + prompt to its CLI / API | The skill is text-in / text-out; no backend-specific code needed. |

The skill checks for `.a-review.yml` in the project root and uses the
configured backend if present, otherwise defaults to Gemini CLI.

## Manual usage

You can run the same pipeline by hand:

```bash
# From any git project root
python /path/to/a-review-skill/a-review/scripts/assemble_context.py | \
  GEMINI_CLI_TRUST_WORKSPACE=true \
  gemini -p "$(cat /path/to/a-review-skill/a-review/references/review-prompt.md)" \
  --approval-mode plan
```

Useful for debugging the context packet or trying an ad-hoc model.

## Repo layout

```
a-review-skill/
  a-review/
    SKILL.md                   # Skill definition (triggers + workflow)
    references/
      review-prompt.md         # Prompt sent to the reviewer
    scripts/
      assemble_context.py      # Builds the context packet
  a-review.skill               # Packaged zip (SKILL.md + references/ + scripts/)
  sessions/                    # Per-project session notes (skill self-dogfoods)
  CLAUDE.md                    # Agent notes
  README.md                    # This file
```

## Packaging a new release

```bash
cd a-review && zip -r ../a-review.skill SKILL.md references/ scripts/
```