Review Pr
PR review with parallel specialized agents. Use when reviewing pull requests or code.
/ork:review-prReview PR
Deep code review using 6-7 parallel specialized agents.
Quick Start
/ork:review-pr 123
/ork:review-pr feature-branchOpus 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 filesCRITICAL: 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 donePhase 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_NUMBERCapture 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
| Task | Use | Avoid |
|---|---|---|
| Fetch PR diff | Bash: gh pr diff | Reading all changed files individually |
| List changed files | Bash: gh pr diff --name-only | bash find |
| Search for patterns | Grep(pattern="...", path="src/") | bash grep |
| Read file content | Read(file_path="...") | bash cat |
| Check CI status | Bash: gh pr checks | Polling 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 commentssecurity-scanning-- OWASP, secrets, dependenciestype-safety-validation-- Zod, TypeScript stricttesting-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 missingAll 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 Detected | Agents to Spawn |
|---|---|
| Backend only | code-quality (x2), security-auditor, test-generator, backend-system-architect |
| Frontend only | code-quality (x2), security-auditor, test-generator, frontend-ui-developer |
| Full-stack | All 6 agents |
| AI/LLM code | All 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 valuableMonitor 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 → notificationSee 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 referenceORCHESTKIT_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/123Task 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 feedbacknitpick:-- Minor suggestionsuggestion:-- Improvement ideaissue:-- Must fixquestion:-- 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")Related Skills
ork:commit: Create commits after reviework:create-pr: Create PRs for reviewslack-integration: Team notifications for review events
References
Load on demand with Read("$\{CLAUDE_SKILL_DIR\}/references/<file>"):
| File | Content |
|---|---|
review-template.md | Review checklist template |
review-report-template.md | Structured review report |
orchestration-mode-selection.md | Task tool vs Agent Teams |
validation-commands.md | Build/test/lint commands |
task-metrics-template.md | Task metrics format |
Rules: Read("$\{CLAUDE_SKILL_DIR\}/rules/<file>"):
| File | Content |
|---|---|
agent-prompts-task-tool.md | Agent prompts for Task tool mode |
agent-prompts-agent-teams.md | Agent 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:
| Agent | Focus Area |
|---|---|
| code-quality-reviewer #1 | Readability, complexity, DRY |
| code-quality-reviewer #2 | Type safety, Zod, Pydantic |
| security-auditor | Security, secrets, injection |
| test-generator | Test coverage, edge cases |
| backend-system-architect | API, async, transactions |
| frontend-ui-developer | React 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 simultaneouslyConfigure 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 reviewCorrect — 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):
- Agent Teams mode (GA since CC 2.1.33) -> recommended for full review with 6+ agents
- Task tool mode -> for quick/focused review
ORCHESTKIT_FORCE_TASK_TOOL=1-> Task tool (override)
| Aspect | Task Tool | Agent Teams |
|---|---|---|
| Communication | All reviewers report to lead | Reviewers cross-reference findings |
| Security + quality overlap | Lead deduplicates | security-auditor messages code-quality-reviewer directly |
| Cost | ~200K tokens | ~500K tokens |
| Best for | Quick/focused reviews | Full 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
| Prefix | Usage |
|---|---|
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 callsUse 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-missingFrontend
cd frontend
npm run format:check
npm run lint
npm run typecheck
npm run test
npm run test -- --coverageIntegration 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 downTest 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
doneResponsive Patterns
Responsive design with Container Queries, fluid typography, cqi/cqb units, subgrid, intrinsic layouts, foldable devices, and mobile-first patterns for React applications. Use when building responsive layouts or container queries.
Scope Appropriate Architecture
Right-sizes architecture to project scope. Prevents over-engineering by classifying projects into 6 tiers and constraining pattern choices accordingly. Use when designing architecture, selecting patterns, or when brainstorm/implement detect a project tier.
Last updated on