Audit Checklist

Run this checklist during Phase 1. The goal is to build a repo profile — an in-memory summary of what the repo communicates and where gaps exist. Do not output the profile to the user; it feeds Phase 2 (gap detection) directly.

Scan order

Process sources in this order. Skip any that do not exist.

1. Existing agent configuration

Read these first — they tell you what's already covered (and what might be stale):

Record: what instructions exist, which tool they target, and whether they're consistent across files.

2. Project documentation

Record: what's documented (this is what agents can discover — it should NOT appear in AGENTS.md).

3. Package manager and dependencies

Key check: Does the lock file match what README/scripts say? A package-lock.json with a README that says "use yarn" is a common source of non-discoverable instructions.

Record: actual package manager, runtime versions, script names and what they do.

4. Build and task runners

Record: multi-step commands, order-sensitive operations, caching quirks.

5. CI / CD pipelines

Key check: Do CI commands differ from local commands? (e.g., CI adds --no-cache, uses different env vars, runs additional steps). These differences are non-discoverable.

Record: CI-specific commands, environment differences, deployment triggers.

6. Linter and formatter configuration

Record: what's enforced automatically. These rules do NOT belong in AGENTS.md — they're already enforced.

7. Project configuration

Key check: Are there env vars used in code that are NOT in .env.example? Scan source files for process.env., os.environ, env::var, std::env patterns and compare against .env.example.

Record: documented vs. undocumented env vars, service dependencies.

8. Directory structure scan

Run a quick directory listing (top 2-3 levels). Look for:

• Deprecated-looking directories still imported somewhere (check barrel files, index.* re-exports)
• Unconventional naming that might confuse agents (e.g., src/ vs lib/ vs app/)
• Module boundaries in monorepos (each top-level package might warrant its own AGENTS.md)

Record: module count (for hierarchical AGENTS.md recommendation), suspicious directories.

Building the repo profile

After scanning, compile findings into these categories:

repo_profile:
  stack:
    languages: [...]
    frameworks: [...]
    package_manager: <actual, from lock file>
    runtime_versions: <from version files>

  existing_agent_instructions:
    files_found: [...]
    total_instructions: N
    stale: [<instruction, reason>]
    redundant: [<instruction, discoverable_from>]
    valid: [<instruction>]

  gaps:
    commands: [<non-obvious command + why>]
    landmines: [<hidden constraint + where found>]
    conventions: [<unforced convention + evidence>]
    env_vars: [<undocumented var + files that use it>]
    routing: [<module-specific guidance needed>]

  ambiguities: [<conflicting signal + what to ask user>]

This profile is consumed by Phase 2 (gap detection). Do not output it to the user.

Scan performance

For large repositories (1000+ files), prioritize:

1. Root-level config files (always read)
2. CI and workflow files (always read)
3. Top-level directory structure (always scan)
4. Source file sampling for env var detection (grep, don't read every file)

Do not read every source file. Use Grep for targeted searches (env vars, imports of suspicious directories, barrel file re-exports).