todo: sweep AGENTS.md/CLAUDE.md so AGENTS.md is primary everywhere

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-25 19:24:17 +00:00
parent 9a3b5dd649
commit 9f2b703b4b
3 changed files with 95 additions and 37 deletions
@@ -0,0 +1,8 @@
+---
+theme: docs-conventions
+heading: 'Documentation conventions — AGENTS.md vs CLAUDE.md'
+kind: theme
+---
+
+Which file is the real instructions and which is the pointer, kept consistent across the platform repo,
+its subdirectories, and every plugin repo.
@@ -0,0 +1,48 @@
+---
+id: docs-conventions/sweep-agents-md-primary-claude-md-pointer
+title: 'Sweep: AGENTS.md becomes the real instructions everywhere, CLAUDE.md a pointer beside it'
+theme: docs-conventions
+status: open
+created: 2026-08-25
+date_source: stated
+order: 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.md` files** (`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.md`** carries 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.