# Review

> |

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

## Install

```sh
agentstack add skill-nc9-skills-review
```

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

## About

# Review

Local, high-signal code review. The skill builds a bundle of context on disk,
hands it to Codex via MCP, and renders the structured JSON verdict back to
the user.

## When to Use

- User says "review", "/review", "review my changes".
- Before committing non-trivial work.
- Before opening a PR.
- After addressing review feedback — to confirm resolution.

## Workflow

### 1. Assemble the bundle

Run `prepare` to gather disk-side context (git diff, issues, plan, conventions).
It prints the bundle directory path as the last line of stdout.

```bash
./scripts/review prepare \
  --issues "#123,PROJ-456" \
  --plan ./plan.md \
  --title "Refactor auth flow"
```

`prepare` writes:

- `CHANGES.diff` — the unified diff
- `CHANGED_FILES.txt` — touched paths
- `ISSUES.md` — fetched GitHub / Linear / Sentry context
- `PLAN.md` — `--plan` argument or most recent `~/.claude/plans/*.md`
- `CONVENTIONS.md` — repo `REVIEW.md` + `CLAUDE.md` + user `~/.claude/CLAUDE.md`
- `REFERENCED_FILES.md` — contents of `--files` paths
- `AGENT_CONTEXT.md` — **placeholder; you fill this in next**
- `REVIEW_PROMPT.md` — the full reviewer prompt (copied from this skill)
- `MANIFEST.json` — file list + metadata

Default source: uncommitted changes if any exist, otherwise prompts for a base
branch or commit.

### 2. Write AGENT_CONTEXT.md

Only you (the agent) have the conversation context. Overwrite the placeholder
`/AGENT_CONTEXT.md` with what's not on disk:

- **User request** — quote the original ask and any clarifying turns.
- **User feedback** — corrections, preferences, course-corrections during the
  work.
- **Plan iteration** — key decisions and tradeoffs that shaped the change,
  especially things not captured in the plan file.
- **Task summary** — one-paragraph description of what was built and why.

Be concrete. This is the canonical statement of intent the reviewer uses for
spec-conformance judgments.

### 3. Invoke Codex via MCP

Read `/REVIEW_PROMPT.md` and pass its contents to `mcp__codex__codex`
along with the bundle path. Recommended config:

```json
{
  "approval-policy": "never",
  "sandbox": "workspace-write"
}
```

Prompt shape:

> {REVIEW_PROMPT.md contents}
>
> Review bundle directory: ``
>
> Read every file in that directory (check MANIFEST.json for the list) before
> producing your JSON response.

Capture the returned `threadId` from `structuredContent.threadId`.

### 4. Verification pass (required)

Call `mcp__codex__codex-reply` with the same `threadId`:

> For each issue you returned, re-read the file and lines cited in `evidence`.
> Drop any finding where the citation does not substantiate the claim (wrong
> file, wrong line, code doesn't match the description, or you inferred from
> naming rather than reading). Return the updated JSON object — same schema,
> only verified findings. Recompute `severity_counts` and `score` accordingly.

This single step is the biggest quality lever — it suppresses hallucinated
findings that name functions or lines that don't exist.

### 5. Parse, persist, render

- Parse the final JSON. If Codex wrapped it in prose or code fences, strip
  them and retry parsing; if it still doesn't parse, send one more
  `codex-reply` asking for valid JSON only.
- Write the verified JSON to `/review.json`.
- Render a human summary to the user:
  - Score + verdict headline (e.g. `4/5 — ready-with-nits`).
  - One-line `summary`.
  - `spec_alignment` paragraph.
  - Issues grouped by severity (critical → high → medium → nit →
    pre_existing), each with `title`, `files[].path:lines`, and one-line
    description. Deep-dive details available in `review.json`.
  - `strengths` and `improvements` bullets if present.
  - Path to `` so the user can inspect raw artifacts.

Keep the rendered output terse — the user can read `review.json` for detail.

## Fallback: Codex MCP unavailable

