Code Reviewer

Code Reviewer

Parallel multi-agent code review with 3 core reviewers (security, logic, performance) and inline self-critique.

Default path spawns 3 reviewer agents (security, logic, performance) that analyze code simultaneously. Each reviewer re-reads its own findings before emitting, validates evidence claims, and rates confidence 1–5. The 3-reviewer default balances coverage with token cost for typical reviews.

--full-fanout restores the 8-reviewer + 10-validator path for maximum coverage at higher token cost. Reach for it on pre-release audits, large refactors, or security-sensitive PRs where thoroughness beats cost.

Tool-Use Rationale

• Read: Load spec.md, rubric.md, CLAUDE.md, and the files under review so reviewers share identical context.
• Grep: Locate call sites, try/catch patterns, and AC markers across the touched files.
• Bash: Run gh pr diff, git diff, and find to build the file list and extract PR metadata.

Model Configuration

Default effort: xhigh — recommended for all code-review tasks per Opus 4.7 conventions. Opt-in max: --effort max enables maximum effort with a warning: "max effort risks overthinking on straightforward problems." Legacy mode: Set quality.thinkingBudget: "legacy" in config to pass a fixed thinking parameter (for pre-4.7 models only).

Prompt Caching

sw:code-reviewer uses Anthropic's ephemeral prompt caching so the shared context (project rules, active spec, rubric) is reused across the parallel reviewer fan-out and between fix-loop iterations. This is especially impactful during sw:done, where the fix loop can invoke code-reviewer up to 5 times per closure.

Files cached by default (via static-context-loader):

• CLAUDE.md (project root)
• .specweave/config.json
• The active increment's spec.md
• The active increment's rubric.md (if present)

Cache window: 5-minute TTL (Anthropic's cache_control: { type: "ephemeral" } breakpoint). Successive reviewer spawns that share this prefix read from cache.

Extending the list: Add paths to cache.staticContextFiles in .specweave/config.json:

{
  "cache": {
    "staticContextFiles": [
      "CLAUDE.md",
      ".specweave/config.json",
      ".specweave/docs/internal/architecture/adr/ADR-001-something.md"
    ]
  }
}

Disable caching: Set cache.staticContextFiles: [] in .specweave/config.json. Reviewer agents will still run, but without the shared prefix cache.

See .specweave/docs/internal/specs/config-reference.md and opus-47-migration.md for the full caching setup.

MANDATORY: Orchestrator Identity

You are an ORCHESTRATOR. You do NOT review code yourself.

• ALWAYS create a team and spawn reviewer agents via Task()
• NEVER read code and produce findings directly — that's what the reviewer agents do
• Your job: detect scope, gate-check, route reviewers, validate findings, aggregate results, produce report

---

0. Scope Detection

Parse arguments to determine WHAT to review.

Argument Parsing

| Argument | Scope | How to Get Diff | |----------|-------|-----------------| | --pr N | Review PR #N | gh pr diff N | | --changes | Uncommitted + staged changes | git diff HEAD | | --increment NNNN | Changes from increment NNNN | git diff on files touched by increment | | --cross-repo | All repos in umbrella | Per-repo git diff (see Section 5) | | path/to/dir | Specific directory/file | Read files directly | | (no args) | Auto-detect (see below) | Varies |

Auto-Detection (no arguments)

# 1. Check for open PR on current branch
PR_NUM=$(gh pr view --json number -q '.number' 2>/dev/null)
if [ -n "$PR_NUM" ]; then
  SCOPE="pr"
  REVIEW_TARGET="$PR_NUM"
fi

# 2. Check for uncommitted changes
if [ -z "$SCOPE" ]; then
  CHANGES=$(git diff --stat HEAD 2>/dev/null)
  if [ -n "$CHANGES" ]; then
    SCOPE="changes"
    REVIEW_TARGET="uncommitted changes"
  fi
fi

# 3. Check for active increment
if [ -z "$SCOPE" ]; then
  ACTIVE=$(find .specweave/increments -maxdepth 2 -name "metadata.json" \
    -exec grep -l '"active"' {} \; 2>/dev/null | head -1)
  if [ -n "$ACTIVE" ]; then
    SCOPE="increment"
    REVIEW_TARGET=$(dirname "$ACTIVE")
  fi
fi

# 4. Fall back to whole project
if [ -z "$SCOPE" ]; then
  SCOPE="project"
  REVIEW_TARGET="."
fi

Build File List

Once scope is determined, build the list of files to review:

case "$SCOPE" in
  pr)       FILES=$(gh pr diff "$REVIEW_TARGET" --name-only) ;;
  changes)  FILES=$(git diff --name-only HEAD) ;;
  increment) FILES=$(git log --name-only --pretty=format: -- "$REVIEW_TARGET") ;;
  project)  FILES=$(find src -type f -name "*.ts" -o -name "*.tsx" -o -name "*.js" 2>/dev/null) ;;
