/craft-review

name: review
description: "PR review skill - invokes pr-reviewer-expert agent against branch diff, story commits, or full project audit. Every run on your own work leaves a record in .craft/reviews/, clean or not, and every finding gets a proposed door; a review of someone else's PR leaves nothing in your project."

Review

Run a PR-style code review using the crystallized pr-reviewer-expert agent. Three approaches based on what you want reviewed.

Modes

| Mode | Trigger | What gets reviewed | |------|---------|-------------------| | **Branch** (default) | `/craft:review` | Everything this branch's pull request would contain, committed or not | | **Story** | `/craft:review story [name]` | Commits from a specific story | | **Project** | `/craft:review project [path]` | Full codebase or subsystem audit (no diffs) |

Optional focus flag: `--focus security|consistency|performance|correctness` (default: correctness + security)

Optional review strategy: `--maze` enables perpendicular maze review (architect generates questions, runner answers them). Without `--maze`, uses the existing single-agent generalist review.

Flow

Step 1: Determine Mode and Scope

**Parse args to determine review scope:**

• No args or `branch` → **Branch mode**
• `story` or `story <name>` → **Story mode**
• `project` or `project <path>` → **Project mode**

When the user says what to review in their own words, such as a PR link, a folder or "whatever would be in the PR", review exactly that, record it under the mode it fits, and tell the user in one line what you resolved it to. This matters because the user knows what they want reviewed, and the arguments above are shortcuts, not limits.

Extract `--focus` flag if present. Default focus is `correctness,security`.

**Whose code:** when the user asked to review a contribution that is not this project's own work (another author's PR, a fork, an upstream change), this is an **outside review**. Say so once, as the review starts, and run Steps 2 through 6 the same way, except that Step 5b is skipped and nothing is written under `.craft/`. Step 6 shows the same message without any `Proposed:` line, `On go:` block or `**Question:** Go?`, and ends after the last finding; the findings are the user's to carry to the PR. The user's words decide this; never infer it from commit authors. An outside review keeps every file it works with, the fetched diff, any batches and the reviewer reports, in your session's scratchpad directory, or a temp directory outside the project when there is none. It saves the close-out message there too, and names that file's full path in one line after the message. This matters because the project must end the review exactly as it started, and the findings are the user's to carry to the PR, so they need a home that outlives the terminal.

Step 2: Gather Context

**Always pre-load these files, and put each one whole in the agent prompt, because the reviewer, not you, decides which parts bear on the diff:**

1. `.craft/design/locked.md` - locked decisions the reviewer must respect 2. `.craft/project.md` - stack, patterns, conventions 3. `.craft/quality.yaml` - quality gates

Step 3: Gather Diff / Scope

**Branch mode:** review what this branch's pull request would contain: every change between the branch it will merge into and the working tree, committed or not, new files included, without staging anything. Find that base branch from the repository itself, or use the one the user names. Before the reviewer runs, tell the user in one line what you compared, how many files that covers and which of them are uncommitted. This matters because the developer reads the review as a review of their PR, and a change left out of the diff is a change nobody reviewed.

If nothing differs from the base, say so in one line naming the base, and stop there. No reviewer ran, so this exit writes no record.

**If diff exceeds ~500 lines**, split by directory or subsystem. Run the agent multiple times with scoped diffs rather than one massive prompt. Each batch reviewer gets the Step 4a prompt unchanged except for its diff; never limit which files its findings may land in, because only findings reach the developer reading the close-out. Tell the user:

> "Large diff ([N] lines across [M] files). I'll review in batches by directory to keep findings sharp."

**Story mode:**

If no story name provided, check `.craft/.global-state` for CURRENT_STORY. If none active, use AskUserQuestion to pick from completed/active stories in the current cycle.

# Read story file to find associated commits
# Look for commits that reference the story name
git log --oneline --all --grep="[story-name]"

# If no story-tagged commits found, ask user for commit range

Get cumulative diff across those commits. Also read the story file itself so the agent knows intent.

**Project mode:**

No diff. Instead gather:

• Directory tree of relevant source files
• If a path was specified, scope to that subtree
• The agent will do full file reads during its review

Step 4: Route - Standard or Maze

Check if `--maze` flag is present. If not, go to **Step 4a (Standard)**. If yes, go to **Step 4b (Maze)**.

---

Step 4a: Standard Review (no --maze)

**INVOKE the pr-reviewer-expert agent using the Agent tool.**

Build the prompt with:

1. **Mode** - what kind of review this is 2. **Context** - locked.md content, project.md content, quality.yaml content 3. **Diff** - the actual diff (branch/story modes) or file list (project mode) 4. **Changed files** - list of files that changed (branch/story modes) 5. **Commit messages** - so the agent understands intent 6. **Focus** - which lens to prioritize 7. **Story intent** - the story file content (story mode only)

**Prompt structure for the agent:**

You are reviewing code for [project name].

PLUGIN_ROOT: ${CLAUDE_PLUGIN_ROOT}
(The agent cannot resolve this variable itself - this line passes the resolved path.)

## Mode: