code-quality-auditor

Multi-AI orchestrator. Three independent auditors find issues; one high-capability critic merges, ranks, and filters. Cross-auditor agreement visible per-finding via raised_by.

The skill always operates on the current working directory. Run Claude Code from inside the repo you want to audit.

Step 0 — Resolve invocation

Parse $ARGUMENTS for these flags. Unknown flags are fatal errors.

Project root: must be the current working directory and must be a git repository.

git rev-parse --show-toplevel

If not a git repo: print an error and STOP. The audit relies on git churn data.

Project name: basename "$(pwd)". Used in the output filenames.

Mode resolution precedence (first that resolves wins):

1. --mode flag value.
2. .claude/CLAUDE.md in the project root, if it documents a Pragmatic / Strict preference (grep for Pragmatic / Strict near the word Architecture or Level).
3. Conversational prompt to the user.
4. pragmatic (default if the user does not answer).

If --scope is missing, default to the whole project. No prompt — narrowing is the user's responsibility, and the recon phase will warn on large repos.

Step 1 — Reconnaissance (bash, no AI)

Source the recon library and gather project metadata.

source "${CLAUDE_SKILL_DIR}/lib/common.sh"
detect_project "$(pwd)"
hotspot_data="$(get_hotspot_data "$(pwd)")"
import_map="$(get_import_map "$(pwd)" "$PROJECT_LANGUAGES" "$PROJECT_SRC_ROOT")"

This sets PROJECT_LANGUAGES, PROJECT_FRAMEWORKS, PROJECT_TEST_FRAMEWORK, PROJECT_SRC_ROOT and produces hotspot + import data. Run it directly with the Bash tool — no subagent.

Large-repo warning

Count source files in scope (after applying --scope). If count > 300, print:

Warning: scope contains N source files. Multi-AI audits scale roughly linearly with file count across three parallel auditors. Consider narrowing with --scope (e.g., --scope src/services/). Proceeding — interrupt (Ctrl-C) to abort.

Then continue. The warning is informational; the user can abort if needed.

Step 2 — Auditor availability

Multi-AI mode (default): probe Codex and Gemini.

command -v codex >/dev/null 2>&1 && echo "codex available"
command -v gemini >/dev/null 2>&1 && echo "gemini available"

The Claude auditor is always available (via the Agent tool).

--single-ai mode: skip the probes; only the Claude auditor runs.

Track three lists:

• available_auditors: succeeded so far (initially: those that exist).
• missing_auditors: those skipped because the CLI is not installed.

Step 3 — Build the auditor prompt

Read ${CLAUDE_SKILL_DIR}/prompts/auditor.md. Strip the leading "# Auditor prompt template" preamble (everything before the first --- divider after the preamble). Replace placeholders:

Write three filled prompt files to $TMPDIR: auditor-claude.txt, auditor-codex.txt, auditor-gemini.txt. (In single-AI mode, only auditor-claude.txt.)

Also pre-allocate output paths: $TMPDIR/findings-claude.json, $TMPDIR/findings-codex.json, $TMPDIR/findings-gemini.json.

Step 4 — Fan out auditors in parallel

Issue all auditor calls in a single message so they run concurrently.

Claude auditor (Agent tool, background)

Agent({
  subagent_type: "general-purpose",
  description: "code quality audit (claude)",
  model: "sonnet",
  run_in_background: true,
  prompt: <contents of auditor-claude.txt> +
          "\n\nWhen finished, write your final JSON block to: $TMPDIR/findings-claude.json"
})

Tell the subagent to write its final JSON block to the file path AND include it in its response — that way you can recover even if the file write fails.

Codex auditor (Bash, dangerouslyDisableSandbox)

bash "${CLAUDE_SKILL_DIR}/scripts/codex-audit.sh" \
  "$TMPDIR/findings-codex.json" \
  "$TMPDIR/auditor-codex.txt"

Skip if codex is not installed.

Gemini auditor (Bash, dangerouslyDisableSandbox)

bash "${CLAUDE_SKILL_DIR}/scripts/gemini-audit.sh" \
  "$TMPDIR/findings-gemini.json" \
  "$TMPDIR/auditor-gemini.txt"

Skip if gemini is not installed.

