code-review-by-team

name	code-review-by-team
description	Multi-agent PR code review pipeline with cleanup, specialized reviewers, adversarial analysis (including optional Codex adversarial review), and feature alignment checking. Use when the user wants a thorough code review, says "review this PR", "review my changes", asks for feedback on their branch, or wants to know if their code is ready to merge. Use when this capability is needed.
metadata	{"author":"dimakrest"}

/code-review -- PR Review Team

Coordinates a multi-phase review pipeline: first cleans up the code, then dispatches specialized reviewers for honest, professional, and concise feedback. Focuses on actionable findings -- no nit-picking, no over-engineering suggestions.

Step 1: Gather PR Changes

Detect the base branch first, then use it consistently for all diffs:

# Detect the base branch (usually main or master)
BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")

# Ensure base branch is up to date before diffing
git fetch origin "$BASE"

# Get list of changed files (three-dot diff shows only changes introduced by the branch)
git diff "origin/$BASE...HEAD" --name-only

# Get the full diff
git diff "origin/$BASE...HEAD"

# Get commit messages for intent context
git log "origin/$BASE..HEAD" --oneline

Use origin/$BASE (the detected base branch) in all subsequent git diff and git log commands throughout this skill — not a hardcoded branch name.

CRITICAL: Always use three-dot diffs (origin/$BASE...HEAD), NOT two-dot (origin/$BASE HEAD). Three-dot diffs show only changes introduced by the branch (from the merge-base to HEAD). Two-dot diffs compare branch tips directly, which inflates the review scope when the branch has merged the base into it.

Step 2: Understand Project Context

Before dispatching agents, gather project context:

• Check for project guidelines: .claude/CLAUDE.md, CONTRIBUTING.md, .editorconfig, linter configs
• Check for engineering standards docs referenced in CLAUDE.md
• Identify the tech stack from changed file extensions and imports
• Note any project-specific patterns, conventions, or agent definitions

Step 3: Categorize Changes

Sort changed files into review domains:

• Backend: Server-side code (Python, Go, Java, Node.js, etc.) excluding DB migrations and test files
• Frontend: Client-side code (TSX, TS, JSX, JS, CSS, SCSS, etc.) excluding test files
• Tests: *test*, *spec* files, test directories
• Security-sensitive: auth files, config files, API endpoints, input handling, external URL fetching

Skip domains with no changed files.

Step 4: Code Cleanup Phase

Before reviewers look at the code, run a cleanup pass to improve code quality. This makes actual changes to the code.

Launch a dedicated agent to run the built-in /simplify skill.

Agent call:
- subagent_type: "general-purpose"
- prompt:
  "You are running the /simplify skill on PR changes as part of a code review pipeline.

  ## Changed Files
  {list of ALL changed files}

  ## Instructions

  1. Run the /simplify skill using the Skill tool (skill: 'simplify')
  2. Let it analyze and fix the changed code
  3. Report back what changes were made (if any)

  If /simplify makes no changes, report 'No simplification changes needed.'"

Wait for this agent to complete before proceeding.

Step 5: Dispatch Review Agents (in parallel)

Launch ALL relevant review agents simultaneously. Each reviewer works independently on the cleaned-up code.

Step 5 preamble: Detect Codex plugin (run once)

Before launching reviewers, check whether the Codex plugin (codex@openai-codex) is installed. If it is, the Codex Adversarial Reviewer below will be dispatched alongside the others; if not, it is skipped silently and Step 7 will surface a one-line install recommendation.

CODEX_PLUGIN_DIR=$(find ~/.claude/plugins -type f -path "*/codex/scripts/codex-companion.mjs" 2>/dev/null \
  | head -1 | xargs -I {} dirname {} | xargs -I {} dirname {})

if [ -n "$CODEX_PLUGIN_DIR" ] \
   && [ -f "$CODEX_PLUGIN_DIR/scripts/codex-companion.mjs" ] \
   && [ -f "$CODEX_PLUGIN_DIR/commands/adversarial-review.md" ]; then
  CODEX_AVAILABLE=1
else
  CODEX_AVAILABLE=0
  CODEX_PLUGIN_DIR=""
