| name | cast-audit |
| description | Comprehensive CAST codebase audit — bugs, security, performance, test coverage. Dispatches 4 parallel researchers to scan the codebase and collates findings into a dated report. Manual invocation only; monthly scheduling is a design intention (helper not yet shipped). |
| user-invocable | true |
| allowed-tools | ["Agent","Read","Glob","Grep"] |
CAST Audit Skill
Overview
The /cast-audit skill automates the 4-way codebase audit that was run manually on 2026-04-16, surfacing accumulating drift and regressions before they compound. It dispatches 4 parallel researchers (bugs/dead code, security, performance, test coverage), collates findings, and writes a report to ~/.claude/reports/cast-audit-YYYY-MM-DD.md.
Does NOT auto-fix. This skill surfaces findings only. Remediation happens via follow-up agent dispatch (debugger, security, test-writer).
Usage
Manual invocation
/cast-audit
Runs full audit and writes report to ~/.claude/reports/cast-audit-YYYY-MM-DD.md.
Options
/cast-audit --since 2026-03-01 — Only flag regressions (increases, new findings) since the date. Compares against the most recent prior audit before that date./cast-audit --section security — Run one section only (security, bugs, performance, or coverage). Output still goes to the full report./cast-audit --no-collate — Run 4 parallel researchers but do NOT collate into a single report. Useful for debugging individual sections.
Scheduled execution
Design intention: first Monday of each month, 08:00 local time. Scheduling via RemoteTrigger or cron requires a helper script that is not yet shipped (see "Scheduling" below). Manual invocation only until then.
The scheduled run:
- Dispatches the 4 researchers in parallel
- Writes section reports to
~/.claude/reports/cast-audit-YYYY-MM-DD-<section>.md
- Collates into
~/.claude/reports/cast-audit-YYYY-MM-DD.md
- (Optional) Sends notification to user inbox
Report Format
Each audit produces a collated report with this structure:
# CAST Audit — YYYY-MM-DD
## Executive Summary
- 🔴 HIGH: [top 1-2 findings by severity]
- 🟡 MED: [secondary findings]
- 🟢 LOW: [informational findings]
Comparison to prior audit (YYYY-MM-DD):
- +3 HIGH / -1 MED / +2 LOW severity
## Findings by Category
### Bugs & Dead Code
[Bulleted findings with severity tags, file paths, line numbers]
### Security
[Bulleted findings]
### Performance
[Bulleted findings]
### Test Coverage
[Bulleted findings]
## Recommended Actions
| Finding | Severity | Recommended Agent | Effort |
|---|---|---|---|
| ... | HIGH | debugger | ~30 min |
Example finding:
- 🔴 HIGH (SECURITY): `scripts/cast-session-end.sh:42` — SQL injection via unquoted SESSION_ID in sqlite3 insert. Use parameterization or add validation guard.
Each section report (written to ~/.claude/reports/cast-audit-YYYY-MM-DD-<section>.md) contains raw findings for that category.
Audit Scope per Section
1. Bugs & Dead Code
Scan for:
- Orphan scripts (referenced in
settings.json but missing from scripts/)
- Orphan agent definitions (in
~/.claude/agents/ but not referenced anywhere)
- Orphan skills (in
~/.claude/skills/ but not wired)
- Unreachable code paths (dead conditionals, TODO/FIXME comments with no issue tracker)
- Cold imports (unused imports in Python scripts)
- Pattern regressions (new instances of 13-python-cold-start, etc.)
2. Security
Scan for:
- SQL injection patterns (env-var interpolation in sqlite3 without parameterization)
- Shell injection in hook scripts (unquoted variable expansion in backticks or $(...))
- Secrets leaking to config files (API keys, tokens, credentials in version-controlled files)
- File permissions issues (world-readable secrets, mismatched owner)
- Subagent write bypass (agents attempting to modify files outside their
owns_files spec)
- Python eval/exec usage (dangerous dynamic code execution)
3. Performance
Scan for:
- Python cold-start counts per hook (inline
python3 -c > 2 per script)
- Slow database queries (N+1 patterns, missing indices, unbounded result sets)
- Unbounded loops or recursive calls
- Hook execution time > 500ms (inferred from
~/.claude/logs/ if available)
- Large file reads into memory
- Repeated network calls without caching
4. Test Coverage
Scan for:
- BATS gaps — shell scripts in
scripts/ without corresponding tests/<name>.bats
- Vitest gaps — frontend React components in
src/components/ without .test.tsx
- TypeScript files without colocated tests
- Test files with zero assertions (stubs)
- Skipped tests (@test.skip, .only overrides)
Implementation
When invoked, the main session:
-
Dispatches 4 researchers in parallel, each with a targeted scope:
Researcher 1 (bugs): Scan scripts/, agents/, skills/ for orphan, unreachable, and cold-start patterns
Researcher 2 (security): Scan all code for SQL injection, shell injection, secrets, file perms
Researcher 3 (performance): Scan for cold-starts, slow queries, unbounded work
Researcher 4 (coverage): Compare test files against source files in scripts/, src/
-
Each researcher writes findings to:
~/.claude/reports/cast-audit-YYYY-MM-DD-bugs.md
~/.claude/reports/cast-audit-YYYY-MM-DD-security.md
~/.claude/reports/cast-audit-YYYY-MM-DD-performance.md
~/.claude/reports/cast-audit-YYYY-MM-DD-coverage.md
-
Main session collates the 4 reports into:
~/.claude/reports/cast-audit-YYYY-MM-DD.md
With executive summary, side-by-side comparison to prior audit (if available), action items, and recommended agents.
-
Idempotency: Running /cast-audit twice on 2026-04-16 overwrites cast-audit-2026-04-16.md and the section files.
Scheduling
Via RemoteTrigger
Create a scheduled task that invokes Claude Code with:
claude-code \
--message "Dispatch /cast-audit skill to run monthly audit." \
--cwd ${HOME}/Projects/personal/claude-agent-team
Schedule: First Monday of each month at 08:00 local time
Via cron (fallback — illustrative, helper not yet shipped)
Example crontab entry (not yet functional — requires scripts/cast-audit-cron.sh which has not been shipped):
# First Monday of month at 08:00 local — CAST audit (illustrative only)
# 0 8 * * 1 [ $(date +\%d) -le 7 ] && cd ${HOME}/Projects/personal/claude-agent-team && bash scripts/cast-audit-cron.sh
Create scripts/cast-audit-cron.sh first if cron scheduling is actually adopted.
Integration with CAST Ecosystem
- Findings are diagnostic only — remediation requires explicit follow-up dispatch of debugger, security, test-writer.
- Report location — Always
~/.claude/reports/cast-audit-YYYY-MM-DD.md. Updated README documents this path.
- Comparison logic — If prior audit exists in
~/.claude/reports/cast-audit-YYYY-MM-*.md, collation step compares finding counts by severity and flags regressions (e.g., "+3 HIGH since last month").
- No auto-fix — This is a discovery tool. Prevents "invisible" drift from accumulating.
Acceptance Criteria
