Skip to main content
OrchestKit v7.43.0 — 104 skills, 36 agents, 173 hooks · Claude Code 2.1.105+
OrchestKit
Skills

Review Pr

PR review with parallel specialized agents. Use when reviewing pull requests or code.

Command medium
Invoke
/ork:review-pr

Review PR

Deep code review using 6-7 parallel specialized agents.

Quick Start

/ork:review-pr 123
/ork:review-pr feature-branch

Opus 4.6: Parallel agents use native adaptive thinking for deeper analysis. Complexity-aware routing matches agent model to review difficulty.


Argument Resolution

The PR number or branch is passed as the skill argument. Resolve it immediately:

PR_NUMBER = "$ARGUMENTS[0]"  # e.g., "123" or "feature-branch"

# If no argument provided, check environment
if not PR_NUMBER:
    PR_NUMBER = os.environ.get("ORCHESTKIT_PR_URL", "").split("/")[-1]

# If still empty, detect from current branch
if not PR_NUMBER:
    PR_NUMBER = "$(gh pr view --json number -q .number 2>/dev/null)"

Use PR_NUMBER consistently in all subsequent commands and agent prompts.


STEP 0: Verify User Intent with AskUserQuestion

BEFORE creating tasks, clarify review focus:

AskUserQuestion(
  questions=[{
    "question": "What type of review do you need?",
    "header": "Focus",
    "options": [
      {"label": "Full review (Recommended)", "description": "Security + code quality + tests + architecture", "markdown": "```\nFull Review (6 agents)\n──────────────────────\n  PR diff ──▶ 6 parallel agents:\n  ┌────────────┐ ┌────────────┐\n  │ Quality x2 │ │ Security   │\n  ├────────────┤ ├────────────┤\n  │ Test Gen   │ │ Backend    │\n  ├────────────┤ ├────────────┤\n  │ Frontend   │ │ (optional) │\n  └────────────┘ └────────────┘\n\n  Synthesized review comment\n  with conventional comments:\n  praise/suggestion/issue/nitpick\n```"},
      {"label": "Security focus", "description": "Prioritize security vulnerabilities", "markdown": "```\nSecurity Review\n───────────────\n  PR diff ──▶ security-auditor:\n  ┌─────────────────────────┐\n  │ Auth changes       ✓/✗ │\n  │ Input validation   ✓/✗ │\n  │ SQL/XSS/CSRF       ✓/✗ │\n  │ Secrets in diff    ✓/✗ │\n  │ Dependency risk    ✓/✗ │\n  └─────────────────────────┘\n  Output: Security-focused\n  review with fix suggestions\n```"},
      {"label": "Performance focus", "description": "Focus on performance implications", "markdown": "```\nPerformance Review\n──────────────────\n  PR diff ──▶ perf analysis:\n  ┌─────────────────────────┐\n  │ N+1 queries        ✓/✗ │\n  │ Bundle size impact  ±KB │\n  │ Render performance  ✓/✗ │\n  │ Memory leaks       ✓/✗ │\n  │ Caching gaps       ✓/✗ │\n  └─────────────────────────┘\n  Agent: frontend-performance\n  or python-performance\n```"},
      {"label": "Quick review", "description": "High-level review, skip deep analysis", "markdown": "```\nQuick Review (~2 min)\n─────────────────────\n  PR diff ──▶ Single pass\n\n  Output:\n  ├── Approve / Request changes\n  ├── Top 3 concerns\n  └── 1-paragraph summary\n  1 agent: code-quality-reviewer\n  No deep security/perf scan\n```"}
    ],
    "multiSelect": false
  }]
)

Based on answer, adjust workflow:

  • Full review: All 6-7 parallel agents
  • Security focus: Prioritize security-auditor, reduce other agents
  • Performance focus: Add frontend-performance-engineer agent
  • Quick review: Single code-quality-reviewer agent only

STEP 0b: Select Orchestration Mode

Load orchestration guidance: Read("$\{CLAUDE_SKILL_DIR\}/references/orchestration-mode-selection.md")


MCP Probe (CC 2.1.71)

ToolSearch(query="select:mcp__memory__search_nodes")
Write(".claude/chain/capabilities.json", { memory, timestamp })
# If memory available: search for past review patterns on these files

CRITICAL: Task Management is MANDATORY

BEFORE doing ANYTHING else, create tasks to track progress:

# 1. Create main review task IMMEDIATELY
TaskCreate(
  subject="Review PR #{number}",
  description="Comprehensive code review with parallel agents",
  activeForm="Reviewing PR #{number}"
)

# 2. Create subtasks for each phase
TaskCreate(subject="Gather PR information", activeForm="Gathering PR information")
TaskCreate(subject="Launch review agents", activeForm="Dispatching review agents")
TaskCreate(subject="Run validation checks", activeForm="Running validation checks")
TaskCreate(subject="Synthesize review", activeForm="Synthesizing review")
TaskCreate(subject="Submit review", activeForm="Submitting review")