fi

Remember CODEX_AVAILABLE and CODEX_PLUGIN_DIR for Steps 5, 6, and 7.

Backend Reviewer (if backend files changed)

Agent call:
- subagent_type: "context-engineering:backend-engineer"
- prompt:
  "Review this PR's backend changes. Scope your review to changes introduced by this PR only.

  ## Changed Files
  {list of changed backend files}

  Run `git diff origin/$BASE...HEAD -- <file>` for each file to see the exact changes. Read full files when needed for context.
  Read commit messages (`git log origin/$BASE..HEAD --oneline`) to understand intent.

  ## Output Format

  Report ONLY substantive findings. Skip anything that passes. Do not invent issues.

  For each finding:
  - **[file:line]** -- Description of the issue
  - **Why it matters** -- One sentence on impact
  - **Suggested fix** -- Brief code suggestion if helpful

  Categorize as:
  - **Must Fix**: Bugs, security issues, pattern violations that will cause problems
  - **Should Fix**: Code quality issues, maintainability concerns
  - **Consider**: Optional improvements worth discussing"

Frontend Reviewer (if frontend files changed)

Agent call:
- subagent_type: "context-engineering:frontend-engineer"
- prompt:
  "Review this PR's frontend changes. Scope your review to changes introduced by this PR only.

  ## Changed Files
  {list of changed frontend files}

  Run `git diff origin/$BASE...HEAD -- <file>` for each file to see the exact changes. Read full files when needed for context.
  Read commit messages (`git log origin/$BASE..HEAD --oneline`) to understand intent.

  ## Output Format

  Report ONLY substantive findings. Skip anything that passes. Do not invent issues.

  For each finding:
  - **[file:line]** -- Description of the issue
  - **Why it matters** -- One sentence on impact
  - **Suggested fix** -- Brief code suggestion if helpful

  Categorize as:
  - **Must Fix**: Bugs, accessibility issues, design system violations
  - **Should Fix**: Code quality, missing shared component usage, type issues
  - **Consider**: Optional improvements worth discussing"

QA Reviewer (if any test files changed OR if non-test code changed without corresponding tests)

Agent call:
- subagent_type: "general-purpose"
- prompt:
  "You are a QA engineer reviewing test coverage for a PR.

  ## Your Review Mindset

  Think like a QA engineer who cares about testability:
  - Are the right things being tested?
  - Are edge cases and error paths covered?
  - Are tests actually testing behavior (not implementation details)?
  - Is there production code that changed without corresponding test updates?

  ## Changed Files
  {list of ALL changed files, both test and non-test}

  Run `git diff origin/$BASE...HEAD -- <file>` for each file to see the exact changes.

  ## Review Focus

  **Test Coverage Gaps**:
  - Which changed production files lack corresponding test changes?
  - Are new functions/endpoints/components untested?
  - Are error paths and edge cases covered?

  **Test Quality**:
  - Do tests verify behavior or just implementation?
  - Are test names descriptive and clear?
  - Are assertions meaningful?
  - Is test setup minimal and focused?
  - Any redundant or duplicate test cases?

  **Missing Tests**:
  - Suggest specific test cases that should be added
  - Focus on high-value tests (happy path + most likely failure modes)
  - Do NOT suggest exhaustive edge-case testing for simple code

  ## Output Format

  **Coverage Summary**:
  - Files with tests: {count}
  - Files missing tests: {list}

  **Findings** (only if substantive):
  - **Gap**: [file] -- What is not tested and why it matters
  - **Quality Issue**: [test_file:line] -- What is wrong with the test
  - **Suggested Test**: Brief description of a test worth adding

  Be pragmatic. Not everything needs a test. Focus on code paths that could break."

Security Reviewer (always runs)