esac

Extract PR Context

When scope is pr, extract metadata for reviewer agents:

if [ "$SCOPE" = "pr" ]; then
  PR_TITLE=$(gh pr view "$REVIEW_TARGET" --json title -q '.title')
  PR_DESCRIPTION=$(gh pr view "$REVIEW_TARGET" --json body -q '.body')
fi

These values replace [PR_TITLE] and [PR_DESCRIPTION] placeholders in agent prompts. For non-PR scopes, placeholders are replaced with empty strings.

---

0.5 Gate Check

Before spawning reviewers, verify the review is worth running. Pass --force to bypass.

PR Scope

if [ "$SCOPE" = "pr" ]; then
  PR_STATE=$(gh pr view "$REVIEW_TARGET" --json state -q '.state')
  [ "$PR_STATE" = "MERGED" ] || [ "$PR_STATE" = "CLOSED" ] && echo "SKIP: PR is $PR_STATE" && exit 0

  IS_DRAFT=$(gh pr view "$REVIEW_TARGET" --json isDraft -q '.isDraft')
  [ "$IS_DRAFT" = "true" ] && echo "SKIP: PR is draft" && exit 0

  DIFF_LINES=$(gh pr diff "$REVIEW_TARGET" -- ':!*.lock' ':!*-lock.json' | grep -c '^[+-]' 2>/dev/null || echo 0)
  [ "$DIFF_LINES" -lt 5 ] && echo "SKIP: /dev/null || echo 0)
  [ "$DIFF_LINES" -lt 5 ] && echo "SKIP:  50 changed lines)
  - reviewer-tests     → non-test source files changed

Cap: --max-reviewers N (default: 3; with --full-fanout: 8)

Routing Decision

# Default: security + logic + performance — all three always spawn
REVIEWERS=("security" "logic" "performance")

if [ "$FULL_FANOUT" = "true" ]; then
  # TypeScript files → add type reviewer
  if echo "$FILES" | grep -qE '\.(ts|tsx)$'; then
    REVIEWERS+=("types")
  fi

  # Code files → add silent failures
  if echo "$FILES" | grep -qE '\.(ts|tsx|js|jsx)$'; then
    REVIEWERS+=("silent-failures")
  fi

  # Increment context → add spec compliance
  if [ "$SCOPE" = "increment" ] || [ -n "$INCREMENT_PATH" ]; then
    REVIEWERS+=("spec-compliance")
  fi

  # Significant changes → add comment reviewer
  if [ "$(echo "$FILES" | wc -l)" -gt 10 ]; then
    REVIEWERS+=("comments")
  fi

  # Source files (non-test) → add test coverage reviewer
  if echo "$FILES" | grep -qE '\.(ts|tsx|js|jsx)$'; then
    if echo "$FILES" | grep -vqE '\.(test|spec)\.(ts|tsx|js|jsx)$'; then
      REVIEWERS+=("tests")
    fi
  fi
fi

---

2. Team Creation and Agent Spawning

Create Review Team

TeamCreate({
  team_name: "review-[timestamp-or-slug]",
  description: "Code review: [REVIEW_TARGET]"
});