# 3. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done

Phase 1: Gather PR Information

# Get PR details
gh pr view $PR_NUMBER --json title,body,files,additions,deletions,commits,author

# View the diff
gh pr diff $PR_NUMBER

# Check CI status
gh pr checks $PR_NUMBER

Capture Scope for Agents

# Capture changed files for agent scope injection
CHANGED_FILES=$(gh pr diff $PR_NUMBER --name-only)

# Detect affected domains
HAS_FRONTEND=$(echo "$CHANGED_FILES" | grep -qE '\.(tsx?|jsx?|css|scss)$' && echo true || echo false)
HAS_BACKEND=$(echo "$CHANGED_FILES" | grep -qE '\.(py|go|rs|java)$' && echo true || echo false)
HAS_AI=$(echo "$CHANGED_FILES" | grep -qE '(llm|ai|agent|prompt|embedding)' && echo true || echo false)

Pass CHANGED_FILES to every agent prompt in Phase 3. Pass domain flags to select which agents to spawn.

Identify: total files changed, lines added/removed, affected domains (frontend, backend, AI).

Tool Guidance

TaskUseAvoid
Fetch PR diffBash: gh pr diffReading all changed files individually
List changed filesBash: gh pr diff --name-onlybash find
Search for patternsGrep(pattern="...", path="src/")bash grep
Read file contentRead(file_path="...")bash cat
Check CI statusBash: gh pr checksPolling APIs

<use_parallel_tool_calls> When gathering PR context, run independent operations in parallel:

  • gh pr view (PR metadata), gh pr diff (changed files), gh pr checks (CI status)

Spawn all three in ONE message. This cuts context-gathering time by 60%. For agent-based review (Phase 3), all 6 agents are independent -- launch them together. </use_parallel_tool_calls>

Phase 2: Skills Auto-Loading

CC auto-discovers skills -- no manual loading needed!

Relevant skills activated automatically:

  • code-review-playbook -- Review patterns, conventional comments
  • security-scanning -- OWASP, secrets, dependencies
  • type-safety-validation -- Zod, TypeScript strict
  • testing-unit, testing-e2e, testing-integration -- Test adequacy, coverage gaps, rule matching

Phase 3: Parallel Code Review (6 Agents)

Project Context Injection

Before spawning agents, load project-specific review context from memory:

# Load project review context (conventions, known weaknesses, past findings)
# This gives agents project-specific knowledge without re-discovering patterns
PROJECT_CONTEXT = Read("${MEMORY_DIR}/review-pr-context.md")  # Falls back gracefully if missing

All agent prompts receive $\{PROJECT_CONTEXT\} so they know project conventions, security patterns, and known weaknesses from prior reviews.

Structured Output

All agents return findings as JSON (see structured output contract in agent prompt files). This enables automated deduplication, severity sorting, and memory graph persistence in Phase 5.

Anti-Sycophancy Response Protocol

All review agents and the coordinator MUST follow Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/shared/rules/anti-sycophancy.md"):

NEVER use: "Great work!", "Excellent!", "Nice!", "Thanks for catching that!", "You're absolutely right!", or ANY performative agreement.

INSTEAD: State findings directly. The code speaks for itself.

  • "Fixed. Changed X to Y in auth.ts:42."
  • "Security: JWT in localStorage. Move to httpOnly cookie."
  • [Just fix it and show the diff]

When feedback seems wrong: Push back with technical reasoning. Not "I respectfully disagree." Just facts and evidence.

Agent Status Protocol

All agents MUST include a status field per Read("$\{CLAUDE_PLUGIN_ROOT\}/agents/shared/status-protocol.md"):

  • DONE — task completed, all requirements met
  • DONE_WITH_CONCERNS — completed but flagging risks
  • BLOCKED — cannot proceed
  • NEEDS_CONTEXT — insufficient information

Domain-Aware Agent Selection

Only spawn agents relevant to the PR's changed domains:

Domain DetectedAgents to Spawn
Backend onlycode-quality (x2), security-auditor, test-generator, backend-system-architect
Frontend onlycode-quality (x2), security-auditor, test-generator, frontend-ui-developer
Full-stackAll 6 agents
AI/LLM codeAll 6 + optional llm-integrator (7th)

Skip agents for domains not present in the diff. This saves ~33% tokens on domain-specific PRs.

Progressive Output (CC 2.1.76+)

Output each agent's findings as they complete — don't batch until synthesis.

Focus mode (CC 2.1.101): In focus mode, the user only sees your final message. Include the full review verdict, all findings by severity, and the approve/request-changes recommendation — don't assume they saw per-agent outputs.

  • Security findings → show blockers and critical issues first
  • Code quality → show pattern violations, complexity hotspots
  • Test coverage gaps → show missing test cases

This lets the PR author start addressing blocking issues while remaining agents are still analyzing. Only the final synthesis (Phase 5) requires all agents to have completed.

Partial results (CC 2.1.98): If a review agent fails mid-analysis, synthesize partial findings:

for agent_result in review_results:
    if "[PARTIAL RESULT]" in agent_result.output:
        # A security agent that found 2 issues before crashing > no security review
        findings.extend(parse_findings(agent_result.output))
        findings[-1]["partial"] = True  # Flag in synthesis
        # Do NOT re-spawn — partial findings are still valuable

Monitor for CI streaming (CC 2.1.98): Stream CI check output in Phase 4:

Bash(command="gh pr checks $PR_NUMBER --watch 2>&1", run_in_background=true)
Monitor(pid=ci_watch_id)  # Each status change → notification

See Agent Prompts -- Task Tool Mode for the 6 parallel agent prompts.

See Agent Prompts -- Agent Teams Mode for the mesh alternative.

See AI Code Review Agent for the optional 7th LLM agent.

Phase 4: Run Validation

Load validation commands: Read("$\{CLAUDE_SKILL_DIR\}/references/validation-commands.md")

Phase 5: Synthesize Review

Combine all agent feedback into a structured report. Load template: Read("$\{CLAUDE_SKILL_DIR\}/references/review-report-template.md")

Memory Persistence

After synthesis, persist critical/high findings to the memory graph so future reviews build on past knowledge:

# Persist review findings for cross-session learning
mcp__memory__create_entities(entities=[{
    "name": "PR-{number}-Review",
    "entityType": "code-review",
    "observations": ["<summary>", "<critical findings>", "<patterns discovered>"]
}])
# Update known-weaknesses entity if new patterns found
mcp__memory__add_observations(observations=[{
    "entityName": "review-known-weaknesses",
    "contents": ["<new pattern from this review>"]
}])

Phase 6: Submit Review

# Approve
gh pr review $PR_NUMBER --approve -b "Review message"

# Request changes
gh pr review $PR_NUMBER --request-changes -b "Review message"

CC 2.1.20 Enhancements

PR Status Enrichment

The pr-status-enricher hook automatically detects open PRs at session start and sets:

  • ORCHESTKIT_PR_URL -- PR URL for quick reference
  • ORCHESTKIT_PR_STATE -- PR state (OPEN, MERGED, CLOSED)

Session Resume with PR Context (CC 2.1.27+)

Sessions are automatically linked when reviewing PRs. Resume later with full context:

claude --from-pr 123
claude --from-pr https://github.com/org/repo/pull/123

Task Metrics (CC 2.1.30)

Load metrics template: Read("$\{CLAUDE_SKILL_DIR\}/references/task-metrics-template.md")

Conventional Comments

Use these prefixes for comments:

  • praise: -- Positive feedback
  • nitpick: -- Minor suggestion
  • suggestion: -- Improvement idea
  • issue: -- Must fix
  • question: -- Needs clarification

Agent Coordination

Context Passing

All review agents receive: changed files list, PR metadata (author, base branch), domain flags (has_frontend, has_backend, has_ai), and project review conventions from memory.

SendMessage (Cross-Review Findings)

When the security agent finds an issue the code-quality agent should also flag:

SendMessage(to="code-quality-reviewer", message="Security: auth middleware bypassed in route handler — flag as issue in review")

Agent Teams Alternative

For complex PRs (> 500 lines, 3+ domains), use mesh topology so reviewers can challenge each other:

# Load: Read("${CLAUDE_SKILL_DIR}/rules/agent-prompts-agent-teams.md")
  • ork:commit: Create commits after review
  • ork:create-pr: Create PRs for review
  • slack-integration: Team notifications for review events

References

Load on demand with Read("$\{CLAUDE_SKILL_DIR\}/references/&lt;file&gt;"):

FileContent
review-template.mdReview checklist template
review-report-template.mdStructured review report
orchestration-mode-selection.mdTask tool vs Agent Teams
validation-commands.mdBuild/test/lint commands
task-metrics-template.mdTask metrics format

Rules: Read("$\{CLAUDE_SKILL_DIR\}/rules/&lt;file&gt;"):

FileContent
agent-prompts-task-tool.mdAgent prompts for Task tool mode
agent-prompts-agent-teams.mdAgent prompts for Agent Teams mode

Rules (3)

Agent Prompts — Agent Teams Mode — HIGH

Agent Prompts — Agent Teams Mode

In Agent Teams mode, form a review team where reviewers cross-reference findings directly.

Project Context Injection

Before spawning agents, load project-specific review context if it exists:

# Load project review context from memory (if available)
PROJECT_CONTEXT = ""
try:
    Read("${MEMORY_DIR}/review-pr-context.md")  # ${MEMORY_DIR} = project memory path
    PROJECT_CONTEXT = "<result from read>"
except:
    PROJECT_CONTEXT = "No project-specific review context available."

Structured Output Contract

Every agent MUST return a JSON block (fenced with json) at the end of their review matching the schema in review-pr-output.md. Category prefixes: SEC, PERF, BUG, MAINT, A11Y, TEST.

Team Formation

