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)

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

Scripts

Resolve script paths relative to this skill directory.

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:

   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:

   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:

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:

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.

Quick-start mapping

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