officerdev/platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

affordances: the file format, where they live, and what is still open

Browse Source 
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>
This commit is contained in:
pastilhas
2026-08-19 07:19:40 +00:00
co-authored by Claude Opus 5
parent 7a9e576ee6
commit d8c97b6814
2 changed files with 98 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TODO.md
+33
View File
@@ -298,6 +298,39 @@ pane belonging to the folder you left; and the breadcrumb opted out of that last
restored. Deliberate as written — a dashboard can hold two browsers and one URL cannot serve both —
but worth re-deciding rather than inheriting.
## Affordances (2026-08-19)
Agreed and written down in `plugins/CLAUDE.md`; **nothing is built**. An affordance is what the surface
on the other end offers the agent — declared by the code that implements it, read at runtime. The first
two are image rendering (core) and gitea (`git` for git, `tea` for everything else).
To build:
- `capabilities/affordances/` created by the setup script, with `officer/core/` populated from an
officer-capabilities repository. The clone is future work; the directory is not.
- A compiler: parse the tree, take each body under its `name` as a heading, produce one small block.
Per session, not per boot — `capabilities/` is already read fresh each agent session, and a plugin
installed mid-day should be live on the next message.
- Delivery. Claude sessions take `systemPrompt: { type: 'preset', preset: 'claude_code', append }`,
which nothing passes today. **Opencode has its own driver and would need the same**, or the affordance
is a claim that only holds on one harness — which is the drift this exists to remove. A bare `claude`
run in a terminal on the host gets neither unless a file is also written.
- Plugin contribution: an `affordances/` directory in the plugin repository, copied to
`capabilities/affordances/<publisher>/<plugin>/` on install and removed on uninstall. Same shape as
`assets/` and `publishAssets`.
Open, and deliberately deferred:
- **Scoping.** Everything is loaded into every conversation. Fine at two files, not at twenty. A
`surface` field was drafted and dropped because it was doing two jobs at once: for image rendering it
means _what the client renders_ (a phone, a web bubble, a cron run with nobody watching), for gitea
_what tooling exists on this machine_. Those are different axes and one field cannot be both. Decide
the axis before adding the field — and note this codebase has already been bitten by a field that
validated itself and was never consumed (`unauthenticatedPaths`, see `plugins/public-paths.ts`).
- **Drift.** The rule is "declared where implemented", but a hand-authored markdown file in a repository
is not that — `ChatImage` could stop rendering images and no file would notice. Accepted for now
because prose that reaches every harness beats a registry that reaches one; revisit if it bites.
## Plugin ecosystem — before it opens to third parties (2026-08-18)
Not now. Months away. Recorded so it is not re-derived.