# DOMAIN-AWARE AGENT SELECTION
# Core agents (always spawn): quality-reviewer, security-reviewer, test-reviewer
# Conditional: backend-reviewer (if HAS_BACKEND), frontend-reviewer (if HAS_FRONTEND)

# Capture scope from Phase 1
CHANGED_FILES = "$(gh pr diff $PR_NUMBER --name-only)"

TeamCreate(team_name="review-pr-$PR_NUMBER", description="Review PR #$PR_NUMBER")

Agent(subagent_type="code-quality-reviewer", name="quality-reviewer",
     team_name="review-pr-$PR_NUMBER",
     prompt="""Review code quality and type safety for PR #$PR_NUMBER.

     ## Project Context
     ${PROJECT_CONTEXT}

     Scope: ONLY review the following changed files:
     ${CHANGED_FILES}
     Do NOT explore beyond these files.
     When you find patterns that overlap with security concerns,
     message security-reviewer with the finding.
     When you find test gaps, message test-reviewer.
     Return findings as a JSON block (```json```) with category prefix MAINT.""")

Agent(subagent_type="security-auditor", name="security-reviewer",
     team_name="review-pr-$PR_NUMBER",
     prompt="""Security audit for PR #$PR_NUMBER.

     ## Project Context
     ${PROJECT_CONTEXT}

     Scope: ONLY review the following changed files:
     ${CHANGED_FILES}
     Do NOT explore beyond these files.
     Check: fail-closed auth, SSRF on user-controlled URLs, rate limiting, secrets in diff.
     Cross-reference with quality-reviewer for injection risks in code patterns.
     When you find issues, message the responsible reviewer (backend-reviewer
     for API issues, frontend-reviewer for XSS).
     Return findings as a JSON block (```json```) with category prefix SEC.""")

Agent(subagent_type="test-generator", name="test-reviewer",
     team_name="review-pr-$PR_NUMBER",
     prompt="""Review TEST ADEQUACY for PR #$PR_NUMBER.
     Scope: ONLY review the following changed files:
     ${CHANGED_FILES}
     Do NOT explore beyond these files.
     1. Check: Does the PR add/modify code WITHOUT adding tests? Flag as MISSING.
     2. Match change types to required test types (testing-unit/testing-e2e/testing-integration rules):
        - API → integration-api, verification-contract
        - DB → integration-database, data-seeding-cleanup
        - UI → unit-aaa-pattern, a11y-testing
        - Logic → verification-techniques
     3. Evaluate test quality: meaningful assertions, no flaky patterns.
     4. When quality-reviewer flags test gaps, verify and suggest specific tests.
     Message backend-reviewer or frontend-reviewer with test requirements.

     ## Project Context
     ${PROJECT_CONTEXT}

     Return findings as a JSON block (```json```) with category prefix TEST.""")

# Only spawn if backend files detected (HAS_BACKEND)
Agent(subagent_type="backend-system-architect", name="backend-reviewer",
     team_name="review-pr-$PR_NUMBER",
     prompt="""Review backend code for PR #$PR_NUMBER.

     ## Project Context
     ${PROJECT_CONTEXT}

     Scope: ONLY review the following changed files:
     ${CHANGED_FILES}
     Do NOT explore beyond these files.
     Check: Redis connection lifecycle, webhook auth (fail-closed), N+1 queries, async patterns.
     When security-reviewer flags API issues, validate and suggest fixes.
     Share API pattern findings with frontend-reviewer for consistency.
     Return findings as a JSON block (```json```) with prefixes BUG/PERF/MAINT.""")

# Only spawn if frontend files detected (HAS_FRONTEND)
Agent(subagent_type="frontend-ui-developer", name="frontend-reviewer",
     team_name="review-pr-$PR_NUMBER",
     prompt="""Review frontend code for PR #$PR_NUMBER.

     ## Project Context
     ${PROJECT_CONTEXT}

     Scope: ONLY review the following changed files:
     ${CHANGED_FILES}
     Do NOT explore beyond these files.
     Check: SSR safety (no navigator/window outside hooks), button type attrs, a11y.
     When backend-reviewer shares API patterns, verify frontend matches.
     When security-reviewer flags XSS risks, validate and suggest fixes.
     Return findings as a JSON block (```json```) with prefixes A11Y/PERF/BUG.""")

Team teardown after synthesis (only shut down agents that were actually spawned):

# After collecting all findings and producing the review
# Core agents — always shut down
SendMessage(type="shutdown_request", recipient="quality-reviewer", content="Review complete")
SendMessage(type="shutdown_request", recipient="security-reviewer", content="Review complete")
SendMessage(type="shutdown_request", recipient="test-reviewer", content="Review complete")
# Conditional agents — only shut down if spawned
# if HAS_BACKEND:
SendMessage(type="shutdown_request", recipient="backend-reviewer", content="Review complete")
# if HAS_FRONTEND:
SendMessage(type="shutdown_request", recipient="frontend-reviewer", content="Review complete")
TeamDelete()

