HPC Claude Code Plugin

AI-powered code review agents for C++ game development at Hidden People Club.

Overview

The HPC Plugin transforms Claude Code into a comprehensive C++ code review system. It deploys 9 specialized AI agents that analyze your code changes for:

• Spec Compliance — Verify code satisfies specification requirements through hypothesis testing
• Coding Style — Naming conventions, includes, headers, memory management
• Architecture — Layer violations, context passing, singletons, data-oriented design
• Documentation — API docs, clarity, MCP annotations, consistency
• Error Handling — Logging, Result propagation, coverage
• Performance — Hot path allocations, loop efficiency, memory patterns
• Testing — Test execution, coverage, structure, quality
• Adversarial Testing — Security vulnerabilities, crash scenarios, null safety, buffer overflows

Each agent produces actionable reports with precise line numbers, context snippets, and suggested fixes.

Why I Built This

I'm building an LLM-first 2D game engine — designed from the ground up to be understood and modified by AI agents. This plugin is part of that effort.

When Claude Code is your primary development interface, you need automated review that goes beyond syntax linting. You need agents that understand architectural intent: layer boundaries between engine (hpc::) and game (mwb::) code, memory management patterns, and spec-driven development workflows.

This plugin deploys specialized AI agents that review code the way a senior engineer would — checking not just "does it compile" but "does it satisfy the spec" and "does it fit our architecture."

It's also an experiment in AI-assisted development tooling: can we build review systems that make working with LLMs on a large C++ codebase more reliable?

Quick Start

Installation

# Clone the plugin repository
git clone https://github.com/hiddenpeopleclub/claude-code-plugins.git

# Launch Claude Code with the plugin
claude --plugin-dir /path/to/claude-code-plugins/hpc

Usage

Run a full code review on your current branch:

/hpc:code-review

Or run individual reviews:

/hpc:coding-style-review
/hpc:architecture-review
/hpc:performance-review
/hpc:adversarial-testing-review

Commands

Command	Description
/hpc:code-review	Run all 8 agents (spec-compliance first, then others in parallel)
/hpc:spec-compliance-review	Verify code satisfies specification requirements
/hpc:spec-review	Review spec files for completeness and implementation clarity
/hpc:coding-style-review	C++ naming, includes, headers, auto, memory, errors, docs
/hpc:architecture-review	Layer violations, context usage, singletons, DOD patterns
/hpc:documentation-review	Completeness, clarity, MCP annotations, consistency
/hpc:error-handling-review	Logging, propagation, coverage, messages
/hpc:performance-review	Allocations, loops, memory, anti-patterns
/hpc:testing-review	Execution, coverage, structure, quality
/hpc:adversarial-testing-review	Security vulnerabilities, crash scenarios, stability issues

Architecture

hpc/
├── .claude-plugin/plugin.json   # Plugin manifest
├── agents/                      # 9 orchestrator agents
│   ├── spec-compliance-agent/   # Runs FIRST, then triggers bug reproduction
│   ├── spec-review-agent/       # Specification file review
│   ├── coding-style-agent/      # Orchestrates 7 style skills
│   ├── architecture-agent/      # Orchestrates 4 architecture skills
│   ├── documentation-agent/     # Orchestrates 5 documentation skills
│   ├── error-handling-agent/    # Orchestrates 4 error handling skills
│   ├── performance-agent/       # Orchestrates 4 performance skills
│   ├── testing-agent/           # Orchestrates 4 testing skills
│   └── adversarial-testing-agent/ # Orchestrates 6 security/stability skills
├── commands/                    # Slash command definitions
├── skills/                      # 38 specialized review skills
└── hooks/                       # Agent lifecycle hooks

Agent-Skill Pattern

Each agent follows an orchestrator pattern:

1. Receive — Get list of changed C++ files from git diff main
2. Filter — Apply exclusion patterns from .hpc-review.json
3. Spawn — Launch all skills in parallel (or sequentially for spec-compliance)
4. Collect — Gather JSON results from each skill
5. Aggregate — Merge and sort violations by file/line
6. Report — Generate final JSON and Markdown reports

Skills by Agent

Spec Compliance Agent (4 skills, sequential)

Skill	Description
spec-parsing	Extract requirements from spec files
probe-generation	Write probe apps that test requirements
probe-execution	Build and run probes, collect results
bug-reproduction	Create failing tests for bugs found

Coding Style Agent (7 skills)

Skill	Description
coding-style-naming	snake_case, PascalCase, m_prefix, ALL_CAPS
coding-style-includes	Include order and grouping
coding-style-headers	Header structure and #pragma once
coding-style-auto	Auto keyword usage
coding-style-memory	MWB_NEW/MWB_DELETE patterns
coding-style-errors	Error handling patterns
coding-style-docs	Inline documentation

