Comprehensive Audit

Full-spectrum codebase audit with configurable scope and domain focus. This is the deep audit — thorough, multi-pass, with cross-examination and fix-and-verify cycles.

Scope Detection

Parse user input for scope:

Service vs domain detection: If the input matches a known service directory (check AGENTS.md or scan for directories with package.json + src/), treat it as a service scope. Otherwise treat it as a domain scope.

Phase 0: Build Project Context

Before launching any agents, you MUST build a context block from the actual codebase.

Read these files (in order, skip if missing):

1. AGENTS.md — canonical patterns, conventions, tech stack
2. CLAUDE.md — project instructions, dev commands
3. package.json (root) — workspace structure, scripts, dependencies
4. Monorepo config if present (turbo.json, nx.json, pnpm-workspace.yaml)
5. api-contract.md for the scoped service (if service-scoped audit)

From these, construct a {context block} that includes:

• Tech stack (framework, language, package manager, monorepo tool if any)
• Project structure (apps, packages, key directories)
• Auth/security patterns (from AGENTS.md — RBAC, RLS, session handling, etc.)
• Key conventions (import aliases, naming, file organization)
• Dev commands (typecheck, lint, build, test — and what "pass" looks like)

This context block gets injected into every agent prompt below where {context block} appears.

Also detect:

• Typecheck command: Look in package.json scripts for typecheck, type-check, tsc; fallback to npx tsc --noEmit
• Test command: Look for test, vitest, jest; note if per-service or monorepo-wide
• Lint command: Look for lint; fallback to npx eslint .; skip if none found
• Build command: Look for build

Also detect which audit domains are relevant:

• Has database/schema files? -> include Data audit
• Has frontend/UI code (React, Vue, HTML pages)? -> include UI/UX audit
• Has only backend/API code? -> skip UI/UX audit
• Has webhook handlers? -> include webhook checks in Security audit
• Has multi-package structure? -> include Integration audit
• Single-service scope? -> skip Integration audit unless it has cross-service deps

Phase 1: Quick Gates (Always Run First)

{TYPECHECK_COMMAND} 2>&1 | tail -30
{TEST_COMMAND} 2>&1 | tail -50
{LINT_COMMAND} 2>&1 | tail -30   # skip if no lint script

Report immediately. If any FAIL, fix before proceeding. Tests are a hard gate.

Phase 2: Audit Agents

Launch agents in parallel based on scope. All use run_in_background: true.

• All agents: model: "sonnet" — use Sonnet for all agents, never Haiku
• All agents use subagent_type: "Explore"

CRITICAL: Every agent prompt starts with the context block built in Phase 0.

CRITICAL: Every agent prompt MUST include the Agent Roster so agents can flag cross-cutting concerns:

## Agent Roster (you are Agent {N})
1. Security Auditor — auth, access control, injection, secrets, HMAC, CORS
2. Architecture Auditor — patterns, conventions, file organization, dependencies
3. Data Layer Auditor — schema, queries, indexes, migrations, tenant isolation
4. UI/UX Auditor — pages, components, accessibility, loading/error/empty states
5. Integration Auditor — cross-package wiring, type flow, env vars, contract compliance
6. Performance Auditor — N+1, pagination, unbounded queries, caching, bundle size

If you find something outside your domain, note it as:
  CROSS-REF [Agent N]: [what they should check]

Skip agents for irrelevant domains — if Phase 0 determined a domain doesn't apply (e.g., no frontend = skip UI/UX), don't launch that agent. Note which were skipped in the final report.

Available Audit Domains

SECURITY AUDIT (Agent: Explore, Model: sonnet)

Use sonnet for security — higher reasoning needed for vulnerability detection.

{context block}

{agent roster}

## Your Focus: Security Audit — {SCOPE}