# Worktree cleanup (CC 2.1.72)
ExitWorktree(action="keep")

Incorrect — No team teardown:

# Agents keep running indefinitely
Agent(subagent_type="code-quality-reviewer", team_name="review-pr-$PR_NUMBER")
Agent(subagent_type="security-auditor", team_name="review-pr-$PR_NUMBER")
# Missing shutdown_request calls!

Correct — Proper team teardown:

# After review synthesis complete
SendMessage(type="shutdown_request", recipient="quality-reviewer", content="Review complete")
SendMessage(type="shutdown_request", recipient="security-reviewer", content="Review complete")
TeamDelete()  # Clean shutdown
ExitWorktree(action="keep")

Fallback: If team formation fails, use standard Task tool spawns from agent-prompts-task-tool.md.

Agent Prompts — Task Tool Mode — HIGH

Agent Prompts — Task Tool Mode

Launch SIX specialized reviewers in ONE message with run_in_background: true:

AgentFocus Area
code-quality-reviewer #1Readability, complexity, DRY
code-quality-reviewer #2Type safety, Zod, Pydantic
security-auditorSecurity, secrets, injection
test-generatorTest coverage, edge cases
backend-system-architectAPI, async, transactions
frontend-ui-developerReact 19, hooks, a11y

Project Context Injection

Before spawning agents, load project-specific review context if it exists:

# Load project review context from memory (if available)
# This file contains project conventions, security patterns, and known weaknesses
# from prior reviews. Agents receive it as PROJECT_CONTEXT in their prompts.
PROJECT_CONTEXT = ""
try:
    Read("${MEMORY_DIR}/review-pr-context.md")  # ${MEMORY_DIR} = project memory path
    PROJECT_CONTEXT = "<result from read>"
except:
    PROJECT_CONTEXT = "No project-specific review context available."

Structured Output Contract

Every agent MUST return a JSON block (fenced with json) at the end of their review:

{
  "agent": "<agent-role>",
  "pr_number": $PR_NUMBER,
  "summary": "One-line summary",
  "findings": [
    {
      "id": "<CATEGORY_PREFIX>-<NNN>",
      "severity": "critical|high|medium|low|info",
      "category": "security|performance|correctness|maintainability|accessibility|testing",
      "file": "relative/path.ext",
      "line": 42,
      "title": "Short title (<80 chars)",
      "description": "Detailed explanation",
      "suggestion": "Fix suggestion",
      "effort": "5min|15min|30min|1h|2h+",
      "conventional_comment": "praise|nitpick|suggestion|issue|question"
    }
  ],
  "stats": { "files_reviewed": 0, "findings_count": 0, "critical": 0, "high": 0, "medium": 0, "low": 0 },
  "verdict": "approve|request-changes|comment-only"
}

Category prefixes: SEC (security), PERF (performance), BUG (correctness), MAINT (maintainability), A11Y (accessibility), TEST (testing).

The lead reviewer collects all agent JSON outputs, deduplicates by file+line+category (keeps highest severity), and persists critical/high findings to the memory graph.

Agent Prompts

# DOMAIN-AWARE AGENT SELECTION
# Only spawn agents relevant to detected domains.
# CHANGED_FILES and domain flags (HAS_FRONTEND, HAS_BACKEND, HAS_AI)
# are captured in Phase 1.

# ALWAYS spawn these 4 core agents:
# - code-quality-reviewer (readability)
# - code-quality-reviewer (type safety)
# - security-auditor
# - test-generator

# CONDITIONALLY spawn these based on domain:
# - backend-system-architect  → only if HAS_BACKEND
# - frontend-ui-developer     → only if HAS_FRONTEND
# - llm-integrator (7th)      → only if HAS_AI

