code-audit

A collection of Claude Code skills for comprehensive code auditing. These skills work together as a layered system: orchestrators compose individual audits, two-pass sweeps generate tests then fix issues, and component skills provide focused analysis.

Installation

Copy the skills/ directory into your Claude Code skills folder:

cp -r skills/* ~/.claude/skills/

Or symlink individual skills:

ln -s "$(pwd)/skills/sweep1" ~/.claude/skills/sweep1

Architecture

                    Orchestrators
            (compose audits in parallel)
    ┌──────────────┬──────────────┬──────────────┐
    │   /sweep1    │   /sweep2    │   /sweep3    │
    │  Contracts   │   Quality    │    Ops &     │
    │ & Security   │              │   Infra      │
    └──────┬───────┴──────┬───────┴──────┬───────┘
           │              │              │
    ┌──────┴──────┐┌──────┴──────┐┌──────┴──────┐
    │/api-contract││  /tech-debt ││/performance- │
    │   -audit    ││             ││  profile     │
    │/migration-  ││/style-review││/dependency-  │
    │   review    ││             ││  audit       │
    │/security-   ││/test-health-││/production-  │
    │   audit     ││   audit     ││  ready       │
    └─────────────┘└─────────────┘└─────────────┘
           Component Skills (read-only analysis)

    ┌─────────────────────────────────────────────┐
    │           Two-Pass Sweeps                    │
    │  Pass 1: audit agent (read-only, generates  │
    │          tests + .tmp analysis file)         │
    │  Pass 2: fix agent (runs tests, fixes code, │
    │          3-attempt loop, writes docs)        │
    ├─────────────┬───────────────┬───────────────┤
    │/architecture│  /crud-sweep  │ /fuzz-sweep   │
    │   -sweep    │               │               │
    │/state-      │ /category-    │               │
    │ machine-    │   sweep       │               │
    │   sweep     │               │               │
    └─────────────┴───────────────┴───────────────┘

    ┌─────────────────────────────────────────────┐
    │           Foundational                       │
    │                                              │
    │  /design-patterns  — GOF vocabulary          │
    │                      (used by all sweeps)    │
    │  /add-events       — event-sink refactoring  │
    │                      (prerequisite for /fuzz)│
    │  /production-sinks — file sinks for events   │
    │                      (logs/catastrophic.log, │
    │                       logs/errors.log)       │
    └─────────────────────────────────────────────┘

Skills Reference

Orchestrator Sweeps

These run /design-patterns first to establish vocabulary, then launch three audits in parallel, then run /design-patterns again to synthesise findings.

Skill	Focus	Component Audits
/sweep1	Contracts & Security	/api-contract-audit + /migration-review + /security-audit
/sweep2	Code Quality	/tech-debt + /style-review + /test-health-audit
/sweep3	Ops & Infrastructure	/performance-profile + /dependency-audit + /production-ready

Two-Pass Sweeps

These launch two agents sequentially: a read-only audit agent that generates tests and writes a .tmp analysis file, then a fix agent that runs the tests, fixes code, and retries up to 3 times.

Skill	What it does	Output
/architecture-sweep	Module depth, information hiding, dependencies, event-sink separation (Ousterhout)	ARCHITECTURE.md
/crud-sweep	Maps all CRUD operations against a 40+ edge case matrix, generates integration tests	CRUD coverage report
/fuzz-sweep	Discovers system boundaries, generates fast-check fuzz tests. Prerequisite: /add-events	Fuzz test report
/state-machine-sweep	Detects status fields as finite automata, generates property-based random walk tests	State machine report
/category-sweep	Finds functors, monads, Kleisli categories, Yoneda instances; writes law tests	CATEGORY_THEORY.md

Component Skills (read-only)

These analyse and report but never modify code.

Skill	Focus
/design-patterns	GOF pattern inventory: patterns in use, anti-patterns, recommended introductions
/api-contract-audit	Response consistency, backward compatibility, idempotency, schema evolution, error contracts
/migration-review	Destructive ops, locking risks, missing indices, rollback strategy
/security-audit	OWASP Top 10, injection, auth bypass, input validation, data exposure
/tech-debt	Coupling, god objects, dead code, duplicated logic; prioritised debt register
/style-review	Clarity, obviousness, module depth, naming, exception handling
/test-health-audit	Pyramid shape, coverage gaps, test quality, flakiness, maintainability
/performance-profile	N+1 queries, bundle bloat, memory leaks, missing caches
/dependency-audit	CVEs, outdated packages, unused deps, license conflicts, supply chain risks
/production-ready	Observability, reliability, data integrity, performance, concurrency, deployment safety

Foundational

Skill	Purpose
/add-events	Refactors business logic to return events as pure data (event-sink pattern). Prerequisite for /fuzz-sweep.
/production-sinks	Creates file sinks that route events by severity to logs/catastrophic.log and logs/errors.log (JSONL). Companion to /add-events.

Usage

Run any skill from Claude Code:

/sweep1                          # Full contracts & security audit
/architecture-sweep              # Two-pass architecture review
/crud-sweep                      # CRUD edge case audit
/fuzz-sweep api                  # Fuzz API routes only
/state-machine-sweep discover    # Find all state machines
/category-sweep full             # Full categorical analysis
/design-patterns src/lib         # GOF analysis of a specific module
/tech-debt full                  # Full tech debt assessment
/dependency-audit security       # Security vulns only

Recommended Workflows

Before shipping:

/sweep1          # contracts, migrations, security

Before refactoring:

/sweep2          # tech debt, style, test health

Before deployment:

/sweep3          # performance, deps, production readiness

Full audit (all three):

/sweep1
/sweep2
/sweep3

Event-driven testing pipeline:

/add-events              # 1. Refactor to return events
/production-sinks        # 2. Create file sinks for errors
/fuzz-sweep              # 3. Fuzz all boundaries
/state-machine-sweep     # 4. Test state machines
/crud-sweep              # 5. Test CRUD edge cases

How the Two-Pass Pattern Works

1. Pass 1 (Audit Agent): Read-only. Analyses the codebase, generates test files, writes a .tmp analysis file (e.g., architect.tmp, crud-audit.tmp). Never modifies application code.

2. Between Passes: The orchestrator confirms the .tmp file exists and summarises findings.

3. Pass 2 (Fix Agent): Reads the .tmp file, runs the generated tests, diagnoses failures, fixes application code, retries up to 3 times. Deletes the .tmp file when done. May write documentation (e.g., ARCHITECTURE.md).

Customisation

The /security-audit skill is currently scoped to a healthcare CRM (Next.js/Prisma). To adapt it for your project, update the "Critical Surfaces" section in skills/security-audit/SKILL.md to list your project's attack surfaces.

All other skills are project-agnostic and auto-detect the tech stack.

License

MIT