Capstone: Build a PR Review Bot

Put everything from the Intermediate stage (Ch5-9) together. Build a tool that reviews any GitHub PR using parallel subagents for security, performance, and code quality — then posts a structured review comment.

What You're Building

A complete PR review system that:

1. Takes a GitHub PR URL as input
2. Fetches the diff and changed files via GitHub MCP
3. Spawns three review agents in parallel (security, performance, quality)
4. Synthesizes their findings into a single structured review
5. Posts the review as a GitHub PR comment

This is a real tool. Teams at scale use exactly this pattern — automated multi-perspective review that runs on every PR. When you're done, you'll have something you can point at any PR in any repo and get a professional-grade review in under 3 minutes.

Architecture

/review-pr https://github.com/user/repo/pull/42
  |
  v
Skill loads --> GitHub MCP fetches PR diff + files
  |
  v
Lead session creates review plan
  |
  +---> Security Agent (P0 findings, confidence >= 80%)
  |       tools: Read, Glob, Grep
  |
  +---> Performance Agent (N+1, missing pagination, etc.)
  |       tools: Read, Glob, Grep
  |
  +---> Quality Agent (code style, error handling, tests)
  |       tools: Read, Glob, Grep
  |
  v (all three complete)
  |
  Lead synthesizes --> structured review
  |
  v
  GitHub MCP posts review comment on the PR

Prerequisites

• Completed Chapters 5-9
• GitHub MCP configured with a token that has PR read/write access
• A GitHub repo with at least one open PR (or create a test PR)

Step 1: Hook Suite (Ch5)

Set up the project with production hooks.

mkdir -p ~/claude-demos/capstone-pr-bot && cd ~/claude-demos/capstone-pr-bot
git init && git branch -M main
mkdir -p .claude/{hooks,skills,agents}

cat > CLAUDE.md << 'EOF'
# PR Review Bot

## Project
A CLI tool and Claude Code skill that reviews GitHub PRs using parallel agents.

## Standards
- TypeScript with strict mode
- Conventional Commits
- No secrets in code — use environment variables
- Every finding needs file:line reference and confidence score
EOF

Create three hooks:

Commit quality gate (from Demo 11):

# Copy your commit-quality-gate.sh from Demo 11
# or create a new one that enforces Conventional Commits

Dangerous command blocker (from Demo 12):

# Copy your block-dangerous.sh from Demo 12

Usage observer (from Demo 14):

# Copy your observe.sh from Demo 14

Wire them in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/commit-quality-gate.sh" },
          { "type": "command", "command": "bash .claude/hooks/block-dangerous.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/observe.sh" }
        ]
      }
    ]
  }
}

Step 2: Review Agents (Ch8)

Create three specialized review agents.

Security agent (.claude/agents/security-reviewer.md):

• Tools: Read, Glob, Grep (read-only)
• Focus: SQL injection, XSS, auth bypass, data exposure, secrets
• Output: P0-P3 severity with file:line and confidence >= 80%
• Include proof-of-concept for P0 findings

Performance agent (.claude/agents/performance-reviewer.md):

• Tools: Read, Glob, Grep (read-only)
• Focus: N+1 queries, missing pagination, unbounded results, blocking I/O
• Output: Impact rating (High/Medium/Low) with file:line

Quality agent (.claude/agents/quality-reviewer.md):

• Tools: Read, Glob, Grep (read-only)
• Focus: Error handling, input validation, test coverage, code duplication
• Output: P1-P3 with specific fix recommendations

Use the patterns from Demo 22 (security scanner) and Demo 24 (multi-perspective review).

Step 3: The /review-pr Skill (Ch6)

Create the main skill that orchestrates everything.

cat > .claude/skills/review-pr.md << 'SKILLEOF'
---
name: review-pr
description: "Review a GitHub PR with parallel security, performance, and quality agents"
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
  - Agent
---

# PR Review Bot

Review a GitHub Pull Request using three specialized agents.

## Input

PR reference: $ARGUMENTS
(accepts: URL like https://github.com/user/repo/pull/42, or owner/repo#42)

## Process

### Step 1: Fetch PR Data
Use GitHub MCP to get:
- PR title, description, author
- List of changed files
- Full diff

Parse the PR reference to extract owner, repo, and PR number.

### Step 2: Check Out the Code
If the repo is available locally, read the changed files directly.
Otherwise, use GitHub MCP to fetch file contents.

### Step 3: Parallel Review
Launch three agents simultaneously:

1. **security-reviewer**: Scan all changed files for vulnerabilities
2. **performance-reviewer**: Check for performance anti-patterns
3. **quality-reviewer**: Assess code quality and maintainability

### Step 4: Synthesize
Combine all three reports into a single review:

```markdown
# PR Review: [PR Title]

## Summary
[Overall assessment in 2-3 sentences]

## Verdict: APPROVE / REQUEST CHANGES / BLOCK

## Findings by Severity

### Critical (P0)
[From security and performance agents]

### Bugs (P1)
[From all three agents]

### Code Quality (P2)
[From quality agent]

### Style (P3)
[Nits from all agents]

## What's Good
[2-3 positive observations]

## Recommended Actions
1. [Most important fix]
2. [Second most important]
3. ...

---
Reviewed by: PR Review Bot (security + performance + quality agents)

Step 5: Post Review (Optional)

If the user says "post it", use GitHub MCP to add the review as a PR comment.

Rules

• Never approve a PR with P0 findings
• Every finding must have file:line and confidence >= 80%
• "Consider improving" is not actionable — say exactly what to change
• Include what the PR does RIGHT, not just what's wrong
• If you can't fetch the PR data, tell the user why and stop SKILLEOF

## Step 4: MCP Integration (Ch7)

Make sure GitHub MCP is configured:

```bash
# Verify GitHub MCP is set up
claude mcp list

# If not, add it
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN -- npx -y @modelcontextprotocol/server-github

Step 5: Test It

Test on a Real PR

Find a PR in one of your repos (or create a test one), then:

claude

/review-pr https://github.com/<your-username>/<your-repo>/pull/<number>

Test on a Known-Bad PR

Create a PR with intentional issues to verify the bot catches them:

cd ~/claude-demos/capstone-pr-bot
git checkout -b feature/bad-code

# Create deliberately vulnerable code
cat > src/api.js << 'EOF'
app.get('/users', (req, res) => {
  // SQL injection
  const query = `SELECT * FROM users WHERE name = '${req.query.name}'`;
  // No pagination
  db.query(query).then(result => {
    // Returning password hashes
    res.json(result.rows);
  });
  // No error handling
});
EOF

git add -A && git commit -m "feat: add user endpoint"
git push -u origin feature/bad-code

# Create the PR
gh pr create --title "Add user endpoint" --body "New endpoint for listing users"

Now review it:

/review-pr <your-username>/<your-repo>#<pr-number>

Expected findings:

• P0: SQL injection in user query
• P1: No pagination on list endpoint
• P1: Password hashes exposed in response
• P1: No error handling
• P2: No input validation on name parameter

Acceptance Criteria

• [ ] Hooks (Ch5): Commit quality gate blocks bad messages, dangerous commands are caught
• [ ] Skills (Ch6): /review-pr skill is invokable and orchestrates the full workflow
• [ ] MCP (Ch7): GitHub MCP fetches PR data and can post comments
• [ ] Subagents (Ch8): Three review agents run with read-only tool restrictions
• [ ] Agent Teams (Ch9): Agents run in parallel, findings are synthesized into one report
• [ ] Output quality: Findings have file:line references, confidence >= 80%, actionable fixes
• [ ] Git history: At least 5 clean commits following Conventional Commits format

Going Further

Once the basic bot works, extend it:

1. Add a /review-pr-post variant that automatically posts the review as a GitHub comment
2. Add Context7 integration to check if the PR's library usage follows current docs
3. Add a regression check — compare this PR's findings against the main branch
4. Create a SessionStart hook that checks for open PRs assigned to you and shows their CI status
5. Build a /changelog skill that reads merged PRs since the last tag and generates release notes

What You've Demonstrated

By completing this capstone, you've shown you can:

• Configure hooks for safety and observability
• Build skills that orchestrate complex multi-step workflows
• Connect Claude to external services via MCP
• Design specialized agents with appropriate tool restrictions
• Orchestrate parallel agent execution with dependency management
• Produce structured, actionable output that's useful in a real development workflow

This is the intermediate-level toolkit. In the Advanced stage (Ch10-14), you'll learn to secure these systems against prompt injection, optimize token usage, run headless in CI/CD, and build production-grade toolchains.