Architecture Agent (4 skills)

Skill	Description
architecture-layers	Layer dependency violations
architecture-context	Context struct passing
architecture-singletons	Forbidden singleton patterns
architecture-dod	Data-oriented design in hot paths

Documentation Agent (5 skills)

Skill	Description
docs-completeness	Public API documentation
docs-clarity	12-year-old test for understandability
docs-mcp	MCP tool @error annotations
docs-files	docs/ folder maintenance
docs-consistency	Style and terminology consistency

Error Handling Agent (4 skills)

Skill	Description
error-logging	LOG(ERROR) has suggested_fix
error-propagation	Result types not ignored
error-coverage	All error paths handled
error-messages	Error message quality

Performance Agent (4 skills)

Skill	Description
performance-allocations	No allocations in hot paths
performance-loops	Loop efficiency, no copies
performance-memory	Memory pool usage
performance-patterns	Known anti-patterns

Testing Agent (4 skills)

Skill	Description
testing-execution	Run bin/test, collect results
testing-coverage	95% coverage threshold
testing-structure	Test file organization
testing-quality	Test case quality

Adversarial Testing Agent (6 skills)

Skill	Description
adversarial-null-safety	Null pointer dereference vulnerabilities
adversarial-bounds-checking	Buffer overflow and out-of-bounds access
adversarial-integer-safety	Integer overflow, underflow, truncation
adversarial-resource-safety	Resource leaks, double-free, exhaustion
adversarial-input-validation	Path traversal, format strings, division by zero
adversarial-state-corruption	Uninitialized vars, use-after-move, iterator invalidation

Configuration

Create .hpc-review.json in your project root to configure exclusions:

{
  "version": "1.0",
  "global": {
    "exclude": [
      "third_party/**",
      "*.generated.cpp",
      "*.generated.h"
    ]
  },
  "coding-style": {
    "exclude": [
      "tests/fixtures/**"
    ]
  },
  "architecture": {
    "exclude": []
  }
}

• global.exclude — Patterns applied to all agents
• <agent-name>.exclude — Patterns specific to one agent

Patterns use standard glob syntax (*, **, ?).

Output

Report Files

All reports are written to project root (git-ignored):

File	Description
CODE_REVIEW_REPORT.md	Combined summary from all agents
*_AGENT_REPORT.md	Individual agent markdown reports
*_AGENT.json	Individual agent JSON reports
CODING_STYLE_*.json	Skill-level JSON outputs

Severity Levels

Level	Meaning	Blocks PR
[ERROR]	Must fix before merge	Yes
[INFO]	Suggestion for improvement	No

Example Report

# HPC Code Review Report

**Generated**: 2025-12-28T12:00:00Z
**Branch**: feature/wand-crafting
**Base**: main

## Summary

| Agent | Status | Errors | Info |
|-------|--------|--------|------|
| spec-compliance | ✗ FAIL | 2 | 0 |
| coding-style | ✓ PASS | 0 | 3 |
| architecture | ✗ FAIL | 1 | 0 |
| documentation | ✓ PASS | 0 | 5 |
| error-handling | ✓ PASS | 0 | 0 |
| performance | ✗ FAIL | 1 | 2 |
| testing | ✓ PASS | 0 | 0 |
| adversarial-testing | ✗ FAIL | 2 | 0 |

**Overall**: ✗ FAIL (6 errors found)

## Errors by File

### src/hpc/game/wand.cpp

- **[architecture:layer_violation]** Line 5: HPC layer includes MWB header
- **[performance:hot_path_allocation]** Line 45: MWB_NEW in update_wand()

Layer Architecture

The plugin enforces this layer dependency model:

mwb::editor:: → mwb::game:: + hpc::editor:: + hpc::
mwb::game::   → hpc:: only
hpc::editor:: → hpc:: only
hpc::         → nothing (pure engine)

Key rules:

• hpc:: namespace must never reference mwb:: types
• Files in src/hpc/ must not include files from src/mwb/

Spec Compliance Workflow

The spec-compliance agent uses a critical rationalist approach:

1. Parse — Extract requirements from specs/NNN-feature-name/spec.md
2. Hypothesize — Generate testable hypotheses for each requirement
3. Probe — Create small programs that test each hypothesis
4. Execute — Build and run probes, collect pass/fail/crash results
5. Reproduce — Create failing tests in tests/ for any bugs found

Branch naming convention: NNN-feature-name (e.g., 004-code-review-agents)

Exit Codes

Code	Meaning
0	No errors found (may have INFO suggestions)
1	At least one ERROR found

Requirements

• Claude Code CLI
• Git repository with main branch as base
• C++ project structure

License

MIT License — Copyright (c) 2025 Hidden People Club

---

Built with Claude Code Plugins by Hidden People Club