Codebase Audit

Codebase Audit — Adaptive Deep Analysis

Comprehensive codebase audit that adapts its agent configuration to the project's tech stack, forces structured findings, adversarially verifies Critical/High findings before they enter the report, diffs against the previous audit's ledger (resolved / still-open / new), and outputs a severity-sorted report plus a phased repair roadmap.

Core Principles

1. READ-ONLY — Audit agents must never create, modify, or delete files in the target. Every agent prompt starts with the read-only preamble in references/agent-prompts.md.
2. Inherit the session model — Omit the model param on all agents so they inherit the session model (usually the strongest available). Only override upward if the session model is clearly weak for cross-file reasoning. Never hardcode a specific model name in this skill.
3. Depth over breadth — Fewer agents with broader merged scopes beat many shallow agents. Each agent traces issues across file boundaries.
4. Adaptive — Agent count and dimensions vary by stack and mode.
5. Verified findings — Critical/High findings must survive an adversarial verify pass. Medium findings pass through but are labeled unverified in the report.

Operating Contract

• Direct actions: read-only inspection, local dependency audits, report writing under the target, and ledger updates under <target>/.audit/ after the user invokes this skill.
• Escalate before: editing audited project source files, dependency manifests, .gitignore, CI config, remote issues, PR state, or anything outside the requested audit/report scope.
• Secret evidence: retain file:line and the surrounding code, but replace credential values with [REDACTED] in findings, reports, and ledger entries; never reproduce the literal. This redacted snippet satisfies the code-evidence requirement.
• Evidence-backed pushback: challenge "all clear" or "resolved" only with file evidence, dependency-audit output, verifier results, or ledger spot-checks.
• Feedback loop: promote repeated misses into prompt updates, ledger matching rules, or fixture eval cases rather than leaving them as session-only notes.

Gotchas

• Dependency-audit commands must run from {TARGET_DIR}, not the assistant's incidental cwd.
• Finder agents must not read evals/expected-findings.json or eval README files when auditing the planted-bug fixture.
• A previous ledger miss is not proof that a finding was resolved; spot-check the file before marking an old finding resolved.

Modes

Optional dimensions (full mode only, enable when user asks or the repo obviously needs them):

• tests — test quality: assertion strength, skip markers, coverage of critical paths (Agent 6)
• concurrency — races, blocking calls in async, leaked tasks/goroutines (Agent 7)

Workflow

Phase 0: Detect & Prepare

1. Stack detection: package.json/tsconfig.json → TS/JS; pyproject.toml/requirements.txt → Python; Cargo.toml → Rust; go.mod → Go; multiple → full-stack.
2. Size estimate: tokei <target> (fallback: find <target> -name '*.<ext>' | xargs wc -l), excluding vendored/generated code. If effective size ≥ 400K LOC, split each agent's scope by top-level directory and note the split in the report.
3. Exclusions (always, in every agent prompt): node_modules/, vendor/, target/, dist/, build/, .git/, lockfiles, generated code.
4. Ledger: read <target>/.audit/findings.json if it exists — this is the previous audit baseline (format: references/ledger-format.md).
5. Deterministic dependency audit: from {TARGET_DIR} (never the assistant's incidental cwd), run each matching tool and feed raw output to the Error Handling & Security prompt:
   • Rust: cargo audit
   • Node: npm audit
   • Python metadata (pyproject.toml / setup.py): pip-audit .
   • Python requirements (requirements.txt): pip-audit -r requirements.txt
   • Python fallback with no project files: pip-audit .
   • Go: govulncheck ./... If a required tool is unavailable, the report must state 依赖审计降级跳过: <tool>; never omit the degradation silently.

Phase 1: Assemble Dimensions

Pick the configuration by detected stack. Full prompt templates in references/agent-prompts.md; prepend the read-only preamble and inject {TARGET_DIR} / {STACK_INFO} into each.

Full-Stack (5 agents) — frontend + backend both present:

Backend-Only (4 agents): replace #1 with "API Contract & Data Integrity" (which absorbs #2's data-flow/registry scope — do NOT also dispatch #2); keep #3–#5. Frontend-Only (3 agents): Component Architecture & Rendering; Error Handling & Code Quality; Config & Build. Quick mode (2 agents): Silent Degradation & Security (= #3); Data Integrity & Registry (= #2 core).

Fallback-path agent types (when using the Agent tool instead of Workflow): agent availability is environment-specific — check the subagent registry visible in the current session and use only type names that appear there. Never invent aliases (there is no generic reviewer type). If no specialized type matches, use general-purpose (or the environment's default catch-all) for every dimension; the prompts are self-contained. See the example mapping in references/agent-prompts.md.