# Peer Review

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-kenwilliford-claude-peer-review-claude-peer-review`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kenwilliford](https://agentstack.voostack.com/s/kenwilliford)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kenwilliford](https://github.com/kenwilliford)
- **Source:** https://github.com/kenwilliford/claude-peer-review

## Install

```sh
agentstack add skill-kenwilliford-claude-peer-review-claude-peer-review
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Peer Review Skill

## Purpose

Run a multi-round scientific peer review process where:
- **External model** acts as Reviewer (critical evaluation)
- **Claude** acts as Author (responds to feedback, revises)
- **Human** acts as Editor (makes final GO/NO-GO decision based on artifacts)

The skill detects available reviewer CLIs and lets the user choose which model
to use as the reviewer. Communication uses direct pipe-and-capture — the
reviewer CLI is invoked with the full prompt and its stdout is captured as the
review. The default is 2 rounds, but more can be requested.

## Invocation

```
/peer-review  [--output-dir=] [--rounds=] [--auto-go] [--reviewer=]
```

**Arguments:**
- ``: Path to the plan/spec/design document to review
- `--output-dir`: Directory for review artifacts (default: same as plan file)
- `--rounds`: Number of review rounds (default: 2)
- `--auto-go`: Autonomous mode — skip model selection (Step 0) and Editor Decision (Step 6). Runs rounds until the reviewer issues GO, or hits the round cap. Proceeds directly to finalization (Step 7). Requires `--reviewer`.
- `--reviewer`: Specify reviewer CLI to use (e.g., `codex`, `gemini`, `claude`). Required when `--auto-go` is set. Skips the interactive model selection in Step 0.

## Workflow

```
┌─────────────────────────────────────────────────────────────────────┐
│                    STEP 0: MODEL SELECTION                          │
├─────────────────────────────────────────────────────────────────────┤
│  [Claude]    Detects available CLIs → asks user to choose reviewer  │
├─────────────────────────────────────────────────────────────────────┤
│                    ROUND 1 .. N (default N=2)                       │
├─────────────────────────────────────────────────────────────────────┤
│  [Claude]    Constructs prompt → pipes to reviewer CLI              │
│      ↓                                                              │
│  [Reviewer]  Reads prompt (plan + prior artifacts) → outputs review │
│      ↓                                                              │
│  [Claude]    Captures stdout → writes plan-reviewN.md               │
│              Analyzes review → writes plan-reviewN-response.md      │
│      ↓                                                              │
│  If reviewer issues NO-GO with Critical findings AND rounds remain: │
│      → continue to next round automatically                         │
│  Else if final round reached:                                       │
│      → proceed to Editor Decision                                   │
├─────────────────────────────────────────────────────────────────────┤
│                      EDITOR DECISION                                │
├─────────────────────────────────────────────────────────────────────┤
│  [Human]     Presented with structured options:                     │
│              GO — proceed to implementation                         │
│              Additional round — run another review round             │
│              Different reviewer — switch to a different model        │
│              NO-GO — abandon or rework outside this process          │
├─────────────────────────────────────────────────────────────────────┤
│                      FINALIZATION (on GO)                            │
├─────────────────────────────────────────────────────────────────────┤
│  [Claude]    Produces -revised.md incorporating all accepted  │
│              revisions from every round into the original plan       │
└─────────────────────────────────────────────────────────────────────┘
```

## Output Artifacts

For N rounds, the following files are produced:

| File | Author | Contains |
|------|--------|----------|
| `-review.md` | Reviewer | Round 1 review with GO/NO-GO |
| `-review-response.md` | Claude | Round 1 response addressing all concerns |
| `-review2.md` | Reviewer | Round 2 review with GO/NO-GO |
| `-review2-response.md` | Claude | Round 2 response |
| `-review.md` | Reviewer | Round N review (if additional rounds) |
| `-review-response.md` | Claude | Round N response |
| `-revised.md` | Claude | **Revised spec** — final output incorporating all accepted changes |

The `*-revised.md` is the implementation-ready document. The review/response
pairs are the audit trail showing how it got there.

## Execution Steps

### Step 0: Detect Available Reviewers and Ask User

**If `--auto-go` is set:** Skip this step entirely. Use the CLI specified by
`--reviewer` (e.g., `--reviewer=codex` uses the `codex` CLI). Proceed to Step 1.

When invoked without `--auto-go`, Claude MUST detect which reviewer CLIs are
available and present a choice to the user. **Do NOT skip this step. Do NOT
default to self-review.**

**Detection commands** (run in parallel):

```bash
which codex 2>/dev/null && codex --version 2>&1    # Codex CLI
which gemini 2>/dev/null && gemini --version 2>&1   # Gemini CLI
which claude 2>/dev/null && claude --version 2>&1   # Claude CLI (separate instance)
```

**Detect Codex default model** (if codex is available):

```bash
grep '^model ' ~/.codex/config.toml 2>/dev/null | head -1 | sed 's/model *= *"\(.*\)"/\1/'
```

If this returns a model name, use it in the Codex option label. If it fails or
returns empty, fall back to displaying just "Codex" without a model name.

