---
id: docs-conventions/agents-md-remaining
title: 'AGENTS.md sweep — what is left after the static docs landed'
theme: docs-conventions
status: open
created: 2026-08-27
date_source: stated
order: 2
---

**The five platform doc pairs are done** (`2360a3ef`, corrected by `a865bcfd`). AGENTS.md holds the
content, CLAUDE.md points at it, `docs:check` reads AGENTS.md. Verified byte-identical per pair.

What is not done, in the order it costs:

## 1. Runtime writers still produce CLAUDE.md only — this one is BROKEN, not untidy

opencode discovers `AGENTS.md` and nothing else. Verified in the binary:
`H.up({targets:["AGENTS.md"], start, stop})` is its sole target. So every brief the platform writes at
runtime is **unread** when the session is opencode — the agent is not misconfigured, it simply knows
nothing, and nothing reports it.

| writer | file it writes | who is briefed with nothing |
| --- | --- | --- |
| `api/command-hq/directory.ts` → `createCommanderDirectory()` | `commanders/<id>/CLAUDE.md` | a commander run under opencode |
| `api/bots/brief.ts` → `ensureBotsBrief()` | `bots/CLAUDE.md` | every bot |
| `api/chat/websocket.ts` → `installPluginChatBrief()` | `<plugin-chats>/CLAUDE.md` and the email account dir | plugin chats, email chats |

Commanders can already run under opencode, so this is live. The fix is small — write both names, or write
AGENTS.md and leave a CLAUDE.md pointer — but it is code, and a wrong guess silently un-briefs a running
agent.

`scripts/backfill-commander-credentials.ts` appends to EXISTING commander files and will need the same
treatment or it will edit a file nothing reads.

## 2. The 21 plugin repos have neither file

**The owner is leading this one** (2026-08-27) — do not sweep it unprompted. It is authoring rather than
moving text: an AGENTS.md for a plugin has to say something true about that plugin, and there are 21 of
them. Wait for the shape he wants before writing any.

`PLUGIN.md`, present in most of them, is a different document and stays untouched.

## 3. Out of scope, recorded so it is not re-derived

- `~/.claude/CLAUDE.md` — the owner's own, hand-maintained, Claude-specific by its path.
- Per-commander files are operational state authored by the commander, not documentation — but see 1,
  they still have to be DISCOVERABLE by both harnesses.