Repository Audit Agent Playbook for Codex or Claude Code

A practical workflow for turning repo audits into structured findings, logs, and patch artifacts.

Audience: Engineering teams automating codebase review, migration prep, or release readiness.

The problem

Agent repo audits often produce persuasive prose but no stable finding schema or reproducible artifact.

Implementation path

Attach a repo snapshot or diff, define the audit checklist, force severity and evidence fields, and return patch files as artifacts only when explicitly requested.

Tradeoffs and failure modes

A finding schema constrains the agent, but it makes review output actionable.

Finding schema

{ "severity": "high", "file": "src/api.ts", "line": 42, "finding": "...", "impact": "...", "fix": "..." }

Run this on Argo