# PARALLEL - All agents in ONE message
Agent(
  description="Review code quality",
  subagent_type="code-quality-reviewer",
  prompt="""# Cache-optimized: stable content first (CC 2.1.73)
  CODE QUALITY REVIEW

  ## Project Context
  ${PROJECT_CONTEXT}

  Review code readability and maintainability:
  1. Naming conventions and clarity
  2. Function/method complexity (cyclomatic < 10)
  3. DRY violations and code duplication
  4. SOLID principles adherence

  Do NOT explore beyond the changed files listed below. Focus your analysis on the diff.

  Return your findings as a JSON block (```json```) matching the structured output contract above.
  Use category prefix MAINT for maintainability findings. Use conventional comments (praise/suggestion/issue/nitpick).

  PR: $PR_NUMBER
  Scope: ONLY review the following changed files:
  ${CHANGED_FILES}
  """,
  run_in_background=True,
  max_turns=25
)
Agent(
  description="Review type safety",
  subagent_type="code-quality-reviewer",
  prompt="""# Cache-optimized: stable content first (CC 2.1.73)
  TYPE SAFETY REVIEW

  ## Project Context
  ${PROJECT_CONTEXT}

  Review type safety and validation:
  1. TypeScript strict mode compliance
  2. Zod/Pydantic schema usage
  3. No `any` types or type assertions
  4. Exhaustive switch/union handling

  Do NOT explore beyond the changed files listed below. Focus your analysis on the diff.

  Return your findings as a JSON block (```json```) matching the structured output contract above.
  Use category prefix MAINT for type safety findings. Use conventional comments.

  PR: $PR_NUMBER
  Scope: ONLY review the following changed files:
  ${CHANGED_FILES}
  """,
  run_in_background=True,
  max_turns=25
)
Agent(
  description="Security audit PR",
  subagent_type="security-auditor",
  prompt="""# Cache-optimized: stable content first (CC 2.1.73)
  SECURITY REVIEW

  ## Project Context
  ${PROJECT_CONTEXT}

  Security audit:
  1. Secrets/credentials in code
  2. Injection vulnerabilities (SQL, XSS)
  3. Authentication/authorization checks
  4. Dependency vulnerabilities
  5. Fail-closed auth patterns (reject when config missing)
  6. SSRF protection on user-controlled URLs
  7. Rate limiting on auth endpoints

  Do NOT explore beyond the changed files listed below. Focus your analysis on the diff.

  Return your findings as a JSON block (```json```) matching the structured output contract above.
  Use category prefix SEC for security findings. Use conventional comments.

  PR: $PR_NUMBER
  Scope: ONLY review the following changed files:
  ${CHANGED_FILES}
  """,
  run_in_background=True,
  max_turns=25
)
Agent(
  description="Review test adequacy",
  subagent_type="test-generator",
  prompt="""# Cache-optimized: stable content first (CC 2.1.73)
  TEST ADEQUACY REVIEW

  Evaluate whether this PR has sufficient tests:

  1. TEST EXISTENCE CHECK
     - Does the PR add/modify code WITHOUT adding/updating tests?
     - Are there changed files with 0 corresponding test files?
     - Flag: "MISSING" if code changes have no tests at all

  2. TEST TYPE MATCHING (use testing-unit/testing-e2e/testing-integration rules)
     Match changed code to required test types:
     - API endpoint changes → need integration tests (rule: integration-api)
     - DB schema changes → need migration + integration tests (rule: integration-database)
     - UI component changes → need unit + a11y tests (rule: unit-aaa-pattern, a11y-testing)
     - Business logic → need unit + property tests (rule: verification-techniques)
     - LLM/AI changes → need eval tests (rule: llm-evaluation)

  3. TEST QUALITY
     - Meaningful assertions (not just truthy/exists)
     - Edge cases and error paths covered
     - No flaky patterns (timing, external deps, random)
     - Mocking is appropriate (not over-mocked)

  4. COVERAGE GAPS
     - Which changed functions/methods lack test coverage?
     - Which error paths are untested?

  ## Project Context
  ${PROJECT_CONTEXT}

  Do NOT explore beyond the changed files listed below. Focus your analysis on the diff.

  Return your findings as a JSON block (```json```) matching the structured output contract above.
  Use category prefix TEST for testing findings. Use conventional comments.

  PR: $PR_NUMBER
  Scope: ONLY review the following changed files:
  ${CHANGED_FILES}
  """,
  run_in_background=True,
  max_turns=25
)
Agent(
  description="Review backend code",
  subagent_type="backend-system-architect",
  prompt="""# Cache-optimized: stable content first (CC 2.1.73)
  BACKEND REVIEW

  ## Project Context
  ${PROJECT_CONTEXT}

  Review backend code:
  1. API design and REST conventions
  2. Async/await patterns and error handling
  3. Database query efficiency (N+1)
  4. Transaction boundaries
  5. Redis connection lifecycle (close in try/finally)
  6. Webhook auth patterns (fail-closed)

  Do NOT explore beyond the changed files listed below. Focus your analysis on the diff.

  Return your findings as a JSON block (```json```) matching the structured output contract above.
  Use category prefixes: BUG (correctness), PERF (performance), MAINT (maintainability). Use conventional comments.

  PR: $PR_NUMBER
  Scope: ONLY review the following changed files:
  ${CHANGED_FILES}
  """,
  run_in_background=True,
  max_turns=25
)
Agent(
  description="Review frontend code",
  subagent_type="frontend-ui-developer",
  prompt="""# Cache-optimized: stable content first (CC 2.1.73)
  FRONTEND REVIEW

  ## Project Context
  ${PROJECT_CONTEXT}

  Review frontend code:
  1. React 19 patterns (hooks, server components)
  2. State management correctness
  3. Accessibility (a11y) compliance — button type attrs, ARIA
  4. Performance (memoization, lazy loading)
  5. SSR safety — no navigator/window outside hooks/useEffect

  Do NOT explore beyond the changed files listed below. Focus your analysis on the diff.

  Return your findings as a JSON block (```json```) matching the structured output contract above.
  Use category prefixes: A11Y (accessibility), PERF (performance), BUG (correctness). Use conventional comments.

  PR: $PR_NUMBER
  Scope: ONLY review the following changed files:
  ${CHANGED_FILES}
  """,
  run_in_background=True,
  max_turns=25
)

