3.1 KiB
id, title, theme, status, created, date_source, order
| id | title | theme | status | created | date_source | order |
|---|---|---|---|---|---|---|
| docs-conventions/sweep-agents-md-primary-claude-md-pointer | Sweep: AGENTS.md becomes the real instructions everywhere, CLAUDE.md a pointer beside it | docs-conventions | open | 2026-08-25 | stated | 1 |
AGENTS.md becomes the main instruction file everywhere, with a CLAUDE.md beside it that just references it — not the other way round, which is how it is today. Wanted 2026-08-25. A full sweep across the platform and every plugin repo.
The root pairing exists already, backwards. platform/AGENTS.md is five lines: "The instructions
live in CLAUDE.md. Read it first — this file only points there." CLAUDE.md is the real, long
document. That is the exact inverse of what is wanted, and it is the clearest single example of the
sweep: swap which file holds the content and which file points, keep both present so either harness's
auto-discovery convention finds the same guidance — which is the reasoning the current file already
states, just applied backwards.
Four subdirectory CLAUDE.md files carry real, substantial documentation and have no AGENTS.md at
all — found 2026-08-25, none of these have a pair to flip, they need one created:
platform/src/apps/CLAUDE.md (271 lines), platform/src/databases/CLAUDE.md (231 lines),
platform/themes/CLAUDE.md (118 lines), platform/plugins/CLAUDE.md (92 lines).
Every plugin repo has NEITHER file — 19 of 19, checked 2026-08-25. atelier, bitcoin-wallet,
browser, desktop, email, example, gitea, invoices, iris, jellyfin, kiosk,
minesweeper, music, offscale, photos, proxy-manager, soulseek, transcribe, transmission,
vault — none has a CLAUDE.md or an AGENTS.md. This is not a swap for plugins, it is adding the
convention where it does not exist yet. PLUGIN.md, present in most of them, is a different document
and stays untouched — it is the plugin's own manifest/reference doc (conventions, API surface), not
agent guidance; do not conflate the two when sweeping.
Two lookalikes are NOT documentation and are out of scope for this sweep — converting them would be wrong, not just unnecessary:
- Per-commander
CLAUDE.mdfiles (data/pastilhas@officer.dev/commanders/<id>/CLAUDE.md) are a single commander's own standing brief — operational state for one running agent, not source-tree documentation nobody discovers it by directory convention the way a coding CLI does at a repo root. plugins/proxy-manager/chat/CLAUDE.mdcarries its own warning: "rewritten from the plugin on every chat that starts here, so an edit would be lost." Generated per session, not read by directory convention either — injected directly into that chat's context by the plugin's own code.
Note atelier-work/ is a separate checkout carrying its own copies of the root, themes/,
plugins/, src/apps/ and src/databases/ CLAUDE.md/AGENTS.md files — apparently a working
clone related to the Atelier extraction. Worth checking whether it is still live before sweeping it
twice; if it is a stale branch, the sweep only needs to happen once, in the platform repo.