[r3dbars]

Standardizes on AGENTS.md as the only agent-doc filename.

Native support: yes

• Installed Claude Code is 2.1.287. The memory docs (code.claude.com/docs/en/memory, "AGENTS.md" section) say Claude Code reads AGENTS.md directly from v2.1.277 on, at launch for the working dir and above, and lazily for a subdirectory when Claude reads a file there. Same as nested CLAUDE.md.
• Catch: by default it only reads AGENTS.md when there's no CLAUDE.md or CLAUDE.local.md in the working dir or above. So a stray CLAUDE.md makes the AGENTS.md next to it silently disappear. That's why the new check exists.
• Sessions that can't read it: versions before 2.1.277, the built-in agents-md plugin turned off, and sometimes the first session right after upgrading from 2.1.276 or older. Before 2.1.281 some Bedrock and telemetry-off sessions couldn't either. In any of those, add a local one-line @AGENTS.md stub. The check allows that.
• Worktrees under .claude/worktrees/ sit inside the main checkout. If the main checkout is on an old branch that still has the root CLAUDE.md, worktree sessions pick up that parent file. Pull main in the main checkout after this lands.

So I deleted every CLAUDE.md instead of leaving stubs.

What changed

• git mv of all 18 Sources/**/CLAUDE.md and Tools/*/CLAUDE.md to AGENTS.md in the same folder. Content didn't change except reference fixes. Root CLAUDE.md (just the @AGENTS.md import) is deleted.
• scripts/dev/check-known-traps.py: new agent-docs check plus self-test. It fails on any CLAUDE.md that isn't a bare @AGENTS.md stub, or on a stub with no AGENTS.md next to it. Set CLAUDE_STUBS_REQUIRED = True and it also fails when a folder with an AGENTS.md has no stub. It already runs in linux-checks.sh, so it's part of check.sh quick.
• References: agent-context.py (nearest-guide lookup and self-test), check-doc-paths.py (budget and self-test), agent-preflight.sh, .agents/test-matrix.yml, .agents/agent-contract.json, the root Package.swift and build-deps.sh TranscriptedCore excludes, deps-staleness.sh and build-beta.sh (they now skip AGENTS.md as well as CLAUDE.md), root AGENTS.md, docs/**, Tools/README.md, .claude/agents/*.md, the PR template, and doc pointers in Swift comments.
• Not touched: product code that skips CLAUDE.md / AGENT.md in users' capture folders (scanners, the QA validator, and their tests). That's user-folder behavior, not repo docs. I also left CHANGELOG.md alone because it's history.

Overlap

• Notch island is the only dictation window #1946 edits Sources/Support/CLAUDE.md and Sources/UI/CLAUDE.md. Keep runtime heartbeat preference reads off the main thread #1941 edits Sources/Observability/CLAUDE.md. Git rename detection should carry their edits over to the new paths, but let CI check the merged result. Whichever lands second should check that no CLAUDE.md came back (the check will fail if one did).
• Transcripted Live: your meeting, live in Claude Code (mod + bundled helper) #1945 touches .agents/test-matrix.yml and build-beta.sh, but in hunks that don't overlap with these.

Checks

• python3 scripts/dev/agent-context.py Sources/Meeting/MeetingSessionController.swift lists AGENTS.md and Sources/Meeting/AGENTS.md
• bash check.sh quick: PASS (60/60)
• python3 scripts/dev/check-known-traps.py --self-test and check-doc-paths.py --self-test: pass
• python3 scripts/dev/check-source-pins.py --changed-only: pass
• bash build-deps.sh --force + swift build (root package; Package.swift touched): pass
• Not run: build.sh / run-tests.sh. The only Swift edits are comments.
• Independent review: not done yet.

🤖 Generated with Claude Code

[r3dbars]

Review verdict on 9615ec2: nothing blocking. No runtime change (Swift edits are comments only), build excludes follow the rename, product code that skips CLAUDE.md in capture folders is untouched, commit credit is right.

Two low findings, both real, both fixed in b4283e6:

1. Fixed. A CLAUDE.local.md would hide AGENTS.md and nothing caught it, and .gitignore still called it the place for personal notes. check_agent_docs now fails on a CLAUDE.local.md anywhere on disk (it's gitignored, so disk is the only place it lives), and the .gitignore comment says not to create one. The ignore line stays so it never gets committed.
2. Fixed. The check walked every file on disk, so an untracked or vendored CLAUDE.md could fail a local run that CI passes. CLAUDE.md/AGENTS.md now come from git ls-files. It falls back to walking only when the root isn't a git toplevel (the self-test temp dirs). Known gap, accepted: an untracked root stub is no longer checked for a sibling AGENTS.md.

While fixing this, check.sh quick caught a real snag: linux-checks.sh points TMPDIR inside the repo, so a temp dir looked like part of the outer checkout. That's why the toplevel comparison is there. The self-test now covers both paths plus CLAUDE.local.md.

Checks on b4283e6: check-known-traps.py and --self-test (also with TMPDIR under build/), check-doc-paths.py, agent-context.py --self-test, bash check.sh quick (60 passed). Spot checks: an untracked Tools/CLAUDE.md with content passes, and a root CLAUDE.local.md fails.

🤖 Generated with Claude Code