todo: fold the existing claude-md-touchpoints audit into the AGENTS.md sweep

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-25 19:26:05 +00:00
parent 9f2b703b4b
commit a7b95a7bd1
1 changed files with 45 additions and 0 deletions
@@ -46,3 +46,48 @@ wrong, not just unnecessary:
 `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.
 ---
 **2026-08-25 — the owner points at prior art: `docs/claude-md-touchpoints.md`, an audit written the
 same day, before any change, exactly so this sweep would not be guessed at.** It replaces the "two
 lookalikes" section above with something precise: **three writers, one reader**, all named by file and
 line —
 1. `command-hq/directory.ts:653`, `createCommanderDirectory()` — generates a commander's `CLAUDE.md`
   ONCE, at creation, from `commanderClaudeMd()`. Never rewritten afterward; the commander extends it
   itself over its own life, which is why this file is correctly excluded from any flip — there is no
   "primary content" to move, because the content is written by the commander, not shipped as
   documentation.
 2. `api/chat/websocket.ts:237`, `installPluginChatBrief()` — copies a plugin's own `chat/CLAUDE.md`
   into a plugin-chat's directory, content-diffed so it only rewrites on an actual change. Of 19
   plugins, exactly one (`proxy-manager`) ships one.
 3. `scripts/backfill-commander-credentials.ts` — a manual, idempotent append pass over EXISTING
   commander files, marker-guarded so it never duplicates a section.
 4. `scripts/docs-check.ts` — read-only, checks `platform/CLAUDE.md` and `officer-dev/CLAUDE.md` (not a
   plugin's, not a commander's) for numeric drift. This is the one file this sweep must not touch
   carelessly: whatever ends up as the "pointer" file still has to carry the two numbers `docs:check`
   parses out of it, or the check needs to move to reading `AGENTS.md` instead.
 **Confirms the exclusion already written above, with better grounding — do not re-derive it, cite the
 audit instead.** Commander files and plugin chat briefs are runtime-authored content injected into an
 agent's cwd, not source-tree documentation a coding CLI discovers by walking up from where it starts.
 Flipping "which file is primary" has no meaning for a file with no counterpart and no static content to
 begin with.
 **Two things the audit surfaces that are genuinely new and unresolved, not covered by "flip the pointer
 everywhere":**
 - **The owner's personal `~/.claude/CLAUDE.md` is explicitly, deliberately, never touched by any of
  this** — the audit's own "Explicitly not written" section: the owner's sessions are un-isolated, `HOME`
  points at their real home, and a generated file there would land inside the hand-maintained document
  the owner edits directly (and that a terminal `claude` also reads). **This file is out of scope for
  the sweep entirely** — it is not a repository doc, it is the owner's own, and it is inherently
  Claude-specific by its path (`~/.claude/`), not something an `AGENTS.md` convention could apply to.
 - **A commander's dynamically-generated file is named `CLAUDE.md` specifically, and commanders can run
  under opencode.** The audit does not ask whether opencode discovers a `CLAUDE.md` in its working
  directory the way Claude Code does — only Claude/opencode's actual read-side behaviour answers that,
  and it was out of scope for an audit about WRITING. If opencode does not read `CLAUDE.md` by
  convention, an opencode-run commander is silently briefed with nothing, which would be a real gap
  this sweep should catch rather than one it assumes away. Check before deciding whether
  `commanderClaudeMd()`'s output needs an `AGENTS.md`-named counterpart too.