# Afk Claude Review

> afk-claude-review: Part of the afk pipeline. Runs Claude (Claude Code CLI) as an independent, read-only fallback external role, and the default outer fallback when Codex implemented the change. It declines to review its own work and follows ordered .afk/config.md gates. Triggers include "/afk-claude-review", "run claude review", "claude gate".

- Skill: `alvinshenssw/afk-claude-review` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add alvinshenssw/afk-claude-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alvinshenssw/afk-claude-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: AlvinShenSSW (https://skillmd.com/u/alvinshenssw)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alvinshenssw/afk-claude-review

---


# afk-claude-review

Per-run `--model <alias-or-id>` and `--effort <level>` override
`CLAUDE_REVIEW_MODEL` and `CLAUDE_REVIEW_EFFORT` independently. The shared
`../../lib/gate/model-select.mjs` expands explicit `opus`, `fable`, `sonnet`,
and `haiku` aliases to pinned IDs; environment model values still require full
IDs. Efforts are `low`, `medium`, `high`, `xhigh`, and `max`. Defaults remain
`claude-opus-5` and `medium`; `--print-args` reports the effective selection.
Response identity verification still applies after alias expansion.

An independent second-opinion review by Claude, used as a fallback external role
after `afk-internal-review`; it is the default outer fallback when Codex is the
implementer. Run the ordered roles required by `.afk/config.md`, and never use a
reviewer whose model matches the implementer or another role.

**This gate exists for the case where Claude is not the implementer** — Codex,
Kimi, GLM, DeepSeek, MiMo, Gemini or Copilot wrote the change and Claude reviews
it. It refuses to run otherwise (see Independence below), so under a Claude Code driver it will
normally self-skip and the next gate in `priority` takes its place. That is the
intended behaviour, not a fault.

The helper `claude-gate.mjs` ships with this skill and travels with the plugin.

## Independence — this gate declines to review its own work

The gate resolves who wrote the change and skips if the answer is Claude:

1. `--implementer <family>` — per invocation. The only source that may permit a
   run as well as block one.
2. `implementer:` in `.afk/config.md` — may only **block**. A per-repo file
   written once must not outrank a live per-run signal.
3. `CLAUDECODE` in the environment — set by Claude Code in every process it
   spawns. Present and undeclared means the driver, and so probably the
   implementer, is Claude.

An unrecognised implementer value fails **closed**: the gate skips rather than
guess that it is independent.

Pass `--implementer <family>` whenever the implementer is not the driver — most
often when `afk-agent-relay` relayed the implementation to another model. In
design mode the flag names the design's author, not the code implementer (see
"Run it"). Known families: `claude`, `codex`, `kimi`, `glm`, `deepseek`, `mimo`, `gemini`, `copilot`.

**Known gap:** `CLAUDECODE` identifies the driver, not the model. A Claude
implementer driven from Copilot, Cursor, CI, or a plain terminal leaves it
unset, so the gate would run. Close it with `--implementer claude` or an
`implementer: claude` line in `.afk/config.md`.

## Read-only

The reviewer session loads `Read`, `Grep` and `Glob` and nothing else — no Bash,
no Write, no Edit. It is read-only by construction rather than by an allowlist,
so there is no command list to maintain and none to get wrong.

Because the reviewer has no shell, the gate pre-injects the diff and its stat
into the prompt; the reviewer uses its read tools for anything the diff does not
answer. This is the gate's advantage over `afk-glm-review`, whose reviewer is
limited to the snapshot it was sent.

## Metering

Metered like any external gate. Batch minimal admitted P1 fixes into one content pass, self-review, then re-run once. Record every other
disposition together at the end without editing a clean revision.

## Review receipts

