opencode discovers only AGENTS.md, Claude Code only CLAUDE.md — so with the
content living in CLAUDE.md, every doc here was invisible to opencode. Swaps
all five pairs (root, src/apps, src/databases, themes, plugins): AGENTS.md now
holds the full text verbatim, CLAUDE.md is a short pointer. docs-check's
permission-count regex now reads root AGENTS.md instead of CLAUDE.md; the
workspace-level officer-dev/CLAUDE.md check is untouched, out of scope.
the substance was in plugins/CLAUDE.md marked "DESIGN, NOT BUILT", which
stopped being true the same day it was written — load.ts reads them, publish.ts
copies a plugin's in on install, and claude-manager compiles them into every
session. moved to docs/affordances.md and corrected; plugins/CLAUDE.md keeps
the plugin-specific part and points here.
the new part is a third test, earned today by nearly failing it twice: CAN IT
BE FIXED INSTEAD? an affordance is for something irreducible about the
surface, and a defect is not irreducible.
both candidates drafted today failed it. "links open in the same tab" was one
missing line in MD_COMPONENTS. "AskUserQuestion never returns an answer" was
true when the code comment was written and already fixed by the time i read
it — that one would have shipped a permanent instruction to work around a bug
that no longer existed, in a file whose whole purpose is to be believed
without checking.
names the failure mode: an affordance describing a defect calcifies it. once
there is a document explaining the workaround, the defect has a rationale, and
the rationale outlives anyone's memory that it was a bug.
also records two things that are not built and read as if they were: nothing
is scoped, so every affordance is in every conversation, and affordanceBlock()
has exactly one caller — an opencode turn gets none at all.
the piece that makes a new notification kind a server change rather than an
app store release. a push carries a code and integers; this is what the code
means, synced to the device instead of compiled into it.
deliberately the same shape as affordances rather than a second mechanism: a
`notifications/` directory of yaml in the plugin repository, copied to
capabilities/notifications/<publisher>/<appName>/ on install, removed on
uninstall. publish.ts mirrors affordances/publish.ts closely enough to diff.
the namespace is DERIVED from where the file lands, never from what it
declares — same rule as mountPrefix. a plugin writing `officer/core:test` as a
key gets `<publisher>/<plugin>:officer/core:test` and the real core entry is
untouched. that is the security property of the whole scheme and it is pinned
by test.
version is a content hash, not a counter. a counter needs somewhere to live
and is then wrong after a restore, a rollback, or two servers built from the
same install; a hash needs no storage and is right in all three. so the client
compares mv !== version, and both docs now say so — i had written "higher".
core entries ship in code rather than on disk, because capabilities/ is
installed rather than committed and `test` has to exist on a machine that has
installed nothing — it is what first light is proved with.
read from disk per request, not memoised: installing a plugin has to change
the answer without a restart, or it presents as "the new plugin's
notifications don't work", which is the hardest kind of bug to place.
verified live: 401 through the platform, plugin catalogue appearing and
disappearing with no restart, version returning to its prior value when the
plugin is removed. 10 catalogue tests, 100% coverage of catalogue.ts.
The path takes `publisher` from the manifest verbatim, so a plugin published
by officerdev lands under officerdev/. `officer/core` is not a plugin at all —
it is the platform's own, shipped by the setup script from the capabilities
repository.
Two spellings marking two different things: platform versus publisher. Arrived
at by accident and kept on purpose. Recorded because the obvious tidy-up
removes the distinction rather than the inconsistency.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Design only — nothing reads any of this yet.
Markdown with YAML frontmatter, like every other item in capabilities/.
Frontmatter is for the PLATFORM, the body is for the agent: `name` becomes the
heading in the compiled block, `description` says when to reach for it and is
not sent, `version` is an INTEGER to match capabilities/agents/ rather than the
semver plugins use. A plugin-contributed affordance sits near both numbers and
they mean different things — the integer is the revision of that text, the
semver is the plugin's.
They live at capabilities/affordances/<publisher>/<plugin>/, with `core` in the
plugin slot for the platform's own. A plugin ships an affordances/ directory
and install copies it in — the same shape as assets/ and publishAssets.
No `surface` field. It was drafted and dropped: for image rendering it would
mean what the CLIENT renders, for gitea what TOOLING exists on the machine.
Two axes wearing one name. Everything loads unconditionally until that is
worked out, which is fine at two files and will not be at twenty — and this
codebase has already been bitten by a field that validated itself and was never
consumed (unauthenticatedPaths).
TODO.md carries the build list and the two deferred questions, including the
honest one: "declared where implemented" is the rule, and a hand-authored file
in a repository is not that. Accepted because prose reaches every harness and a
registry reaches one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
DESIGN, NOT BUILT. No registry, no API, nothing to call. Written down now
because the name and the boundary are the parts that get expensive later, and
because a plugin author who invents a different word for this is hard to merge
with afterwards.
An affordance is what the surface on the other end offers the agent — declared
by the code that implements it, read at runtime. Not what the agent can do;
what the client will honour.
The worked example is images. Officer's chat DOES render markdown images, but
an <img> carries no bearer token, so it can only load what the browser can
fetch unauthenticated. A fresh agent knows none of that: it writes
, nothing renders, and nothing says why. That knowledge
currently lives as prose in a hand-written CLAUDE.md on one machine, phrased as
a workaround ("use a public URL") rather than as the constraint — with nothing
keeping the two in sync.
Prose is the wrong container for three reasons: it drifts from the code, it is
per-machine, and a plugin cannot contribute to it. The last one is the point —
a plugin IS a new surface arriving at runtime, and no agent learns it exists.
The rule that makes it worth building: an affordance is declared where it is
implemented, like permissions/registry.ts. A list maintained elsewhere is the
CLAUDE.md problem again with a better name.
`capability` and `skill` were both already taken here, twice in skill's case.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pastilhas
