# Repo Audit & Improvement Plan — /repo-audit slash command for Claude Code (parallel subagents, adversarially verified findings, agent-executable task plan) > Source: > Published: 2026-06-10 10:36:00+00:00 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.