49 lines
3.1 KiB
Markdown
49 lines
3.1 KiB
Markdown
---
|
|
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.
|