Incorrect — Sequential agents:

# 6 reviewers run one-by-one (slow)
Agent(subagent_type="code-quality-reviewer", prompt="...")
# Wait for completion
Agent(subagent_type="security-auditor", prompt="...")
# Wait again...

Correct — Parallel agents:

# All 6 agents in ONE message (fast)
Agent(subagent_type="code-quality-reviewer", prompt="...", run_in_background=True)
Agent(subagent_type="security-auditor", prompt="...", run_in_background=True)
Agent(subagent_type="test-generator", prompt="...", run_in_background=True)
# All launch simultaneously

Configure an AI code review agent for prompt injection and token limit checks — MEDIUM

AI Code Review Agent (Optional)

If PR includes AI/ML code, add a 7th agent:

Agent(
  description="Review LLM integration",
  subagent_type="llm-integrator",
  prompt="""LLM CODE REVIEW for PR $ARGUMENTS

  Review AI/LLM integration:
  1. Prompt injection prevention
  2. Token limit handling
  3. Caching strategy
  4. Error handling and fallbacks

  SUMMARY: End with: "RESULT: [PASS|WARN|FAIL] - [N] LLM issues: [key concern]"
  """,
  run_in_background=True,
  max_turns=25
)

Incorrect — Missing LLM review for AI code:

# PR modifies prompt.py but no LLM reviewer
Agent(subagent_type="code-quality-reviewer", ...)
Agent(subagent_type="security-auditor", ...)
# Missing: LLM-specific review

Correct — Add LLM reviewer for AI code:

# Detect AI/ML changes, add specialized reviewer
if pr_contains_llm_code:
    Agent(subagent_type="llm-integrator", prompt="LLM CODE REVIEW...", run_in_background=True)

References (5)

Orchestration Mode Selection

Orchestration Mode Selection

Choose Agent Teams (mesh -- reviewers cross-reference findings) or Task tool (star -- all report to lead):

  1. Agent Teams mode (GA since CC 2.1.33) -> recommended for full review with 6+ agents
  2. Task tool mode -> for quick/focused review
  3. ORCHESTKIT_FORCE_TASK_TOOL=1 -> Task tool (override)
AspectTask ToolAgent Teams
CommunicationAll reviewers report to leadReviewers cross-reference findings
Security + quality overlapLead deduplicatessecurity-auditor messages code-quality-reviewer directly
Cost~200K tokens~500K tokens
Best forQuick/focused reviewsFull reviews with cross-cutting concerns

Fallback: If Agent Teams encounters issues, fall back to Task tool for remaining review.

Review Report Template

Review Report Template

Use this template when synthesizing agent feedback in Phase 5:

# PR Review: #$ARGUMENTS

## Summary
[1-2 sentence overview]

## Code Quality
| Area | Status | Notes |
|------|--------|-------|
| Readability | // | [notes] |
| Type Safety | // | [notes] |

## Test Adequacy
| Check | Status | Details |
|-------|--------|---------|
| Tests exist for changes | // | [X changed files have tests, Y do not] |
| Test types match changes | // | [e.g., API changes have integration tests] |
| Coverage gaps | // | [N untested paths] |
| Test quality | // | [meaningful assertions, no flaky patterns] |

**Verdict:** [ADEQUATE | GAPS (list) | MISSING (critical)]

## Security
| Check | Status |
|-------|--------|
| Secrets | / |
| Input Validation | / |
| Dependencies | / |

## Blockers (Must Fix)
- [if any]

## Suggestions (Non-Blocking)
- [improvements]

Review Template

PR Review Template

Review Output Format

# PR Review: #[NUMBER]
**Title**: [PR Title]
**Author**: [Author]
**Files Changed**: X | **Lines**: +Y / -Z

## Summary
[1-2 sentence overview of changes]

