clauditor

name

clauditor

description

Spawn adversarial fresh-eyes review subagents through the local Claude Code CLI, using the user's normal Claude CLI authentication and the strongest available model. Use when the user invokes /clauditor or $clauditor, asks for adversarial reviewers, wants Claude subagents to critique a project, wants independent persona-based UI/content/product feedback, or wants a multidisciplinary code audit panel with roles such as security, performance, UX, DX, and edge-case specialists.

Clauditor

Overview

Run an adversarial review panel by launching independent Claude Code CLI sessions as read-only subagents. Use the installed claude binary as the current user; do not use hidden API keys, do not bypass Claude permissions, and do not grant mutating tools unless the user explicitly asks for a fix pass.

Prefer the strongest available Claude model for every reviewer:

• Use CLAUDITOR_MODEL when the user/environment sets it to a specific highest-tier model.
• Otherwise use Claude Code's opus alias with --effort max, because the alias should track the latest Opus-class model available to that user.
• If the user provides or the environment documents a newer explicit Opus model ID, such as an Opus 4.7-or-newer identifier, set CLAUDITOR_MODEL to that ID instead of relying on the alias.
• Do not silently downgrade to Sonnet or a smaller model. If Opus-class access fails, report the blocker and ask before continuing with a lower model.

Workflow

0. Smoke-test the Claude CLI once before launching a panel.
   • Run from the same shell context that will launch the reviewers:

printf '%s\n' "Passthrough smoke test. Reply exactly: CLAUDITOR_OK" | \
claude --print \
  --model "${CLAUDITOR_MODEL:-opus}" \
  --effort max \
  --output-format text \
  --allowed-tools Read Grep Glob

• If this fails with 401 Invalid authentication credentials, stop and report that the local Claude CLI auth is stale or invalid. Do not invent alternate credentials or switch to a blank environment; ask the user to refresh claude auth login in their normal shell.

1. Build a short review brief.

   • Identify the project root, scope, target audience, success criteria, and what should be considered a meaningful finding.
   • For code audits, include the relevant diff, paths, product assumptions, and whether edits are in scope.
   • Have the parent process gather the changed-files list and the diff/PR text, then include that context in the reviewer prompt. Do not make child reviewers run shell commands just to discover the diff.
   • For UI/content reviews, include the intended audience, page/app goal, and target workflow.

2. Select personas before launching reviewers.

   • Read references/persona-playbook.md when persona choice is not obvious.
   • Use project-specific personas, not generic "reviewer 1" labels.
   • Default to one adversarial reviewer. Fan out only when the user requested multiple personas, another skill such as $be-thorough needs them, or the change is high-stakes enough to justify parallel cost and noise.
   • For code audits, include roles modeled after $audit-code: Security, Performance, UX, DX, Edge Case, plus a lead synthesis pass.
   • For web UI work, include realistic target users across experience levels, plus accessibility and domain-skeptic perspectives.
   • For content pages, include reader comprehension personas: first-time reader, rushed evaluator, technical buyer/operator, skeptical domain expert, and clarity/accessibility reviewer where relevant.

3. Launch independent Claude subagents.

   • Prefer direct Claude CLI calls that fit the current task and shell. The LLM running this skill should decide the exact prompt shape, persona count, output location, and whether to run reviewers in parallel.
   • Use the current user's normal shell environment. Do not use env -i, --bare, separate API credentials, or any command that bypasses the user's normal Claude CLI auth/session.
   • Set CLAUDITOR_ACTIVE=1 on spawned reviewer processes. If this variable is already set, do not spawn more reviewers; this prevents recursive self-review loops.
   • Give child Claude reviewers a strict allowlist: Read, Grep, and Glob. Keep Bash, Edit, Write, Task, and MCP tools unavailable during review passes.
   • When automating result capture, prefer --output-format stream-json --verbose and read the final type: "result" event. This is easier to supervise than scraping a full interactive transcript.
   • Wrap reviewer processes in a watchdog. If an Opus --print review appears to hang, capture report/stderr/exit/timeout files, inspect whether stdout and stderr remain at zero bytes, and verify a tiny Opus diagnostic prompt still succeeds. Then retry Opus with a shorter human prompt, fewer/no tools, pasted context if needed, and lower Opus effort before asking to use a smaller model. If repeated Opus/max attempts remain zero-byte silent while diagnostics pass, stop retrying max and use Opus at lower effort with the smallest useful read-only tool set.
   • A typical direct call looks like this:

cat <<'PROMPT' | CLAUDITOR_ACTIVE=1 claude --print \
  --model "${CLAUDITOR_MODEL:-opus}" \
  --effort max \
  --output-format stream-json \
  --verbose \
  --allowed-tools Read Grep Glob
You are an independent adversarial reviewer. Review only this supplied diff and use Read/Grep/Glob only for extra context.
PROMPT

• Use the bundled Bash runner only when a simple repeatable panel is useful:

path/to/clauditor/scripts/clauditor \
  --project /path/to/project \
  --scope "Describe files, routes, diff, pages, or workflows to review" \
  --brief "State the review goal and meaningful-finding bar" \
  --persona "Security reviewer|Find authz, data exposure, injection, unsafe IO, and abuse paths." \
  --persona "Performance reviewer|Find scale, latency, cost, concurrency, cache, and payload risks."

• Run from the target repository when possible. The runner stores prompts and reports under .clauditor/ by default; use --output "$(mktemp -d)" for no-edit/no-artifact audits.
• Keep prompts isolated. Do not give subagents prior findings, suspected bugs, intended fixes, or the main thread's conclusions unless needed to define scope.
• Ask each reviewer for evidence-backed findings only, with file references or concrete UI/content evidence, impact, confidence, proposed fix, and verification.

4. Reconcile as lead reviewer.

   • Classify each subagent item as actionable defect, duplicate, stale/already fixed, speculative, style preference, or out of scope.
   • Merge duplicates and sort remaining findings by severity, blast radius, exploitability/user impact, and confidence.
   • Treat disagreement as a reason to inspect the evidence yourself, not as a vote count.

5. Converge when edits are in scope.

   • Fix meaningful findings, run the narrowest relevant verification, then rerun the affected personas.
   • Continue until a full reviewer round produces no meaningful new findings, or document the blocker/cost constraint.
   • If the user requested report-only/no edits, do not fix; keep findings in the report and state that convergence fixes were intentionally skipped.

Guardrails

• Keep Claude sessions read-only by default. Do not grant Edit, Write, MultiEdit, package installation, deployment, secret-reading, or external mutation tools for review passes.
• Never print secrets. If a reviewer needs credentials or production access to validate a claim, classify it as externally unverified.
• Do not run destructive shell commands from reviewer sessions.
• Use concise prompts. The point is independent judgment, not reproducing the whole main-thread context.
• Capture report paths, commands, model, return codes, and any Claude auth/model failures in the final response.

Output

Return one synthesized report:

1. Findings
2. Open Questions / Assumptions
3. Change Summary or Remediation Plan
4. Suggested Verification
5. Reviewer Artifacts

For each finding, include the responsible persona, severity, confidence, impact, evidence, proposed fix, and verification. If there are no validated findings, say so clearly and mention residual test or evidence gaps.