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

A developer has created a "/repo-audit" slash command for Claude Code that performs a principal-engineer-grade repository audit using parallel subagents and adversarially verified findings. The tool maps the repository, fans out subagents across audit dimensions while mining git history for churn and complexity hotspots, then verifies every Critical and High finding against actual code before generating a comprehensive AUDIT.md report. The read-only command produces an executive summary with health grades, severity-rated findings, and a milestone-ordered task plan with runnable acceptance criteria that can be handed directly to fresh agent sessions.

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. 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. 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.