If `mcp__codex__codex` isn't loaded in the session, fall back to the Codex
CLI with the same bundle:

```bash
codex exec \
  --cd  \
  --sandbox workspace-write \
  --ask-for-approval never \
  "$(cat /REVIEW_PROMPT.md)

Review bundle directory: 
Read every file in that directory before producing your JSON response."
```

Then run a second `codex exec` against the same working directory for the
verification pass, referencing the JSON written in step 1. Parse and render
as in step 5.

## Output schema

See `REVIEW_PROMPT.md` for the full schema. Summary:

```json
{
  "score": 0,
  "verdict": "ship | ready-with-nits | needs-changes | significant-changes | rethink",
  "summary": "...",
  "severity_counts": { "critical": 0, "high": 0, "medium": 0, "nit": 0, "pre_existing": 0 },
  "spec_alignment": "...",
  "issues": [
    {
      "id": "R-001",
      "severity": "critical | high | medium | nit | pre_existing",
      "category": "bug | security | spec | performance | maintainability | tests",
      "title": "...",
      "description": "...",
      "files": [{ "path": "...", "lines": "..." }],
      "suggested_fix": "...",
      "confidence": "high | medium | low",
      "evidence": "file:line — justification"
    }
  ],
  "strengths": [],
  "improvements": []
}
```

### Verdict ladder

| Score | Verdict | Meaning |
|-------|---------|---------|
| 5 | `ship` | No blockers — commit as-is |
| 4 | `ready-with-nits` | Commit OK — address nits when convenient |
| 3 | `needs-changes` | Address feedback before commit |
| 2 | `significant-changes` | Non-trivial rework required |
| 0-1 | `rethink` | Design/spec-level concerns |

## Command

```bash
./scripts/review prepare [OPTIONS]
```

## Options

| Option | Description |
|--------|-------------|
| `--base, -b BRANCH` | Compare against branch |
| `--uncommitted, -u` | Review staged/unstaged/untracked changes (default when changes exist) |
| `--commit, -c SHA` | Review specific commit |
| `--issues, -i REFS` | Issue refs (comma-separated): `#123`, `PROJ-456`, `sentry:12345`, or URLs |
| `--plan, -p PATH` | Plan file path (default: most recent `~/.claude/plans/*.md`) |
| `--files, -f PATHS` | Additional files (comma-separated) |
| `--title, -t TEXT` | Commit/PR title recorded in `MANIFEST.json` |
| `--bundle-dir PATH` | Override bundle location (default: `~/.claude/review-bundles/`) |

## Requirements

- `mcp__codex__codex` + `mcp__codex__codex-reply` tools loaded (preferred), **or**
  `codex` CLI installed and authenticated (fallback).
- Codex MCP server: set `client_session_timeout_seconds` high (e.g. `360000`)
  in your MCP client config — reviews routinely run many minutes.
- `gh` CLI for GitHub issues.
- `LINEAR_API_KEY` (optional) for Linear issues.
- `SENTRY_AUTH_TOKEN`, `SENTRY_ORG` (optional) for Sentry issues.

## Per-repo customization — REVIEW.md

Drop a `REVIEW.md` at the repo root to inject house rules (skip paths, nit
caps, mandatory checks). It concatenates into `CONVENTIONS.md` in every bundle
and overrides the generic prompt where they conflict. See `REVIEW.md.example`
in this skill for a template.

## Examples

```bash
# Most common: review uncommitted changes, auto-pick latest plan
./scripts/review prepare

# Explicitly review staged/unstaged, include linked issue
./scripts/review prepare --uncommitted --issues "#142"

# Review the last commit
./scripts/review prepare --commit HEAD

# Branch-diff review against main
./scripts/review prepare --base main
```

## Source & license

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

- **Author:** [nc9](https://github.com/nc9)
- **Source:** [nc9/skills](https://github.com/nc9/skills)
- **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-nc9-skills-review
- Seller: https://agentstack.voostack.com/s/nc9
- 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%.