Agent call:
- subagent_type: "context-engineering:security-auditor"
- prompt:
  "Review this PR's diff for security issues. This is a PR-scoped review, NOT a full security audit — only report issues INTRODUCED or AFFECTED by this PR.

  ## Changed Files
  {full list of changed files}

  Run `git diff origin/$BASE...HEAD` to see the full diff.
  Read commit messages (`git log origin/$BASE..HEAD --oneline`) to understand intent.

  Do NOT report pre-existing issues, theoretical vulnerabilities without evidence in the diff, or general recommendations not tied to specific changes.

  ## Output Format

  For each finding:
  - **Severity**: CRITICAL / HIGH / MEDIUM / LOW
  - **[file:line]** -- Description
  - **Attack scenario** -- One sentence on how this could be exploited
  - **Fix** -- Brief remediation

  Categorize as:
  - **Must Fix**: CRITICAL/HIGH severity
  - **Should Fix**: MEDIUM severity
  - **Consider**: LOW severity

  If no security issues found, say 'No security issues identified in this PR' and briefly note what you checked."

Devil's Advocate Reviewer (always runs)

Agent call:
- subagent_type: "general-purpose"
- prompt:
  "You hate this implementation. Your job is to find real, verified problems — not style preferences.

  ## Changed Files
  {list of ALL changed files}

  Run `git diff origin/$BASE...HEAD` to see the full diff.
  Read commit messages (`git log origin/$BASE..HEAD --oneline`) to understand intent.

  ## Process

  1. Read the diff and form your harshest critique — what could break, what's fragile, what's wrong
  2. Batch your findings and verify them using up to 5 subagents (group related issues per subagent, use model: "sonnet" for each):
     - Edge case? Have the subagent trace the code path and confirm it's actually reachable
     - Race condition? Have the subagent check if concurrency is actually possible in this context
     - Missing validation? Have the subagent check if it's handled upstream
     - Wrong approach? Have the subagent find how similar problems are solved in this codebase
  3. Drop anything the subagent disproves. Only report verified issues.

  ## What to look for

  - Assumptions that break under load, concurrency, or unexpected input
  - Edge cases in the changed logic (nulls, empty collections, boundary values, unicode, timezone)
  - Error paths that silently swallow failures or leave state inconsistent
  - Coupling or design choices that will make the next change painful
  - Things that work now but will break when requirements inevitably shift

  ## What to skip

  - Style, naming, formatting — not your problem
  - Theoretical issues you can't verify from the code
  - Anything already covered by type system or framework guarantees

  ## Output Format

  For each VERIFIED finding:
  - **[file:line]** -- What's wrong
  - **Verification** -- What the subagent checked and confirmed
  - **Impact** -- What breaks and when
  - **Suggested fix** -- Brief, if you have one

  Categorize as:
  - **Must Fix**: Will cause bugs, data loss, or security issues
  - **Should Fix**: Fragile code that will bite someone soon
  - **Consider**: Design concerns worth discussing

  If the implementation is actually solid, say so. Don't manufacture problems."

Feature Alignment Reviewer (always runs)

Agent call:
- subagent_type: "general-purpose"
- prompt:
  "Review every change in this PR for feature alignment and intent clarity.

  ## Changed Files
  {list of ALL changed files}

  Run `git diff origin/$BASE...HEAD` to see the full diff.
  Read commit messages (`git log origin/$BASE..HEAD --oneline`) to understand the feature intent.

  ## Process

  1. Determine what feature/goal this PR is trying to accomplish from commit messages and the diff
  2. Group meaningful changes (not trivial reformats) and spawn up to 5 subagents (use model: "sonnet" for each) to verify them in batches. Each subagent should:
     - Read the surrounding code and understand the before/after context
     - Check how similar things are done elsewhere in the codebase
     - Determine if there's an existing pattern or utility that could be used instead
  3. Annotate every change with your assessment

  ## For each change, answer:

  - **What it does** -- One sentence explaining the change in plain language
  - **Why it's needed** -- How it serves the feature goal (or doesn't)
  - **Alignment** -- Does this change directly serve the feature, or is it tangential/unnecessary?
  - **Could it be done better?** -- Based on what the subagent found about existing codebase patterns

  ## Output Format

  ### Feature Intent
  One paragraph summarizing what this PR is trying to accomplish.

  ### Change-by-Change Review

  For each file (or logical group of changes):

  **[file:lines]** -- {what changed}
  - **Purpose**: Why this change exists
  - **Alignment**: Direct / Supportive / Tangential / Unnecessary
  - **Alternative**: {better approach if one exists, with codebase evidence from subagent}

  ### Summary
  - Changes that directly serve the feature: {count}
  - Changes that could be done better: {list}
  - Changes that seem unnecessary for this feature: {list, if any}
  - Overall assessment: is the PR focused and well-scoped?"