### OWASP Top 10 Checks
1. **Injection**: Search for raw SQL (string concatenation in queries), unvalidated user input
2. **Broken Auth**: Verify all mutations require auth, check session handling
3. **Sensitive Data Exposure**: Search for secrets in code, error messages leaking internals in production
4. **XXE/XSS**: Check for dangerouslySetInnerHTML, unescaped user content, innerHTML
5. **Broken Access Control**: Verify access control covers ALL routes/procedures, check tenant isolation
6. **Security Misconfiguration**: CSP headers, HSTS, security headers
7. **Insecure Deserialization**: Check webhook payload handling
8. **Components with Vulnerabilities**: Note any known-vulnerable dependencies
9. **Insufficient Logging**: Verify security events are logged
10. **SSRF**: Check for user-controlled URLs in server-side fetches


### Application-Specific Checks (adapt to what exists)

1. **Access Control**:
   - If RBAC/permissions matrix exists: list ALL routes/procedures, cross-reference against matrix, flag any NOT registered
   - If role checks exist: verify role assignments make sense (read-only vs mutation roles)

2. **Tenant Isolation** (if multi-tenant):
   - Is tenant scoping enforced in middleware?
   - Do all tenant-scoped tables have row-level filtering?
   - Are there queries that could leak data across tenants?

3. **Webhook Security** (if webhooks exist):
   - All webhooks validate signatures
   - HMAC uses crypto.timingSafeEqual (not === comparison)
   - timingSafeEqual has length guard
   - Secrets loaded from env config (not process.env directly)

4. **Token Handling**:
   - OAuth tokens encrypted at rest
   - No tokens in URL parameters
   - Refresh token rotation

5. **Rate Limiting** (if exists):
   - All public endpoints rate-limited
   - Rate limit headers returned

6. **CSP & Headers** (if web app):
   - Content-Security-Policy configured
   - HSTS with max-age
   - X-Content-Type-Options: nosniff
   - X-Frame-Options or frame-ancestors

7. **Error Handling**:
   - Production error messages are generic (no stack traces)
   - NODE_ENV guard on detailed errors
   - No error.message exposed to users in production


## OUTPUT FORMAT (MANDATORY)
SECURITY AUDIT REPORT
=====================
Scope: {scope}
Date: {date}
Risk Level: [CRITICAL/HIGH/MEDIUM/LOW]

Findings: {total} ({H} HIGH, {M} MEDIUM, {L} LOW)

HIGH:
- [H-NNN]: [title]
  File: [path:line]
  Issue: [description]
  Fix: [recommendation]

MEDIUM:
- [M-NNN]: [title]
  File: [path:line]
  Issue: [description]
  Fix: [recommendation]

LOW:
- [L-NNN]: [title]
  File: [path:line]
  Issue: [description]
  Fix: [recommendation]

CROSS-REF:
- [Agent N]: [what they should verify]

Access Control: [summary]
Tenant Isolation: [status or N/A]
Webhook Security: [all validated / gaps / N/A]
CSP Status: [configured / gaps / N/A]

ARCHITECTURE AUDIT (Agent: Explore, Model: sonnet)

{context block}

{agent roster}

## Your Focus: Architecture & Patterns — {SCOPE}