**Present options** using AskUserQuestion with header "Reviewer":

- For each detected CLI, list it as an option with model info
- Always include "Claude (self-review)" as last option — but label it clearly
  as single-model review (less rigorous than cross-model)
- Recommend cross-model options first

Example options (model name is detected dynamically):
- `Codex ()` — "Cross-model review using OpenAI reasoning model"
- `Gemini` — "Cross-model review using Google model"
- `Claude (self-review)` — "Same-model review — less diversity of perspective"

**If user selects Gemini**, ask a follow-up question for model choice with
header "Model":
- `gemini-2.5-pro (Recommended)` — "Strong reasoning, default model"
- `gemini-2.5-flash` — "Faster, lower quota usage"
- `gemini-3-pro` — "Highest quality (requires previewFeatures enabled)"

### Step 1: Read Plan and Prepare

After user selects reviewer:

1. Read the plan file (error if not found)
2. Read `references/REVIEW_TEMPLATE.md` for the review format
3. **Check for existing artifacts:** Look for `-review.md` and
   `-review-response.md` in the output directory. If found, ask the user
   via AskUserQuestion with header "Resume" and options:
   - `Resume at Round 2` — "Round 1 artifacts found, continue from where you left off"
   - `Start fresh` — "Discard existing artifacts and begin Round 1"
   If resuming, skip to the appropriate round with existing artifacts loaded.
4. Construct the reviewer prompt (see "Reviewer Prompt Construction" below)
5. Display: "Review initiated. Launching [Model] reviewer..."

### Step 2: Launch Reviewer (Round 1)

Write the constructed prompt to a temp file, then pipe it via stdin to the
selected reviewer CLI. Wrap each invocation in a 5-minute timeout.

**Why temp file + stdin:** Passing the prompt as a CLI argument would hit
argument length limits and break on shell metacharacters in the plan content.
Using a heredoc with quoted delimiter (`'PROMPT_EOF'`) prevents shell expansion.

```bash
# Write prompt to temp file (quoted delimiter prevents shell expansion)
PROMPT_FILE=$(mktemp /tmp/peer-review-XXXXXX.md)
cat > "$PROMPT_FILE" 
PROMPT_EOF
```

Then invoke the reviewer CLI using stdin redirection:

#### Codex

```bash
timeout 300 codex exec --full-auto -  -review.md`
2. Analyze each finding
3. Describe revisions in the response document (see "Plan Immutability" below)
4. Write `-review-response.md` using response template
5. If reviewer issued NO-GO with Critical findings AND more rounds remain,
   display: "Round 1 complete. Critical issues found — launching Round 2..."
   Otherwise display: "Round 1 complete. Launching Round 2 review..."

**If timeout or CLI failure:** Display error with the specific reviewer CLI
that failed and suggest troubleshooting. **Do NOT fall back to self-review
silently.**

#### Plan Immutability During Review

Claude MUST NOT modify the original plan file during the review rounds. All
revisions are described in the response documents (`*-review-response.md`).
The "original plan" passed to subsequent rounds is always the unmodified
original.

**After the editor says GO**, Claude produces a separate `-revised.md`
that incorporates all accepted revisions into the original plan (see Step 7).
The original file is preserved as part of the audit trail.

**Rationale:** Keeping the original stable during review means reviewers in
later rounds see a consistent base document plus explicit change descriptions,
rather than a moving target.

### Step 4: Launch Reviewer (Round 2+)

Construct a follow-up round prompt that includes:
- The original plan (unmodified — see Plan Immutability)
- All prior review and response artifacts
- Instructions to assess whether concerns were addressed

Pipe to the same reviewer CLI using the same temp-file + stdin pattern as Step 2.

Repeat Steps 4–5 for each round up to the configured round cap.

### Step 5: Process Follow-up Review

After capturing the reviewer's stdout for round N:

1. Save as `-review.md` (e.g., `-review2.md`)
2. Analyze concerns (focusing on residual issues)
3. Describe revisions in the response document (do not modify the original plan)
4. Write `-review-response.md`
5. If more rounds remain AND reviewer issued NO-GO with Critical findings,
   continue to next round automatically
6. If this is the final round, proceed to Step 6

### Step 6: Editor Decision

**If `--auto-go` is set:** Skip this step. Instead, check the reviewer's
assessment from the final round:
- If the reviewer issued **GO** or **CONDITIONAL GO**: proceed directly to Step 7
  (finalization).
- If the reviewer issued **NO-GO** and the round cap has not been reached:
  continue to the next round (loop back to Step 4).
- If the reviewer issued **NO-GO** and the round cap has been reached: proceed
  to Step 7 anyway — produce the revised spec incorporating all accepted
  revisions. The parent process can decide what to do with the result.

When invoked without `--auto-go`, present the human with a structured decision
using AskUserQuestion with header "Editor Decision":

- `GO — proceed to implementation` — "Review complete, plan is ready"
- `Additional round — run another review round` — "Extend the review by one more round"
- `Different reviewer — switch to a different model` — "Re-run with a different reviewer CLI"
- `NO-GO — abandon or rework outside this process` — "Stop review, plan needs significant rework"

