Merge branch 'docs-audit'

README.md

@@ -0,0 +1,106 @@
+# 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/
+```