Repo Audit & Improvement Plan — /repo-audit slash command for Claude Code (parallel subagents, adversarially verified findings, agent-executable task plan)

README.md

/repo-audit — a Claude Code slash command

A principal-engineer-grade repository audit, tuned for Claude's latest models running inside Claude Code.

It maps the repo, fans out parallel subagents (one per audit dimension, plus git-history mining for churn × complexity hotspots), adversarially verifies every Critical/High finding against the actual code before reporting it, runs the repo's own lint/type-check/test commands instead of guessing at health, and writes a single AUDIT.md containing:

• Executive Summary — health grade A–F, top 3 risks, top 3 opportunities
• Repo Map
• Severity-rated findings (file:line cited, facts separated from judgments)
• Improvement strategy — the 3–5 themes behind the findings, with measurable "done" signals
• A milestone-ordered task plan where each task is a self-contained brief a fresh agent session can execute, with runnable acceptance criteria
• Quick wins flagged separately

Read-only: it never modifies your code. The report is the only file it creates.

Install — user-wide (available in every repo)

mkdir -p ~/.claude/commands
curl -fsSL https://gist.githubusercontent.com/OmerFarukOruc/753f95b1ac278b683be83ed26b3bcc1f/raw/repo-audit.md -o ~/.claude/commands/repo-audit.md

Open a new Claude Code session and run /repo-audit.

Install — single project only

mkdir -p .claude/commands
curl -fsSL https://gist.githubusercontent.com/OmerFarukOruc/753f95b1ac278b683be83ed26b3bcc1f/raw/repo-audit.md -o .claude/commands/repo-audit.md

Install — manual

Copy the contents of repo-audit.md from this gist into ~/.claude/commands/repo-audit.md. That's it — Claude Code picks up the file automatically.

Usage

/repo-audit

• Pass an optional focus: /repo-audit security or /repo-audit src/billing.
• Run it in normal mode, not plan mode. The audit is read-only; plan mode inserts an approval stop that costs you nothing but waiting.
• For very large repos where you want maximum depth, opt into multi-agent orchestration explicitly: /repo-audit use a workflow (or include the word ultracode).
• The audit runs end to end without check-ins — it's read-only and safe to leave running.
• Output lands in AUDIT.md at the repo root, written for a reader who didn't watch the run.

Why this version

This is a rework of the viral "Repo Audit & Improvement Plan" prompt, restructured around how current Claude models actually work best:

• Purpose over persona — states why the audit exists (the report becomes a work queue for future agent sessions) instead of role-playing a "world-class engineer".
• Orchestrated, not single-threaded — parallel subagents per dimension instead of one linear pass.
• Verified, not just cited — fresh-context subagents try to refute each Critical/High finding; what doesn't survive gets dropped or downgraded. Claims are checked against actual tool output (including really running the test suite) before they enter the report.
• History-aware — mines git history for bug-fix-dense, high-churn files instead of auditing a frozen snapshot.
• Agent-executable output — tasks have runnable pass/fail acceptance criteria, so you can hand each one straight to a new Claude Code session.

repo-audit.md

description	Principal-level repo audit → evidence-verified findings → agent-executable task plan
argument-hint	optional focus — a subdirectory dimension or concern

Repo Audit & Improvement Plan

Context — why this audit exists

I maintain multiple products solo and don't have time to review tech debt by hand. Your audit becomes the work queue for future Claude Code sessions: each task you produce will be handed to a fresh agent with no other context. Audit accordingly — truth over reassurance; a flattering report is worthless to me.

Audit focus for this run, if any: $ARGUMENTS

Ground rules

• Every finding cites file:line you actually read this session. If you can't verify a claim, label it unverified — never guess. Before writing the final report, check each claim against a tool result from this session.
• Analysis only. Do not modify code, config, or dependencies. The only file you create is the report.
• Don't just read claims of health — observe them. Run the repo's own read-only commands (install, lint, type-check, test suite, dependency audit) where practical, and report outcomes faithfully: if the tests fail, say so with the output.
• Calibrate to the project's maturity — don't demand enterprise rigor of a prototype. If the repo is large, go deep on the core 20% that does 80% of the work, and say what you skipped.
• Prefer 15 high-confidence findings over 50 speculative ones. Separate facts from judgments. If a dimension is healthy, say so in one sentence and move on. List genuine strengths too — they tell me what to protect.

