cast-audit

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:

1. Dispatches the 4 researchers in parallel
2. Writes section reports to ~/.claude/reports/cast-audit-YYYY-MM-DD-<section>.md
3. Collates into ~/.claude/reports/cast-audit-YYYY-MM-DD.md
4. (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:

1. 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/
   

2. 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
   

3. 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.

4. 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

• /cast-audit skill exists with clear invocation instructions
• Dispatches 4 parallel researchers (bugs, security, performance, coverage)
• Each researcher writes section report to ~/.claude/reports/cast-audit-YYYY-MM-DD-<section>.md
• Main session collates into ~/.claude/reports/cast-audit-YYYY-MM-DD.md with executive summary
• Report location documented (this file)
• Scheduled-task configuration documented but NOT registered (user approval required)
• Idempotent — running twice on same date overwrites prior result
• README updated with one-line mention of the skill