From 9f2b703b4bb8964f099c458b9ab9b2b106cf8e6f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Padez?= Date: Tue, 25 Aug 2026 19:24:17 +0000 Subject: [PATCH] todo: sweep AGENTS.md/CLAUDE.md so AGENTS.md is primary everywhere Co-Authored-By: Claude Fable 5 --- TODO.md | 76 ++++++++++--------- todo/docs-conventions/_index.md | 8 ++ ...eep-agents-md-primary-claude-md-pointer.md | 48 ++++++++++++ 3 files changed, 95 insertions(+), 37 deletions(-) create mode 100644 todo/docs-conventions/_index.md create mode 100644 todo/docs-conventions/sweep-agents-md-primary-claude-md-pointer.md diff --git a/TODO.md b/TODO.md index dfa49c71..63345477 100644 --- a/TODO.md +++ b/TODO.md @@ -18,45 +18,47 @@ the owner's OS user and can never be granted. Indirection there really is accide - **due 2026-08-22** — **Settings to choose which server each feature uses** — [fleet/settings-to-choose-which-server-each-feature](todo/fleet/settings-to-choose-which-server-each-feature.md) - **An affordance: a scoped agent warns when a request lands outside its scope** — [affordances/an-affordance-a-scoped-agent-warns-on-the](todo/affordances/an-affordance-a-scoped-agent-warns-on-the.md) +- **A commander's watcher does not survive a reboot, and nothing says so** — [agent-coordination/a-commander-s-watcher-does-not-survive-a-reboot](todo/agent-coordination/a-commander-s-watcher-does-not-survive-a-reboot.md) ## Themes -**97 open, 31 closed**, across 32 themes. +**100 open, 31 closed**, across 33 themes. -| Theme | Open | Closed | -| --- | --- | --- | -| [Affordances](todo/affordances/) | 2 | 0 | -| [Agents coordinating agents](todo/agent-coordination/) | 3 | 0 | -| [Speaking into a session from the backend](todo/agent-delivery/) | 1 | 1 | -| [Backburner](todo/backburner/) | 3 | 0 | -| [Background jobs](todo/background-jobs/) | 2 | 1 | -| [Chat interface](todo/chat/) | 1 | 0 | -| [Code editor](todo/code-editor/) | 1 | 0 | -| [Components — the shared UI layer](todo/components/) | 1 | 0 | -| [File watchers](todo/file-watchers/) | 1 | 0 | -| [Fleet — one command across every server](todo/fleet/) | 5 | 2 | -| [Headscale](todo/headscale/) | 0 | 5 | -| [Infra (alpha)](todo/infra/) | 7 | 0 | -| [Known bugs](todo/known-bugs/) | 5 | 4 | -| [Memory — one store instead of per-harness files](todo/memory/) | 1 | 0 | -| [Mobile apps](todo/mobile-apps/) | 4 | 0 | -| [Multi-user](todo/multi-user/) | 17 | 5 | -| [Notifications](todo/notifications/) | 1 | 0 | -| [Plugin ecosystem — before it opens to third parties (2026-08-18)](todo/plugin-ecosystem/) | 3 | 0 | -| [Plugin infrastructure](todo/plugin-infrastructure/) | 2 | 0 | -| [Plugin repos — what writing their READMEs turned up](todo/plugin-repos/) | 10 | 9 | -| [Plugin system — gaps the email extraction found (2026-08-18)](todo/plugin-system/) | 3 | 0 | -| [Prompt library](todo/prompt-library/) | 1 | 0 | -| [SendOff](todo/sendoff/) | 1 | 0 | -| [Settings — portable, and readable by an agent](todo/settings/) | 2 | 0 | -| [Shell — spotlight and the dock](todo/shell/) | 4 | 1 | -| [Sub-agents — agents spawning agents](todo/sub-agents/) | 0 | 2 | -| [Sudo terminal modal](todo/sudo-terminal-modal/) | 1 | 0 | -| [Tooling — the list about the list](todo/tooling/) | 0 | 1 | -| [Transmission](todo/transmission/) | 6 | 0 | -| [URL state — routing, query strings and selection](todo/url-state/) | 4 | 0 | -| [Waiting on the owner to run it](todo/waiting-on-owner/) | 3 | 0 | -| [Workspaces & Panels](todo/workspaces-panels/) | 2 | 0 | +| Theme | Open | Closed | +| ------------------------------------------------------------------------------------------ | ---- | ------ | +| [Affordances](todo/affordances/) | 2 | 0 | +| [Agents coordinating agents](todo/agent-coordination/) | 4 | 0 | +| [Speaking into a session from the backend](todo/agent-delivery/) | 1 | 1 | +| [Backburner](todo/backburner/) | 3 | 0 | +| [Background jobs](todo/background-jobs/) | 2 | 1 | +| [Chat interface](todo/chat/) | 1 | 0 | +| [Code editor](todo/code-editor/) | 1 | 0 | +| [Components — the shared UI layer](todo/components/) | 1 | 0 | +| [Documentation conventions — AGENTS.md vs CLAUDE.md](todo/docs-conventions/) | 1 | 0 | +| [File watchers](todo/file-watchers/) | 1 | 0 | +| [Fleet — one command across every server](todo/fleet/) | 5 | 2 | +| [Headscale](todo/headscale/) | 0 | 5 | +| [Infra (alpha)](todo/infra/) | 7 | 0 | +| [Known bugs](todo/known-bugs/) | 5 | 4 | +| [Memory — one store instead of per-harness files](todo/memory/) | 1 | 0 | +| [Mobile apps](todo/mobile-apps/) | 4 | 0 | +| [Multi-user](todo/multi-user/) | 17 | 5 | +| [Notifications](todo/notifications/) | 1 | 0 | +| [Plugin ecosystem — before it opens to third parties (2026-08-18)](todo/plugin-ecosystem/) | 4 | 0 | +| [Plugin infrastructure](todo/plugin-infrastructure/) | 2 | 0 | +| [Plugin repos — what writing their READMEs turned up](todo/plugin-repos/) | 10 | 9 | +| [Plugin system — gaps the email extraction found (2026-08-18)](todo/plugin-system/) | 3 | 0 | +| [Prompt library](todo/prompt-library/) | 1 | 0 | +| [SendOff](todo/sendoff/) | 1 | 0 | +| [Settings — portable, and readable by an agent](todo/settings/) | 2 | 0 | +| [Shell — spotlight and the dock](todo/shell/) | 4 | 1 | +| [Sub-agents — agents spawning agents](todo/sub-agents/) | 0 | 2 | +| [Sudo terminal modal](todo/sudo-terminal-modal/) | 1 | 0 | +| [Tooling — the list about the list](todo/tooling/) | 0 | 1 | +| [Transmission](todo/transmission/) | 6 | 0 | +| [URL state — routing, query strings and selection](todo/url-state/) | 4 | 0 | +| [Waiting on the owner to run it](todo/waiting-on-owner/) | 3 | 0 | +| [Workspaces & Panels](todo/workspaces-panels/) | 2 | 0 | ## Records — no items, kept for the reasoning @@ -69,11 +71,11 @@ the owner's OS user and can never be granted. Indirection there really is accide - `2026-08-25` **An affordance: a scoped agent warns when a request lands outside its scope** — [affordances/an-affordance-a-scoped-agent-warns-on-the](todo/affordances/an-affordance-a-scoped-agent-warns-on-the.md) - `2026-08-25` **Commit signing is inconsistent across harnesses — Claude names itself, opencode names nothing** — [agent-coordination/commit-signing-is-inconsistent-across-harnesses](todo/agent-coordination/commit-signing-is-inconsistent-across-harnesses.md) +- `2026-08-25` **A commander's watcher does not survive a reboot, and nothing says so** — [agent-coordination/a-commander-s-watcher-does-not-survive-a-reboot](todo/agent-coordination/a-commander-s-watcher-does-not-survive-a-reboot.md) - `2026-08-25` **Resurrect Projects/Apps** — [backburner/resurrect-projects-apps](todo/backburner/resurrect-projects-apps.md) +- `2026-08-25` **Sweep: AGENTS.md becomes the real instructions everywhere, CLAUDE.md a pointer beside it** — [docs-conventions/sweep-agents-md-primary-claude-md-pointer](todo/docs-conventions/sweep-agents-md-primary-claude-md-pointer.md) - `2026-08-25` **Refresh mid-turn folds the live tool call — it reads as finished while still running** — [known-bugs/refresh-mid-tool-call-renders-the-turn-folded](todo/known-bugs/refresh-mid-tool-call-renders-the-turn-folded.md) - `2026-08-25` **The model picker shows `claude-code` instead of the model that is running** — [known-bugs/the-model-picker-shows-the-bare-harness](todo/known-bugs/the-model-picker-shows-the-bare-harness.md) - `2026-08-25` **Understand how Claude and opencode do memory, then centralize both into one vector database** — [memory/understand-and-centralize-agent-memory-into-a](todo/memory/understand-and-centralize-agent-memory-into-a.md) - `2026-08-25` **Deep-link a todo notification straight to that item's markdown** — [mobile-apps/deep-link-a-todo-notification-to-its-file](todo/mobile-apps/deep-link-a-todo-notification-to-its-file.md) - `2026-08-25` **Add a favorites tab/panel to the file browser** — [multi-user/add-a-favorites-tab-panel-to-the-file-browser](todo/multi-user/add-a-favorites-tab-panel-to-the-file-browser.md) -- `2026-08-23` **A worker cannot verify that the owner delegated to a manager, so it has to ask every time** — [agent-coordination/a-peer-cannot-verify-a-delegation](todo/agent-coordination/a-peer-cannot-verify-a-delegation.md) -- `2026-08-23` **An agent cannot learn its own transcript id, so it cannot sign its own work** — [agent-coordination/an-agent-cannot-learn-its-own-session-id](todo/agent-coordination/an-agent-cannot-learn-its-own-session-id.md) diff --git a/todo/docs-conventions/_index.md b/todo/docs-conventions/_index.md new file mode 100644 index 00000000..e7ae787d --- /dev/null +++ b/todo/docs-conventions/_index.md @@ -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. diff --git a/todo/docs-conventions/sweep-agents-md-primary-claude-md-pointer.md b/todo/docs-conventions/sweep-agents-md-primary-claude-md-pointer.md new file mode 100644 index 00000000..54d86678 --- /dev/null +++ b/todo/docs-conventions/sweep-agents-md-primary-claude-md-pointer.md @@ -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//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.