/review

name: review
description: Reviews code using pi CLI with read-only tools. Delegates the review to pi (dev/pi) with a structured review rubric, running in read-only mode to prevent accidental edits. By default reviews uncommitted working tree changes (git diff HEAD) with pi restricted to the read tool; explicit targets (--branch/--diff/@file/PR) or --explore widen pi to read,grep,find,ls. Use when the user asks to "review code with pi", "pi review", "have pi review", "let pi review", or invokes /pi:review.
user-invocable: true
argument-hint: "[@target] [--branch BRANCH] [--diff RANGE] [--endpoint ENDPOINT] [--model MODEL] [--thinking LEVEL] [--explore] [--with-packages] | --edit-config [--local|--shared|--global] | --list-models"
allowed-tools: ["Task", "Bash(git:*)", "Bash(jq:*)", "Bash(ls:*)", "Bash(find:*)", "Bash(cat:*)", "Bash(mkdir:*)", "Bash(echo:*)", "Bash(command -v:*)", "Bash(mktemp:*)", "Bash(rm:*)", "Bash(mv:*)", "Bash(sed:*)", "Bash(grep:*)", "Bash(head:*)", "Bash(awk:*)", "Bash(tr:*)", "Bash(gh:*)", "Bash(bash:*)", "Bash(vi:*)", "Read", "Grep", "Glob"]

CRITICAL: pi Code Review

This skill delegates a code review to the `pi` CLI tool (`@earendil-works/pi-coding-agent`). pi runs with **read-only tools** to prevent accidental edits — it analyzes code and returns findings as text.

**CRITICAL: The default review target is the uncommitted working tree (`git diff HEAD`), and pi must NOT be able to explore the whole codebase or run git itself.** pi's `--tools` flag is a hard allowlist — only listed tools are registered (pi's built-in tools are `read, grep, find, ls, bash, edit, write`; there is no standalone `git` tool, but `bash` can run `git diff`). By default restrict pi to `read` only so it can inspect files mentioned in the diff but cannot `find`/`grep`/`ls` the repo or run `bash`/`git`. Only expand to `read,grep,find,ls` when an explicit target (`--branch`, `--diff`, PR number) or `--explore` requires it.

Before Execution: Check Installation

command -v pi >/dev/null 2>&1

If not installed, tell the user and stop.

Persistent Settings

User preferences persist across invocations via JSON files. The resolution chain (highest priority first):

1. **CLI flag** (from `$ARGUMENTS`) 2. **`.claude/pi.local.json`** — project-specific overrides, gitignored 3. **`.claude/pi.json`** — project shared defaults, committed 4. **`~/.claude/pi.local.json`** — global user-wide defaults 5. **Built-in defaults** (listed below)

Settings files use the format below. Load `references/settings.md` for the full format, reading logic, `--edit-config`, and `--list-models`:

{
  "endpoints": {
    "my-proxy": {
      "provider": "openai",
      "baseUrl": "http://10.10.0.195:8317/v1",
      "models": ["gemini-3.6-flash-high", "gemini-3.6-pro"]
    }
  },
  "defaultEndpoint": "my-proxy",
  "defaultModel": "gemini-3.6-flash-high"
}

Each endpoint key has `provider` (required), optional `baseUrl`, and `models`. Values may reference env vars via `$VAR`. Read the merged settings with the `Reading settings` snippet in `references/settings.md` — it yields `ENDPOINT`, `MODEL`, `THINKING`, `PROVIDER`, `BASE_URL`, `API_KEY`, `WITH_PACKAGES`.

Before parsing review targets, handle the two settings-only flags from `references/settings.md` and stop (do not proceed to review):

• `$ARGUMENTS` is exactly `--edit-config` (with optional scope flag) → open the settings file (see `references/settings.md`).
• `$ARGUMENTS` is exactly `--list-models` → print configured endpoints and models (see `references/settings.md`).

Argument Parsing

Parse `$ARGUMENTS` to extract the review target and optional flags. The target is everything before the first `--` flag. If no flags are present, the entire argument is the target.

| Flag | Description | Source Priority | |------|-------------|-----------------| | `--endpoint` | Endpoint key name (must match a key in settings `endpoints`) | CLI > settings > `defaultEndpoint` | | `--model` | Model ID to use for this review | CLI > settings > (endpoint's first model) | | `--thinking` | Thinking level (off/minimal/low/medium/high/xhigh/max) | CLI > settings > `max` | | `--explore` | Force full read-only exploration tools (`read,grep,find,ls`) even for the default working-tree review. Without this, the default review gets `read` only. | CLI flag | | `--with-packages` | Load the user's global pi packages/skills/extensions (default is clean mode: off) | CLI > settings `withPackages` > `false` |

Resolution order per flag

For each flag, resolve the value by checking CLI flag first, then settings file, then built-in default:

1. Parse `$ARGUMENTS` for that flag. If present, use it. 2. Otherwise, read from `$CONFIG` (the merged settings). If non-null/non-empty, use it. 3. Otherwise, use the built-in default.

Endpoint resolution

1. If `--endpoint` is specified, use it as the key into `endpoints` config. 2. If `--model` is specified without `--endpoint`, scan all endpoints for a model matching the ID — use the first match's endpoint. 3. Otherwise, use `defaultEndpoint` from settings. 4. If the resolved model is empty, use the first model in the resolved endpoint's model list. 5. Resolve the pi provider from the endpoint's `provider` field (default `openai`).

Base URL resolution

The pi-agent handles `baseUrl` — it conditionally writes it into the agent-dir `models.json` (pi has no `--base-url` flag) only when it differs from the existing value. The skill just passes the resolved `BASE_URL` to the agent; it does not write models.json itself.

Review Target

Determine what to review from the parsed arguments. The target can be:

| Pattern | What it reviews | pi tools | |---------|----------------|---------| | No target (default) | `git diff HEAD` — uncommitted working tree changes (staged + unstaged) | `read` only | | `--branch <name>` | `git diff main...<branch>` | `read,grep,find,ls` | | `--diff <range>` | `git diff <range>` | `read,grep,