## ✅ Strengths
- [What's done well - from praise comments]
- [Good patterns observed]

## 🔍 Code Quality
| Area | Status | Notes |
|------|--------|-------|
| Readability | ✅/⚠️/❌ | [notes] |
| Type Safety | ✅/⚠️/❌ | [notes] |
| Test Coverage | ✅/⚠️/❌ | [X% coverage] |
| Error Handling | ✅/⚠️/❌ | [notes] |

## 🔒 Security
| Check | Status | Issues |
|-------|--------|--------|
| Secrets Scan | ✅/❌ | [count] |
| Input Validation | ✅/❌ | [issues] |
| Dependencies | ✅/❌ | [vulnerabilities] |

## ⚠️ Suggestions (Non-Blocking)
- [suggestion 1 with file:line reference]
- [suggestion 2]

## 🔴 Blockers (Must Fix Before Merge)
- [blocker 1 if any]
- [blocker 2 if any]

## 📋 CI Status
- Backend Lint: ✅/❌
- Backend Types: ✅/❌
- Backend Tests: ✅/❌
- Frontend Format: ✅/❌
- Frontend Lint: ✅/❌
- Frontend Types: ✅/❌
- Frontend Tests: ✅/❌

Approval Message

## ✅ Approved

Great work! Code quality is solid, tests pass, and security looks good.

### Highlights
- [specific positive feedback]

### Minor Suggestions (Non-Blocking)
- [optional improvements]

🤖 Reviewed with Claude Code (6 parallel agents)

Request Changes Message

## 🔄 Changes Requested

Good progress, but a few items need addressing before merge.

### Must Fix
1. [blocker 1]
2. [blocker 2]

### Suggestions
- [optional improvements]

🤖 Reviewed with Claude Code (6 parallel agents)

Conventional Comments

PrefixUsage
praise:Highlight good patterns
nitpick:Minor style preference
suggestion:Non-blocking improvement
issue:Must be addressed
question:Needs clarification

Example Comments

praise: Excellent use of the repository pattern here - clean separation of concerns.

nitpick: Consider using a more descriptive variable name than `d` - maybe `data` or `response`.

suggestion: This loop could be replaced with a list comprehension for better readability.

issue: This SQL query is vulnerable to injection - use parameterized queries instead.

question: Is there a reason we're not using the existing `UserService` here?

Task Metrics Template

Task Metrics Template (CC 2.1.30)

Task tool results now include efficiency metrics. After parallel agents complete, report:

## Review Efficiency
| Agent | Tokens | Tools | Duration |
|-------|--------|-------|----------|
| code-quality-reviewer | 450 | 8 | 12s |
| security-auditor | 620 | 12 | 18s |
| test-generator | 380 | 6 | 10s |

**Total:** 1,450 tokens, 26 tool calls

Use metrics to:

  • Identify slow or expensive agents
  • Track review efficiency over time
  • Optimize agent prompts based on token usage

Validation Commands

Validation Commands

Backend

cd backend
poetry run ruff format --check app/
poetry run ruff check app/
poetry run pytest tests/unit/ -v --tb=short
poetry run pytest tests/ -v --cov=app --cov-report=term-missing

Frontend

cd frontend
npm run format:check
npm run lint
npm run typecheck
npm run test
npm run test -- --coverage

Integration Tests (if infrastructure detected)

# Detect real service testing capability
ls **/docker-compose*.yml 2>/dev/null
ls **/testcontainers* 2>/dev/null

# If detected, run integration tests against real services
docker-compose -f docker-compose.test.yml up -d
poetry run pytest tests/integration/ -v
docker-compose -f docker-compose.test.yml down

Test Adequacy Check

# List changed files without corresponding test files
gh pr diff $ARGUMENTS --name-only | while read f; do
  # Skip test files, configs, docs
  case "$f" in
    tests/*|*test*|*.md|*.json|*.yml) continue ;;
  esac
  # Check if a test file exists
  test_file="tests/$(basename "$f" .py)_test.py"
  if [ ! -f "$test_file" ]; then
    echo "NO TEST: $f"
  fi
done
Edit on GitHub

Last updated on

On this page

Review PRQuick StartArgument ResolutionSTEP 0: Verify User Intent with AskUserQuestionSTEP 0b: Select Orchestration ModeMCP Probe (CC 2.1.71)CRITICAL: Task Management is MANDATORYPhase 1: Gather PR InformationCapture Scope for AgentsTool GuidancePhase 2: Skills Auto-LoadingPhase 3: Parallel Code Review (6 Agents)Project Context InjectionStructured OutputAnti-Sycophancy Response ProtocolAgent Status ProtocolDomain-Aware Agent SelectionProgressive Output (CC 2.1.76+)Phase 4: Run ValidationPhase 5: Synthesize ReviewMemory PersistencePhase 6: Submit ReviewCC 2.1.20 EnhancementsPR Status EnrichmentSession Resume with PR Context (CC 2.1.27+)Task Metrics (CC 2.1.30)Conventional CommentsAgent CoordinationContext PassingSendMessage (Cross-Review Findings)Agent Teams AlternativeRelated SkillsReferencesRules (3)Agent Prompts — Agent Teams Mode — HIGHAgent Prompts — Agent Teams ModeProject Context InjectionStructured Output ContractTeam FormationAgent Prompts — Task Tool Mode — HIGHAgent Prompts — Task Tool ModeProject Context InjectionStructured Output ContractAgent PromptsConfigure an AI code review agent for prompt injection and token limit checks — MEDIUMAI Code Review Agent (Optional)References (5)Orchestration Mode SelectionOrchestration Mode SelectionReview Report TemplateReview Report TemplateReview TemplatePR Review TemplateReview Output FormatApproval MessageRequest Changes MessageConventional CommentsExample CommentsTask Metrics TemplateTask Metrics Template (CC 2.1.30)Validation CommandsValidation CommandsBackendFrontendIntegration Tests (if infrastructure detected)Test Adequacy Check