overnight-repo-auditor

What this skill does

# Overnight Repo Auditor

Autonomously audit an entire codebase overnight and produce a single severity-rated report covering security, performance, accessibility, dependencies, and code quality. Built for Anthropic's Managed Agents runtime (14.5-hour task horizon): run to completion without questions or confirmation, writing structured findings to disk as execution proceeds so partial results survive interruption.

## Contents

- `references/reconnaissance.md` -- Phase 1 steps and the reconnaissance report template.
- `references/shared-rubric.md` -- Severity rating rubric and structured finding format. Pass both to every agent.
- `references/agent-security.md` -- Security Auditor brief and output format.
- `references/agent-performance.md` -- Performance Auditor brief and output format.
- `references/agent-accessibility.md` -- Accessibility Auditor brief, skip condition, and output format.
- `references/agent-dependency.md` -- Dependency Auditor brief, skip condition, and output format.
- `references/agent-code-quality.md` -- Code Quality Auditor brief and output format.
- `references/compilation-and-templates.md` -- Phase 3 compilation steps, final report template, and completion message.

## Operating Rules

- Run autonomously. Never ask the user for input. When a decision is ambiguous, choose the more thorough option and document the choice in the report.
- Read-only against source. Create only the `audit-workspace/` directory and `overnight-audit-report.md`. Never modify, build, or execute project code. The sole exception: the Dependency Auditor may run read-only package-audit commands (`npm audit`, `pip audit`, and equivalents).
- Be exhaustive, not sampling-based, while the time window allows.

## Workflow

### Phase 1: Reconnaissance (sequential, ~5-10 min)

1. Scan repository structure, identify languages, frameworks, config files, and estimate lines of code.
2. Determine which audit modules are relevant (Security and Code Quality always; Performance always; Accessibility only with frontend/template files; Dependency only with a manifest/lockfile).
3. Write `audit-workspace/00-reconnaissance.md` as the shared context document for all agents.

Follow `references/reconnaissance.md` for exact commands and the report template.

### Phase 2: Parallel Audit Deployment

4. Deploy every relevant audit agent simultaneously via the Agent tool. Use `run_in_background: true` on every call and send ALL agent calls in a single message.
5. Build each agent's prompt by combining: the full reconnaissance report (paste inline -- agents do not share filesystem context automatically), the severity rubric and finding format from `references/shared-rubric.md`, and the agent-specific brief from its reference file. Each agent writes to its own output file under `audit-workspace/`.
   - Security -> `references/agent-security.md` -> `01-security-audit.md`
   - Performance -> `references/agent-performance.md` -> `02-performance-audit.md`
   - Accessibility -> `references/agent-accessibility.md` -> `03-accessibility-audit.md` (honor skip condition)
   - Dependency -> `references/agent-dependency.md` -> `04-dependency-audit.md` (honor skip condition)
   - Code Quality -> `references/agent-code-quality.md` -> `05-code-quality-audit.md`
6. For a targeted run (e.g., "security and dependencies only"), deploy just those agents and include only their sections in the final report.

### Phase 3: Report Compilation (sequential, ~5-10 min)

7. After all background agents return, read every agent report, deduplicate cross-agent findings, assign final severities, and generate the executive summary with the top-10 priority items.
8. Write the compiled `overnight-audit-report.md` to the repository root, then emit the brief completion message.

Follow `references/compilation-and-templates.md` for the deduplication map, final report template, and completion message.

## Scaling

| Codebase Size | Estimated Duration | Agent Strategy |
|---------------|-------------------|----------------|
| < 10K lines | 15-30 minutes | All agents, single pass each |
| 10K - 50K lines | 30-90 minutes | All agents, thorough pass |
| 50K - 200K lines | 1-4 hours | All agents, may need sub-agents for Security and Code Quality |
| 200K - 500K lines | 4-8 hours | All agents spawn 2-3 sub-agents each to parallelize file review |
| 500K+ lines | 8-14 hours | Full sub-agent deployment with file-batch assignments per sub-agent |

For codebases over 200K lines, each audit agent should spawn sub-agents to parallelize within its domain (for example, Security splits into Auth & Sessions, Data Handling, API Surface, and Infrastructure). Each brief instructs agents to self-organize sub-agent deployment based on the size discovered during their audit.

## Error Handling

- **Agent failure**: retry the agent once with the same brief. If it fails again, write a partial report noting the failure, continue with the other agents, and document the lost coverage in the final report. Never let one agent block the others.
- **File access errors**: skip the file, log it in that agent's Methodology Notes, and continue.
- **Timeout management**: prioritize high-risk files first (auth, payments, data handling, public endpoints). If an agent reviews more than 2000 files, note that a sampling strategy was used for lower-risk files. The Commander compiles partial results if the window is closing.
- **Re-runs**: a new audit overwrites the previous `audit-workspace/` directory and `overnight-audit-report.md`. Suggest the user commit or copy prior results first.

## Notes

- Reports describe source code, so treat them with the same sensitivity as the code itself.
- If `.gitignore` exists but does not list `audit-workspace/`, suggest adding it to prevent committing audit output.