codebase-audit

name	codebase-audit
version	1.0.0
description	On-demand codebase analysis that dispatches multiple independent agents to find issues, filters for high-confidence findings via convergence scoring, and produces structured reports with cross-run tracking. Use when you want a health check of the codebase — "/codebase-audit" or "audit the codebase".
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","Agent","TaskCreate","TaskUpdate"]

Codebase Audit

Dispatch 6 parallel analysis agents (3 generalist + 3 specialist), synthesize findings with convergence scoring, and produce a structured report with cross-run tracking.

Announce at start: "Running codebase audit — dispatching 6 analysis agents in parallel."

Analysis Categories

The 14 categories agents evaluate against:

Code Health

1. DRY / duplication — repeated logic, copy-pasted patterns
2. Code clarity — naming, readability, understandability without context
3. File focus — single responsibility per file, files not doing too much
4. Consistency — similar things look similar across the codebase

Architecture

5. Code organization — module boundaries, separation of concerns, package structure
6. Design patterns — appropriate use of patterns (over-engineering counts too)
7. Dependency direction — circular deps, leaky abstractions, dependency flow
8. Idiomatic usage — tRPC, Hono, Zod, React Router 7, Radix used as intended

Robustness

9. Error handling — failures handled at system boundaries, not silently swallowed or over-handled
10. Type safety — any usage, missing types, Zod schema coverage at boundaries
11. Security — shell execution sandboxing, injection risks, secrets handling, WebSocket auth

Operational

12. API cost efficiency — Claude/OpenAI API call patterns, token waste, streaming efficiency
13. Performance — obvious bottlenecks, unnecessary re-renders, N+1 patterns
14. Coupling — how hard is it to change one thing without breaking another

Orchestration Flow

Follow these phases exactly. Do not skip phases or reorder them.

Phase 0: Setup

1. Generate file tree. Run: find . -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.json' -o -name '*.yml' -o -name '*.yaml' -o -name 'Dockerfile*' \) | grep -v node_modules | grep -v dist | grep -v .react-router | sort in the project root. Save this output — you will include it in agent prompts.

2. Check for prior audit. Look for the most recent folder in docs/superpowers/audits/ (folders are named YYYY-MM-DD). If one exists, read its summary.md file. This is the "prior summary" — you will pass it to the synthesis agent.

3. Identify specialist file lists. Use both filename matching (Glob) and content matching (Grep) to build each list. Combine results and deduplicate.

   • Security:
     • Glob: files in **/ws/, **/tools/ directories; filenames containing exec, shell, websocket, auth, sandbox
     • Grep: files importing child_process, exec, execFile, spawn; files referencing WebSocket, process.env
   • Cost:
     • Glob: filenames containing api, claude, anthropic, openai, whisper, tts, stt
     • Grep: files importing from @anthropic-ai/sdk, openai; files referencing stream, token in API contexts
   • Idioms:
     • Glob: filenames containing trpc, router, route, middleware, schema, hono; all .tsx files
     • Grep: files importing from @radix-ui, @trpc, hono, zod

Phase 1 + 2: Dispatch All 6 Agents (Parallel)

Dispatch all 6 agents in a single message using 6 parallel Agent tool calls. Each agent runs independently with no knowledge of the others.

Read each prompt template file before dispatching. Use the Read tool to load each one from ~/.claude/skills/codebase-audit/prompts/.

For each agent, construct the prompt by:

1. Reading the prompt template
2. Injecting the file tree (for generalists) or the curated file list (for specialists)
3. Injecting the lens/perspective (for generalists — see the 3 lenses below)

Generalist Agents (3x, model: sonnet)

Use the prompts/generalist-sweep.md template for all three. Each gets a different lens:

• Agent A — Onboarding lens: "Analyze as if you're onboarding a new developer. What's confusing, inconsistent, or surprising?"
• Agent B — Production lens: "Analyze as if you're preparing this for production scale. What breaks, wastes money, or creates risk?"
• Agent C — Review lens: "Analyze as if you're reviewing a PR of the entire codebase. What would you flag?"

Dispatch with model: "sonnet" and subagent_type: "general-purpose".

Example Agent invocation (for Generalist A):

Agent tool:
  description: "Generalist A: onboarding lens"
  subagent_type: "general-purpose"
  model: "sonnet"
  prompt: |
    [contents of generalist-sweep.md with {{LENS}} replaced by the onboarding lens text
     and {{FILE_TREE}} replaced by the actual file tree from Phase 0]

Use the same pattern for all 6 agents, substituting the appropriate prompt template, lens/file list, and model.

Specialist Agents (3x)

Each uses its own prompt template with the curated file list injected.

• Security — prompts/deep-dive-security.md, model: "opus"
• Cost — prompts/deep-dive-cost.md, model: "sonnet"
• Idioms — prompts/deep-dive-idioms.md, model: "opus"

Dispatch with subagent_type: "general-purpose".

Phase 3: Synthesis (Sequential)

Wait for all 6 agents to return. Then:

1. Read the prompts/synthesis.md template.
2. Construct the synthesis prompt by injecting:
   • All 6 agent outputs (label each clearly: "Generalist A output:", "Security specialist output:", etc.)
   • The prior audit summary (if one exists from Phase 0), or "No prior audit found" if this is the first run
   • Today's date
3. Dispatch one Agent with model: "opus", subagent_type: "general-purpose".

The synthesis agent returns structured markdown content for all 5 output files.

Phase 4: Write Output

1. Create the output directory: docs/superpowers/audits/YYYY-MM-DD/ (using today's date). If the directory already exists (same-day re-run), overwrite the files — the newer audit supersedes the earlier one.

2. Parse the synthesis agent's output and write 5 files:

   • summary.md
   • critical.md
   • important.md
   • minor.md
   • prior-comparison.md

   Split the synthesis output on the === SUMMARY ===, === CRITICAL ===, === IMPORTANT ===, === MINOR ===, and === PRIOR COMPARISON === delimiters. Each section's content (after the delimiter line) becomes the corresponding file.

3. Report completion to the user with a brief summary of finding counts by severity.

4. Ask the user if they'd like to commit the audit results. If yes: git add docs/superpowers/audits/YYYY-MM-DD/ && git commit -m "audit: codebase audit YYYY-MM-DD"

Output Format Reference

See examples/sample-output.md for the exact format each output file should follow. The synthesis agent's prompt includes these formats — the orchestrator just needs to split the output into the 5 files.

Error Handling

• If an agent fails or returns empty output, note it in the summary ("Agent X did not return results") and proceed with the remaining outputs. Do not retry.
• If no prior audit exists, skip the comparison. The prior-comparison.md should say "First audit run — no prior data for comparison."
• If the synthesis agent fails, save the raw agent outputs to docs/superpowers/audits/YYYY-MM-DD/raw/ so the run isn't lost.