code-review

name	code-review
description	Review changes or PRs against project guidelines
allowed-tools	Read, Write, Grep, Glob, Bash

Code Review

Review local changes or pull requests against project guidelines. All output is written locally — never posted to GitHub.

Arguments

/code-review [target] [--output path]

Target (optional)

Specifies what to review. Can be:

• Nothing - auto-detect new commits on current branch vs main (default)
• Commit range - review specific commits (e.g., HEAD~3..HEAD, abc123..def456)
• Single commit - review one commit (e.g., HEAD~1, abc123)
• Branch comparison - review branch diff (e.g., main..feature/foo)
• PR number - review a pull request (e.g., #123 or 123)

Output (optional)

--output path or -o path - where to write the review:

• A folder name within .ai/ (e.g., issue-59-add-no-verify-option)
• A relative path (e.g., .ai/issue-59-add-no-verify-option)
• If omitted with auto-detect mode: auto-detects from branch name, writes to .ai/
• If omitted with explicit target: outputs directly to conversation (no file)
• If omitted with PR mode: auto-saves to .ai/ (see step 6)

Examples

# Auto-detect new commits vs main (writes to .ai/)
/code-review

# Auto-detect, specify output folder
/code-review --output issue-59-add-no-verify-option
/code-review -o .ai/my-feature

# Review specific commits (outputs to conversation)
/code-review HEAD~3..HEAD
/code-review abc123
/code-review main..feature/foo

# Review commits and save to file
/code-review HEAD~5..HEAD --output code-audit

# Review a pull request (auto-saves to .ai/)
/code-review #123
/code-review 123

Instructions

1. Parse Arguments

   • Check if a commit/range target was provided
   • Check if the target is a PR number (#123 or bare 123 that isn't a valid git ref)
   • Check if --output or -o flag was provided
   • Determine review mode: "auto-detect" (default), "explicit", or "pr"

2. Gather Context

   For auto-detect mode (no target specified):

   • Get current branch name
   • Find associated workflow folder in .ai/
   • Read the original issue/concept and plan if available

   For explicit mode (commit/range target specified):

   • Validate the commit range/ref exists
   • No workflow folder lookup needed

   For PR mode (PR number specified):

   • Fetch PR metadata:

     gh pr view <number> --json title,author,baseRefName,headRefName,headRefOid,number
     

   • No workflow folder lookup needed

3. Detect and Get Changes

   For auto-detect mode:

   • Determine the main branch: run git config gitflow.branch.main.name (fallback to main)
   • Detect new commits: run git log <main>..HEAD --oneline
   • If no new commits exist, inform the user and stop
   • Get the diff for those commits: git diff <main>...HEAD
   • List the commits being reviewed

   For explicit mode:

   • If range (contains ..): git diff <range> and git log <range> --oneline
   • If single commit: git show <commit> --stat and git log -1 <commit>

   For PR mode:

   • Get the full diff: gh pr diff <number>
   • Get the commit list: gh pr view <number> --json commits --jq '.commits[].oid'
   • List all modified files from the diff

   For all modes:

   • List all modified files

Issue Categories

Categorize findings using the severity levels defined in REVIEW_CRITERIA.md (Must fix, Should fix, Nit).