update-agent-config

어떤 스킬인가요?

Use if auditing AGENTS.md/CLAUDE.md/REVIEW.md for drift after refactors — stale refs, rules.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

policy:
  allow_implicit_invocation: false

# Agent Dispatch Scaffolds

Reusable prompt templates for the two parallel-Opus phases: **auditor** (falsifiable-claim verification) and **writer** (in-place corrections + gap-folder authoring). Fill the placeholders with repo evidence before dispatching.

## Contents

- [Auditor Agent](#auditor-agent) — Phase 2
- [Writer Agent — In-Place Correction](#writer-agent--in-place-correction) — Phase 4
- [Writer Agent — Gap-Folder Author](#writer-agent--gap-folder-author) — Phase 4 (new files)

## Auditor Agent

The auditor reads existing AGENTS / REVIEW docs, extracts every falsifiable claim, verifies against current code, and returns a findings list. **It does not edit.**

Dispatch one auditor per logical group (3–5 in parallel for a typical repo). Each prompt 500–1500 words.

```text
You are an auditor in a multi-phase AGENTS.md refresh. Your job is to find drift between the docs and the current code state. **Do not edit anything — just produce a list of inaccuracies.**

Repo: <absolute path>
Current HEAD: <SHA> (mature; significant recent changes: <one-line summary of churn>)

## Files to audit

1. <absolute path to AGENTS.md #1> (<N> lines)
2. <absolute path to REVIEW.md #1> (<N> lines)
... up to ~4 files per auditor

## Drift hypotheses (from main agent's Phase 0 scan)

<paste the specific things you already know are stale, e.g.:>
- Schema version was bumped from v1.1 → v1.3 — sweep doc literal references
- styles.css grew 2,679 → 5,138 lines since these docs were last edited (commit <sha>) — every styles.css line ref is presumed stale
- Files marked "NOT YET LANDED" that may now exist: <list>
- Refactor commit <sha> moved every $playback.set out of audio-player.ts into stores/playback.ts action helpers

## Verification discipline

For each statement that names a specific `file:line`, `file:line-range`, a function/symbol/CLI flag, or a count, verify against current code:

- `grep -n "<symbol>" <file>` to confirm symbols still exist where claimed
- `sed -n 'L_START,L_ENDp' <file>` to confirm lines say what the doc claims
- `wc -l <file>` to confirm size claims
- `ls <file>` for existence claims (especially "NOT YET LANDED" stubs)
- `git log -S "<symbol>" --oneline -- <file>` if a symbol moved (rename/refactor)
- `grep -oc "<pattern>" <file>` to recount frequency-table entries
- For Make targets and npm scripts: check actual `Makefile` and `package.json`

For each falsifiable claim, report exactly one of:

- **VERIFIED ✓** — claim matches current code
- **STALE: <actual state with file:line>** — concept still right, location/count drifted
- **INCORRECT: <reality>** — claim itself is now wrong (rule invalidated, architecture changed, status flipped)
- **MISSING: <new content the doc should mention>** — code has something the doc doesn't acknowledge
- **UNVERIFIED: <why couldn't check>** — auditor couldn't cheaply confirm; flag for `[unverified]` marker

## Output format

```
## File: <path>
- L<N> "<exact quoted claim>" — VERIFIED ✓
- L<N> "<exact quoted claim>" — STALE: <actual state>
- L<N> "<exact quoted claim>" — INCORRECT: <reality + file:line evidence>
- L<N> "<exact quoted claim>" — MISSING: <new fact the doc should add>
- L<N> "<exact quoted claim>" — UNVERIFIED: <why>
```

Show the verification commands you ran for the non-trivial cases. Skip statements that are evidently general guidance (no file:line, no count, no symbol). Focus on the falsifiable ones.

End with a 3-bullet summary of the largest drifts found across all your files.

## Constraints

- **Read-only.** No Edit, no Write, no Bash mutations.
- **Be ruthless.** These files were authored months ago and the codebase has shifted. Default-suspect every line ref, every count.
- **Cite evidence, not opinion.** A claim is wrong because grep returned X, not because "it seems off".
- Aim for <800 words in the findings list. Don't audit prose that has no falsifiable content.
```

### What to vary per auditor

- **Files** — disjoint sets per auditor.
- **Drift hypotheses** — give each auditor the specific churn signals from Phase 0 that affect their files.
- **Domain hint** — if files are domain-specific (design system, audio engine, etc.), say so so the auditor knows which grep patterns matter.

## Writer Agent — In-Place Correction

The writer receives the auditor's findings and applies Edit calls in place. **It does not re-audit.**

Dispatch one writer per logical group, same grouping as auditors. Prompts 500–2000 words.

```text
Apply corrections to <N> files at <repo path>. Use the Edit tool. **Preserve voice, structure, and length** — do not aggressively rewrite. Re-grep / re-sed only to verify current line numbers before each edit. Repo HEAD: <SHA>.

## Files to update

1. <path #1> (<N> lines)
2. <path #2> (<N> lines)
...

## Audit findings to fix

<paste the auditor's findings list for these files verbatim>

For each finding:
- **STALE** → update the line number / file path / count to current
- **INCORRECT** → rewrite the rule/claim to match current reality, citing file:line evidence
- **MISSING** → add the new content where it belongs in the existing section structure (do not invent new sections)
- **UNVERIFIED** → leave the original claim or mark `[unverified]` if the doc supports it

## Approach

For each file:
1. Read the current content.
2. Re-verify line refs and counts via `grep -n` / `sed -n` / `wc -l` before each edit — the auditor's findings may be slightly stale by now, and recount is cheap.
3. Apply Edit calls in place. One concern per Edit (don't bundle).
4. Preserve the existing section structure. Don't renumber. Don't reorder.
5. Length should stay within ±5% of original. If a single section grew substantially, you're rewriting, not patching — stop and reconsider.

## Frequency tables

When the audit flagged a frequency-table recount: re-grep against the current source file, fill in the new counts. Examples:

```bash
# Color counts
for HEX in <list>; do grep -oc "$HEX" src/styles.css; done

# escapeHtml call counts per UI module
for f in src/ui/*.ts; do grep -c escapeHtml "$f"; done
```

Write the new counts, not the auditor's numbers — recompute fresh.

## Internal consistency

If the audit flags a §1 row contradicting §8 prose: pick the truth (verify against code), edit both sections to match. Don't leave one stale while fixing the other.

## Stub graduation

For each "NOT YET LANDED" / "deferred" entry the audit flagged as now-shipped:
1. Add a proper row in the manifest table describing the file.
2. Remove the stub line.
3. If the doc has a §1 manifest table and a separate §N "Stubs" paragraph, edit both.

## Forbidden

- **No new sections.** Update mode only edits existing structure. If the code has new scope, that's a separate `init-agent-config` pass.
- **No voice rewrites.** Surgical edits only.
- **No "while I'm here" cleanups.** If the audit didn't flag it, don't touch it.
- **No commits/pushes.** The main agent handles git.

## Output

Report: 3-line summary per file of what shifted (e.g., "Updated 12 line refs, fixed §3 rule about HTMLAudioElement → Web Audio, dropped two stub-marked entries"). Then the absolute path list.
```

### What to vary per writer

- **Files** — same grouping as the corresponding auditor.
- **Audit findings** — feed the relevant subset of the auditor's report verbatim.
- **Stylistic constraints** — if the file has a known voice quirk (e.g., uses `**bold**` for verb names), call it out.

## Writer Agent — Gap-Folder Author

When the Phase 0 scan found a code-bearing folder without a local `AGENTS.md`. **Pattern after the closest sibling — no greenfield template.**

Prompt 1500–3000 words because the author needs to read the target folder's code AND the sibling AGENTS.md as a stylistic model.

```text
Write `<absolute path>/AGENTS.md` and `<absolute path>/REVIEW.md` for the <folder name> folder. Do NOT create the CLAUDE.md symlink — the main agent will.

## Context

The repo has a mature AGENTS hierarchy with files at: <list root + all existing folder AGENTS.md paths>. The folder at <gap path> is the only code-bearing folder without local guidance.

Code in this folder:

```
<paste `find <gap path> -type f -not -name '*.test.*' | head -20`>
```

## Style template — MIMIC this file

Read `<closest sibling AGENTS.md path>` BEFORE writing as the stylistic template. It sets the bar for:
- evidence-grounded prose (file:line refs everywhere)
- "Verified DON'Ts" closing section
- Density (information per line, table layouts where they fit)
- Tone (terse, no marketing, direct)

Also read the corresponding `<sibling REVIEW.md>` as the model for REVIEW format.

## What to discover

Before writing, read the actual code in the target folder. Capture:

1. **Module manifest** — every file in the folder + its role + exports + tests
2. **Canonical handler/render/entry shape** — what's the common code skeleton?
3. **Cross-file conventions** — does it have a `_shared.ts` / `helpers.ts` pattern?
4. **Runtime / environment differences from parent** — e.g., Workers vs browser, server vs client
5. **Test pattern** — vitest? jest? in-band? fake-env?
6. **Error model / response shapes** — what status codes, what envelope, what failure modes
7. **Verified DON'Ts** — what mistakes would a coder make if these docs didn't exist?

## What to write

### `<path>/AGENTS.md` (target ~150 lines)

Section sketch (adapt to fit what the folder actually has):

1. Framing paragraph — what this folder owns, how it differs from src/
2. Module manifest (table)
3. Canonical handler/render shape (with file:line citation)
4. Common patterns (e.g., `_shared.ts` rule, D1 binding access, etc.)
5. Local dev incantation (exact CLI, verified against Makefile / package.json)
6. Testing pattern (from an actual test file)
7. Error model
8. The no-throw rule (or equivalent invariant)
9. Verified DON'Ts (≥6 items, each with `file:line` evidence)
10. Open questions / `[unverified]` (be honest — flag anything you couldn't validate)

### `<path>/REVIEW.md` (target ~50 lines)

Section sketch:

1. Framing — diff-scrutiny rules; operating guidance lives in `<path>/AGENTS.md`
2. Critical Areas (numbered list, each tagged **Block** or **Hold** with evidence)
3. Security (auth, validation, escaping)
4. Conventions
5. Patterns
6. Trigger words for deeper review (grep-able phrases)

## Style requirements

- **Concrete `file:line:column` references**, not "see the file".
- **Each statement is falsifiable** — reviewer can grep and confirm.
- **`[unverified]` for any claim you couldn't validate.**
- **No marketing language.** Direct, terse.
- **Verified DON'Ts section mandatory**, ≥6 items.
- **Complete enough that a coder editing this folder need not read another AGENTS.md.**

## Constraints

- Do NOT write the CLAUDE.md symlink — the main agent owns that.
- Do NOT modify any file outside the target folder.
- Do NOT invent claims — if the code doesn't show it, don't write it.
- Length should be roughly in line with the sibling template you used.

## Output

Report: absolute paths created, 4-sentence summary of AGENTS.md content + 3-sentence summary of REVIEW.md content.
```

### What to vary per gap-folder dispatch

- **Closest sibling** — pick the AGENTS.md whose runtime/concerns are most similar. For a Pages Functions folder, `src/services/AGENTS.md` is closer than `src/ui/AGENTS.md`.
- **Code reading hints** — if the folder has unusual conventions (e.g., a `_shared.ts` per-subfolder pattern), call it out so the author looks for it.
- **Length target** — match the sibling's density.

## Why three scaffolds, not one

- The **auditor** must be cognitively committed to *reading and verifying*, not *fixing*. Mixing the role contaminates the audit.
- The **in-place writer** must trust the audit and stay surgical. If it re-audits, it second-guesses and rewrites.
- The **gap-folder author** is doing a different cognitive task: discovery + drafting, more like `init-agent-config`'s writer pass. Different brief, different freedom.

Dispatch them as separate agents. Don't try to merge.

# Agent Entrypoints, Review Context, and Cross-Agent Compatibility

How AGENTS-first repositories expose the same instruction hierarchy to agent-native loaders and review adapters without creating competing sources of truth.

## Core Model

`AGENTS.md` is the source of truth for agent behavior. `REVIEW.md` is the review-standardization layer when the run or repo evidence warrants one. Agent-native entrypoints and review adapters are companions, not peers.

Default order:
1. discover the repo
2. write the root and folder `AGENTS.md` hierarchy
3. create or repair sibling `CLAUDE.md` companions
4. create the repo-grounded `REVIEW.md` layer when in scope, or record why it is skipped
5. ask about platform-native review adapters only after the review-context decision

## Support Matrix

| Agent | Reads root `AGENTS.md` | Reads nested `AGENTS.md` | Native file | Recommended role |
|------|-------------------------|--------------------------|-------------|------------------|
| Codex CLI | Yes | Yes | `AGENTS.md` | Primary shared consumer |
| Cursor | Yes | Yes | `.cursor/rules/*.mdc` | Reads AGENTS directly, add `.mdc` only for Cursor-only behavior |
| VS Code Copilot | Yes | Yes | `.github/copilot-instructions.md` | Shared rules stay in AGENTS |
| Claude Code | Through `CLAUDE.md` | Through nested `CLAUDE.md` companions | `CLAUDE.md` + `.claude/` | Mirror each AGENTS file with a companion entrypoint |
| Gemini CLI | Yes | Root-first | `GEMINI.md` | Shared rules in AGENTS, Gemini-only notes in `GEMINI.md` |
| Aider | Yes | Root-first | `.aider.conf.yml` | Configure `read: AGENTS.md` |
| Windsurf | Yes | Root-first | `.windsurfrules` | Keep native file minimal and pointer-oriented |
| Root-only agents | Yes | No | Agent-specific | Depend on a strong root AGENTS file |

## Default Entrypoint Strategy

| Agent | Primary file | Default strategy in this skill |
|------|--------------|--------------------------------|
| Claude Code | `CLAUDE.md` | Symlink to sibling `AGENTS.md` |
| Gemini CLI | `GEMINI.md` | Small pointer or agent-only delta that points back to `AGENTS.md` |
| GitHub Copilot | `.github/copilot-instructions.md` | Pointer to `AGENTS.md` plus scoped files only if needed |
| Cursor | `.cursor/rules/*.mdc` | Use only for Cursor-only behavior; shared rules stay in `AGENTS.md` |
| Aider | `.aider.conf.yml` | Configure `read: AGENTS.md` |
| Windsurf | `.windsurfrules` | Condensed pointer or summary when native file is required |

## Core Standardization Surfaces

Every finished repo should leave this skill with an AGENTS source of truth and a review-context decision:

| File | Purpose |
|------|---------|
| `AGENTS.md` | How agents should work, where code belongs, what boundaries exist |
| `CLAUDE.md` | Sibling compatibility companion for each finalized `AGENTS.md` |
| `REVIEW.md` | What diffs should be flagged, protected, or held to a higher bar when review context is in scope |

Keep them complementary:
- `AGENTS.md` tells the agent how to operate
- `REVIEW.md` tells the reviewer what to scrutinize when generated
- neither file should become a duplicate of the other

## Configurable Native Review Adapters

These are final-stage adapters generated from the completed `AGENTS.md` hierarchy and the recorded review-context decision.

| Platform | Native files | Use them for | Keep out of them | Key gotcha |
|----------|--------------|--------------|------------------|------------|
| Copilot | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | Copilot review guidance and scoped review rules | Shared repo-wide coding policy that belongs in `AGENTS.md` | Copilot reads instruction files from the base branch, not the PR branch |
| Devin | `REVIEW.md` plus optional scoped `REVIEW.md` and existing `AGENTS.md` | Bug Catcher diff criteria and scoped review surfaces | Duplicated review rules in `AGENTS.md` | Avoid relying on undocumented precedence for overlapping scoped files |
| Greptile | `.greptile/config.json` plus optional `rules.md`, `files.json` | Review configuration, prose rules, scoped context files | Shared coding-agent policy that belongs in `AGENTS.md` | Greptile reads config from the source branch, not the base branch |

## Final-Step Question

After the AGENTS hierarchy and review-context decision are done, ask one concise question:

`The AGENTS.md hierarchy is complete and the REVIEW.md decision is recorded. Which native review adapters should also be generated for this repo: Copilot, Devin, Greptile, or none?`

Use that answer to decide whether to stop or generate adapters in this same workflow.

## Claude Code: Symlink-First Policy

For every finalized `AGENTS.md`, create the matching companion file:

```bash
ln -s AGENTS.md CLAUDE.md
```

For nested folders:

```bash
cd src/api
ln -s AGENTS.md CLAUDE.md
```

This skill treats the sibling symlink as the default Claude compatibility policy because it keeps `AGENTS.md` authoritative and eliminates drift.

## When the Symlink Cannot Be Used

Use the fallback wrapper only when the target environment cannot preserve symlinks:

```markdown
@AGENTS.md
```

If you have to use the wrapper:
- keep it one line unless the user explicitly wants more
- call out the reason in your response
- do not let the wrapper grow into a second instruction document

## Where Claude-Only Behavior Belongs

Keep Claude-specific features in `.claude/`, not in the symlinked `CLAUDE.md`.

| Need | Put it here | Why |
|------|-------------|-----|
| Path-scoped Claude rules | `.claude/rules/` | Claude loads them natively without duplicating AGENTS content |
| Custom slash commands | `.claude/commands/` | Native feature, not shared policy |
| Named agents | `.claude/agents/` | Claude-only orchestration surface |
| Hooks and permissions | `.claude/settings.json` | Operational config, not portable instruction text |
| Team-wide project rules | `AGENTS.md` | Shared by all coding agents |

**Rule:** if a line applies to more than Claude, it does not belong in `CLAUDE.md`.

## Other Agent Entrypoints

### GitHub Copilot

Use `.github/copilot-instructions.md` plus scoped `.github/instructions/*.instructions.md` as the Copilot translation of the completed review context.

Brief setup map:
- enable Copilot code review in repository or organization GitHub settings before expecting the files to matter
- keep universal rules in `AGENTS.md`
- keep repo review standards grounded in `REVIEW.md`
- keep each Copilot instruction file under the platform limit
- remember that Copilot review uses the base branch version of the instruction files

Minimal pointer example:

```markdown
See AGENTS.md for shared repository instructions.
Keep this file limited to Copilot-only behavior.
```

Generate these files only if the user explicitly chose Copilot at the final stage.

### Devin

Devin uses the same split as this skill:
- `REVIEW.md` for Bug Catcher review criteria
- `AGENTS.md` for coding behavior, architecture, workflow, and testing expectations

Brief setup map:
- prefer `REVIEW.md` only unless coding behavior guidance is also needed
- keep review criteria out of `AGENTS.md`
- verify with a test PR or `npx devin-review`
- avoid contradictions across multiple scoped `REVIEW.md` or `AGENTS.md` files

Generate extra Devin-specific review surfaces only if the user explicitly chose Devin at the final stage.

### Gemini CLI

Use `GEMINI.md` only for Gemini-only behavior. Shared rules still live in `AGENTS.md`.

Example:

```markdown
# Gemini Notes

See `AGENTS.md` for shared project instructions.
Only add Gemini-specific execution notes here if they are genuinely unique.
```

### Greptile

Use `.greptile/config.json` as the primary Greptile translation of the completed review context, with optional `rules.md` and `files.json` when repo evidence justifies them.

Brief setup map:
- install the Greptile GitHub app or GitLab webhook before expecting repo config to run
- prefer the `.greptile/` directory over legacy `greptile.json`
- keep `scope` as an array and `ignorePatterns` as a newline-separated string
- add context files only when they materially improve review quality
- remember Greptile reads config from the source branch

Generate these files only if the user explicitly chose Greptile at the final stage.

### Cursor

Cursor reads `AGENTS.md` directly. Use `.cursor/rules/*.mdc` only for Cursor-specific globs, not for shared project rules.

### Aider

Configure the read list rather than duplicating instructions:

```yaml
read:
  - AGENTS.md
```

## Decision Table: Where an Instruction Belongs

| Instruction type | Destination |
|------------------|-------------|
| Shared project command or convention | `AGENTS.md` |
| Repo-wide diff-review rule | `REVIEW.md` |
| Folder-specific workflow | Folder-local `AGENTS.md` |
| Folder-specific diff-review rule | Scoped `REVIEW.md` |
| Claude-only path rule | `.claude/rules/*.md` |
| Claude-only command or agent profile | `.claude/commands/` or `.claude/agents/` |
| Copilot-only scoped behavior | `.github/instructions/*.instructions.md` |
| Gemini-only runtime note | `GEMINI.md` |
| Personal override | Gitignored local file, not shared config |

## Universal vs Agent-Specific Content

### Safe in AGENTS

- verified commands
- architecture boundaries
- folder-local risks
- repo-wide conventions
- Always/Ask/Never rules
- non-obvious WHY context

### Safe in REVIEW

- diff-review criteria
- high-risk change patterns
- boundaries that should trigger findings
- ignore patterns for generated or irrelevant files
- testing or validation expectations that matter during review

### Keep out of AGENTS

- Claude path-scoped rules
- Claude slash commands and agents
- Cursor glob rules
- Copilot scoped instruction files
- Gemini-only runtime behavior
- Aider read-list configuration

### Keep out of REVIEW

- generic coding advice
- linter-enforced style rules
- agent workflow instructions that belong in AGENTS
- platform-native syntax that belongs in adapters

## Recommended Layouts

### Single project

```text
repo/
├── AGENTS.md
├── CLAUDE.md -> AGENTS.md
├── GEMINI.md
└── .github/
    └── copilot-instructions.md
```

### Large `src/` tree

```text
repo/
├── AGENTS.md
├── CLAUDE.md -> AGENTS.md
└── src/
    ├── api/
    │   ├── AGENTS.md
    │   └── CLAUDE.md -> AGENTS.md
    ├── web/
    │   ├── AGENTS.md
    │   └── CLAUDE.md -> AGENTS.md
    └── jobs/
        ├── AGENTS.md
        └── CLAUDE.md -> AGENTS.md
```

### Monorepo

```text
repo/
├── AGENTS.md
├── CLAUDE.md -> AGENTS.md
├── apps/
│   ├── web/
│   │   ├── AGENTS.md
│   │   └── CLAUDE.md -> AGENTS.md
│   └── api/
│       ├── AGENTS.md
│       └── CLAUDE.md -> AGENTS.md
└── packages/
    └── shared/
        ├── AGENTS.md
        └── CLAUDE.md -> AGENTS.md
```

## Strategy by Team Shape

### Single-agent team

If the user explicitly wants one agent only, that agent's native file can be enough. This skill still prefers AGENTS-first unless the user asks for a single-agent exception.

### Multi-agent team

1. use AGENTS as the shared source of truth
2. create local AGENTS files for meaningful folders
3. mirror each finalized AGENTS file with a sibling `CLAUDE.md` companion
4. add native files only for genuinely agent-specific behavior
5. keep personal overrides gitignored

### Root-only agent consumers

Because some agents do not read nested files, the root `AGENTS.md` still needs:
- verified repo-wide commands
- top-level architecture
- shared boundaries
- a concise map of the folders that have stronger local rules

## Migration Patterns

### From standalone `CLAUDE.md`

1. extract shared instructions into root `AGENTS.md`
2. create local `AGENTS.md` files where the architecture needs them
3. replace `CLAUDE.md` with a sibling symlink to `AGENTS.md`
4. move Claude-only behavior into `.claude/`

### From `.cursorrules`

1. copy universal content into `AGENTS.md`
2. move Cursor-only globs and behavior into `.cursor/rules/*.mdc`
3. create companion `CLAUDE.md` files only if Claude support is needed

### From no config

Out of scope for `update-agent-config`. Route to `init-agent-config` for greenfield setup.

## Verification

```bash
# Find companion files
find . -name CLAUDE.md -o -name GEMINI.md -o -path './.github/copilot-instructions.md'

# Check which Claude files are symlinks
find . -type l -name CLAUDE.md -print

# Check for adjacent native review surfaces
find . \( -path './.github/copilot-instructions.md' -o -name 'REVIEW.md' -o -path './.greptile/config.json' \) 2>/dev/null
```

Then verify in the target agent:
- ask Claude Code to summarize its instructions in one nested folder
- ask a second agent to summarize the root instructions
- confirm both responses reflect the same AGENTS hierarchy

Use at least two agents when validating a shared setup. One should read nested files and one can be root-only.

If the user later opts into review adapters, validate those adapter files against the completed `REVIEW.md` rather than reopening the AGENTS authoring pass.

## Real-World Examples

### Example 1: Claude + Codex on an app repo

```text
AGENTS.md
CLAUDE.md -> AGENTS.md
src/api/AGENTS.md
src/api/CLAUDE.md -> AGENTS.md
src/web/AGENTS.md
src/web/CLAUDE.md -> AGENTS.md
```

Codex reads the root and nested AGENTS files directly. Claude follows the mirrored companions. Both agents converge on the same instruction hierarchy.

### Example 2: Open-source repo with mixed contributors

```text
AGENTS.md
src/cli/AGENTS.md
src/core/AGENTS.md
```

Keep the root file strong enough for root-only tools. Add native companion files only if contributors actually use those agents.

### Example 3: Enterprise monorepo

```text
AGENTS.md
CLAUDE.md -> AGENTS.md
apps/web/AGENTS.md
apps/web/CLAUDE.md -> AGENTS.md
apps/api/AGENTS.md
apps/api/CLAUDE.md -> AGENTS.md
.github/copilot-instructions.md
.claude/rules/
```

AGENTS stays authoritative. Copilot and Claude each get only the native extras they need.

## Common Gotchas

| Gotcha | Why it bites | Fix |
|--------|-------------|-----|
| Writing `CLAUDE.md` first | Claude becomes the real source of truth | Write `AGENTS.md` first, then mirror it |
| Skipping `REVIEW.md` because no PR tool is installed | Review standards disappear when repo risks are real | Create `REVIEW.md` when review context is in scope or evidence warrants it |
| Adding shared rules to `CLAUDE.md` | Other agents never see them | Move them into `AGENTS.md` |
| Using wrapper text as a second policy file | Shared rules drift | Keep wrapper one line or use the symlink |
| Keeping Claude-only notes in AGENTS | Pollutes portable instructions | Move them into `.claude/` |
| Forgetting nested companions | Claude misses folder-local rules | Mirror each finalized nested `AGENTS.md` with a sibling `CLAUDE.md` |
| Root file is too weak for root-only agents | Too much was pushed into nested files | Restore repo-wide commands, architecture, and boundaries to root |
| REVIEW duplicates AGENTS | The two files compete instead of complementing | Keep operating guidance in AGENTS and diff scrutiny in REVIEW |
| Native files duplicate AGENTS content | Shared policy drifts by tool | Point back to AGENTS and keep only agent-specific deltas |
| Copilot rules authored on a feature branch | The PR review ignores them | Merge the instruction changes to the base branch first |
| Devin `REVIEW.md` and `AGENTS.md` say the same thing | Devin reads both and review noise increases | Keep review criteria in `REVIEW.md`, coding behavior in `AGENTS.md` |
| Greptile config uses the wrong field shapes | The config silently misbehaves | Keep `scope` as arrays and `ignorePatterns` as a newline string |
| Asking about review adapters too early | The main task gets derailed before AGENTS and REVIEW are done | Ask only at the final configurable step |

## Out-of-Scope Exception

A standalone, Claude-only `CLAUDE.md` may still be valid when the user explicitly wants a Claude-only setup and portability does not matter. That is not the default operating model for this skill. This skill assumes AGENTS-first unless the user says otherwise.

# AGENTS.md Authoring Guide

How to design, write, and verify an AGENTS-first instruction hierarchy with the minimum number of files that still preserves folder-local signal.

## Purpose

`AGENTS.md` is the primary instruction surface in this skill's operating model.

Use it to capture:
- commands agents must run correctly
- architecture boundaries agents cannot infer safely
- folder-local risks and conventions
- Always/Ask/Never rules that prevent real mistakes

Do not use it for:
- agent-native syntax
- generic coding advice
- duplicated README prose
- comments about unresolved uncertainty

## Core Rules

1. Plain markdown only.
2. Root file first, folder files second.
3. Each child file contains only the local delta from its parent.
4. Default to local files for meaningful `src/*`, `apps/*`, `services/*`, or `packages/*` subtrees identified as gap folders during Phase 0, but skip or collapse folders with no distinct workflow, risk, or convention.
5. Every file must answer: `What does a coder working in this scope need to know to avoid mistakes?`
6. If a line would not prevent a mistake, cut it.
7. Companion agent files must point back to AGENTS rather than competing with it.

## Root vs Folder Scope

| Scope | Include | Exclude |
|------|---------|---------|
| Root `AGENTS.md` | Verified repo-wide commands, top-level architecture, shared conventions, repo-wide boundaries | Folder-only entrypoints, deep implementation trivia, duplicated docs |
| Folder `AGENTS.md` | Local entrypoints, folder-specific commands, non-obvious conventions, local risks, parent overrides | Generic advice, full root command list, repo-wide policy already stated above |

## Authoring Mental Model

Write for the coder standing in the current folder.

Ask these questions before adding a line:
- What mistake would happen here without this instruction?
- Is this shared across the repo or only true in this subtree?
- Is this a real command, boundary, or non-obvious design choice?
- Does this belong in the parent file instead?

## WHAT / WHY / HOW

Every strong instruction belongs to one of these buckets:

### WHAT

Document technical reality the agent cannot infer safely.

Good:
- `src/app/ uses App Router, not Pages Router`
- `packages/contracts/ owns public API schemas`

Bad:
- `This project uses TypeScript`
- `Components live in src/components/`

### WHY

Explain the reason behind a non-obvious choice when it changes agent behavior.

Good:
- `Use sessions, not JWT, because SSR reads auth state server-side`
- `Keep SQL in sqlc definitions because generated types are the contract`

### HOW

Document verified commands or workflows the agent must execute correctly.

Good:
- `Test API contracts: pnpm test -- src/api`
- `Regenerate types with cargo build -p contracts`

Bad:
- guessed commands
- vague steps like `run the usual tests`

## Recommended Sections

Only create a section when repo evidence justifies it.

### Root File

```markdown
# Project Name

## Commands
- Dev: `verified command`
- Test: `verified command`

## Architecture
- `src/api/` — API boundary
- `src/web/` — UI boundary

## Conventions
- Project-specific rule

## Boundaries
- Always: repo-wide invariant
- Ask: change that needs approval
- Never: dangerous action
```

### Folder File

```markdown
# src/api

## Local Focus
- HTTP handlers, request validation, error shapes

## Local Commands
- Test: `verified folder-level command`

## Local Conventions
- Rule specific to this subtree

## Local Boundaries
- Always: action required in this folder
- Never: local mistake to avoid
```

## Folder Coverage Strategy

Start from the filesystem, not from templates.

1. Scan the tree with `treezip .` when available (compressed brace-grouped output with build
   noise pre-filtered), otherwise `tree -d .` or `tree -dL 2 .`. If one subtree floods the
   output anyway (vendored deps, checked-in worktrees), skip to where the real source resumes —
   don't page through noise and don't write a parser for it.
2. Mark the repo root plus each meaningful `src/*`, `apps/*`, `services/*`, or `packages/*` folder.
3. After the audit, create a local `AGENTS.md` for each first-level subtree with its own workflow, entry points, or failure modes.
4. If the audit proves a folder has no distinct workflow, risk, or convention, skip it or collapse the guidance into the parent.
5. If a folder has a small but real local delta, keep the file short instead of moving the detail to the root.
6. Add deeper nesting only when the second-level subtree has genuinely different rules from its parent.

**Selection test — a folder earns its own file only when all four hold:**

| Test | Passes when | Fails when (→ skip) |
|------|-------------|---------------------|
| Code-bearing | Real source files live here | Data, assets, generated output, planning docs |
| Substantial | ~10+ source files or ~1,500+ LOC (soft floor) | A handful of small helpers — unless one holds a dangerous invariant |
| Invariant-dense | Rules the code can't show: protocol facts, ordering contracts, "never do X" traps, test gotchas | Conventional glue: utility helpers, thin view wrappers, generated bindings, standard CRUD |
| Not already covered | Nearest ancestor `AGENTS.md` lacks these rules | Parent file already carries them — prefer one file at the subsystem root over one per leaf |

Expect to skip most folders. On a mid-size repo a healthy pass yields 2–4 folder files. Every
skip is reported with a one-line reason so the user can veto — "conventional UI code",
"8 files / 400 LOC utility folder", "covered by `src/AGENTS.md`".

## Example Hierarchy

```text
repo/
├── AGENTS.md
├── CLAUDE.md -> AGENTS.md
├── src/
│   ├── api/
│   │   ├── AGENTS.md
│   │   └── CLAUDE.md -> AGENTS.md
│   ├── components/
│   │   ├── AGENTS.md
│   │   └── CLAUDE.md -> AGENTS.md
│   ├── lib/
│   │   ├── AGENTS.md
│   │   └── CLAUDE.md -> AGENTS.md
│   └── jobs/
│       ├── AGENTS.md
│       └── CLAUDE.md -> AGENTS.md
└── tests/
    └── AGENTS.md
```

Use the same pattern at `apps/*`, `services/*`, or `packages/*` when those directories are the true architecture boundaries.

## Size and Signal

| File | Ideal | Good | Hard Ceiling |
|------|-------|------|--------------|
| Root `AGENTS.md` | <80 lines | <120 lines | 200 lines |
| Folder `AGENTS.md` | <25 lines | <40 lines | 80 lines |

For every line, ask:

| Check | If true |
|------|---------|
| The agent can infer it from code | Cut it |
| Tooling already enforces it | Cut it |
| It belongs in the parent file | Move it up |
| It belongs in one folder only | Move it down |
| It is generic advice | Rewrite or cut it |
| It would not prevent a mistake | Cut it |

## Good vs Bad Nested Files

### Bad: child file repeats the parent

```markdown
# src/api

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`

## Conventions
- Use pnpm
- Run tests before committing
```

This wastes context because it mostly repeats root-level rules.

### Good: child file is local

```markdown
# src/api

## Local Focus
- HTTP handlers, request validation, response contracts

## Local Commands
- Contract tests: `pnpm test -- src/api`

## Local Boundaries
- Always: update request schema and response contract together
- Never: bypass the shared error formatter in `src/api/errors`
```

## Common Bloat Patterns

| Pattern | Why it is bad | Better move |
|--------|----------------|-------------|
| Full directory tree dump | The agent can inspect the tree | Keep only meaningful boundaries |
| README copy | Duplicates existing docs | Reference README instead |
| Generic best practices | Too vague to change behavior | Use specific local rules |
| Full dependency list | Package manifests already exist | Document only non-obvious choices |
| Repeated root commands in child files | Wastes context twice | Keep only local commands in child files |

## Discovery Handoff

Do not draft from templates before discovery is complete.

### Phase 0 scan must answer
- repo-wide command sources
- top-level architecture
- current instruction surfaces
- candidate local file boundaries

### the audit must answer
- what a coder in this folder needs to know
- folder-local commands and workflows
- non-obvious patterns and WHY context
- which rules belong in the parent instead

### Writer prompts must include
- target file path
- folder ownership
- parent-child boundary
- verified commands and paths
- relevant Phase 0 scan and the audit findings

## Companion File Rule

After an `AGENTS.md` file is finalized:

1. create sibling `CLAUDE.md -> AGENTS.md`
2. if symlinks are impossible, use the fallback wrapper:
   ```markdown
   @AGENTS.md
   ```
3. keep agent-native behavior outside the AGENTS file

See `agent-entrypoints.md` for the full policy and cross-agent behavior.

## Verification

```bash
find . -name AGENTS.md | sort
find . -name CLAUDE.md -maxdepth 6 -print
find . -type l -name CLAUDE.md ! -exec test -e {} \; -print
```

Then ask the target agents to summarize the instructions they see for a folder you touched.

## Derailments

| Pattern | Trigger | Correction |
|---------|---------|------------|
| AGENTS-second drafting | Editing native files first | Write AGENTS first |
| One-wave exploration | Writing after Phase 0 scan only | Complete the audit first |
| Weak explorer prompts | Short vague dispatches | Use substantive prompts with scope and deliverables |
| Writers too early | Findings not merged | Synthesize before dispatch |
| Missing folder coverage | Root-only file plan | Add local AGENTS files |
| Root duplication | Child file repeats root | Keep child files local |
| Invented commands | Unsure command syntax | Verify or mark `[unverified]` |
| Missing WHY | Non-obvious choice documented | Pair WHAT with WHY |
| Generic best practices | Vague advice shows up | Replace with measurable rules |
| Unknowns in files | Caveats inside docs | Put caveats in the response |
| Over-nesting | Too many empty local files | Keep only meaningful local files |

# Audit and Update Guide

How to audit a mature AGENTS.md hierarchy for drift and apply the corrections — falsifiable claims, grep verification, in-place edits.

## The two-phase contract

```
audit (claims → grep → findings) → triage → write (in-place edits) → re-audit
```

Auditors do not edit. Writers do not re-audit. The boundary is load-bearing because:

- Auditors that edit get rushed; they stop verifying carefully when the next claim is one Edit call away.
- Writers that re-audit double the work and silently disagree with the auditor's findings, leading to half-applied corrections.

Keep the phases separate.

## Drift categories

Every finding lands in one of four buckets. Use them in the Quality Report.

| Category | Definition | Impact | Fix urgency |
|---|---|---|---|
| **STALE** | The reference still points at the right concept; just the line number / file path / count is wrong | Low – cosmetic, but accumulates | Batch with surrounding edits |
| **INCORRECT** | The claim itself is no longer true — the rule, the count, the architecture, the symbol's purpose has changed | High – misroutes future agents | Fix this pass |
| **MISSING** | A file / export / verb / section that now exists but the doc still says "NOT YET LANDED" or doesn't mention | High – future agents won't know about it | Fix this pass |
| **UNVERIFIED** | The auditor couldn't cheaply confirm or refute (e.g. deeply nested helper, requires reading 500 lines of code) | Variable – flag with `[unverified]` in the doc | Defer to next pass or leave as `[unverified]` marker |
| **INTERNAL CONTRADICTION** | Same doc says X in §1 and not-X in §8 | High – picks a side for the reader | Pick the truth, propagate |

## Falsifiable-claim discipline

A claim is **falsifiable** if a grep / sed / wc / ls call can prove or disprove it. These are the only claims the auditor scores. Everything else is descriptive prose — leave it alone in update mode.

Falsifiable patterns to extract from a doc:

- `<file.ext>:<line>` or `<file.ext>:<line>-<line>` — line refs
- `` `<symbol>` `` in code-font where the symbol names a function, class, type, export, or constant
- "uses X" / "exports Y" / "imports Z" claims
- Numeric counts: "33 uses of `#hex`", "12 occurrences of `font-weight: 600`", "5 places call `formatDate`"
- Status claims: "NOT YET LANDED", "deferred", "removed in PR #N"
- Existence claims: "no test file exists", "no @vitejs/plugin-react"
- Schema literals: "`archive.compact.v1.1`" — sweep for the literal across multiple docs
- Verb / action enumerations: "data-action values: foo, bar, baz" — check for new verbs

For each, the auditor cites the exact verification command:

```bash
# line ref verification
sed -n '50,60p' src/services/audio-player.ts

# symbol existence
grep -n "function pickNextTrack" src/services/next-track.ts

# count recount
grep -oc "#3e463f" src/styles.css

# status check
ls src/services/leaderboard.ts 2>&1

# verb enumeration
rg -oN 'data-action="([^"]+)"' src/ui/ | sort -u
```

## Quality Report format

Ships **before** any edit. Headline + per-file detail + decision request.

```markdown
## Agent Instructions Quality Report

### Summary

| Surface | Count | Avg score | Stale-ref count | Notes |
|---|---|---|---|---|
| `AGENTS.md` | 6 | 9.7/10 | 47 lines flagged | All evidence-grounded; line refs drifted post-refactor |
| `CLAUDE.md` symlinks | 6 | ✅ | — | All correct |
| `REVIEW.md` | 6 | 9.8/10 | 12 | Severity tags accurate |
| Gap folders | 1 | — | — | `functions/` lacks local AGENTS.md |
| Native adapters | 0 | — | — | None present |

### File-by-file

#### `src/services/AGENTS.md` (246 lines)
**Score: 8 / 10** (was 10/10 at last edit; drift since `<commit-sha>`)

Findings:
- L9 "wraps HTMLAudioElement" — **INCORRECT**: now Web Audio (`AudioContext` + `AudioBufferSourceNode`); class at L140
- L62 "playTrack (:49)" — **STALE**: actual L204
- L186-197 outbound HTTP enumeration — **MISSING**: media-cdn.ts, leaderboard-api.ts, profile-cloud.ts added since
- §11 "Zero AbortController in src/" — **INCORRECT**: now used in 4 files

Drift driver: refactor commits `<sha-1>`, `<sha-2>` since doc's last edit `<doc-sha>`.

#### `src/ui/AGENTS.md` (266 lines)
**Score: 7 / 10**

...

### Recommended scope

- **Fix this pass (high-impact):** invalidated rules, missing content, internal contradictions — `src/services/AGENTS.md` §3 + §11, `src/AGENTS.md` §2 frequency table.
- **Batch with surrounding edits (low):** stale line refs that don't change meaning.
- **Author new (gap folders):** `functions/AGENTS.md` + `functions/REVIEW.md`, patterned after `src/services/AGENTS.md`.

### Awaiting user
1. Approve scope above? [y/n/edit]
2. Generate native review adapters (Copilot/Devin/Greptile) after corrections? [list/none]
```

After the user confirms, dispatch the auditor agents with the scope.

## Driving audit scope from git churn

The under-used steering signal. Skip the whole-doc audit; focus where the code has actually moved.

```bash
# Doc's last edit timestamp
DOC=src/services/AGENTS.md
T=$(git log -1 --format=%ct -- "$DOC")

# Files referenced by the doc (line-ref patterns)
REFS=$(grep -oE '\b[\w./-]+\.[a-z]+(:[0-9]+)?' "$DOC" | awk -F: '{print $1}' | sort -u)

# Source files that have churned since the doc was last touched
for f in $REFS; do
  COUNT=$(git log --since="@$T" --oneline -- "$f" 2>/dev/null | wc -l)
  [ "$COUNT" -gt 0 ] && echo "$COUNT commits  $f"
done | sort -rn
```

Files at the top of that list are where the auditor focuses. Files with zero commits since the doc's edit are unlikely to have drifted line refs.

For a single doc: pair this with `wc -l` then-vs-now on the largest referenced files. If `styles.css` grew 2,679 → 5,138 lines since the doc's edit, every line ref in that doc is stale by definition — recompute, don't grep one-by-one.

## Recounting frequency tables

Any numbered table in a doc (color frequencies, font-size frequencies, gap frequencies, escapeHtml call counts) is auto-recountable.

```bash
# Color hex counts in styles.css
for HEX in '#3e463f' '#9da89a' '#d8e6cd' '#98c684' '#2a2f29' '#5e7d56'; do
  COUNT=$(grep -oc "$HEX" src/styles.css)
  echo "$HEX  $COUNT"
done

# font-size counts
for SIZE in 9 10 11 12 13 14 15 16 18 24 28 40; do
  COUNT=$(grep -c "font-size: ${SIZE}px" src/styles.css)
  echo "${SIZE}px  $COUNT"
done

# escapeHtml call counts per UI module
for f in src/ui/*.ts; do
  [ -f "$f" ] && echo "$(grep -c escapeHtml "$f")  $f"
done | sort -rn
```

Run the recount, write the new numbers into the table. Do **not** "estimate" updated counts — that's the entire point of recounting.

## Internal-consistency checks

Within a single doc:

- Manifest tables in §1 must agree with later prose in §N. If §1 says "atom" and §8 says "persistentAtom", pick the truth.
- "Stub" / "NOT YET LANDED" entries must agree with `ls`. If the file exists, it's not a stub.
- Numbered count claims in prose (`"There are 4 breakpoints"`) must agree with code (`rg "@media \(max-width:"`).

Across docs:

- A symbol cited in `src/services/AGENTS.md` and again in `src/services/REVIEW.md` must have the same `file:line` in both.
- `i18n.ts` line numbers cited in `src/services/AGENTS.md` and in `src/services/REVIEW.md` must agree.

The auditor reports cross-doc disagreements; the writer picks the right one and propagates.

## Stub-graduation sweep

A common drift pattern: docs marked "NOT YET LANDED" for files that have since shipped. Sweep:

```bash
# Find stub claims
rg -nC1 'NOT YET LANDED|not yet built|deferred|will appear when' src/**/*.md AGENTS.md

# For each cited file in those stubs, check existence
ls src/services/leaderboard.ts src/services/profile-cloud.ts src/services/feedback.ts
```

Files that exist: remove the stub line, add a proper row in the manifest table.

## Symbol-rename detection

If the auditor reports "symbol `foo` no longer exists at the cited line":

```bash
# Was foo renamed? Find the commit that removed it
git log -S 'function foo' --oneline -- src/services/<file>.ts | head -5

# Find what replaced it
git diff <pre-rename-sha>..<post-rename-sha> -- src/services/<file>.ts | head -40
```

Update the doc to the new symbol name + line.

## Companion symlink checks

After writer edits, verify:

```bash
for AGENTS in $(find . -name AGENTS.md -not -path './node_modules/*'); do
  DIR=$(dirname "$AGENTS")
  CLAUDE="$DIR/CLAUDE.md"
  if [ -L "$CLAUDE" ]; then
    TARGET=$(readlink "$CLAUDE")
    [ "$TARGET" = "AGENTS.md" ] && echo "OK  $CLAUDE" || echo "BAD-LINK  $CLAUDE -> $TARGET"
  elif [ -f "$CLAUDE" ]; then
    grep -q '^@AGENTS.md' "$CLAUDE" && echo "WRAPPER  $CLAUDE" || echo "DRIFTED  $CLAUDE (not a symlink, not a wrapper)"
  else
    echo "MISSING  $CLAUDE"
  fi
done
```

For new gap folders: create the symlink (`ln -s AGENTS.md CLAUDE.md`).

## Re-audit gate (Phase 5)

Before declaring done:

1. `bash scripts/audit-agents-md.sh` — confirm surface counts match Phase 0 (or +N for newly created gap files).
2. Run the falsifiable-claim verification on 2–3 of the auditor's highest-impact corrections. If the writer applied them correctly, the new ref/count/symbol passes its grep.
3. Confirm no new `[unverified]` markers were introduced without a matching open-question entry.

## What NOT to do

- Audit headlines only and miss prose claims.
- Score whole files when only specific sections drifted — score per-section if drift is uneven.
- Rewrite sections in update mode because they "could be clearer". Update preserves voice.
- Strip the audit's `[unverified]` markers without verifying — they exist because the auditor couldn't cheaply confirm.
- Add new sections to capture new code. New scope = a separate `init-agent-config` pass.

## Final rule

If the audit says a file is mostly correct, tighten only the drifted lines. The goal is fewer agent mistakes, not prettier diffs.

# Review Context

How to create `REVIEW.md` without turning it into a duplicate `AGENTS.md` file.

## Contents

- [Purpose](#purpose)
- [When To Create It](#when-to-create-it)
- [Root Review File](#root-review-file)
- [Scoped Review Files](#scoped-review-files)
- [Writing Rules](#writing-rules)
- [Relationship To Native Adapters](#relationship-to-native-adapters)

## Purpose

`REVIEW.md` standardizes what changes should be flagged, protected, or held to a higher bar during review.

Use it to capture:
- repo-specific diff risks
- high-risk architectural boundaries
- security, data, API, schema, or migration changes that need scrutiny
- review ignore rules for generated or irrelevant files
- testing expectations that reviewers should require for risky changes

Do not use it for:
- agent workflow instructions
- generic coding advice
- rules already enforced by lint, format, typecheck, or deterministic tests
- platform-native syntax for Copilot, Devin, or Greptile
- a second copy of `AGENTS.md`

## When To Create It

Default to a root `REVIEW.md` when the run is standardizing repository review context or when discovery finds review-critical risks worth encoding.

Document an explicit exception instead of creating `REVIEW.md` when:
- the user requested only AGENTS migration or companion entrypoints
- the repo has no shared review standard or risk model to encode yet
- an existing repository policy already provides the same review context and duplicating it would create drift

If you skip `REVIEW.md`, say why in the final response.

## Root Review File

The root file should answer:

`What kinds of changes should be flagged or scrutinized because they break this repo's intended standards or risk boundaries?`

Suggested section order:
- `## Critical Areas`
- `## Security`
- `## Conventions`
- `## Performance`
- `## Patterns`
- `## Ignore`
- `## Testing`

Only include sections backed by repo evidence. Prefer 5-10 strong review rules over a long checklist.

## Scoped Review Files

Use scoped `REVIEW.md` files only when a subtree has review risks that would bloat or contradict the root.

Good scoped triggers:
- a package owns public contracts or schemas
- a service has distinct auth, data, migration, or deployment risks
- a docs or skills subtree has standards that differ from application code
- generated code needs special ignore or regeneration review rules

Do not create scoped review files just because a folder has a local `AGENTS.md`. Most local `AGENTS.md` files do not need a matching `REVIEW.md`.

## Writing Rules

- Ground every rule in repo evidence.
- Make each rule specific, measurable, actionable, and semantic.
- Put highest-risk rules first.
- Skip anything already enforced by tooling unless reviewers need to verify the tooling was run.
- Keep operating instructions in `AGENTS.md`; keep diff scrutiny in `REVIEW.md`.
- If review drafting exposes a missing work boundary, update the relevant `AGENTS.md` instead of stuffing workflow guidance into `REVIEW.md`.
- Preserve existing review warnings unless the repo proves they are stale.
- Keep unresolved unknowns in the response, not in the file.

## Relationship To Native Adapters

Native review adapters are translations of completed review context, not independent policy files.

| Platform | Native files | Relationship to `REVIEW.md` |
|----------|--------------|-----------------------------|
| Copilot | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | Translate root and scoped review criteria into Copilot-compatible files |
| Devin | `REVIEW.md`, optional scoped `REVIEW.md` | Treat `REVIEW.md` as the main Bug Catcher review surface |
| Greptile | `.greptile/config.json`, optional `rules.md`, `files.json` | Translate review criteria into config plus prose/context files |

Ask about native adapters only after the AGENTS hierarchy and review-context decision are complete.

#!/bin/sh
set -eu

usage() {
  cat <<'EOF'
Usage: audit-agents-md.sh [repo-root]

Read-only audit of AGENTS-first instruction surfaces in a repository.
Defaults to the current directory.
EOF
}

case "${1:-}" in
  -h|--help)
    usage
    exit 0
    ;;
esac

root=${1:-.}
if [ ! -d "$root" ]; then
  echo "error: repo root is not a directory: $root" >&2
  exit 2
fi

cd "$root"

find_pruned() {
  find . \( -path './.git' -o -path '*/.claude/worktrees' -o -name 'node_modules' -o -name '.venv' -o -name 'venv' -o -name 'vendor' -o -name '__pycache__' -o -name 'dist' -o -name 'target' -o -name 'DerivedData' -o -name 'Pods' \) -prune -o "$@" -print | sort
}

# Source files under a directory, with build/dependency noise pruned.
# Extend the extension list rather than removing prunes.
src_find() {
  find "$1" \( -path '*/.*' -o -name 'node_modules' -o -name '.venv' -o -name 'venv' -o -name 'vendor' -o -name '__pycache__' -o -name 'dist' -o -name 'build' -o -name 'out' -o -name 'target' -o -name 'coverage' -o -name 'DerivedData' -o -name 'Pods' \) -prune -o -type f \( \
    -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.mjs' -o -name '*.cjs' \
    -o -name '*.py' -o -name '*.rs' -o -name '*.go' -o -name '*.swift' -o -name '*.kt' -o -name '*.java' \
    -o -name '*.rb' -o -name '*.php' -o -name '*.c' -o -name '*.h' -o -name '*.cpp' -o -name '*.hpp' \
    -o -name '*.cs' -o -name '*.m' -o -name '*.mm' -o -name '*.vue' -o -name '*.svelte' -o -name '*.sql' \
  \) -print
}

print_section() {
  printf '\n## %s\n' "$1"
}

print_line_count() {
  file=$1
  if [ -f "$file" ] || [ -L "$file" ]; then
    count=$(wc -l < "$file" 2>/dev/null || printf '?')
    printf '%7s  %s\n' "$count" "$file"
  fi
}

classify_claude() {
  file=$1
  if [ -L "$file" ]; then
    target=$(ls -ld "$file" | sed 's/.* -> //')
    printf 'symlink -> %s' "$target"
    return
  fi

  first=$(sed -n '/[^[:space:]]/{s/^[[:space:]]*//;s/[[:space:]]*$//;p;q;}' "$file" 2>/dev/null || true)
  case "$first" in
    '@AGENTS.md'|'@./AGENTS.md'|'@../AGENTS.md'|'See AGENTS.md'*|'See `AGENTS.md`'*)
      printf 'wrapper'
      ;;
    *)
      nonblank=$(grep -c '[^[:space:]]' "$file" 2>/dev/null || printf '0')
      if [ "$nonblank" -le 5 ] && grep -Eq 'AGENTS\.md' "$file" 2>/dev/null; then
        printf 'wrapper'
      else
        printf 'independent'
      fi
      ;;
  esac
}

agents=$(find_pruned -name 'AGENTS.md')
claudes=$(find_pruned -name 'CLAUDE.md')
reviews=$(find_pruned -name 'REVIEW.md')

echo "# AGENTS.md Instruction Surface Audit"
printf 'Repo: %s\n' "$(pwd)"

print_section "AGENTS.md files"
if [ -n "$agents" ]; then
  printf '%s\n' "$agents"
else
  echo "none"
fi

print_section "CLAUDE.md files"
if [ -n "$claudes" ]; then
  printf '%s\n' "$claudes" | while IFS= read -r file; do
    printf '%s  [%s]\n' "$file" "$(classify_claude "$file")"
  done
else
  echo "none"
fi

print_section "REVIEW.md files"
if [ -n "$reviews" ]; then
  printf '%s\n' "$reviews"
else
  echo "none"
fi

print_section "Native surfaces"
for path in \
  './.claude' \
  './GEMINI.md' \
  './.cursor' \
  './.cursorrules' \
  './.github/copilot-instructions.md' \
  './.github/instructions' \
  './.greptile' \
  './greptile.json'
do
  if [ -e "$path" ] || [ -L "$path" ]; then
    echo "$path"
  fi
done

print_section "Line counts"
{
  printf '%s\n' "$agents"
  printf '%s\n' "$claudes"
  printf '%s\n' "$reviews"
  find_pruned -name 'GEMINI.md'
  find_pruned -name '.cursorrules'
  find_pruned -path './.github/copilot-instructions.md'
  find_pruned -path './greptile.json'
} | sed '/^$/d' | sort -u | while IFS= read -r file; do
  print_line_count "$file"
done

print_section "Folder coverage map"
echo "Code-bearing directories (depth <= 2) vs. their nearest own AGENTS.md."
echo "src-files/LOC counted recursively with build+dependency noise pruned."
printf '%-40s %9s %9s  %s\n' "DIRECTORY" "SRC-FILES" "SRC-LOC" "AGENTS.md"
coverage_dirs=$( { echo .; find . -mindepth 1 -maxdepth 2 -type d \
  ! -name '.*' ! -path './.*' ! -path '*/.*' \
  ! -name 'node_modules' ! -name 'vendor' ! -name 'venv' ! -name '__pycache__' \
  ! -name 'dist' ! -name 'build' ! -name 'out' ! -name 'target' ! -name 'coverage' \
  ! -name 'DerivedData' ! -name 'Pods' ! -name 'docs' ! -name 'doc' \
  ! -name 'assets' ! -name 'images' ! -name 'public' ! -name 'static' ! -name 'fixtures'; } | sort)
printf '%s\n' "$coverage_dirs" | while IFS= read -r dir; do
  [ -d "$dir" ] || continue
  files=$(src_find "$dir" | wc -l | tr -d ' ')
  [ "$files" -eq 0 ] && continue
  loc=$(src_find "$dir" | tr '\n' '\0' | xargs -0 cat 2>/dev/null | wc -l | tr -d ' ')
  if [ -f "$dir/AGENTS.md" ]; then
    marker="yes ($(wc -l < "$dir/AGENTS.md" | tr -d ' ') lines)"
  else
    marker="—"
  fi
  printf '%-40s %9s %9s  %s\n' "$dir" "$files" "$loc" "$marker"
done

print_section "Likely stale duplicate source-of-truth risks"
risk=0

if [ -n "$claudes" ]; then
  old_ifs=$IFS
  IFS='
'
  for file in $claudes; do
    kind=$(classify_claude "$file")
    dir=$(dirname "$file")
    if [ "$kind" = "independent" ] && [ -e "$dir/AGENTS.md" ]; then
      printf 'risk: %s is independent beside %s/AGENTS.md\n' "$file" "$dir"
      risk=1
    fi
  done
  IFS=$old_ifs
fi

for native in './.github/copilot-instructions.md' './.github/instructions' './.greptile' './greptile.json'; do
  if [ -e "$native" ] && [ -z "$reviews" ]; then
    printf 'check: %s exists without REVIEW.md; add shared review context only if review standards are in scope, otherwise document the skip reason\n' "$native"
    risk=1
  fi
done

if [ -z "$agents" ] && { [ -n "$claudes" ] || [ -e './.cursorrules' ] || [ -e './GEMINI.md' ]; }; then
  echo "risk: native instruction files exist without AGENTS.md as shared source of truth"
  risk=1
fi

independent_count=0
if [ -n "$claudes" ]; then
  independent_count=$(printf '%s\n' "$claudes" | while IFS= read -r file; do classify_claude "$file"; echo; done | grep -c '^independent$' || true)
fi

if [ "$independent_count" -gt 1 ]; then
  printf 'risk: %s independent CLAUDE.md files may drift from AGENTS.md\n' "$independent_count"
  risk=1
fi

if [ "$risk" -eq 0 ]; then
  echo "none detected by heuristic checks"
fi

# audit-agents-md.sh

Read-only audit for AGENTS-first repository instruction surfaces.

## Usage

```bash
sh scripts/audit-agents-md.sh [repo-root]
```

Run it during the initial audit before editing existing instruction files. It defaults to the current directory.

## Reports

- root and nested `AGENTS.md`
- root and nested `CLAUDE.md`
- whether `CLAUDE.md` files are symlinks, wrappers, or independent files
- root and nested `REVIEW.md`
- common native surfaces: `.claude/`, `GEMINI.md`, `.cursor/`, `.cursorrules`, Copilot, and Greptile files
- line counts for discovered instruction files
- **folder coverage map**: every code-bearing directory (depth ≤ 2) with recursive source-file
  count, source LOC, and its own `AGENTS.md` status + line count — the gap-detection input.
  Source counting prunes dot-directories, dependency dirs (`node_modules`, venvs, `vendor`,
  `Pods`), and build output (`dist`, `build`, `out`, `target`, `coverage`, `DerivedData`), and
  matches common source extensions only. A folder showing `—` is a gap *candidate*, not a
  mandate — the skill's invariant-density test decides.
- likely stale duplicate source-of-truth risks

Wrapper detection treats symlinks, direct `@AGENTS.md` wrappers, and very small files that point to `AGENTS.md` as companions. Larger files that mention `AGENTS.md` are still reported as independent so they can be inspected for drift.

## Safety

The script does not write files, delete files, change git state, or follow any workflow beyond filesystem inspection.

---
name: update-agent-config
description: "Use if auditing AGENTS.md/CLAUDE.md/REVIEW.md for drift after refactors — stale refs, rules."
disable-model-invocation: true
---

# Update Agent Config

Refresh a **mature** AGENTS.md hierarchy that has drifted from current code. Audit first, in evidence. Then dispatch parallel writers fed by the audit. Add files only for code-bearing folders that genuinely lack one. Preserve voice, structure, length — patch, do not rewrite.

This skill assumes the AGENTS hierarchy already exists. For greenfield creation of root + folder AGENTS.md files, route to `init-agent-config`.

## When to use

- *"audit our AGENTS.md / CLAUDE.md / REVIEW.md files"*
- *"the AGENTS docs are stale after the recent refactor — refresh them"*
- *"verify every `file:line` reference in `src/AGENTS.md` is correct"*
- *"recompute the color / font-size / spacing frequency tables in `src/AGENTS.md`"*
- *"the doc claims X but the code now says Y — sweep the drift across all docs"*
- *"find every code folder without an `AGENTS.md` and write one"* (expect mostly skips — see Phase 0 selection test)
- *"show me which folders have AGENTS.md coverage and how big each file is"*
- *"the schema version changed; sweep all docs that quote the old literal"*
- *"docs marked `NOT YET LANDED` for files that now exist — fix the manifest tables"*

## Do NOT use for

- **Greenfield setup** (root + folder AGENTS.md from scratch) → use `init-agent-config`
- **PR review** → use `run-review` Mode A
- **Skill creation/maintenance** → use `build-skill`
- **One-off doc fix** where the audit overhead doesn't pay off (e.g., correct a single typo)
- **Native review adapter generation** (Copilot/Devin/Greptile) when AGENTS is already accurate — the existing `init-agent-config` Step 12 covers that

## File responsibilities (same contract as init)

| Surface | Purpose | Update-mode concern |
|---|---|---|
| `AGENTS.md` | How agents should work, where code lives, what local boundaries exist | Refresh refs, recount tables, drop "NOT YET LANDED" stubs that landed |
| `CLAUDE.md` | Compatibility companion symlink → `AGENTS.md` | Verify symlink integrity; create for new gap folders |
| `REVIEW.md` | What diffs should be flagged, protected, or held to a higher bar | Update severity refs; drop trigger phrases for rules that became false |
| Folder `AGENTS.md` | Local delta only — never restate root | Same; add for newly-discovered code-bearing folders |

## Non-negotiables

Hard guardrails — read every run.

1. **Audit before editing.** Always. The Quality Report ships before any Edit/Write call.
2. **Falsifiable claims only.** Every statement that names `file:line`, a function/symbol/CLI flag, or a count is verified by `grep -n` / `sed -n` / `wc -l` against current HEAD before correction. Drift is a fact, not a guess.
3. **Parallel Opus auditors then parallel Opus writers.** Two phases, hard boundary. Auditors do not edit; writers do not re-audit (they trust their brief).
4. **Preserve voice, structure, length.** Patch in place. Don't rewrite a 313-line file into 280 lines because the new wording is "cleaner". The goal is accurate, not prettier.
5. **Internal consistency.** When fixing §1, check §8 doesn't contradict. When the manifest table says "Y is a stub", check the prose later doesn't already describe Y as landed.
6. **Gap folders get new files patterned after the closest sibling.** No greenfield template. The closest sibling `AGENTS.md` is the model — its tone, density, and section structure transfer.
7. **Companion `CLAUDE.md` symlinks intact.** Verify post-edit. Create for new gap folders. Fallback to `@AGENTS.md` wrapper only when symlinks are forbidden — call it out.
8. **Re-audit before declaring done.** `scripts/audit-agents-md.sh` runs once before edits and once after. Diff the surface counts.
9. **No new sections without 3+ repo-specific facts.** Updating ≠ expanding. If a section is missing because the code is missing, leave it missing.

## Anti-derail guardrails

| Derail | Correction |
|---|---|
| Editing the doc before the audit completes | Audit-first is the contract; the Quality Report ships first |
| Rewriting from memory ("I recall the file changed") | Always re-grep / re-sed; cite line numbers from the actual file |
| Auditor agent also edits | Auditors produce findings only; writers act |
| Writer agent re-runs the audit | Writers trust the brief; re-grep only for the specific recount they're applying |
| Frequency tables left untouched because "they're roughly right" | Recount every numbered table via grep — the cascade of additions silently shifts counts |
| "NOT YET LANDED" stub claims left in place | `ls` the alleged-missing files; if they exist, document them and remove the stub line |
| Internal contradictions silently surviving (§1 row vs §8 prose) | Cross-check the rule in §N against every later reference to the same symbol/file |
| Voice rewrite ("I made it more readable") | Patch in place; if you can't make a surgical edit, the change isn't ready |
| Auditing only headlines, missing prose claims | Every paragraph with a `file.ext:line` token is in scope |
| Adding new sections during update | Update mode only — new content goes to a separate `init-agent-config` pass |
| One AGENTS.md per directory ("coverage looks thorough") | Most folders are skips; a file needs invariants, not just code. 2–4 new files per pass is healthy |
| Paging through build noise in the tree scan | Use treezip (or prune by hand), find where real source resumes, read that — never script around it |
| Verifying claims inside a stale worktree / vendored copy | Resolve every path against the repo's live source tree before grepping |

## Scripts

Resolve script paths relative to this skill directory.

| Script | Use when | Mutates |
|---|---|---|
| `scripts/audit-agents-md.sh` | Phase 0 inventory + post-edit re-audit: existing surfaces, line counts, companion symlink status, folder coverage map (src-files / LOC / AGENTS.md per code folder), duplicate-source risk. See `scripts/audit-agents-md.sh.md`. | No |

The init-only `scaffold-agents-md.sh` was dropped — update-mode never emits greenfield skeletons.

## The Five Phases

```
mature AGENTS hierarchy with drift after code churn
                            │
       Phase 0 — Scan + Gap detection + Last-edit churn signal
                            │
       Phase 1 — Quality Report (BEFORE any edit; ask user)
                            │
       Phase 2 — Parallel Opus auditor dispatch (falsifiable claims)
                            │
       Phase 3 — Triage findings + scope confirmation
                            │
       Phase 4 — Parallel Opus writer dispatch (patch in place + author gap files)
                            │
       Phase 5 — Post-edit re-audit + commit + push
                            │
                   refreshed hierarchy
```

Each phase has a gate. Do not skip forward. See `references/audit-and-update.md` for the per-phase detail and Quality Report format.

### Phase 0 — Scan + Gap detection + Churn signal

Three reads, no writes:

1. **Existing surfaces + coverage map.** `bash scripts/audit-agents-md.sh` from the repo root — lists every `AGENTS.md`, `CLAUDE.md` (with symlink target), `REVIEW.md`, native adapter, current line counts, **and a folder coverage map**: each code-bearing directory (depth ≤ 2) with its source-file count, source LOC, and whether it has its own `AGENTS.md` (with line count). This table is the gap-detection input — read it, don't recompute it by hand.
2. **Tree scan.** Prefer `treezip .` (compressed, AI-readable tree; `npm i -g treezip`) over raw `tree` — it brace-groups siblings and hardcodes an aggressive noise filter (VCS dirs, `node_modules`, venvs, caches, `DerivedData`, worktrees under `.claude/`), so the structure fits in context without hand-filtering. Fall back to `tree -dL 2 .` (`-dL 3` for monorepos) when treezip isn't installed. Either way, **budget the read**: if the output is dominated by one noisy subtree (vendored deps, build products, checked-in worktrees), locate where the real source tree resumes and read that section — never page through build noise, and never write a one-off script to parse the tree.
3. **Gap folders — select, don't enumerate.** From the coverage map, a folder is a gap **candidate** only when all of these hold:
   - **Code-bearing:** it has real source files (the map's SRC-FILES column), not just data, assets, generated output, or planning artifacts.
   - **Substantial:** rough floor ~10 source files or ~1,500 LOC. Below that, a folder earns a file only if it holds a genuinely dangerous invariant.
   - **Invariant-dense:** it owns rules an agent can't infer from the code — protocol facts, ordering contracts, "never do X" traps, local test gotchas. A folder of conventional glue (small utility helpers, thin view wrappers, generated bindings, test scaffolding) gets **no file no matter its size** — the root doc plus code reading covers it.
   - **Not already covered:** its nearest ancestor `AGENTS.md` doesn't already carry the folder's rules. Prefer one file at the subsystem root (e.g. `src/transcription/`) over one per leaf (`cloud/`, `engine/`, `streaming/`).

   Expect to **skip most folders.** A healthy pass on a mid-size repo adds 2–4 folder files, not one per directory. In the Quality Report, list skipped candidates with a one-line reason each ("conventional UI code", "covered by root") so the user can veto.
4. **Churn signal — the steering trick.** For each existing doc, get its last edit timestamp:
   ```bash
   git log -1 --format=%ct -- <doc>
   ```
   Then for the source files that doc references (anything matching `\b[\w./-]+\.[a-z]+:\d+\b` in the doc), list commits since that timestamp:
   ```bash
   git log --since=<timestamp> --oneline -- <referenced-file>
   ```
   **This is the audit scope.** If the doc was last touched at `T` and `styles.css` has had 12 commits since `T`, that file's line refs and counts are guaranteed stale. Drive auditor focus there. Files with zero churn since the doc's last edit can be lower-priority.

### Phase 1 — Quality Report (BEFORE editing)

Output the report — no edits yet. Format in `references/audit-and-update.md`. Headline rows:

| Surface | Count | Avg score | Stale-ref count | Notes |
|---|---|---|---|---|
| `AGENTS.md` | N | X/10 | M lines flagged | … |
| `CLAUDE.md` symlinks | N | ✅ / ⚠ | — | … |
| `REVIEW.md` | N | X/10 | M | … |
| Gap folders | N | — | — | List |
| Native adapters | N | — | — | List |

Then the **coverage table** — every code-bearing folder from the Phase 0 map, so the user sees what exists, how big it is, and what you propose:

| Folder | Src files | Src LOC | AGENTS.md | Decision |
|---|---|---|---|---|
| `src/api/` | 41 | 7,200 | yes (65 lines) | audit for drift |
| `src/transcription/` | 29 | 4,800 | — | **author** (invariant-dense) |
| `src/components/` | 76 | 13,000 | — | skip: conventional UI, covered by root |
| `src/utils/` | 8 | 400 | — | skip: small utility folder |

Every skipped row carries its one-line reason. Per-file: score + 5-line summary of what's drifted (line refs / invalidated rules / missing content / internal contradictions). Then ask the user:

1. Which files to fix (default: all flagged as drift > 0)
2. Which gap folders to fill (default: code-bearing ones only)
3. Skip the post-edit native-adapter regeneration unless explicitly requested

### Phase 2 — Parallel Opus auditor dispatch

After user confirms scope. Dispatch **3–5 parallel Opus agents**, one per logical group of files. Sample grouping for a typical repo:

- Auditor A: root `AGENTS.md` + `REVIEW.md` + `scripts/AGENTS.md` + `scripts/REVIEW.md` (orchestration + pipeline)
- Auditor B: `src/AGENTS.md` + `src/REVIEW.md` (design system / styles)
- Auditor C: `src/services/AGENTS.md` + `src/stores/AGENTS.md` + their `REVIEW.md` (TypeScript code refs)
- Auditor D: `src/ui/AGENTS.md` + `src/ui/REVIEW.md` (UI module contract)

Each auditor follows the **falsifiable-claim discipline** — see `references/agent-dispatch.md` Auditor section. They:

- Quote each statement that names `file:line` / symbol / count
- Verify with `grep -n` / `sed -n` / `wc -l` / `ls`
- Report **VERIFIED ✓** / **STALE: <actual>** / **INCORRECT: <reality>** / **UNVERIFIED: <reason>**
- Do **not** edit. They return a findings list only.

Use the churn signal from Phase 0 to focus their attention.

### Phase 3 — Triage findings

Classify the returned findings:

- **High impact** — rule is now wrong (e.g., "every `$playback.set` must live in audio-player.ts" is no longer true). These are dangerous; future agents will misroute work.
- **Medium impact** — content missing (new files, new exports, new verbs not in the manifest). Future agents won't know about features.
- **Low impact** — line numbers shifted but semantic content correct. Cosmetic; batch these.
- **Internal contradiction** — same doc says X in §1 and not-X in §8. Pick the truth, propagate.

Decide which to fix this pass vs. defer. Default: fix high + medium; fix low only in surrounding edits.

### Phase 4 — Parallel Opus writer dispatch

Dispatch **3–5 parallel Opus writers** with the same grouping. Each writer gets:

- Target file paths
- The auditor's findings list for that group
- Instructions to **preserve voice, structure, length** (see Non-negotiable #4)
- Permission to re-grep for recounts (frequency tables) but not re-audit
- For gap folders: pattern after the closest sibling `AGENTS.md` (cite which one)

Each writer applies Edit calls in place. They do **not** add new sections. They report which paths they touched and a 3-line summary per file. See `references/agent-dispatch.md` Writer section.

### Phase 5 — Post-edit re-audit + commit + push

1. Re-run `bash scripts/audit-agents-md.sh` — diff against the Phase 0 snapshot. Surface counts should match (or +N for gap folders newly created). No new orphan symlinks.
2. Spot-check 2–3 high-impact corrections via grep — confirm the new ref points where the doc claims.
3. Commit. One commit per concern:
   - `docs(agents): refresh stale refs + counts after <churn-event>`
   - `docs(<folder>): add AGENTS.md + REVIEW.md` (separate commit per gap folder if substantial)
4. Push. Watch CI (typecheck on docs is no-op; the push exists to land the refresh).

## Creative steering signals

These are the under-used patterns. Reach for them when the audit feels generic.

- **`git log` since doc's last edit** (Phase 0) — drives scope toward files that have actually churned. Don't audit the whole tree blindly; audit where the diff is.
- **File-size delta as drift proxy.** If a referenced file grew 2× since the doc's last edit (e.g., `styles.css` 2,679 → 5,138 lines), every line ref is stale by definition.
- **`ls` against "NOT YET LANDED" stubs.** A doc's stub-table is a falsifiable claim too. `ls` each alleged-missing file; if it exists, the stub is wrong.
- **Frequency-table auto-recount.** Every numbered table in the doc (colors, font-sizes, spacing, escape-html call counts) is recountable via `grep -c`. Recount before correcting.
- **Cross-doc consistency.** If two docs independently cite the same symbol's location, both must agree. A pre-edit grep finds the surviving stale one.
- **Symbol rename detector.** If the auditor finds "function `foo` no longer exists at the cited line", run `git log -S 'foo' -- <file>` to find the rename commit. Update to the new name.
- **Stub-graduation sweep.** Any line containing "NOT YET LANDED" / "not yet built" / "deferred" is a candidate for an `ls`-based audit.
- **Test-file existence cross-check.** Manifest tables that claim "Tests: none" can be falsified by `ls <module>.test.*`.
- **Coverage-map thresholds as a conversation, not a law.** The ~10-file / ~1,500-LOC floor filters candidates; the invariant-density test decides. A 4-file folder holding a wire protocol earns a file; a 40-file folder of CRUD forms doesn't.
- **Mine merged-PR descriptions and review findings for gap-file content.** The invariants worth writing down usually surfaced somewhere: adversarial review rounds, PR descriptions, fix commits (`git log --grep=fix -- <folder>`). Verify each against HEAD before encoding it — a review finding may have been fixed differently than described.

## Reference routing

Read the smallest reference set that unblocks the current decision.

| Need | Reference |
|---|---|
| Quality Report format, drift categories, post-edit verification, falsifiable-claim discipline | `references/audit-and-update.md` |
| Auditor + writer prompt scaffolds (parallel-Opus dispatch) | `references/agent-dispatch.md` |
| AGENTS authoring, folder scoping, WHAT/WHY/HOW filter (applies to in-place edits too) | `references/agents-md-format.md` |
| Companion `CLAUDE.md` symlinks, native review adapter rules, cross-agent surfaces | `references/agent-entrypoints.md` |
| `REVIEW.md` purpose, root/scoped split, severity tagging | `references/review-context.md` |

### Quick-start mapping

| Situation | Start with | Then read |
|---|---|---|
| Big refactor just landed; sweep all docs | `references/audit-and-update.md` | `references/agent-dispatch.md` |
| Just need to refresh frequency tables | `references/audit-and-update.md` (recount section) | — |
| Add AGENTS.md for newly-discovered code folder | `references/agents-md-format.md` | `references/agent-entrypoints.md` |
| REVIEW.md needs severity refresh after rule changes | `references/review-context.md` | `references/audit-and-update.md` |

## Final output expectations

When you finish a run, return:

1. **Phase 0 scan** — surface counts before and after; gap folders identified
2. **Quality Report** — pre-edit, with per-file scores and drift findings
3. **Triage decision** — which findings landed this pass, which deferred
4. **Files edited + files authored** — explicit list with line-count deltas
5. **Companion symlink status** — verified intact; new ones for gap folders
6. **Re-audit diff** — Phase 5 output vs Phase 0
7. **Commits + push state** — commit SHAs, CI status
8. **Unresolved unknowns** — `[unverified]` markers left in place, why