om-scogo Code Review Skill
Purpose: Enforce automated code reviews as a mandatory guardrail before every commit and deployment. Choose between Claude, OpenAI Codex, Google Gemini, or multiple engines for comprehensive analysis.
Sub-skills:
- adr-gate.md — Pre-review ADR and spec enforcement
Pre-Review: ADR Gate (Mandatory)
Before any review engine runs, the ADR gate executes automatically:
- Classify — trivial changes (typos, deps, tests-only) skip the gate
- Discover — scan
docs/adr/,_project_specs/, iCPG ReasonNodes, git history for linked ADRs and specs - Enforce — if no ADRs found for non-trivial changes:
- Interactive (default): draft ADR from git history, ask user to confirm
- Unattended (CI): write as
Status: proposed, proceed - Strict: block review until ADR exists
- Inject — feed discovered ADRs + specs into the review prompt as architectural context
ADR Compliance Review Dimension
Added to the standard 7 review categories:
| Category | What It Checks |
|---|---|
| ADR Compliance | Change conforms to documented decisions, no undocumented architectural shifts |
| Finding | Severity |
|---|---|
| Change contradicts accepted ADR | Critical |
| Architectural decision not in any ADR | High |
| ADR exists but is outdated/stale | Medium |
| Minor drift from ADR intent | Low |
See adr-gate.md for full protocol, reverse-engineering rules, and configuration.
Review Engine Choice
When running /code-review, users can choose their preferred review engine:
┌─────────────────────────────────────────────────────────────────┐
│ CODE REVIEW - Choose Your Engine │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ○ Claude (default) │
│ Built-in, no extra setup, full conversation context │
│ │
│ ○ OpenAI Codex CLI │
│ GPT-5.2-Codex specialized for code review, 88% detection │
│ Requires: npm install -g @openai/codex │
│ │
│ ○ Google Gemini CLI │
│ Gemini 2.5 Pro with 1M token context, free tier available │
│ Requires: npm install -g @google/gemini-cli │
│ │
│ ○ Dual Engine (any two) │
│ Run two engines, compare findings, catch more issues │
│ │
│ ○ All Three (maximum coverage) │
│ Run Claude + Codex + Gemini for critical/security code │
│ │
└─────────────────────────────────────────────────────────────────┘
Engine Comparison
| Aspect | Claude | Codex | Gemini | Multi-Engine |
|---|---|---|---|---|
| Setup | None | npm + OpenAI API | npm + Google Account | All setups |
| Speed | Fast | Fast | Fast | 2-3x time |
| Context | Conversation | Fresh per review | 1M tokens | N/A |
| Detection | Good | 88% (best) | 63.8% SWE-Bench | Combined |
| Free Tier | N/A | Limited | 1,000/day | Varies |
| Best for | Quick reviews | High accuracy | Large codebases | Critical code |
Set Default Engine
# ~/.claude/settings.toml or project CLAUDE.md
[code-review]
default_engine = "claude" # Options: claude, codex, gemini, dual, all
Usage Examples
# Use default engine
/code-review
# Explicitly choose engine
/code-review --engine claude
/code-review --engine codex
/code-review --engine gemini
# Dual engine (pick any two)
/code-review --engine claude,codex
/code-review --engine claude,gemini
/code-review --engine codex,gemini
# All three engines
/code-review --engine all
# Quick shortcuts
/code-review # Uses default
/code-review --codex # Use Codex
/code-review --gemini # Use Gemini
/code-review --all # All three engines
Multi-Engine Output
When using multiple engines, findings are compared and deduplicated:
Dual Engine Example
┌─────────────────────────────────────────────────────────────────┐
│ CODE REVIEW RESULTS - DUAL ENGINE (Claude + Codex) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ✅ AGREED (Found by both): │
│ 🔴 SQL injection in auth.ts:45 │
│ 🟡 Missing error handling in api.ts:112 │
│ │
│ 🔷 CLAUDE ONLY: │
│ 🟠 Potential race condition in worker.ts:89 │
│ 🟢 Consider extracting helper function │
│ │
│ 🔶 CODEX ONLY: │
│ 🟠 Memory leak - unclosed stream in upload.ts:34 │
│ 🟡 N+1 query pattern in orders.ts:156 │
│ │
├─────────────────────────────────────────────────────────────────┤
│ SUMMARY │
│ Agreed: 2 | Claude only: 2 | Codex only: 2 │
│ Critical: 1 | High: 2 | Medium: 2 | Low: 1 │
│ Status: ❌ BLOCKED - Fix critical/high issues │
└─────────────────────────────────────────────────────────────────┘
Triple Engine Example (All Three)
┌─────────────────────────────────────────────────────────────────┐
│ CODE REVIEW RESULTS - TRIPLE ENGINE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ✅ UNANIMOUS (All 3 found): │
│ 🔴 SQL injection in auth.ts:45 │
│ │
│ ✅ MAJORITY (2 of 3 found): │
│ 🟠 Memory leak - unclosed stream in upload.ts:34 (Codex+Gemini)│
│ 🟡 Missing error handling in api.ts:112 (Claude+Codex) │
│ │
│ 🔷 CLAUDE ONLY: │
│ 🟠 Potential race condition in worker.ts:89 │
│ │
│ 🔶 CODEX ONLY: │
│ 🟡 N+1 query pattern in orders.ts:156 │
│ │
│ 🟢 GEMINI ONLY: │
│ 🟡 Consider using batch API for better performance │
│ 🟢 Type could be more specific in types.ts:23 │
│ │
├─────────────────────────────────────────────────────────────────┤
│ SUMMARY │
│ Unanimous: 1 | Majority: 2 | Single: 5 │
│ Critical: 1 | High: 2 | Medium: 3 | Low: 2 │
│ Status: ❌ BLOCKED - Fix critical/high issues │
└─────────────────────────────────────────────────────────────────┘
When to Use Each Mode
| Mode | Use When |
|---|---|
| Single (Claude) | Quick in-flow reviews, exploration |
| Single (Codex) | CI/CD automation, high accuracy needed |
| Single (Gemini) | Large codebases (100+ files), free tier |
| Dual | Important PRs, pre-merge reviews |
| Triple (All) | Security-critical code, payment systems, auth |
Core Philosophy
┌─────────────────────────────────────────────────────────────────┐
│ CODE REVIEW IS NON-NEGOTIABLE │
│ ───────────────────────────────────────────────────────────── │
│ │
│ Every commit must pass code review. │
│ Every PR must be reviewed before merge. │
│ Every deployment must include review sign-off. │
│ │
│ AI catches what humans miss. Humans catch what AI misses. │
│ Together: fewer bugs, cleaner code, better security. │
├─────────────────────────────────────────────────────────────────┤
│ INVOKE: /code-review │
│ PLUGIN: code-review@claude-plugins-official │
└─────────────────────────────────────────────────────────────────┘
When to Run Code Review
Mandatory Review Points
| Trigger | Action | Command |
|---|---|---|
| Before commit | Review staged changes | /code-review |
| Before PR | Review all changes vs base | /code-review |
| Before merge | Final review of PR | /code-review |
| Before deploy | Review deployment diff | /code-review |
Automatic Integration
Run code review automatically before every commit:
┌─────────────────────────────────────────────────────────────────┐
│ COMMIT WORKFLOW │
│ ───────────────────────────────────────────────────────────── │
│ │
│ 1. Write code │
│ 2. Run tests (TDD - must pass) │
│ 3. Run /code-review ← MANDATORY │
│ 4. Address critical/high issues │
│ 5. Commit │
│ 6. Push │
│ │
│ Skip step 3? ❌ NO COMMIT ALLOWED │
└─────────────────────────────────────────────────────────────────┘
Using the Code Review Plugin
Basic Usage
# Review current changes
/code-review
# Review specific files
/code-review src/auth/*.ts
# Review a PR
/code-review --pr 123
# Review with specific focus
/code-review --focus security
/code-review --focus performance
/code-review --focus architecture
Review Categories
The code review plugin analyzes:
| Category | What It Checks |
|---|---|
| Security | Vulnerabilities, injection risks, auth issues, secrets |
| Performance | N+1 queries, memory leaks, inefficient algorithms |
| Architecture | Design patterns, SOLID principles, coupling |
| Code Quality | Readability, complexity, duplication |
| Best Practices | Language idioms, framework conventions |
| Testing | Coverage gaps, test quality, edge cases |
| Documentation | Missing docs, outdated comments |
Severity Levels
| Level | Action Required | Can Commit? |
|---|---|---|
| 🔴 Critical | Must fix immediately | ❌ NO |
| 🟠 High | Should fix before commit | ❌ NO |
| 🟡 Medium | Fix soon, can commit | ✅ YES |
| 🟢 Low | Nice to have | ✅ YES |
| ℹ️ Info | Suggestions only | ✅ YES |
Pre-Commit Hook Integration
Install Pre-Commit Hook
#!/bin/bash
# .git/hooks/pre-commit
echo "🔍 Running code review..."
# Run Claude code review on staged files
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx|py|go|rs)$')
if [ -n "$STAGED_FILES" ]; then
# Invoke code review (requires claude CLI)
claude --print "/code-review $STAGED_FILES" > /tmp/code-review-result.txt 2>&1
# Check for critical/high issues
if grep -q "🔴\|Critical\|🟠\|High" /tmp/code-review-result.txt; then
echo "❌ Code review found critical/high issues:"
cat /tmp/code-review-result.txt
echo ""
echo "Fix these issues before committing."
exit 1
fi
echo "✅ Code review passed"
fi
exit 0
Make Hook Executable
chmod +x .git/hooks/pre-commit
Codex CLI Setup (For Codex/Both Modes)
If you want to use Codex or Both modes, install the Codex CLI:
# Prerequisites: Node.js 22+
node --version # Must be 22+
# Install Codex CLI
npm install -g @openai/codex
# Authenticate (choose one):
# Option 1: ChatGPT subscription (Plus, Pro, Team, Enterprise)
codex # Follow prompts to sign in
# Option 2: API key
export OPENAI_API_KEY=sk-proj-...
Verify Installation
# Check Codex is installed
codex --version
# Test review
codex
> /review
See codex-review.md skill for full Codex documentation.
Gemini CLI Setup (For Gemini/Multi-Engine Modes)
If you want to use Gemini or multi-engine modes, install the Gemini CLI:
# Prerequisites: Node.js 20+
node --version # Must be 20+
# Install Gemini CLI
npm install -g @google/gemini-cli
# Or via Homebrew (macOS)
brew install gemini-cli
# Install Code Review extension
gemini extensions install https://github.com/gemini-cli-extensions/code-review
Authenticate
# Option 1: Google Account (recommended, 1000 req/day free)
gemini # Follow browser login prompts
# Option 2: API key (100 req/day free)
export GEMINI_API_KEY="your-key-from-aistudio.google.com"
Verify Installation
# Check Gemini is installed
gemini --version
# List extensions
gemini extensions list
# Test review
gemini
> /code-review
See gemini-review.md skill for full Gemini documentation.
CI/CD Integration
GitHub Actions - Claude Only
# .github/workflows/code-review.yml
name: Code Review
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
code-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Get changed files
id: changed-files
run: |
echo "files=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | tr '\n' ' ')" >> $GITHUB_OUTPUT
- name: Run Claude Code Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
npx @anthropic-ai/claude-code --print "/code-review ${{ steps.changed-files.outputs.files }}" > review.md
- name: Post Review Comment
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const review = fs.readFileSync('review.md', 'utf8');
github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: `## 🔍 Claude Code Review\n\n${review}`
});
- name: Check for Critical Issues
run: |
if grep -q "Critical\|🔴" review.md; then
echo "❌ Critical issues found"
exit 1
fi
GitHub Actions - Codex Only
# .github/workflows/codex-review.yml
name: Codex Code Review
on:
pull_request:
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Codex Review
uses: openai/codex-action@main
with:
openai_api_key: ${{ secrets.OPENAI_API_KEY }}
model: gpt-5.2-codex
safety_strategy: drop-sudo
GitHub Actions - Both Engines
# .github/workflows/dual-review.yml
name: Dual Code Review
on:
pull_request:
jobs:
claude-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Claude Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
npx @anthropic-ai/claude-code --print "/code-review" > claude-review.md
- uses: actions/upload-artifact@v4
with:
name: claude-review
path: claude-review.md
codex-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install Codex
run: npm install -g @openai/codex
- name: Codex Review
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
codex exec --full-auto --sandbox read-only \
--output-last-message codex-review.md \
"Review this code for bugs, security issues, and quality problems"
- uses: actions/upload-artifact@v4
with:
name: codex-review
path: codex-review.md
combine-reviews:
needs: [claude-review, codex-review]
runs-on: ubuntu-latest
steps:
- uses: actions/download-artifact@v4
- name: Combine Reviews
run: |
echo "## 🔍 Dual Code Review Results" > combined-review.md
echo "" >> combined-review.md
echo "### Claude Findings" >> combined-review.md
cat claude-review/claude-review.md >> combined-review.md
echo "" >> combined-review.md
echo "### Codex Findings" >> combined-review.md
cat codex-review/codex-review.md >> combined-review.md
- name: Post Combined Review
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const review = fs.readFileSync('combined-review.md', 'utf8');
github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: review
});
GitHub Actions - Gemini Only
# .github/workflows/gemini-review.yml
name: Gemini Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Gemini CLI
run: npm install -g @google/gemini-cli
- name: Run Review
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
run: |
# Get diff
git diff origin/${{ github.base_ref }}...HEAD > diff.txt
# Run Gemini review
gemini -p "Review this pull request diff for bugs, security issues, and code quality problems. Be specific about file names and line numbers.
$(cat diff.txt)" > review.md
- name: Post Review Comment
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const review = fs.readFileSync('review.md', 'utf8');
github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: `## 🤖 Gemini Code Review\n\n${review}`
});
- name: Check for Critical Issues
run: |
if grep -qi "critical\|security vulnerability\|injection" review.md; then
echo "❌ Critical issues found"
exit 1
fi
GitHub Actions - All Three Engines
# .github/workflows/triple-review.yml
name: Triple Engine Code Review
on:
pull_request:
jobs:
claude-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Claude Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
npx @anthropic-ai/claude-code --print "/code-review" > claude-review.md
- uses: actions/upload-artifact@v4
with:
name: claude-review
path: claude-review.md
codex-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install Codex
run: npm install -g @openai/codex
- name: Codex Review
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
codex exec --full-auto --sandbox read-only \
--output-last-message codex-review.md \
"Review this code for bugs, security issues, and quality problems"
- uses: actions/upload-artifact@v4
with:
name: codex-review
path: codex-review.md
gemini-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Gemini CLI
run: npm install -g @google/gemini-cli
- name: Gemini Review
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
run: |
git diff origin/${{ github.base_ref }}...HEAD > diff.txt
gemini -p "Review this code diff for bugs, security, and quality issues:
$(cat diff.txt)" > gemini-review.md
- uses: actions/upload-artifact@v4
with:
name: gemini-review
path: gemini-review.md
combine-reviews:
needs: [claude-review, codex-review, gemini-review]
runs-on: ubuntu-latest
steps:
- uses: actions/download-artifact@v4
- name: Combine Reviews
run: |
echo "## 🔍 Triple Engine Code Review Results" > combined-review.md
echo "" >> combined-review.md
echo "### 🟣 Claude Findings" >> combined-review.md
cat claude-review/claude-review.md >> combined-review.md
echo "" >> combined-review.md
echo "---" >> combined-review.md
echo "### 🟢 Codex Findings" >> combined-review.md
cat codex-review/codex-review.md >> combined-review.md
echo "" >> combined-review.md
echo "---" >> combined-review.md
echo "### 🔵 Gemini Findings" >> combined-review.md
cat gemini-review/gemini-review.md >> combined-review.md
- name: Post Combined Review
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const review = fs.readFileSync('combined-review.md', 'utf8');
github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: review
});
- name: Check Critical Issues
run: |
# Fail if any engine found critical issues
if grep -qi "critical\|🔴" combined-review.md; then
echo "❌ Critical issues found by at least one engine"
exit 1
fi
Review Checklist
Before Every Commit
- Run
/code-reviewon staged changes - No critical (🔴) issues
- No high (🟠) issues
- Security concerns addressed
- Performance issues considered
Before Every PR
- Full code review of all changes
- All critical/high issues resolved
- Tests added for new functionality
- Documentation updated if needed
Before Every Deployment
- Final review of deployment diff
- Security scan passed
- No new vulnerabilities introduced
- Rollback plan documented
Common Review Findings
Security Issues (Always Fix)
| Issue | Example | Fix |
|---|---|---|
| SQL Injection | query = f"SELECT * FROM users WHERE id = {id}" |
Use parameterized queries |
| XSS | innerHTML = userInput |
Sanitize or use textContent |
| Secrets in code | apiKey = "sk-xxx" |
Use environment variables |
| Missing auth | Unprotected endpoints | Add authentication middleware |
| Insecure crypto | MD5/SHA1 for passwords | Use bcrypt/argon2 |
Performance Issues (Should Fix)
| Issue | Example | Fix |
|---|---|---|
| N+1 queries | Loop with individual queries | Use batch/eager loading |
| Memory leak | Unclosed connections | Use connection pooling |
| Missing index | Slow queries | Add database indexes |
| Large payload | Fetching unused fields | Select only needed fields |
| No pagination | Loading all records | Implement pagination |
Code Quality (Nice to Fix)
| Issue | Example | Fix |
|---|---|---|
| Long function | 100+ lines | Extract into smaller functions |
| Deep nesting | 5+ levels | Early returns, extract methods |
| Magic numbers | if (status === 3) |
Use named constants |
| Duplicate code | Copy-pasted blocks | Extract shared function |
| Missing types | any everywhere |
Add proper TypeScript types |
Post-Review: Decision Extraction
After review completes, extract architectural decisions automatically:
- If review flagged new architectural choices → prompt to create ADR in
docs/adr/ - If review approved a new pattern → log to
_project_specs/session/decisions.md - If review found ADR drift → flag the ADR for update or supersede
### Auto-Log Entry (decisions.md)
- [YYYY-MM-DD] **[Review Finding]**: Brief description
- Source: Code review of [PR/commit]
- ADR: Created/Updated ADR-NNNN
- Impact: What changed
Integration with TDD Workflow
┌─────────────────────────────────────────────────────────────────┐
│ TDD + CODE REVIEW WORKFLOW │
│ ───────────────────────────────────────────────────────────── │
│ │
│ 1. RED: Write failing tests │
│ 2. GREEN: Write code to pass tests │
│ 3. REFACTOR: Clean up code │
│ 4. REVIEW: Run /code-review ← NEW STEP │
│ 5. FIX: Address critical/high issues │
│ 6. VALIDATE: Lint + TypeCheck + Coverage │
│ 7. COMMIT: Only after review passes │
│ │
│ Review catches what tests miss: │
│ - Security vulnerabilities │
│ - Performance issues │
│ - Architecture problems │
│ - Code maintainability │
└─────────────────────────────────────────────────────────────────┘
Review Response Template
When code review finds issues, respond with:
## Code Review Results
### 🔴 Critical Issues (Must Fix)
1. **SQL Injection in userController.ts:45**
- Issue: User input directly interpolated into query
- Fix: Use parameterized query
- Code: `db.query('SELECT * FROM users WHERE id = $1', [userId])`
### 🟠 High Issues (Should Fix)
1. **Missing authentication on /api/admin endpoints**
- Issue: Admin routes accessible without auth
- Fix: Add auth middleware
### 🟡 Medium Issues (Fix Soon)
1. **N+1 query in getOrders function**
- Consider eager loading or batch query
### 🟢 Low Issues (Nice to Have)
1. **Consider extracting validation logic to separate file**
### ✅ Strengths
- Good test coverage
- Clear function names
- Proper error handling
### 📊 Summary
- Critical: 1 | High: 1 | Medium: 1 | Low: 1
- **Status: ❌ BLOCKED** - Fix critical/high issues before commit
Claude Instructions
When to Invoke Code Review
Claude should automatically suggest or run code review:
- After completing a feature → "Let me run a code review before we commit"
- Before creating a PR → "Running code review on all changes"
- When user says "commit" → "First, let me review the changes"
- After fixing bugs → "Reviewing the fix for any issues"
Review Focus Areas
Prioritize review based on change type:
| Change Type | Focus Areas |
|---|---|
| Auth/Security code | Security, input validation, crypto |
| Database code | SQL injection, N+1, transactions |
| API endpoints | Auth, rate limiting, validation |
| Frontend code | XSS, state management, performance |
| Infrastructure | Secrets, permissions, logging |
Quick Reference
Commands
# Basic review
/code-review
# Review specific files
/code-review src/auth.ts src/users.ts
# Review with focus
/code-review --focus security
# Review PR
/code-review --pr 123
Severity Actions
🔴 Critical → STOP. Fix now. No commit.
🟠 High → STOP. Fix now. No commit.
🟡 Medium → Note it. Fix soon. Can commit.
🟢 Low → Optional. Nice to have.
ℹ️ Info → FYI only.
Workflow
Code → Test → Review → Fix → Commit → Push → PR → Review → Merge → Deploy
↑ ↑ ↑
/code-review /code-review /code-review