---
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.