Read-only repository review

An evidence-first AI agent repo audit

Before adding more autonomy, inspect what the repository actually tells an agent, what it mechanically enforces, and what nobody has verified yet.

Copy this read-only audit prompt

Audit this repository's AI coding-agent setup.

Do not edit files, install packages, change configuration, or run commands
with side effects. Use read-only inspection only.

Inspect:
1. Durable project guidance and nested overrides
2. Documented build, test, lint, type-check, and development commands
3. Permission, sandbox, and sensitive-path policies
4. Hooks and their documented trigger tests
5. Skills, subagents, plugins, and MCP configuration
6. CI or unattended-agent configuration
7. Separation of shared configuration from credentials and local overrides
8. Evidence that configured behavior has actually been exercised

For every finding, report:
- status: present, partial, missing, conflicting, or unverified
- exact file and line evidence
- practical consequence
- smallest safe next action
- how to verify that action

Distinguish instructions from enforcement. Do not describe a prompt rule,
pattern matcher, or secret scan as a complete security boundary.
Report unknowns explicitly.

1. Inventory the active surfaces

Locate configuration before judging it. Relevant files may include CLAUDE.md, .claude/, AGENTS.md, .codex/, SKILL.md files, agent definitions, MCP configuration, and CI workflows that invoke an agent non-interactively.

Also identify user-level configuration that affects the current machine but is not reproducible for teammates.

2. Audit the instructions

• Do documented commands exist in the package or build system?
• Are slow and destructive commands distinguished from routine checks?
• Does architecture guidance explain non-obvious boundaries rather than restating the directory tree?
• Are generated files, migrations, credentials, and deployment paths handled explicitly?
• Is the definition of done observable?
• Do nested instructions conflict with the repository root?

Mark stale or unverifiable instructions as partial. A guidance file’s existence is not evidence that its contents are correct.

3. Separate guidance from controls

Create two columns: “the agent is asked to do this” and “the environment enforces this.” Enforcement may include permission rules, a sandbox, protected credentials, hooks, branch protection, CI checks, or repository tooling.

If instructions say “never edit production migrations,” but no permission rule or hook covers that path, record it as guidance rather than enforcement. That may be acceptable; accurate labeling is the point.

4. Inspect every automation dependency

• Which event or command triggers it?
• Which files or tools does it match?
• What input does it expect?
• What happens when it succeeds, fails, times out, or lacks a dependency?
• Can it modify files, contact a service, publish, deploy, or change Git state?
• Is there a documented trigger test?

Do not execute destructive trigger tests during the audit. Record the safe test that should later run in a disposable environment.

5. Check skills and specialized agents

For each workflow, ask whether its purpose is clear, whether referenced scripts and files exist, and whether the task has a measurable completion condition. Look for overlapping skills, broad tool access, stale placeholder commands, and descriptions too vague to select reliably.

6. Check team reproducibility

• Shared configuration is committed and reviewed.
• Credentials are not embedded in project files.
• Local overrides are identified and excluded where appropriate.
• Required tools and versions are documented.
• CI has explicit limits, permissions, and failure behavior.
• A new contributor can identify which configuration is active.

A simple evidence score

Score instructions, commands, permissions, hooks, workflows, and team reproducibility from zero to two:

Use an evidence-first report

Prioritize contradictions and consequential unverified controls before adding new automation.

Audit FAQ