# Code Reviewer

> Multi-agent code review system. Spawns 3 parallel reviewers (security, logic, performance) with inline self-critique. Use when saying 'review code', 'code review', 'audit code', 'review PR', 'review changes', 'check code quality'.

- **Type:** Skill
- **Install:** `agentstack add skill-anton-abyzov-specweave-code-reviewer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [anton-abyzov](https://agentstack.voostack.com/s/anton-abyzov)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [anton-abyzov](https://github.com/anton-abyzov)
- **Source:** https://github.com/anton-abyzov/specweave/tree/develop/plugins/specweave/skills/code-reviewer
- **Website:** https://spec-weave.com

## Install

```sh
agentstack add skill-anton-abyzov-specweave-code-reviewer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`:
```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)

```bash
# 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:

```bash
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:

```bash
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

```bash
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

```bash
# 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

```typescript
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`

2. **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)

3. **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({
     team_name: "review-[slug]",
     name: "reviewer-[domain]",
     subagent_type: "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:

```markdown
# 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

```typescript
// 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

```typescript
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](https://github.com/anton-abyzov)
- **Source:** [anton-abyzov/specweave](https://github.com/anton-abyzov/specweave)
- **License:** MIT
- **Homepage:** https://spec-weave.com

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-anton-abyzov-specweave-code-reviewer
- Seller: https://agentstack.voostack.com/s/anton-abyzov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.