Codex Adversarial Reviewer (only if Codex plugin installed)

Dispatch this in the SAME parallel batch as the other Step 5 reviewers (single message, multiple Agent tool calls). Skip entirely when CODEX_AVAILABLE=0.

Substitute the resolved absolute $CODEX_PLUGIN_DIR into the prompt before sending it.

Agent call:
- subagent_type: "general-purpose"
- prompt:
  "You are dispatching the external Codex adversarial review for a PR review pipeline.
  Codex is an out-of-process reviewer that focuses on breaking confidence in the
  change (auth, data loss, race conditions, schema drift, observability gaps).

  ## Task

  1. Run this exact bash command and wait for it to complete (it may take several minutes):

     node \"$CODEX_PLUGIN_DIR/scripts/codex-companion.mjs\" adversarial-review --wait

     The `--wait` flag forces foreground execution and skips Codex's interactive
     'wait or run in background' prompt. Do not change the flag, do not switch
     to `--background`, do not call `/codex:status` or `/codex:result` — just
     block on this single command.

  2. Capture the full stdout verbatim. Do NOT paraphrase, summarize, reformat,
     or trim it. Codex returns structured findings; the deep-analyzer needs the
     raw output.

  3. If the command exits non-zero or returns no findings, report:
     'Codex adversarial review failed' followed by the captured stderr (last
     ~50 lines). Do not retry — the orchestrator will treat this as a missing
     reviewer.

  4. Return ONLY the verbatim Codex stdout (or the failure note above). No
     preamble, no commentary."

Step 6: Deep Analysis & Artifact Generation

Do NOT compile the report yourself. After ALL Step 5 reviewers complete, collect every reviewer's full output verbatim and dispatch a single deep-analyzer agent. It verifies each finding is real, assesses impact, deduplicates, and writes two persistent artifacts (Markdown + HTML).

