diff --git a/todo/docs-conventions/agents-md-remaining.md b/todo/docs-conventions/agents-md-remaining.md new file mode 100644 index 00000000..d7adc44a --- /dev/null +++ b/todo/docs-conventions/agents-md-remaining.md @@ -0,0 +1,48 @@ +--- +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//CLAUDE.md` | a commander run under opencode | +| `api/bots/brief.ts` → `ensureBotsBrief()` | `bots/CLAUDE.md` | every bot | +| `api/chat/websocket.ts` → `installPluginChatBrief()` | `/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. diff --git a/todo/known-bugs/calendar-skill-never-used-by-an-agent.md b/todo/known-bugs/calendar-skill-never-used-by-an-agent.md new file mode 100644 index 00000000..1339a98f --- /dev/null +++ b/todo/known-bugs/calendar-skill-never-used-by-an-agent.md @@ -0,0 +1,26 @@ +--- +id: known-bugs/calendar-skill-never-used-by-an-agent +title: 'The calendar/contacts skill has never been exercised by an actual agent' +theme: known-bugs +status: open +created: 2026-08-27 +date_source: stated +order: 9 +--- + +Every recipe in `plugins/caldav/skills/calendar-and-contacts/SKILL.md` was **run by hand** against +alpha's real data and works: create `201`, move `204`, delete `200`, contact create and delete, and the +JSON read for lookups. Isolation was proven too — own account `207`/`201`, another account `403`, spoofed +username `401`. + +**What has never happened is an agent reading the skill and acting on a sentence.** "I'm having dinner +Saturday with my wife, add that" has not been said in a chat. A skill can be entirely correct and still +not get picked up — wrong description, wrong trigger words, or simply not surfaced — and that failure +looks identical to the feature not existing. + +Five minutes to test, on this machine or alpha. Until it is done, the feature is unproven rather than +working. + +The trap it was written to prevent, worth re-checking in the transcript when it IS tested: `date -u -d` +does not convert local to UTC — it parses AND prints as UTC, so "Saturday at 8" becomes 20:00Z, an hour +late in Lisbon. If an agent gets that wrong, the skill's wording is not strong enough. diff --git a/todo/plugin-ecosystem/marketplace-browse-by-tag.md b/todo/plugin-ecosystem/marketplace-browse-by-tag.md new file mode 100644 index 00000000..a1443c57 --- /dev/null +++ b/todo/plugin-ecosystem/marketplace-browse-by-tag.md @@ -0,0 +1,32 @@ +--- +id: plugin-ecosystem/marketplace-browse-by-tag +title: 'Marketplace: browse by tag — filter list, card grid, detail with a back button' +theme: plugin-ecosystem +status: open +created: 2026-08-27 +date_source: stated +order: 5 +--- + +**The data layer is done** (`d381140d`): `PLUGIN_TAGS` is a closed vocabulary, every plugin declares its +own tags in its manifest, the sync caches them, and `CatalogueEntry.tags` serves them normalised. All 21 +are tagged and every tag has at least three plugins behind it. + +**The UI is not started.** What the owner asked for, 2026-08-27: + +- tags listed down the LEFT, as the filter +- plugins on the right as **cards in a grid**, app-store style — not the current master/detail list +- clicking a card opens the detail, with a **back button returning where you were** + +Two things to settle before building: + +- **"All" has to be the default selection**, or a store that filters opens on nothing. +- **Does the detail replace the grid or sit beside it?** A back button implies replace, which changes the + screen from master-detail to list-then-page. The current screen is explicitly built the other way + (`?selected=` rather than a route, deliberately — see `docs/navigation-audit.md`), so this is a real + change rather than a tweak. + +Whatever it becomes, the filter AND the selection both belong in the URL, or Back breaks. + +**More is wanted here beyond this** — the owner has said so, including "one very challenging but fun" +thing not yet described.