/deep-audit

name: deep-audit
description: Run a comprehensive deep audit by orchestrating specialist agents (security, performance, libraries, quality, dead code) into a single dated report.
when_to_use: When the user explicitly asks for a "deep audit", "full codebase audit", or "comprehensive code review". Resource-intensive — never run it for a quick diff review.
argument-hint: "[aspects] [sequential]"
allowed-tools:
  - Bash("${CLAUDE_PLUGIN_ROOT}/scripts/dead-code-detect.sh" *)
  - Bash(npx knip*)
  - Bash(npm run lint*)
  - Bash(npm run typecheck*)
  - Bash(deadcode*)
  - Glob
  - Grep
  - Read
  - Write
  - Agent
  - TodoWrite
disable-model-invocation: true
hooks:
  Stop:
    - hooks:
        - type: agent
          timeout: 120
          prompt: >-
            Hook input: $ARGUMENTS. If stop_hook_active is true in the input,
            respond {"ok": true} immediately. Otherwise, glob the project root
            for a code-audit-*.md report file created during this audit; if one
            exists respond {"ok": true}, if the audit ran but no report was
            saved respond {"ok": false, "reason": "The audit findings must be
            saved to code-audit-[timestamp].md before stopping"}.

Deep Audit (Orchestrator)

Run a comprehensive, on-demand codebase audit by inspecting the project, deciding which specialist agents apply, launching them, and aggregating their findings into a single dated report.

This is **resource-intensive** and should only run when explicitly requested. For quick checks on recent changes, just ask Claude to review the diff.

**Aspects requested (optional):** "$ARGUMENTS"

Audit Aspects

• **security** → `security-auditor` (secrets, injection, XSS, weak crypto, CVEs)
• **perf** → `performance-analyzer` (algorithms, N+1, async, memory, bundles)
• **deps** → `library-modernizer` (custom code → mature lib, deprecated APIs, `@types` duplication)
• **quality** → `code-quality-reviewer` (smells, complexity, duplication, error handling)
• **dead** → `dead-code-cleanup` in detect-only mode (unused imports/exports/files/deps, with verification)
• **all** → run every applicable specialist (default if no aspects given)

The launch mode is **parallel by default** — `/deep-audit` produces a batch report, so there's no reason to wait. All selected specialists are launched at once via a single message with multiple `Agent` calls. Append the literal token `sequential` to fall back to one-at-a-time execution (useful when debugging a specialist or when a transcript is easier to read serially).

Workflow

1. Parse arguments

Split `$ARGUMENTS` on whitespace. Tokens that match an aspect (`security`, `perf`, `deps`, `quality`, `dead`, `all`) select that specialist. The token `sequential` switches launch mode to one-at-a-time. Anything else is treated as a free-form scope hint to pass into each specialist (e.g., a path, glob, or "src/api only").

If no aspects are given, treat it as `all`.

2. Pre-analysis (orchestrator does this directly)

Read the project skeleton so each specialist gets a useful brief:

• Tech stack: presence of `package.json`, `tsconfig.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.
• Project conventions: read `CLAUDE.md` and top-level `README.md` if present.
• Existing baselines: if a lint/typecheck script exists in `package.json`, run it once and capture errors as a baseline (don't re-flag those).
• Inventory: a Glob count of code files by extension to gauge audit size.

Build a short "project brief" that you'll include in every specialist's task input.

3. Decide which specialists apply

| Aspect | Applies when | | --- | --- | | `security-auditor` | Always (every codebase has a security surface) | | `performance-analyzer` | Always | | `library-modernizer` | A dependency manifest exists (`package.json`, `requirements.txt`, `go.mod`, etc.) | | `code-quality-reviewer` | Always | | `dead-code-cleanup` | A dependency manifest exists. If `dead` was requested (or selected via `all`) but no manifest exists, **the Notes section must include an explicit `Dead code: skipped — no manifest` line** before the report is written — never silently omit. |

If the user requested specific aspects, only run those — don't override their selection.

4. Launch specialists

Use the `Agent` tool to invoke each selected specialist. Pass each one:

• The **project brief** from step 2
• The **scope** (free-form scope hints from `$ARGUMENTS`, or "full codebase")
• An instruction to **return only the structured findings block** described in the agent's prompt — not save a file

**Parallel mode (default):** issue all selected `Agent` calls in a single assistant message so they run concurrently. Capture each result as it returns.

**Sequential mode (`sequential` arg present):** issue one `Agent` call, wait for the result, capture the markdown, then issue the next.

For `dead`, invoke `dead-code-cleanup` and instruct it to **detect only** (no removal). Tell it to return its verified findings as a markdown block matching the format below.

4a. Verify each specialist returned a valid findings block

Before pasting a result into the report, confirm it starts with the specialist's expected `## ` heading and contains at least one of `### Critical`, `### High`, or `### Medium`. A specialist with literally zero findings still emits the heading and severity sections (possibly empty).

| Specialist | Expected heading | | --- | --- | | `security-auditor` | `## Security Findings` | | `performance-analyzer` | `## Performance Findings` | | `library-modernizer` | `## Library Modernization Findings` | | `code-quality-reviewer` | `## Code Quality Findings` | | `dead-code-cleanup` | `## Dead Code Analysis Report` (or `## Dead Code Findings`) |

If a result is empty, missing the expected heading, or has no severity sections, treat the specialist as **failed**: do not paste a placeholder block. Record it under `Specialists that failed:` in the Notes