To retain canonical inputs and explicit outcomes, use the optional
`--review-receipt <request.json>` flag under the
[shared receipt contract](../afk/SKILL.md#canonical-review-receipts). Preserve
unknown identity explicitly; skipped or incomplete attempts and previews never
supply approval.

## Review context

Use the [shared context contract](../afk/SKILL.md#supported-review-context) to
carry frozen acceptance scope and named prior findings with accessible proof.
`--review-phase re-review --review-context <packet.json>` preserves the selected
review target while supplying closure context; `--print-args` reports its digest.
Use `--print-prompt` to inspect the supplied section before a provider call.
Required history is validated and never silently truncated.

## Run it

The bundled helper `claude-gate.mjs` sits beside this SKILL.md. Locate its
directory as `${CLAUDE_PLUGIN_ROOT}/skills/afk-claude-review` if the env var is
set, else `<pluginRoot>/skills/afk-claude-review` from `.afk/config.md`, else this
skill's own directory. If `.afk/` is absent, the `afk-init` bootstrap runs
automatically first:

```text
node "<helper-dir>/claude-gate.mjs"
```

Run it in the **background** with a generous timeout; redirect stdout to a file
and read it when it completes. Pass through any target flag (`--base <branch>` /
`--commit <sha>` / `--uncommitted`). Do not poll in a sleep loop.

Pass `--implementer <family>` when another model wrote the change. In design
mode (`--design`) the flag instead names the design's **author**, never the
eventual code implementer — see `../afk/SKILL.md` ("Design-stage external
gate"): declaring the code implementer there can hand a driver-authored design
to the driver's own model for review. A persistent `implementer:` line in
`.afk/config.md` also names the code implementer, and in design mode it can
wrongly block that family's independent review of a driver-authored design —
declare the design's author explicitly then: the per-run flag outranks the
config line.

Add the flag only when that other model *actually* produced the artifact under
review — it can permit a run as well as block one (Independence above), so a
value copied in from an example defeats the self-skip this gate exists for.

**The review is bounded** by `CLAUDE_REVIEW_TIMEOUT_MS` (default 15 min), with
`AFK_REVIEW_TIMEOUT_MS` as the shared fallback. A timeout is a non-zero `ERROR`,
never a partial verdict; it follows the role's transient retry rule.

**Design mode** (`--design <path>`) reviews a design document's reasoning instead
of a diff — the opt-in design-stage gate (see `../afk/SKILL.md`, "Design-stage
external gate"). The reviewer keeps its read-only `Read,Grep,Glob` tools, so it
can check whether the code says what the design claims. A missing or unreadable
`--design` path fails loudly (`ERROR`, non-zero), never a skip.

Read the verdict between the `===== CLAUDE REVIEW (final message) =====` markers. Treat only column-0 marker lines as markers; the last END marker wins.
A `SKIPPED: …` line is not a failure — record it and continue per the `afk`
gate-selection rule. The reasons are distinct on purpose, so the ledger can tell
"correctly declined" from "could not review":

- `SKIPPED: independence check — …` — the gate refused to review Claude's own
  work. Correct behaviour; use another gate.
- `SKIPPED: Claude gate disabled via CLAUDE_REVIEW_GATE.`
- `SKIPPED: Claude CLI not installed …`
- `SKIPPED: Claude not authenticated (HTTP 401) …`
- `SKIPPED: Configured model "…" is unavailable (HTTP 404) …`
- `SKIPPED: Claude is rate-limited or out of quota (HTTP 429) …` — the
  selection rule treats a rate-limited reviewer as unavailable; the next gate
  in priority takes its place.
- `SKIPPED: No changes found for …`

An `ERROR: …` line with a non-zero exit means the gate ran and could not produce
a verdict; that is not a clean round.

## Handle findings

Same discipline as the other gate skills:

1. Map every hypothesis to the frozen contract and apply the P1 admission rule.
2. Verify its trigger and consequence; a reviewer severity is only a proposal.
3. Fix admitted P1 findings in one batch with only inseparable
   corrections justified below.
4. Self-review once.
5. Re-run the gate once if structural findings were fixed.
6. Record remaining dispositions in one final pass without editing the clean
   revision or running another gate round.

Treat every reported finding as `UNTRIAGED`. Admit P1 only after mapping it to
the frozen issue contract or an invariant, demonstrating a reachable trigger
and wrong consequence, explaining why the current artifact cannot safely
advance, and naming the minimal causal fix. Do not edit for an untriaged claim;
record structural P2 for the operator-owned merge boundary, and defer minor or
out-of-scope items without expanding the PR.

Record P2/minor observations without implementation; a lower-severity-only
verdict never reopens a clean revision. An inseparable correction may accompany
the minimal P1 fix only with recorded causal necessity, not merely a shared
file or an available review cycle.

Use the issue-wide allowance and finding record in `../afk/SKILL.md`
("Review-cycle allowance"). Initial review is comprehensive; re-review checks
accepted findings, the intervening diff, and affected regression paths. Broader
investigation requires specific evidence of an affected area. New evidenced
in-scope blockers remain reportable. Supply prior findings and verification
through supported context; missing context is unavailable, never invented.
Reviewer identity alone does not reopen a closed finding. Exhaustion leaves
unresolved work `OUTSTANDING`; finish the current cycle's validation without
starting another repair or requesting another round automatically.

Apply any invariant in `.afk/config.md` as an extra lens.

## Stop rule

Stop when the loop-termination rule in `../afk/SKILL.md` ("External gate")
holds: triage leaves no `UNTRIAGED`, `Contested`, or open admitted P1, and every
lower-severity item has a recorded disposition that does not block the role stamp (a
structural P2 may still bar auto-merge). That same verdict
earns the role stamp only if it requires no content change; a content fix
invalidates it and the role re-reviews the fixed revision.

Report `CLEAN`, or `OUTSTANDING` with what remains. A clean pass is not
authority to merge.

## Setup

Optional and self-skipping. Needs the Claude Code CLI installed and logged in,
plus Node and `git` on PATH. Uses the operator's existing Claude subscription —
no API key. Disable with `CLAUDE_REVIEW_GATE=off`.

Config knobs:

- `CLAUDE_REVIEW_MODEL` (default `claude-opus-5`)
- `CLAUDE_REVIEW_EFFORT` (default `medium`)
- `CLAUDE_REVIEW_MAX_CTX_BYTES` (default `400000`)
- `CLAUDE_GATE_BIN` — override the resolved `claude` binary

No fallback model is passed: a quiet downgrade to a weaker reviewer is a quality
regression with no visible symptom, so an unavailable model surfaces as a skip.

## The reviewer model is pinned, and checked against what answered

`CLAUDE_REVIEW_MODEL` must be a full model ID. An alias (`opus`, `sonnet`) is
resolved by the host and can select an older generation without a symptom —
`--model opus` answered as `claude-opus-4-8` while the pipeline required a
current generation — so an alias is refused before any call is spent.

The gate then reads `modelUsage` in the result envelope and requires the
requested identity to be present; a dated snapshot of the same model satisfies
it, and the auxiliary models a normal run also bills are ignored. A review whose
envelope names another generation, or names nothing, is discarded with an
`ERROR` rather than attributed to a model that may not have run. Neither case is
a clean round:

- `ERROR: cannot review — CLAUDE_REVIEW_MODEL "…" is an alias …`
- `ERROR: reviewer identity unverified — requested "…" but …`