Agent call:
- subagent_type: "general-purpose"
- model: "opus"
- prompt:
  "You are the deep-analysis agent for a multi-reviewer PR review pipeline.
  Your job: take raw reviewer findings, verify each one is real, assess impact,
  deduplicate aggressively, and produce two artifacts (Markdown + HTML).

  ## Inputs

  ### Raw reviewer outputs (verbatim, do not paraphrase before analysis)
  {Backend reviewer output}
  {Frontend reviewer output}
  {QA reviewer output}
  {Security reviewer output}
  {Devil's Advocate reviewer output}
  {Feature Alignment reviewer output}
  {Codex Adversarial reviewer output, or "(Codex plugin not installed — skipped)" when CODEX_AVAILABLE=0}

  ### PR metadata
  - Base branch: origin/$BASE
  - Changed files: {list from Step 1}
  - Commit messages: output of `git log origin/$BASE..HEAD --oneline`
  - Cleanup applied: {/simplify summary}

  ## Process

  1. **Parse** every finding from every reviewer into a structured list:
     (source_reviewer, file, line, severity, description, suggested_fix).

  2. **Deduplicate** — group findings by (file, line-range, root-cause).
     Merge duplicates into a single entry; record ALL reviewers that flagged it.

  3. **Verify** — batch related findings and spawn up to 5 sub-subagents in
     parallel (one Agent call per batch, each with subagent_type: 'general-purpose'
     and model: 'sonnet'). Each sub-subagent must:
       - Read the cited file(s) at the cited lines
       - Trace the code path / call sites with grep
       - Confirm the issue is real and reachable from actual entry points
       - Return one of: VERIFIED | DISPUTED | NOT_REPRODUCIBLE, with a one-line reason

     Drop NOT_REPRODUCIBLE findings (record them in 'Dropped Findings' with the
     sub-subagent's reason). Mark DISPUTED findings and include the dispute reason
     in the report so the human reviewer can adjudicate.

  4. **Assess impact** — for each VERIFIED finding, write 1-2 sentences on:
       - What breaks (data loss, wrong output, crash, security exposure, etc.)
       - When it triggers (always, under load, on edge input, etc.)
       - Blast radius (single user, all users, downstream services)

  5. **Re-categorize** by impact, not by reviewer's original label:
       - Must Fix: real bugs, security issues, data loss risks
       - Should Fix: maintainability/quality issues with clear cost
       - Consider: optional, low-impact suggestions

     Drop pure style nits and over-engineering suggestions (extra abstraction
     layers, premature optimization).

  6. **Generate artifacts** — write BOTH files using the Write tool. Create the
     `thoughts/shared/reviews/` directory first if it does not exist (use Bash:
     `mkdir -p thoughts/shared/reviews`). Filename uses today's date and the
     branch name: `{YYYY-MM-DD}-{branch-slug}-review.{md,html}`.

     a) Markdown: `thoughts/shared/reviews/{YYYY-MM-DD}-{branch-slug}-review.md`
        Sections, in order:
          - Summary (one paragraph: PR intent + overall quality)
          - Verdict (Ready to merge | Needs changes, with counts)
          - Must Fix
          - Should Fix
          - Consider
          - Test Coverage (QA narrative)
          - Security (security summary)
          - Feature Alignment (intent, tangential changes, better alternatives)
          - Cleanup Applied (/simplify summary)
          - Disputed Findings (with dispute reason)
          - Dropped Findings (with NOT_REPRODUCIBLE reason)

        Each finding entry must include: **[file:line]**, description, **Impact:**,
        **Suggested fix:**, **Verification:** (what the sub-subagent checked),
        **Source reviewers:** (chips of reviewer names).

     b) HTML: `thoughts/shared/reviews/{YYYY-MM-DD}-{branch-slug}-review.html`
        Self-contained single file. Constraints:
          - Inline CSS, no external stylesheets, no JS frameworks
          - System font stack (-apple-system, Segoe UI, Roboto, sans-serif)
          - Dark-mode-friendly palette (use `prefers-color-scheme: dark` media query)
          - Sticky header showing verdict + counts (Must / Should / Consider)
          - One collapsible <details> block per category and per narrative section
          - Each finding rendered as a card: monospace file:line, severity badge
            (color-coded), impact paragraph, suggested fix (in <pre> if code),
            verification line, source-reviewer chips
          - Vanilla <details>/<summary> for collapsibles — no JavaScript required

  7. **Return** to the orchestrator:
       - The two absolute file paths
       - Counts: must_fix / should_fix / consider / disputed / dropped
       - A one-paragraph executive summary of the PR's quality and verdict

  Do NOT print the full findings list in your return — the artifacts are the
  source of truth. The orchestrator only needs the summary and paths."

Wait for the deep-analyzer to complete before proceeding.

Step 7: Present to User

Print a short chat summary using the deep-analyzer's return values. Do NOT re-list every finding inline — the artifacts are the source of truth.

## PR Review Complete

{one-paragraph executive summary from deep-analyzer}

**Verdict:** {Ready to merge | Needs changes}
**Findings:** {N must-fix} / {M should-fix} / {K consider}  ({D disputed}, {X dropped})

**Reports:**
- Markdown: `thoughts/shared/reviews/{date}-{branch}-review.md`
- HTML:     `thoughts/shared/reviews/{date}-{branch}-review.html`

To open the HTML report:
`open thoughts/shared/reviews/{date}-{branch}-review.html`

When CODEX_AVAILABLE=0, append this blockquote to the summary so the user knows an extra reviewer is available:

> **Tip:** Install the Codex plugin to add an out-of-process adversarial reviewer to this pipeline. Once installed, `/code-review` will automatically include it.
> - `/plugin marketplace add openai/codex`
> - `/plugin install codex@openai-codex`
> Requires the `codex` CLI on PATH (`brew install codex` or see openai/codex).

Do not add this tip when Codex was used in this run.

---

Source: dimakrest/context-engineering — distributed by TomeVault.