audit

---

name: audit description: | Comprehensive codebase audit with specialized reviewers. Generates actionable reports. Use when asked to "audit the codebase", "review code quality", "check for issues", "security review", or "performance audit". Accepts path scope like "apps/web".

Reviewers run in batches of 2 by default to avoid resource exhaustion. Use --parallel to run all reviewers simultaneously (resource-intensive). license: MIT metadata: author: howells argument-hint: [--parallel] [--security|--performance|--architecture|--design] website: order: 13 desc: Codebase audit summary: Run a comprehensive audit of your entire codebase—or target a specific area. Spawns specialist reviewers for security, performance, architecture, and more. what: | Audit spins up multiple specialist agents—security, performance, architecture, data, UI, simplicity—each analyzing your code through their lens. Run it on your whole project before launch, or target a specific path (/arc:audit apps/api) for focused feedback. Each agent works independently, then findings are consolidated into a single report: critical issues first, then warnings, then suggestions. The output is a markdown file you can work through or convert into tasks. why: | A security expert misses performance issues. A performance expert misses architectural violations. A frontend expert misses data integrity problems. Audit gives you a panel of specialists in one command—the kind of thorough review you'd want before shipping, without coordinating six different people. decisions: - Whole project or targeted. Run on everything, or scope to a path like src/lib/auth. - Agents run in batches (2 at a time by default). Use --parallel for speed if you have resources. - Focus flags available. --security, --performance, --design for targeted audits. agents: - security-engineer - performance-engineer - architecture-engineer - daniel-product-engineer - lee-nextjs-engineer - senior-engineer - designer - data-engineer

<required_reading> Read these reference files NOW:

1. ${CLAUDE_PLUGIN_ROOT}/disciplines/dispatching-parallel-agents.md </required_reading>

<progress_context> Use Read tool: docs/progress.md (first 50 lines)

Check for recent changes that should be included in audit scope. </progress_context>

<rules_context> Check for project coding rules:

Use Glob tool: .ruler/*.md

If .ruler/ exists, detect stack and read relevant rules:

Pass relevant rules to each reviewer agent.

If .ruler/ doesn't exist: Continue without rules — they're optional.

For UI/frontend audits, also load interface rules:

Rules location: ${CLAUDE_PLUGIN_ROOT}/rules/interface/

Pass relevant rules to each UI reviewer in their prompt. These inform what to look for, not mandates to redesign. </rules_context>

Parse arguments:

• $ARGUMENTS may contain:
  • A path (e.g., apps/web, packages/ui, src/)
  • A focus flag (e.g., --security, --performance, --architecture, --design)
  • --parallel flag to run all reviewers simultaneously (resource-intensive)
  • Combinations (e.g., apps/web --security, src/ --parallel, --design)

If no scope provided:

Use Glob tool to detect structure:

• apps/*, packages/* → monorepo (audit both)
• src/* → standard (audit src/)
• Neither → audit current directory

Detect project type with Glob + Grep:

Check for database/migrations:

Use Glob tool: prisma/*, drizzle/*, migrations/* → has-db

Run dependency vulnerability scan (critical/high only):

Copy# Node.js projects
npm audit --json 2>/dev/null | jq '[.vulnerabilities | to_entries[] | select(.value.severity == "critical" or .value.severity == "high")] | length'

# Python projects
pip-audit --format json 2>/dev/null | jq '[.[] | select(.vulns[].fix_versions)] | length'

# Or use: pnpm audit --json, yarn audit --json

Only surface critical and high severity vulnerabilities. Ignore moderate/low — they create noise without actionable urgency.

Detect project scale:

Use file counts to determine appropriate audit depth:

Copy# Count source files (exclude node_modules, .git, dist, build)
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \) | grep -v node_modules | grep -v .git | wc -l

Scale-appropriate signals:

• Small projects: Skip architecture-engineer (no complex boundaries to review)
• Small projects: Skip simplicity-engineer (not enough code to over-engineer)
• No tests present + small project: Don't flag missing tests as critical
• Single developer: Skip senior-engineer (no code review discipline needed)

Summarize detection:

CopyScope: [path or "full codebase"]
Project type: [Next.js / React / Python / etc.]
Project scale: [small / medium / large]
Has database: [yes/no]
Has tests: [yes/no]
Coding rules: [yes/no]
Focus: [all / security / performance / architecture / design]
Execution mode: [batched (default) / parallel]

Phase 2: Select Reviewers

Base reviewer selection by project scale:

Add framework-specific reviewers (medium/large only):

Conditional additions:

• If scope includes DB/migrations → add data-engineer
• If monorepo with shared packages (large only) → add simplicity-engineer
• If UI-heavy (React/Next.js, medium/large) → add designer
• If recent AI-assisted work or branch audit → add llm-engineer (deslop)

Focus flag overrides:

• --security → only security-engineer
• --performance → only performance-engineer
• --architecture → only architecture-engineer
• --design → only designer
• --deslop → only llm-engineer

Final reviewer list:

• Small projects: 2-3 reviewers
• Medium projects: 3-4 reviewers
• Large projects: 4-6 reviewers

Phase 3: Run Audit

Read agent prompts: For each selected reviewer, read:

Copy${CLAUDE_PLUGIN_ROOT}/agents/review/[reviewer-name].md

Execution strategy:

By default, reviewers run in batches of 2 to avoid resource exhaustion on large codebases. If --parallel flag is set, all reviewers run simultaneously.

Batched Execution (Default)

Split reviewers into batches of 2. Run each batch, wait for completion, then run next batch.

Example with 6 reviewers:

CopyBatch 1: security-engineer, performance-engineer
  → Wait for both to complete
Batch 2: architecture-engineer, daniel-product-engineer
  → Wait for both to complete
Batch 3: lee-nextjs-engineer, senior-engineer
  → Wait for both to complete

Model selection per reviewer:

For each batch, spawn 2 agents in parallel:

CopyTask [security-engineer] model: sonnet: "
Audit the following codebase for security issues.

Scope: [path]
Project type: [type]
Coding rules: [rules content if any]

Focus on: OWASP top 10, authentication/authorization, input validation, secrets handling, injection vulnerabilities.

Return findings in this format:
## Findings
### Critical
- [file:line] Issue description

### High
- [file:line] Issue description

### Medium
- [file:line] Issue description

### Low
- [file:line] Issue description

## Summary
[1-2 sentences]
"

Task [performance-engineer] model: sonnet: "
Audit the following codebase for performance issues.
[similar structure]
Focus on: N+1 queries, missing indexes, memory leaks, bundle size, render performance.
"

Task [designer] model: opus: "
Review UI implementation for visual design quality.
[similar structure]
Focus on: aesthetic direction, memorable elements, typography, color cohesion, AI slop patterns.
"

Wait for batch to complete before starting next batch.

Repeat for remaining batches:

• Batch 2: architecture-engineer + UI reviewer (if applicable)
• Batch 3: remaining reviewers

Parallel Execution (--parallel flag)

Only if --parallel flag is explicitly set, spawn all reviewers simultaneously:

CopyTask [security-engineer] model: sonnet: "..."
Task [performance-engineer] model: sonnet: "..."
Task [architecture-engineer] model: sonnet: "..."
[All additional reviewers in same message...]

⚠️ Warning: Parallel execution spawns 4-6 Claude instances simultaneously. This can cause system unresponsiveness on resource-constrained machines or large codebases.

Wait for all agents to complete.

Phase 4: Consolidate Findings

Collect all agent outputs.

Deduplicate:

• Same file:line mentioned by multiple reviewers → merge into single finding
• Note which reviewers flagged each issue

Categorize by severity:

1. Critical — Security vulnerabilities, data loss risks, breaking issues
2. High — Performance blockers, architectural violations
3. Medium — Technical debt, code quality issues
4. Low — Suggestions, minor improvements

Group by domain:

• Security (from security-engineer + dependency scan)
• Performance (from performance-engineer)
• Architecture (from architecture-engineer)
• Code Quality (from senior-engineer, simplicity-engineer)
• LLM Artifacts (from llm-engineer) — AI-generated slop
• UI/UX Code (from daniel-product-engineer, lee-nextjs-engineer)
• Design Quality (from designer) — visual/aesthetic concerns
• Data Integrity (from data-engineer)

Phase 5: Generate Report

Create audit report:

Copymkdir -p docs/audits

File: docs/audits/YYYY-MM-DD-[scope-slug]-audit.md

Copy# Audit Report: [scope]

**Date:** YYYY-MM-DD
**Reviewers:** [list of agents used]
**Scope:** [path or "full codebase"]
**Project Type:** [detected type]

## Executive Summary

[1-2 paragraph overview of findings]

- **Critical:** X issues
- **High:** X issues
- **Medium:** X issues
- **Low:** X issues

## Critical Issues

> Immediate action required

### [Issue Title]
**File:** `path/to/file.ts:123`
**Flagged by:** security-engineer, architecture-engineer
**Description:** [What's wrong and why it matters]
**Recommendation:** [How to fix]

[Repeat for each critical issue]

## High Priority

> Should fix soon

[Same format as Critical]

## Medium Priority

> Technical debt

[Same format]

## Low Priority / Suggestions

> Nice to have

[Same format]

---

## Domain Breakdown

### Security
[Summary of security findings]

### Performance
[Summary of performance findings]

### Architecture
[Summary of architecture findings]

### Code Quality
[Summary of code quality findings]

### LLM Artifacts
[Summary of AI-generated slop: unnecessary comments, defensive checks in trusted codepaths, type escapes]

### UI/UX Code
[Summary of UI/UX code findings, if applicable]

### Design Quality
[Summary of visual/aesthetic findings, if applicable]

### Data Integrity
[Summary of data integrity findings, if applicable]

---

## Next Steps

1. [Prioritized action item]
2. [Prioritized action item]
3. [Prioritized action item]

Commit the report:

Copygit add docs/audits/
git commit -m "docs: add audit report for [scope]"

Phase 6: Present & Offer Actions

Show summary to user:

Copy## Audit Complete

Reviewed: [scope]
Reviewers: [count] agents
Report: docs/audits/YYYY-MM-DD-[scope]-audit.md

### Summary
- Critical: X
- High: X
- Medium: X
- Low: X

### Top Issues
1. [Critical issue 1]
2. [Critical issue 2]
3. [High issue 1]

Offer next steps:

CopyWhat would you like to do?

1. **Create tasks from findings** → Add critical/high issues to /arc:tasklist
2. **Focus on critical issues** → Create implementation plan for critical fixes
3. **Deep dive on [domain]** → Explore specific domain findings
4. **Done for now** → End session

If user selects:

• Create tasks → Write critical/high issues to docs/tasklist.md
• Focus on critical → Invoke /arc:detail with critical issues as scope
• Deep dive → Show full findings for selected domain
• Done → End session

Phase 7: Cleanup

Kill orphaned subagent processes:

After spawning multiple reviewer agents, some may not exit cleanly. Run cleanup to prevent memory accumulation:

Copy${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-orphaned-agents.sh

This is especially important after --parallel runs or when auditing large codebases.

<progress_append> After completing the audit, append to progress journal:

Copy## YYYY-MM-DD HH:MM — /arc:audit
**Task:** Audit [scope]
**Outcome:** Complete
**Files:** docs/audits/YYYY-MM-DD-[scope]-audit.md
**Decisions:**
- Critical: [N] issues
- High: [N] issues
- Reviewers: [list]
- Execution mode: [batched / parallel]
**Next:** [Create tasks / Focus on critical / Done]

---

</progress_append>

<success_criteria> Audit is complete when:

• Scope detected (path, full codebase, or focus flag)
• Project type detected
• Execution mode determined (batched default, or --parallel)
• 4-6 reviewers selected based on context
• Reviewers run in batches of 2 (or all at once if --parallel)
• All reviewers completed
• Findings consolidated and deduplicated
• Report generated in docs/audits/
• Report committed to git
• Summary presented to user
• Next steps offered
• Progress journal updated
• Orphaned agents cleaned up (run cleanup script) </success_criteria>