Project Health Audit

Comprehensive project-wide health assessment using 5 parallel specialist subagents.

Usage

/phx:audit              # Full audit (default)
/phx:audit --quick      # 2-3 minute pulse check
/phx:audit --focus=security   # Deep dive single area
/phx:audit --focus=performance
/phx:audit --since abc123   # Incremental audit since commit
/phx:audit --since HEAD~10  # Audit last 10 commits

When to Use

• Quarterly health checks
• Before major releases
• After large refactors
• New team member onboarding (understand codebase health)

Subagent Architecture

Spawn 5 specialists in parallel using Task tool:

Subagent	Focus	Output File
Architecture Reviewer	Structure quality, coupling, cohesion	arch-review.md
Performance Auditor	N+1, indexes, bottlenecks, scalability	perf-audit.md
Security Auditor	OWASP scan, auth patterns, secrets	security-audit.md
Test Health Auditor	Coverage, quality, flaky tests	test-audit.md
Dependency Auditor	Vulnerabilities, outdated, unused	deps-audit.md

Workflow

Step 1: Spawn All 5 Auditors (Parallel)

Task(subagent_type: "general-purpose", prompt: "Architecture audit...", run_in_background: true)
Task(subagent_type: "general-purpose", prompt: "Performance audit...", run_in_background: true)
Task(subagent_type: "general-purpose", prompt: "Security audit...", run_in_background: true)
Task(subagent_type: "general-purpose", prompt: "Test health audit...", run_in_background: true)
Task(subagent_type: "general-purpose", prompt: "Dependency audit...", run_in_background: true)

Agent prompts must be FOCUSED. Scope each prompt to the
relevant directories and patterns. Do NOT give vague prompts
like "analyze the codebase."

Step 2: Collect Results

Wait for ALL auditors to FULLY complete using TaskOutput. If
TaskOutput shows an auditor is still running, wait and check
again. NEVER proceed while any auditor is still running.

Read reports from .claude/audit/reports/.

Step 3: Compress Findings

After all 5 auditors complete, spawn context-supervisor:

Task(subagent_type: "context-supervisor", prompt: """
Compress audit findings.
Input: .claude/audit/reports/
Output: .claude/audit/summaries/
Priority: Health scores per category, critical findings
only, cross-category correlations, deduplicate findings
found by 2+ agents.
""")

Read .claude/audit/summaries/consolidated.md for synthesis.

Step 4: Calculate Health Score

Each category scores 0-100. See references/scoring-methodology.md.

Step 5: Generate Report

Write to .claude/audit/summaries/project-health-{date}.md.

Quick Mode (--quick)

Only run essential checks (~2-3 minutes):

mix compile --warnings-as-errors
mix hex.audit && mix deps.audit
mix xref graph --format stats
mix test --trace 2>&1 | tail -20

Skip: Full security scan, N+1 analysis, test quality metrics, architecture deep dive.

Focus Mode (--focus=area)

Deep dive single area with full specialist resources:

Focus	Subagent	Extra Checks
security	security-analyzer	Full OWASP, sobelow, manual patterns
performance	(performance subagent)	Profile-level analysis, query explain
architecture	(arch subagent)	Full xref, coupling matrix, cohesion
tests	testing-reviewer	Coverage by context, quality metrics
deps	(deps subagent)	License audit, maintenance status

Incremental Mode (--since <commit>)

Analyze only changes since a specific commit. Useful for pre-merge checks:

# Identify changed files
git diff --name-only <commit>...HEAD

# Run targeted audits on changed files only
# Skips full project scan, focuses on modified code

Combines with other flags: /phx:audit --since HEAD~5 --focus=security

Output Format

# Project Health Audit: {project_name}

**Generated**: {date}
**Mode**: full | quick | focus={area}

## Executive Summary

### Health Score: {A-F} ({numeric}/100)

| Category | Score | Status |
|----------|-------|--------|
| Architecture | 85/100 | Good |
| Performance | 70/100 | Needs Attention |
| Security | 95/100 | Excellent |
| Test Quality | 60/100 | Needs Work |
| Dependencies | 90/100 | Good |

### Critical Issues (Must Address)
1. {issue}
2. {issue}

### Top Recommendations
1. {recommendation}
2. {recommendation}

## Detailed Findings

[Per-category sections from subagents]

## Action Plan

### Immediate (This Sprint)
- [ ] {critical fix}

### Short-term (Next 2 Sprints)
- [ ] {improvement}

### Long-term (Backlog)
- [ ] {nice-to-have}

Relationship to Other Commands

Command	Scope	Frequency
/phx:review	Changed files (diff)	Every PR
/phx:audit	Entire project	Quarterly
/phx:boundaries	Context structure	On-demand
/phx:verify	Compile/test pass	Anytime

References

• references/scoring-methodology.md - How scores are calculated
• references/architecture-checks.md - Detailed architecture criteria