The review-* prefix bypasses the increment-existence-guard (reviews don't need increments).

Read and Spawn Agents

For each selected reviewer:

1. Determine template source:

• logic, security, performance → read from team-lead's agents/ dir:

skills/team-lead/agents/reviewer-{name}.md

• silent-failures, types, spec-compliance → read from own agents/ dir:

skills/code-reviewer/agents/reviewer-{name}.md

• comments, tests → read from own agents/ dir:

skills/code-reviewer/agents/reviewer-{name}.md

1. Replace placeholders:

• [REVIEW_TARGET] → the detected scope description
• [INCREMENT_PATH] → increment path (for spec-compliance only)
• [PR_NUMBER] → PR number (if scope is PR)
• [PR_TITLE] → PR title (empty if not PR scope)
• [PR_DESCRIPTION] → PR description body (empty if not PR scope)

1. Spawn via Task():

```typescript // Model tier per reviewer (non-Claude environments ignore gracefully) const MODEL = { "logic": "opus", "security": "opus", "performance": "sonnet", "silent-failures": "sonnet", "types": "sonnet", "spec-compliance": "sonnet", "comments": "sonnet", "tests": "sonnet" };

Task({ teamname: "review-[slug]", name: "reviewer-[domain]", subagenttype: "general-purpose", model: MODEL["[domain]"], mode: "bypassPermissions", prompt: }); ```

All reviewers spawn in parallel — no dependency chain for reviews.

CRITICAL: Always use mode: "bypassPermissions" — reviewers cannot handle trust-folder prompts.

---

3. Result Aggregation

Collect REVIEW_COMPLETE Messages

Wait for all spawned reviewers to signal REVIEW_COMPLETE:. Track completion:

Reviewer Status:
  logic:            REVIEW_COMPLETE (5 findings)
  security:         REVIEW_COMPLETE (2 findings)
  types:            REVIEW_COMPLETE (8 findings)
  silent-failures:  REVIEW_COMPLETE (3 findings)
  performance:      (not spawned)
  spec-compliance:  (not spawned)

Timeout Handling

If a reviewer doesn't respond within a reasonable number of turns:

1. Send STATUS_CHECK message
2. If still no response after 2 more turns, declare stuck and proceed without it
3. Note the missing reviewer in the final report

Deduplication

Multiple reviewers may flag the same issue (e.g., logic + silent-failures both catch an empty catch block):

• Group findings by file:line
• Merge findings at the same location into a single entry
• Keep the highest severity level
• Combine descriptions from different perspectives

---

3.5 Inline Self-Critique (default)

Default reviews use inline self-critique instead of spawning separate validator subagents. Each reviewer re-reads its own findings before emitting, validates evidence claims, and rates confidence 1–5.

Self-Critique Contract

Every reviewer prompt includes this closing instruction:

Before emitting REVIEW_COMPLETE, perform self-critique:
  1. Re-read each finding you produced.
  2. For each finding, re-open the cited file at the cited line and confirm the described issue is really there.
  3. Rate confidence 1–5 (5 = certain, 1 = speculative).
  4. Drop any finding where confidence /dev/null)
    if [ -n "$changes" ]; then
      CHANGED_REPOS+=("$repo_dir")
    fi
  fi
done

Per-Repo Review

For each changed repo:

1. Determine files changed in that repo
2. Route reviewers based on those files
3. Spawn reviewer agents scoped to that repo
4. Prefix all findings with repo path

Cross-Repo Integration Check

After per-repo reviews complete, check for cross-repo issues:

• Shared type definitions changed but consumers not updated
• API contract changes without corresponding client updates
• Version/dependency mismatches between repos
• Shared configuration drift

Merged Report

Produce a single report with sections per repo:

# Cross-Repo Code Review Report

## Repository: repositories/org/api-service
[findings for api-service]

## Repository: repositories/org/web-client
[findings for web-client]

## Cross-Repo Issues
[integration findings]

---

6. Cleanup and Output

Shutdown Agents

// Shutdown each reviewer
SendMessage({ type: "shutdown_request", recipient: "logic-inline", content: "Review complete" });
SendMessage({ type: "shutdown_request", recipient: "reviewer-security", content: "Review complete" });
// ... for each spawned reviewer

Destroy Team

TeamDelete();

Present Results

1. Display the unified report to the user
2. Highlight CRITICAL and HIGH findings prominently
3. If reviewing an increment: offer to create tasks for critical findings
4. Report location of JSON report file

Offer Follow-Up

Review complete. [N] findings across [M] files.
  - [X] critical, [Y] high findings need attention

Report saved to: [REPORT_PATH]

Next steps:
  - Fix critical issues before merging
  - sw:do to implement fixes (if increment exists)
  - sw:code-reviewer --changes to re-review after fixes

---

7. Troubleshooting

| Issue | Cause | Fix | |-------|-------|-----| | Reviewer stuck | Agent not responding | Send STATUS_CHECK, then shutdown after 2 turns | | No files to review | Empty diff or wrong scope | Check git status, verify scope argument | | Ghost review-* team | Previous review didn't clean up | TeamDelete by name before starting | | Spec compliance skipped | No increment path found | Pass --increment NNNN explicitly | | Cross-repo misses a repo | Repo has no .git or no changes | Check repo has uncommitted work |

---

Related Skills

| Skill | Relationship | |-------|-------------| | sw:grill | Grill is increment-scoped, runs during closure. Code-reviewer is general-purpose, runs anytime. | | sw:team-lead --mode review | Team-lead delegates review mode to this skill | | sw:validate | Rule-based validation (130+ checks). Code-reviewer is AI-powered analysis. |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: anton-abyzov
• Source: anton-abyzov/specweave
• License: MIT
• Homepage: https://spec-weave.com

Install and usage instructions live in the source repository linked above.