Also display:
- Summary of all review rounds (findings count, assessments)
- Final GO/NO-GO from the reviewer (identify which model reviewed)
- Path to the final `*-response.md` for detailed review

If the user selects "Additional round," increment the round cap by 1 and loop
back to Step 4. If "Different reviewer," return to Step 0 (model selection).

### Step 7: Finalize Revised Spec

When the editor selects **GO**, Claude produces the revised spec:

1. Start from the original plan content
2. Walk through every response document in order, applying all revisions with
   disposition **Accepted** or **Partially Accepted**
3. Skip revisions with disposition **Acknowledged** or **Contested** (these
   were noted but not adopted)
4. Write the result as `-revised.md` in the output directory
5. Display: "Revised spec written to `-revised.md`"

The revised spec should read as a clean, standalone document — not a diff or
changelog. It is the implementation-ready artifact.

**What stays unchanged:** The original plan file and all review/response
artifacts remain untouched. They form the audit trail showing how the
revised spec was derived.

## Reviewer Prompt Construction

The reviewer prompt sent to the external CLI MUST include:

1. **Role description**: "You are a peer reviewer..."
2. **Plan content**: The full plan text (inline in the prompt)
3. **Review format**: The structured review template (from `references/REVIEW_TEMPLATE.md`)
4. **Output instructions**: Write the review directly to stdout

**Round 1 Template:**

```
You are a scientific peer reviewer. Your task is to critically evaluate the
plan document below and write a structured review.

Read the plan carefully, then write your review following the template format
at the end. Output your review directly — nothing else.

Be rigorous, specific, and constructive. Every concern must include a
concrete recommendation. Acknowledge strengths as well as problems. Include
a GO/NO-GO assessment.

## Plan Document

{PLAN_CONTENT}

## Review Format

{REVIEW_TEMPLATE_CONTENT}
```

**Follow-up Round Template (Round 2+):**

```
You are a scientific peer reviewer conducting a follow-up review round.

In prior rounds, you reviewed the plan and raised concerns. The author has
responded and described revisions. Your task is to:

1. Assess whether prior concerns were adequately addressed
2. Identify any new issues introduced by revisions
3. Evaluate residual risk
4. Provide a GO/NO-GO assessment

Output your review directly — nothing else.

## Original Plan

{PLAN_CONTENT}

## Prior Review and Response Artifacts

{ALL_PRIOR_ARTIFACTS}

## Review Format

{REVIEW_TEMPLATE_CONTENT}

In addition to the standard review sections, include a "Prior Concern
Resolution" table at the top of your findings:

| Finding | Status | Notes |
|---------|--------|-------|
| F1 | Resolved / Partially Resolved / Unresolved | [Brief note] |
```

## Review Document Format

See `references/REVIEW_TEMPLATE.md` for the review format.
See `references/RESPONSE_TEMPLATE.md` for the response format.
See `references/CODEX_INSTRUCTIONS.md` for detailed reviewer role description.

## GO/NO-GO Criteria

Each review and response MUST include a GO/NO-GO assessment:

| Assessment | Meaning |
|------------|---------|
| **GO** | Plan is sound, ready for implementation |
| **CONDITIONAL GO** | Minor issues that can be addressed during implementation |
| **NO-GO** | Significant issues that must be resolved before proceeding |

## Error Handling

| Scenario | Action |
|----------|--------|
| No external CLI available | Warn user; offer Claude self-review with clear labeling |
| Reviewer CLI fails to start | Display error with CLI name; do NOT silently self-review |
| Reviewer timeout (5 min) | Display timeout error; suggest checking CLI auth/config |
| Plan file not found | Error with helpful message |
| Empty reviewer output | Display warning; reviewer may have failed silently |

**CRITICAL: Never silently fall back to Claude self-review.** If the selected
external reviewer fails, report the failure and let the user decide next steps.

## Prerequisites Per Reviewer

### Codex
- `codex` CLI installed (`npm install -g @openai/codex` or via bun)
- OpenAI API authentication (`codex login`)

### Gemini
- `gemini` CLI installed (`npm install -g @google/gemini-cli@latest`)
- Google AI API key or Google OAuth authentication

### Claude CLI (self-review)
- `claude` CLI installed

## Example Usage

```bash
# Invoke peer review (will detect available CLIs and ask)
/peer-review docs/specs/PDS_INGESTION_SPEC.md

# With custom output directory
/peer-review specs/NEW_FEATURE.md --output-dir=reviews/

# With 3 review rounds
/peer-review specs/COMPLEX_FEATURE.md --rounds=3

# Autonomous mode (no human interaction — for use in automation)
/peer-review specs/FEATURE.md --auto-go --reviewer=codex
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kenwilliford](https://github.com/kenwilliford)
- **Source:** [kenwilliford/claude-peer-review](https://github.com/kenwilliford/claude-peer-review)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kenwilliford-claude-peer-review-claude-peer-review
- Seller: https://agentstack.voostack.com/s/kenwilliford
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.