audit
Project health audit and health check — architecture, performance, tests, dependencies, code quality. Use when assessing overall project health, before releases, or after refactors.
How do I install this agent skill?
npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix --skill auditIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is a project health auditing tool designed for Elixir and Phoenix applications. It utilizes standard development utilities such as mix, git, and grep to perform architectural reviews, security scans, and performance audits. No malicious behaviors or unauthorized data exfiltration attempts were found.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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)
Iron Laws
- Wait for ALL agents before synthesizing — Partial results create misleading health scores because cross-category correlations get missed
- Scope agent prompts to specific directories — Vague prompts like "analyze the codebase" produce generic findings that waste tokens and miss real issues
- Never compare scores across projects — Scoring methodology depends on project size and maturity; only track trends within the same project
- Quick mode before full mode — Run
--quickfirst to catch compile/test failures before spending tokens on 5 parallel agents
Subagent Architecture
Spawn 5 specialists in parallel using Agent tool. Three route to plugin
specialists with a declared model; the two categories without a specialist use
general-purpose pinned to model: "sonnet" — unpinned, they inherit the
session model (Opus by default):
| Subagent | Focus | Output File | Routes to |
|---|---|---|---|
| Architecture Reviewer | Structure quality, coupling, cohesion | arch-review.md | phoenix-patterns-analyst (sonnet) |
| Performance Auditor | N+1, indexes, bottlenecks, scalability | perf-audit.md | general-purpose, model: "sonnet" (no perf specialist yet) |
| Security Auditor | OWASP scan, auth patterns, secrets | security-audit.md | security-analyzer (opus) |
| Test Health Auditor | Coverage, quality, flaky tests | test-audit.md | testing-reviewer (sonnet) |
| Dependency Auditor | Vulnerabilities, outdated, unused | deps-audit.md | general-purpose, model: "sonnet" (hex-deps-triager is per-package only) |
Workflow
Step 1: Create Task List and Spawn All 5 Auditors (Parallel)
If TaskCreate is in your tool list, create Claude Code tasks for
progress visibility (Sonnet 5+ and Opus 4.8+ omit it unless
CLAUDE_CODE_ENABLE_TODO_TOOLS=1; never ToolSearch for it — skip this block):
For each auditor:
TaskCreate({subject: "{Area} audit", activeForm: "Auditing {area}..."})
TaskUpdate({taskId, status: "in_progress"})
Then spawn all 5 agents with Agent tool (parallel). Route to declared-model
specialists where they exist, keep general-purpose only where no specialist
covers the audit category:
Agent(subagent_type: "phx:phoenix-patterns-analyst", prompt: "Architecture audit: analyze module structure, context boundaries, coupling, cohesion. Write findings to .claude/audit/reports/arch-review.md", run_in_background: true)
Agent(subagent_type: "general-purpose", model: "sonnet", prompt: "Performance audit: N+1 queries, missing indexes, bottlenecks, scalability. Write findings to .claude/audit/reports/perf-audit.md", run_in_background: true)
Agent(subagent_type: "phx:security-analyzer", prompt: "Security audit: OWASP scan, auth patterns, secret leakage. Write findings to .claude/audit/reports/security-audit.md", run_in_background: true)
Agent(subagent_type: "phx:testing-reviewer", prompt: "Test health audit: coverage, quality, flakes. Write findings to .claude/audit/reports/test-audit.md", run_in_background: true)
Agent(subagent_type: "general-purpose", model: "sonnet", prompt: "Dependency audit: vulnerabilities, outdated, unused. Write findings to .claude/audit/reports/deps-audit.md", run_in_background: true)
Why specialist routing matters: a general-purpose subagent without
model: inherits the session model — Opus on every plan since CC 2.1.280.
Plugin specialists declare their own model in frontmatter, and the two
general-purpose tracks pin model: "sonnet", so no audit track runs on Opus.
Agent prompts must be FOCUSED. Scope each prompt to the relevant directories and patterns. Do NOT give vague prompts like "analyze the codebase."
Output efficiency: Tell each agent: "Report ONLY issues found. Do NOT list clean checks, passing categories, or 'What's Good'. One summary line per clean area suffices."
Step 2: Collect Results
Wait for ALL auditors to complete — one completion notification per agent
spawned. If you created tasks, mark each completed as it finishes. NEVER
proceed while any auditor is still running.
Read reports from .claude/audit/reports/.
Rate-limit circuit breaker: if 2+ auditors return empty results or
rate-limit/API errors, STOP spawning. Synthesize from the reports that
exist, mark missing categories as "not audited (rate limit)", and tell
the user to re-run /phx:audit after the limit resets. Never leave the
user typing "continue" against dead agents.
Step 3: Compress Findings
After all 5 auditors complete, spawn context-supervisor:
Agent(subagent_type: "phx: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.
""", run_in_background: false)
Read .claude/audit/summaries/consolidated.md for synthesis.
Step 4: Calculate Health Score
Each category scores 0-100. See ${CLAUDE_SKILL_DIR}/references/scoring-methodology.md.
Step 5: Generate Report
Write to .claude/audit/summaries/project-health-{date}.md.
Output Format
Report includes: Executive summary with health score (A-F, numeric/100), per-category score table (Architecture, Performance, Security, Tests, Dependencies), critical issues, top recommendations, and action plan (Immediate/Short-term/Long-term).
Quick Mode (--quick)
Only run essential checks (~2-3 minutes):
Run mix compile --warnings-as-errors, then mix hex.audit && mix deps.audit,
then mix xref graph --format stats, then 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 | general-purpose | Profile-level analysis, query explain (no plugin specialist yet) |
architecture | phoenix-patterns-analyst | Full xref, coupling matrix, cohesion |
tests | testing-reviewer | Coverage by context, quality metrics |
deps | general-purpose | License audit, maintenance status (per-package hex-deps-triager only) |
Incremental Mode (--since <commit>)
Analyze only changes since a specific commit. Useful for pre-merge checks:
Run git diff --name-only <commit>...HEAD to identify changed files, then run targeted audits on changed files only (skips full project scan).
Combines with other flags: /phx:audit --since HEAD~5 --focus=security
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
${CLAUDE_SKILL_DIR}/references/scoring-methodology.md- How scores are calculated${CLAUDE_SKILL_DIR}/references/architecture-checks.md- Detailed architecture criteria
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/oliver-kriska/claude-elixir-phoenix/audit">View audit on skillZs</a>