1. **Dependency Graph Integrity**:
   - Read package.json in each workspace package (if monorepo)
   - Verify no circular dependencies
   - Verify dependency direction matches architecture (leaf packages don't import app layer)
   - Confirm dependency graph matches AGENTS.md (if documented)

2. **Import Conventions**:
   - Cross-package imports use the project's alias convention (not relative paths across package boundaries)
   - Import style matches project conventions

3. **File Organization**:
   - Files are in the correct directories per AGENTS.md/CLAUDE.md conventions
   - No misplaced files (e.g., backend code in frontend, shared code in app-specific dirs)

4. **Naming Conventions**:
   - Route/file/variable naming follows project patterns
   - Consistent naming across similar concepts

5. **Middleware/Pipeline Chain** (if applicable):
   - Security -> auth -> business logic chain is intact
   - Each layer verified present

6. **Pattern Violations**:
   - Server/client boundary violations (if SSR framework)
   - Proper use of framework conventions (loading states, error boundaries, etc.)

## OUTPUT FORMAT (MANDATORY)
ARCHITECTURE AUDIT REPORT
=========================
Scope: {scope}
Findings: {total} ({H} HIGH, {M} MEDIUM, {L} LOW)

HIGH:
- [H-NNN]: [title] | [file] | [description] | [fix]

MEDIUM:
- [M-NNN]: [title] | [file] | [description] | [fix]

LOW:
- [L-NNN]: [title] | [file] | [description] | [fix]

CROSS-REF:
- [Agent N]: [what they should verify]

Dependency Graph: [CLEAN/VIOLATIONS: list]
Import Conventions: [PASS/FAIL: violations]
File Organization: [PASS/FAIL: misplaced files]
Middleware Chain: [INTACT/BROKEN/N/A: issues]

DATA LAYER AUDIT (Agent: Explore, Model: sonnet)

{context block}

{agent roster}

## Your Focus: Database, Schema & Data Integrity — {SCOPE}

1. **Schema Completeness**:
   - All tables have appropriate column types (numeric precision, enum usage, not text for structured data)
   - FK relationships with proper ON DELETE behavior
   - Tenant isolation columns on all tenant-scoped tables (if multi-tenant)
   - Timestamps (created_at, updated_at) where appropriate
   - Type helpers exported if ORM supports it

2. **Migration Quality** (if migrations exist):
   - Each migration wrapped in transaction
   - Idempotent (IF NOT EXISTS / IF EXISTS patterns)
   - Data migration present when changing column types
   - No destructive operations without safety (DROP with IF EXISTS)
   - Migrations numbered sequentially

3. **Query Patterns**:
   - ALL tenant queries include tenant filter (if multi-tenant)
   - Pagination on list queries (cursor-based preferred over offset)
   - No N+1 patterns (look for db operations inside loops)
   - Batch operations for bulk inserts
   - Proper transaction usage for multi-table operations

4. **Index Coverage**:
   - Composite indexes on frequently filtered columns
   - FK columns indexed
   - Columns used in WHERE/ORDER BY indexed

5. **Enum Consistency**:
   - DB enums match application-level enums
   - Validation schemas reference same enum values

## OUTPUT FORMAT (MANDATORY)
DATA LAYER AUDIT REPORT
=======================
Scope: {scope}
Findings: {total} ({H} HIGH, {M} MEDIUM, {L} LOW)

HIGH:
- [H-NNN]: [title] | [file:line] | [description] | [fix]

MEDIUM:
- [M-NNN]: [title] | [file:line] | [description] | [fix]

LOW:
- [L-NNN]: [title] | [file:line] | [description] | [fix]

CROSS-REF:
- [Agent N]: [what they should verify]

Schema Integrity: [PASS/PARTIAL/FAIL]
Migration Quality: [PASS/PARTIAL/FAIL/N/A]
Tenant Isolation: [PASS/PARTIAL/FAIL/N/A]
N+1 Risks: [none/list]
Index Coverage: [adequate/gaps: list]

UI/UX AUDIT (Agent: Explore, Model: sonnet)

Skip entirely if Phase 0 determined no frontend exists. Note "SKIPPED — no frontend" in final report.

{context block}

{agent roster}

## Your Focus: UI/UX Quality & Consistency — {SCOPE}

1. **Page Completeness** — for every page:
   - Has loading state (skeleton, spinner, loading.tsx, Suspense)
   - Has error boundary coverage
   - Has empty state when data list is empty
   - Has proper metadata (title, description) if SSR/SSG

2. **Component Quality** — for every component:
   - Uses the project's UI component library (not raw HTML for covered patterns)
   - Dark mode compatible (CSS variables, not hardcoded hex) — if applicable
   - Accessible: aria-labels on interactive elements, color contrast >= 4.5:1
   - Mobile-responsive: no fixed widths, proper breakpoints
   - Keyboard navigable: interactive elements reachable via Tab

3. **Form Patterns**:
   - Uses the project's form library with schema validation
   - Error messages displayed inline near the field
   - Submit button disabled during mutation
   - Success/error feedback via toast/notification (not window.alert)

4. **Navigation**:
   - New pages linked in nav/sidebar
   - Active route highlighted
   - Breadcrumbs on detail pages (if pattern exists)
   - Back navigation available

5. **Error Handling**:
   - Dev-only error details (NODE_ENV guard on stack traces)
   - User-friendly error messages in production
   - Retry actions available on transient errors

6. **Loading States**:
   - Skeleton components match final layout shape
   - No layout shift when data loads
   - Suspense boundaries at appropriate granularity

## OUTPUT FORMAT (MANDATORY)
UI/UX AUDIT REPORT
==================
Scope: {scope}
Findings: {total} ({H} HIGH, {M} MEDIUM, {L} LOW)

HIGH:
- [H-NNN]: [title] | [file] | [description] | [fix]

MEDIUM:
- [M-NNN]: [title] | [file] | [description] | [fix]

LOW:
- [L-NNN]: [title] | [file] | [description] | [fix]

CROSS-REF:
- [Agent N]: [what they should verify]

Pages Audited: [count]
Missing loading states: [list or "none"]
Missing empty states: [list or "none"]
Missing error boundaries: [list or "none"]
Accessibility: [PASS/PARTIAL/FAIL]
Dark Mode: [PASS/PARTIAL/FAIL/N/A]

INTEGRATION AUDIT (Agent: Explore, Model: sonnet)

{context block}

{agent roster}

## Your Focus: Cross-Package Integration & Wiring — {SCOPE}

1. **API Wiring**:
   - Every new route/procedure registered in the root router/index
   - Every route/procedure registered in access control (if applicable)
   - Input schemas importable from shared types
   - Output types flow correctly to frontend

2. **Frontend-Backend Contract**:
   - API calls use correct paths/procedure names
   - Mutation results handled (onSuccess/onError)
   - Query invalidation after mutations
   - Optimistic updates where appropriate

3. **API Contract Compliance** (if api-contract.md or similar exists):
   - Response shapes match the documented contract
   - Status codes match documented behavior
   - Error response formats are consistent with spec
   - All documented endpoints actually exist

4. **Environment Variables**:
   - All new vars in typed env config
   - All new vars in .env.example
   - Optional vs required matches actual usage
   - No process.env direct access where typed config exists

5. **Webhook Integration** (if applicable):
   - Webhook handlers in correct paths
   - Signature validation present
   - Cache invalidation wired for relevant data changes
   - Error responses don't leak internal details

6. **Package Boundary Types**:
   - No `any` at package boundaries
   - Proper re-exports from package index files
   - Types flow: schema -> shared types -> backend -> frontend

7. **Build Pipeline**:
   - Build tool config has correct task dependencies
   - New packages in workspace detected
   - No import that would break at build time

## OUTPUT FORMAT (MANDATORY)
INTEGRATION AUDIT REPORT
========================
Scope: {scope}
Findings: {total} ({H} HIGH, {M} MEDIUM, {L} LOW)

HIGH:
- [H-NNN]: [title] | [file] | [description] | [fix]

MEDIUM:
- [M-NNN]: [title] | [file] | [description] | [fix]

LOW:
- [L-NNN]: [title] | [file] | [description] | [fix]

CROSS-REF:
- [Agent N]: [what they should verify]

Route Registration: [X/Y complete]
Contract Compliance: [PASS/PARTIAL/FAIL/N/A]
Access Control Registration: [X/Y complete / N/A]
Env Var Sync: [synced/out-of-sync: list]
Type Flow: [PASS/PARTIAL/FAIL]
Build Pipeline: [PASS/FAIL]

PERFORMANCE AUDIT (Agent: Explore, Model: sonnet)

Only included in /audit full or /audit performance.

{context block}

{agent roster}

## Your Focus: Performance & Scalability — {SCOPE}

1. **Query Performance**:
   - N+1 patterns (db operations inside loops)
   - Missing pagination on list queries
   - Unbounded queries (SELECT * without LIMIT)
   - Missing indexes for common WHERE/ORDER BY patterns

2. **Caching Strategy** (if caching exists):
   - Cache on hot-path queries
   - Cache invalidation on mutations
   - TTL appropriate for data staleness tolerance
   - Fail-open pattern (cache down doesn't break app)

3. **Bundle Size** (if web frontend):
   - "use client" only where needed (if Next.js/RSC)
   - Dynamic imports for heavy components
   - No barrel imports pulling entire packages

4. **Rate Limiting** (if exists):
   - All public endpoints protected
   - Appropriate limits
   - Rate limit headers in responses

5. **Batch Operations**:
   - Bulk inserts use single query (not per-row)
   - Background jobs handle large payloads
   - Pagination on all list endpoints

## OUTPUT FORMAT (MANDATORY)
PERFORMANCE AUDIT REPORT
========================
Scope: {scope}
Findings: {total} ({H} HIGH, {M} MEDIUM, {L} LOW)

HIGH:
- [H-NNN]: [title] | [file:line] | [description] | [fix]

MEDIUM:
- [M-NNN]: [title] | [file:line] | [description] | [fix]

LOW:
- [L-NNN]: [title] | [file:line] | [description] | [fix]

CROSS-REF:
- [Agent N]: [what they should verify]

N+1 Risks: [none/list]
Cache Coverage: [adequate/gaps/N/A]
Rate Limiting: [complete/gaps/N/A]
Unbounded Queries: [none/list]

Phase 2.5: Cross-Examination Round

After all agents complete, orchestrate a cross-examination.

1. Collect all reports
2. Extract all CROSS-REF items — questions agents have for each other
3. Identify overlapping findings — where 2+ agents flagged the same area
4. Identify blind spots — areas only one agent covered that deserve a second opinion

For each substantive cross-reference or overlap, launch a targeted verification agent:

subagent_type: "Explore"
model: "sonnet"
run_in_background: true

Prompt pattern:

{context block}

## Cross-Examination Task

Agent {N} ({domain}) found:
  {finding summary with file paths}

Agent {M} ({domain}) is asked to verify:
  {the cross-ref question}

Additional context from other agents:
  {any related findings from other agents on the same files/areas}

Your job: Read the relevant files and either CONFIRM, REFUTE, or EXPAND the finding.

## OUTPUT FORMAT (MANDATORY)
CROSS-EXAM RESULT
=================
Original Finding: [H/M/L-NNN from Agent N]
Verdict: [CONFIRMED / REFUTED / EXPANDED]
Evidence: [what you found]
Revised Severity: [same / upgraded / downgraded]
Additional Finding: [if EXPANDED, the new issue] or "none"

Guidelines:

• Only cross-examine substantive findings (HIGH, CROSS-REFs, and overlaps)
• Batch related cross-refs touching the same files into single agents
• Limit to ~4 cross-exam agents max
• If no CROSS-REFs and no overlaps, skip this phase

Phase 3: Consolidation

After all agents (including cross-exam) complete:

1. Collect all reports + cross-exam verdicts
2. Adjust severities based on cross-exam (confirmed = higher confidence, refuted = drop)
3. Deduplicate findings (same issue found by 2+ agents = higher confidence)
4. Global numbering: H-001, H-002, ..., M-001, ..., L-001, ...
5. Flag potential phantom findings (refuted by cross-exam or citing wrong line numbers)
6. Present consolidated report:

Comprehensive Audit Report — {SCOPE}
=====================================
Date: {date}
Agents: {count launched} ({list of domains}), {count skipped} skipped
Duration: {time}

Quick Gates: Typecheck {PASS/FAIL} | Tests {PASS/FAIL} | Lint {PASS/FAIL}

Summary:
  HIGH:   {count} (must fix)
  MEDIUM: {count} (should fix)
  LOW:    {count} (nice to have)

Cross-Agent Confirmations (highest confidence):
  {findings confirmed by cross-examination or flagged by 2+ agents}

HIGH Findings:
  H-001: [{domain}] {title} — {file} — {description}
  H-002: [{domain}] {title} — {file} — {description}

MEDIUM Findings:
  M-001: [{domain}] {title} — {file} — {description}

LOW Findings:
  L-001: [{domain}] {title} — {file} — {description}

Potential Phantom Findings (refuted or suspicious):
  {findings that cross-exam refuted or couldn't verify}

Recommendation: {Fix HIGH now / Schedule MEDIUM for next sprint / All clear}

Phase 4: Fix Cycle (User Approval Required)

ALWAYS ask user before fixing. Present options:

1. "Fix all HIGH items" (recommended default)
2. "Fix HIGH + MEDIUM"
3. "Fix specific items: H-001, M-003, ..."
4. "Skip fixes, report only"

Fix Agent Pattern

For each approved fix (or batch of related fixes):

1. Launch fix agent: subagent_type: "general-purpose", run_in_background: true
2. Prompt includes:

• The specific finding(s) to fix
• File path(s) and line numbers
• Recommended fix from the audit report
• Instruction: "Read the file first, then apply the fix. Do NOT run tests."

1. Wait for all fix agents
2. Run all gates again (typecheck + tests + lint)
3. Launch trailing verification agents — 1-2 Explore agents (sonnet) that re-audit the specific files changed by fix agents:

subagent_type: "Explore"
model: "sonnet"
run_in_background: true

Prompt:

{context block}

## Post-Fix Verification

The following fixes were just applied:
{list of findings fixed, with file paths and what changed}

Your job:
1. Read each modified file
2. Verify the fix actually resolves the issue (not just a surface patch)
3. Check that the fix didn't introduce NEW issues (regressions, type errors, broken imports)
4. Check that the fix follows project conventions (from AGENTS.md)

## OUTPUT FORMAT (MANDATORY)
FIX VERIFICATION REPORT
=======================
Verified: [count]
Regressions: [count or "none"]

Per-Fix:
- [H/M-NNN]: [GOOD / REGRESSION / INCOMPLETE]
  Evidence: [what you found]

New Issues Introduced:
- [description] or "none"

1. If regressions found -> fix, re-run gates, re-verify (limit to 2 cycles)
2. Report to user

Verification Pattern

After fixes are applied and verified:

Fix Verification:
  Gates:       Typecheck {PASS/FAIL} | Tests {PASS/FAIL} | Lint {PASS/FAIL}
  Code Review: {PASS/FAIL with details}

Fixed:
  H-001: {title} — VERIFIED
  H-002: {title} — VERIFIED
  M-001: {title} — VERIFIED

Remaining (deferred):
  M-002: {title} — {reason for deferral}
  L-001: {title} — {reason for deferral}

Phase 5: Commit & Document

With user approval:

[AUDIT]: {scope} — {count} findings resolved

{severity}: {one-line per finding}

Deferred to {next phase/sprint}:
- {M/L items not fixed}

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Domain Selection Reference

Anti-Patterns to Avoid

1. Don't audit during Ralph execution — wait for a natural checkpoint
2. Don't fix MEDIUM items that are addressed by upcoming stories — check the PRD first
3. Don't trust line numbers from agents blindly — cross-examination helps, but always verify the actual file
4. Don't batch too many fixes in one agent — one finding per agent for complex fixes
5. Don't skip trailing verification — fix agents can introduce new bugs
6. Don't fix phantom findings — if cross-exam refuted it or it doesn't exist in the actual code, skip it
7. Don't launch agents for irrelevant domains — if no frontend, skip UI/UX. Note skipped domains in the report.