Claude Review

claude-review — Headless Claude Review

Get an independent review from Claude without burning tokens on a full Claude session. One claude --print call produces a structured report.

When To Invoke

Usage

~/.codex/skills/claude-review/scripts/claude-review <type> <file_or_dir> [--deep]

Examples:

# Review plan before implementation (auto-chains plan-eng-review)
~/.codex/skills/claude-review/scripts/claude-review plan ./docs/plan.md

# Architecture review with deep consultation (also chains office-hours)
~/.codex/skills/claude-review/scripts/claude-review architecture ./docs/design.md --deep

# Quality-check docs before shipping (single pass, no chain)
~/.codex/skills/claude-review/scripts/claude-review docs ./README.md

# Audit a work directory for buried failures
~/.codex/skills/claude-review/scripts/claude-review work-log ./.codexfree/

What Happens

1. Script validates inputs and resolves absolute path 2. Assembles a headless-mode prompt (no AskUserQuestion, single final report) 3. Calls claude --print --permission-mode bypassPermissions once 4. For plan / architecture: Claude auto-invokes its plan-eng-review skill in the same session and consolidates 5. For --deep (plan / architecture only): Claude additionally chains the office-hours skill 6. Report streamed to stdout AND saved to .claude-review/<timestamp>-<type>.md in the current working directory

All skill chaining happens inside ONE Claude session — you pay for one --print invocation regardless of how many sub-skills are chained.

Output Format

The report is always Markdown with this structure:

# Review Report — <type>
**Target:** <absolute path>
**Timestamp:** <UTC ISO>

## Executive Summary
...

## Critical Issues (must fix before proceeding)
...

## High-Priority Findings (should fix soon)
...

## Suggestions (nice to have)
...

## Chained: plan-eng-review  (only for plan/architecture)
...

## Chained: office-hours  (only with --deep)
...

## Decision
approve | revise | block
<1-2 sentence rationale>

Codex should read the report, treat revise findings as required fixes, then re-invoke the skill on the updated artifact. block means the artifact has fundamental problems and needs a rewrite, not a patch.

Decision Taxonomy

Why Headless?

Calling Claude interactively burns tokens on greetings, clarification, and tool overhead. --print mode:

• Single request → single response → exit
• All tool use happens inside one session
• No context carried across invocations
• Much lower token cost than a conversation

The tradeoff: Claude cannot ask follow-up questions. The script's prompt assumes sensible defaults and instructs Claude to produce a complete report in one pass.

Skill Chain Reference

docs and work-log don't chain because plan-eng-review is an architecture-review skill, not a copy-editing or audit skill.

Prerequisites

• claude CLI installed (npm install -g @anthropic-ai/claude-code)
• User is logged into Claude Code (claude --version works)
• For plan / architecture: the plan-eng-review skill must be installed in the user's Claude skill directory (part of the gstack plugin)
• For --deep: the office-hours skill must be installed

Files

• scripts/claude-review — main bash wrapper
• references/review-prompts.md — lens definitions for each review type (Claude reads these via the bash-assembled prompt)

Review Prompts Per Type

Claude reads this file as part of its headless prompt and applies the lens matching the requested type. Each lens focuses the review on issues that matter most for that artifact class.

Type: plan

You are reviewing an implementation plan that a developer or agent is about to execute. Your job is to catch problems BEFORE code is written, when fixes are cheap.

Apply this lens:

• Completeness — Are there gaps where steps are assumed to "just work"? Missing error handling paths? Missing tests? Missing rollback?
• Sequencing — Is the order correct? Are there hidden dependencies between tasks that aren't represented?
• Scope drift — Does the plan include work that doesn't serve the goal? Apply YAGNI.
• Ambiguity — Would two different engineers read this the same way? Flag anything that could be interpreted multiple ways.
• Risk surface — For each major step, what breaks if it fails? What's the blast radius? Is there a rollback?
• Testability — Is success verifiable? Are acceptance criteria concrete and checkable, or vague ("works correctly")?
• Verification gates — Where does the plan pause to verify before moving on? If nowhere, flag it.

Be concrete. Cite specific sections or line numbers. Don't hand-wave.

Type: architecture

You are reviewing an architecture or design document. Your job is to surface structural problems before they calcify into code.

Apply this lens:

• Coupling — Where are the hidden dependencies between components? What knows about what?
• Single responsibility — Does each component have one clear reason to exist? Or is it a bag of loosely related features?
• Interface clarity — Are module boundaries crisp? Are contracts (inputs, outputs, failure modes) well-defined?
• Failure modes — What happens when each component fails? Where are retries, timeouts, circuit breakers, fallbacks?
• Observability — Can you tell from outside what the system is doing right now? Logs, metrics, traces — is the story complete?
• Evolution — When requirements change (they will), where will this design hurt? What's hard to undo?
• Data flow — Trace one realistic request end-to-end. Does every step make sense? Where does data transform, and why?

Be concrete. Reference specific components or diagrams. If a diagram is missing, say so.

Type: docs

You are reviewing user-facing or API documentation for shipping readiness. Your job is to prevent users from being confused, misled, or stuck.

Apply this lens:

• Accuracy — Does the doc match the actual behavior of the code? Cite specific mismatches.
• Completeness — For each public API or feature: parameters, return values, side effects, error conditions. Anything missing?
• Ambiguity — Could any passage be read two ways? Flag each case with a concrete alternative interpretation.
• Examples — Is there at least one canonical example per concept? Do the examples actually work (read the code — don't assume)?
• Onboarding — Can a new user follow the doc end-to-end without outside context? Where do they get stuck?
• Deprecation / versioning — Are version constraints clear? Are breaking changes explicitly marked?
• Jargon — Is terminology defined before first use? Are there unnecessary internal names leaking?

Be concrete. Cite section headings and paragraph starts.

Type: work-log

You are auditing a work log (STATUS.md, errors.md, notes.md, or similar). Your job is to find failures that have been soft-pedaled, misreported, or silently dropped. Assume nothing — verify against evidence in the log itself and in the surrounding code if possible.

Apply this lens:

• Buried failures — Is there an "unresolved" item dressed up as "deferred" or "out of scope"?
• Silent retries — Are there loops where the same error appears multiple times with no root-cause fix, just "tried again"?
• Acceptance criteria drift — Did the original plan's success criteria quietly get watered down between phases?
• Missing errors — Based on what was built and tested, are there failures the log doesn't mention? Look for suspicious absence.
• State claims vs. reality — Does STATUS.md say "COMPLETED" for phases whose acceptance criteria you can't verify from the log?
• Handoff readiness — If someone had to pick up tomorrow with only these files, would they know what's done, what's broken, and what's next?
• Red flags — "Works on my machine", "should be fine", "will fix later", "good enough" — each of these is a potential hidden failure.

Be specific: cite file:line, phase numbers, and exact error messages from the log. Call out what's suspicious AND what's verified clean.