How to work

• If you were launched in plan mode, every decision is already made here: your plan is one line ("run this audit as specified") — submit it for approval immediately.
• Fan out parallel subagents: Explore agents for discovery first, then one auditor per audit dimension, spawned as a single parallel batch and each handed the repo map so it doesn't re-derive it. Keep synthesizing while they run.
• If a repo tool (pnpm, yarn, a linter) is missing from PATH, try corepack or version-manager shims (mise, asdf, nvm) before concluding it's absent.
• Plain subagents (the Agent tool) are the right default: you keep synthesizing, steering refuters, and re-verifying citations between waves. Only if my invocation says "use a workflow" or "ultracode" should you script the fan-out with the Workflow tool instead — treat those words as orchestration opt-in, not as an audit focus.
• Mine git history, not just the snapshot: high-churn × high-complexity files, bug-fix-dense modules, abandoned directories, the age of TODO/FIXME comments.
• Adversarial verification: before any Critical or High finding enters the report, a fresh-context subagent must try to refute it against the actual code. Drop or downgrade findings that don't survive.
• Work end to end without checking in — this is read-only and safe. When you have enough information to act, act.

Phase 1 — Discovery (read before judging)

Map: purpose and intended users, stack and runtime targets, entry points, core modules, main data/control flow, build/CI/env config, existing conventions (so recommendations fit the culture, not fight it), maturity level. Output a concise Repo Map, including anything that surprised you.

Phase 2 — Audit

Dimensions: architecture & layering; code quality (duplication, dead code, complexity hotspots, swallowed errors, type-safety holes); security (secrets, injection, missing validation, auth weaknesses, vulnerable deps); testing (gaps around core logic, tests that assert nothing); performance (N+1 queries, blocking calls in async paths, unbounded growth); dependencies (outdated, unmaintained, heavy; lockfile hygiene); DevEx & ops (build friction, CI gaps, observability, deployment story); docs vs reality.

Each finding: what, where (file:line), why it matters, severity (Critical/High/Medium/Low), confidence, fact-or-judgment.

Phase 3 — Improvement strategy

The 3–5 themes that explain most findings; target state and the principle behind it per theme; what you are NOT fixing and why (effort vs payoff); "done" defined as measurable signals (e.g. "CI fails on lint errors", "core-path coverage ≥ 80%").

Phase 4 — Task plan

Discrete tasks a fresh Claude Code session can execute from the brief alone: title, one context paragraph, files affected, acceptance criteria as runnable checks wherever possible (a command that passes or fails), effort (S <2h, M half-day, L 1–2 days, XL needs breakdown), risk, dependencies. Order into milestones:

• M0 — Safety net: tests around critical paths, CI gates
• M1 — Critical fixes: security and correctness
• M2 — High-leverage: changes that make all future work easier
• M3 — Quality & polish

Flag quick wins (high impact, S effort) separately. Include implementation sketches for the top 3 tasks.

Deliverable

Write one file, AUDIT.md, at the repo root. Open it with the audited commit SHA, the date, and a one-paragraph method note ending in the refuter tally (findings refuted outright / downgraded / survived). Then: Executive Summary (health grade A–F, top 3 risks, top 3 opportunities) → Repo Map → Audit Report (worst first) → Improvement Strategy → Task Plan → Open Questions (each naming the decision I need to make).

Write it for a reader who didn't watch you work: lead with the outcome, complete sentences, spell out terms, no working shorthand. Don't pad — be selective about what you include, don't compress the writing.

This is awesome! Repo audit is a good first pass for an agent verifying agent, we built a deterministic layer which sits between agent and tool calls for security checks in all vibe coding sessions. Nothing blocks users as everything is opt-in warn mode. immunity-agent is free and open source, would love some feedback and contribution