Both wrapper scripts always exit 0 and report status on the last stdout line: done / unavailable / error:<msg>. Parse that line to update available_auditors / missing_auditors.

Wait for completion

Wait for the Claude background agent to complete and the bash calls to return. Then verify each expected findings-*.json exists and parses as JSON.

If a JSON file is missing or invalid, move that auditor from available_auditors to missing_auditors and record the error.

Step 5 — Quorum check

In --single-ai mode, surviving = 1 is the expected state and degraded stays false (single-AI mode is the user's explicit choice, not a failure).

Step 6 — Deterministic pre-merge

Read each surviving findings-*.json. Tag each finding with _auditor = auditor name. Then merge by (file, category, overlapping line range).

Two findings overlap iff: a.line_start <= b.line_end AND b.line_start <= a.line_end

Algorithm (apply exactly):

1. Concatenate all findings into a single list, each tagged with _auditor.
2. Group by (file, category).
3. Within each group, sort by line_start.
4. Linear scan: maintain a current cluster. If the next finding overlaps with the cluster's running [min line_start, max line_end], add it to the cluster. Otherwise close the cluster and start a new one.
5. Each cluster becomes one merged finding:
   • raised_by: sorted unique list of _auditor values in the cluster.
   • merged_from: list of original ids in the cluster.
   • line_start, line_end: min/max across the cluster.
   • principle, what, why, direction, context_notes: take from the finding raised by the most auditors; ties broken by lexicographic auditor name (claude < codex < gemini).
   • id: keep the chosen finding's id.
   • churn: max across the cluster (single source of truth — auditors should agree but defend against drift).
6. Strip the _auditor field.

Also merge testability_metrics: union by suite. For duplicate suites, average the numeric ratios and sum test_double_count. Add a reported_by array with the auditor names that produced each row.

Write the result to $TMPDIR/merged.json with shape:

{
  "findings": [...],
  "testability_metrics": [...]
}

Step 7 — Critic

Pick the critic model:

1. Default: Opus. The critic must NOT be one of the auditors — the auditors are Sonnet, the critic is Opus, so this holds.
2. Fallback: Sonnet. If Opus is unavailable / rate-limited (the Agent call fails with an Opus-specific error), retry once with Sonnet and set critic_degraded = true.

Build the critic prompt: read ${CLAUDE_SKILL_DIR}/prompts/critic.md, strip the preamble, fill placeholders:

Spawn the critic:

Agent({
  subagent_type: "general-purpose",
  description: "audit critic",
  model: "opus",  // or "sonnet" on fallback
  prompt: <filled critic prompt>
})

The critic must NOT have file-system access for source code. The prompt itself instructs this; no extra enforcement is needed beyond NOT giving the critic prompt any file paths or browse instructions. Do NOT include the import map in the critic prompt.

Capture the critic's full response.

Step 8 — Extract artifacts and write output

Compute filenames:

ts=$(date -u +%Y%m%dT%H%M%SZ)
project=$(basename "$(pwd)")
raw_path="./${ts}-${project}-audit.raw.txt"
json_path="./${ts}-${project}-audit.json"

Write the critic's full markdown response to $raw_path (this is the human-readable report).

Extract the last fenced ```json block from the critic's response. If critic_degraded was set, post-process the JSON to set critic_degraded: true (the critic should already do this from the placeholder, but verify). Write the JSON to $json_path.

If JSON extraction fails:

• Still keep $raw_path.
• Print a clear warning: "Critic produced no parseable JSON. Markdown report saved at $raw_path."

Step 9 — Final report to the user

Print a short summary:

Audit complete — <project>
  Auditors: <available_auditors> (missing: <missing_auditors>)
  Degraded: <degraded>
  Critic: <opus|sonnet (degraded)>
  Findings: <total> (critical: N, warning: N, info: N, likely-FP: N)
  Files:
    Report: ./<ts>-<project>-audit.raw.txt
    JSON:   ./<ts>-<project>-audit.json

Do NOT paste the full report into the chat — point at the file. The user can open it themselves.

Failure modes

Privacy

• Use relative paths from the project root in the report body — never paths containing the user's home directory.
• The orchestrator may use absolute paths internally (in $TMPDIR, in script arguments) but must not write them to the output artifacts.
• No secrets, API keys, or credentials in the report.