KOKO\Mimi
107 lines
4.4 KiB
Markdown
107 lines
4.4 KiB
Markdown
---
|
|
name: auditing-agents-md
|
|
description: Use when a user asks to audit, check, review, improve, update, or fix AGENTS.md or AGENTS.override.md files, or asks whether Codex repository guidance is accurate and current.
|
|
---
|
|
|
|
# Audit AGENTS.md
|
|
|
|
## Overview
|
|
|
|
Audit Codex guidance against the repository that it governs. Treat instruction
|
|
precedence, factual accuracy, scope, and conciseness as observable properties:
|
|
report evidence before proposing a change, and propose before editing.
|
|
|
|
## Workflow
|
|
|
|
1. **Resolve scope.** Identify the project root, current working directory, and
|
|
requested audit scope. Resolve Codex home from `CODEX_HOME`, falling back to
|
|
`~/.codex`; inspect global guidance only when it is in scope.
|
|
2. **Discover guidance.** Find `AGENTS.override.md` and `AGENTS.md` while
|
|
excluding VCS metadata, dependencies, caches, and generated output. At each
|
|
directory, an override is selected before the standard file. Map the active
|
|
chain from project root to the working directory and label files that govern
|
|
only other subtrees.
|
|
3. **Inspect evidence.** Read each selected file completely. Check commands,
|
|
paths, architecture claims, and conventions against manifests, source,
|
|
tests, config, and version control. Run only safe, relevant verification;
|
|
do not deploy, mutate external state, or expose credentials to score a file.
|
|
4. **Score every file.** Read
|
|
[quality-criteria.md](references/quality-criteria.md). Use its six weighted
|
|
criteria, 100-point total, and grade bands. Check conflicts, duplication,
|
|
misplaced scope, override behavior, and the combined 32 KiB default
|
|
instruction budget.
|
|
5. **Report before changing.** Emit the output contract below even when the
|
|
guidance is already strong.
|
|
6. **Propose targeted diffs.** Read
|
|
[update-guidelines.md](references/update-guidelines.md). Include only claims
|
|
supported by repository evidence. Use
|
|
[templates.md](references/templates.md) only when a missing structure is
|
|
genuinely useful.
|
|
7. **Request approval.** Stop after the report and proposed diffs. Ask which
|
|
changes the user wants applied.
|
|
8. **Apply and verify.** Edit only approved files, preserve their organization,
|
|
and re-check commands, paths, conflicts, active-chain order, and byte budget.
|
|
|
|
## Required Report
|
|
|
|
```markdown
|
|
## AGENTS.md Quality Report
|
|
|
|
### Summary
|
|
- Files found: N
|
|
- Active chain: path -> path
|
|
- Average score: N/100
|
|
- Files needing update: N
|
|
- Combined active-chain size: N bytes (default limit: 32 KiB)
|
|
|
|
### File-by-File Assessment
|
|
#### 1. path (scope; active/inactive)
|
|
**Score: N/100 (Grade: A-F)**
|
|
|
|
| Criterion | Score | Evidence |
|
|
| --- | ---: | --- |
|
|
| Commands and workflows | N/20 | ... |
|
|
| Repository map and instruction scope | N/20 | ... |
|
|
| Non-obvious constraints and gotchas | N/15 | ... |
|
|
| Conciseness and duplication | N/15 | ... |
|
|
| Currency against the codebase | N/15 | ... |
|
|
| Actionability and verifiability | N/15 | ... |
|
|
|
|
**Issues**
|
|
- ...
|
|
|
|
**Recommended changes**
|
|
- ...
|
|
```
|
|
|
|
After all assessments, show each proposed diff under `### Update: <path>` with
|
|
a one-line `Why:`. End with an explicit approval question. Do not edit in the
|
|
same turn unless the user already approved the exact diff.
|
|
|
|
## Quick Reference
|
|
|
|
| Question | Evidence |
|
|
| --- | --- |
|
|
| Which file applies? | Global selection, then one selected file per directory from root to working directory |
|
|
| Is a command current? | Manifest plus a safe command run when practical |
|
|
| Is a path accurate? | Filesystem and repository search |
|
|
| Is guidance misplaced? | Narrowest subtree where the rule is true |
|
|
| Is the chain too large? | Combined selected-file bytes versus configured/default limit |
|
|
| Should content be added? | Project-specific, durable, non-obvious, and actionable |
|
|
|
|
## Example
|
|
|
|
If `AGENTS.md` requires `npm test` but `package.json` contains only
|
|
`test:unit`, score currency and actionability down, cite `package.json`, and
|
|
propose the verified command. Do not invent an aggregate script or silently
|
|
edit the file.
|
|
|
|
## Common Mistakes
|
|
|
|
- Scoring the repository once instead of scoring every guidance file.
|
|
- Treating a nested override as deleting unrelated root guidance.
|
|
- Claiming a file is an entry point because its name looks plausible.
|
|
- Recommending generic best practices or facts obvious from code.
|
|
- Running destructive, deployment, or credential-sensitive commands to audit.
|
|
- Applying recommendations before the user approves the displayed diff.
|