holocron/docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md

A plugin's published description states its domain boundary and never enumerates its skills

Three of this repo's six plugins publish a description that lists the skills they ship. That style has now failed three times in four days, the third time inside the correction for the second. It is enforced by nothing, it obliges a marketplace release on every skill addition, and it was never applied to the other three plugins. This ADR retires it: a published description says what the plugin is for, and the inventory lives where an inventory can be read off the tree.

Status: accepted (2026-08-17).

Context

A plugin's published description is one string authored twice — in plugins/<name>/apm.yml and in the matching marketplace.packages[] entry of the root apm.yml — and compiled into six files per plugin edit: .claude-plugin/plugin.json, .github/plugin/plugin.json, .claude-plugin/marketplace.json, .github/plugin/marketplace.json, and (for the version field only) their codex counterpart. It is the only text a consumer sees in a marketplace listing before installing. It is not a SKILL.md description: it is never preloaded into an agent's context and routes nothing at runtime. ADR-0020 governs that other artifact; this one governs this one. The overlap is a finding, not a scope: ADR-0020 established that capability enumeration in a description is "a correctness hazard, not only a token cost". The hazard at this layer is different — staleness in published metadata rather than an agent shortcutting the body — but the enumeration is the same construct and it fails the same way.

Measured at de84d1b, the branch tip before this change. Each figure is reproducible from the tree: skill counts are ls plugins/<name>/.apm/skills/ | wc -l, description text is plugins/<name>/apm.yml.

Plugin	Style	Skills	Items enumerated	Skills named	Unnamed
bin	enumeration	11	8	9	caveman, zoom-out
git	enumeration	9	8	8	git-workflow
gitea	enumeration	7	7	6	gitea-workflow
core	boundary	3	—	—	—
kyberforge	boundary	7	—	—	—
lint	boundary	2	—	—	—

Three failures, in order.

bb9158d (2026-08-14) — core's description described bin. The text it deleted read "Cross-cutting utility skills for everyday AI-assisted coding — triage, diagnosis, architecture review, and session navigation." All four items are real skills and not one of them is core's: they are bin's triage, diagnose, improve-codebase-architecture and zoom-out. core ships agentsmd-author, agentsmd-audit and provider-adapter-author, and the published description named none of them.

This is the failure the whole style was later adopted against, and it is worth being exact about what it was, because the record has been read the other way twice since. It was wrong content, not an incomplete list. The description was a syntactically perfect, complete, four-item enumeration of a real skill set; it just belonged to a different plugin. Enumerating harder could not have caught it, and a gate that asked "does every enumerated item exist as a skill?" would have passed it — all four did exist. bb9158d's own fix went the other direction: it replaced the enumeration with a domain boundary, and core has needed no correction since. The precedent set by that commit was therefore boundary, and the two commits below cite it while doing the opposite.

65bac15 (2026-08-17) — git advertised gitea's domain, gitea advertised a skill that does not exist. git read "conventional commits, branch management, pull requests, and feature flow"; pull requests reach the forge over HTTP and are gitea's, which is the exact boundary docs/spec/architecture.md draws between the two plugins. gitea read "issues, pull requests, milestones, releases, and wikis"; grep -ri wiki plugins/gitea/.apm/ returns nothing and no wiki skill has ever existed. Both were repaired by re-enumerating.

de84d1b (2026-08-17) — the re-enumeration was itself incomplete. bin's "A place for things to be binned" was replaced with an eight-item list over eleven skills; caveman and zoom-out are absent. zoom-out is the same skill bb9158d had called "session navigation" three days earlier while deleting it from the wrong plugin's description — named when it was in the wrong place, unnamed once it was in the right one. And the miss is not confined to bin: git-workflow is unnamed in git's corrected description, though 65bac15's own commit message states it was added ("omitting pc-author/pc-run, git-submodules and git-workflow"), and gitea-workflow is unnamed in gitea's. Across the three plugins, 23 of 27 skills are named at the third attempt.

Nothing checks any of this. scripts/check-manifests.sh does not contain the string description. scripts/skill-size-check.sh and the three ADR-0020 validators read SKILL.md and agent frontmatter and never open an apm.yml. apm audit --ci, apm pack --check-clean and scripts/sync-plugin-content.sh --check --all all compare compiled output against apm.yml, so their entire job is to propagate whatever the description says into six files byte-for-byte and confirm they match. The wiki claim passed every one of the fourteen pre-push hooks, every day it was published.

And the obligation is unbounded. Under enumeration, adding one skill to bin, git or gitea means editing two copies of a prose string, a PATCH bump on the package, a bump on marketplace.version, and a regeneration of eight compiled files — a marketplace release, triggered by a directory appearing. A skill rename triggers the same. 27 of the repo's 39 skills sat behind a description carrying that obligation; the other 12 did not, and their three plugins have generated no defect of this class.

Scope

This decision covers the six plugins this repo authors. The root marketplace also lists mattpocock-skills, a third-party package whose description is not this repo's to write; its entry is out of scope and is left as published upstream.

Decision

A plugin's published description states the plugin's domain boundary. It does not enumerate the skills the plugin ships, by name or by paraphrase.

• The boundary answers "what kind of work belongs to this plugin, and where is its edge against its nearest sibling" — the question a consumer deciding whether to install is actually asking. It is stable under skill addition, rename and removal, which is the entire point: an artifact that does not change when the tree changes cannot go stale against it.

• The boundary must cover everything the plugin actually ships. A boundary drawn narrower than the contents is the same defect as an incomplete enumeration, one level up, and it is the specific risk in this change. git carries pc-author and pc-run, which are not git operations at all; "Skills for working with Git" silently drops them, so the boundary names the pre-commit hooks explicitly rather than trusting a reader to file them under Git.

• The two copies — package apm.yml and the root marketplace.packages[] entry — stay identical. This is already the rule in practice and both prior corrections state why: the root entry is what reaches the compiled marketplace, so fixing only the package manifest leaves it half-propagated.

• The three descriptions, rewritten here, with core/kyberforge/lint shown for register:

  Plugin	Published description	Chars
  bin	Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.	152
  git	Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.	146
  gitea	Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone.	134
  core	(unchanged) Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.	101
  kyberforge	(unchanged) Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.	105
  lint	(unchanged) Skills and agents for configuring and running linters.	54

• No gate is added. This is a deliberate omission and the reasoning is below, not an item left for later.

Why no gate

The check enumeration would need — "every skill directory appears in the description" — was writable in principle and was never written, including by the two commits that corrected an enumeration by enumerating again and had every reason to. It is also only half a check: it catches a skill missing from the list, and it cannot catch wiki, because "this noun does not name any skill" requires a vocabulary of permissible non-skill nouns that no one is going to maintain. Under a boundary there is no correspondence left to check, which is the property being bought.

What survives un-gated is bb9158d's actual failure: a boundary that is simply wrong about its plugin. That was never machine-checkable in either style — the text was a well-formed description of a real plugin — and it is caught by the same review that has to happen when a published, consumer-facing string is edited at all. A gate that would catch it needs a declared per-plugin skill-to-boundary mapping for the description to be checked against, which is a second artifact requiring exactly the per-skill maintenance this ADR exists to delete, relocated one file over.

Two cheap partial gates were considered and rejected in the same breath. Forbidding a comma-separated run of three or more noun phrases is a prose heuristic that fires on lint's perfectly good "configuring and running linters" class of sentence. Forbidding any string matching a skill directory name under plugins/<name>/.apm/skills/ bans legitimate boundary vocabulary — git-branches exists, and a git boundary has every right to say "branches". Both would be believed, and both would be wrong, which ADR-0020 already records as worse than no gate.

Considered options

Keep enumeration and gate it. The only option that makes the current style safe. Rejected on the three grounds above: the check is one-directional, it cannot see an invented capability, and it makes a marketplace release the consequence of adding a directory. It also hard-couples published consumer copy to internal directory names, so a skill rename becomes a version bump on the plugin and on the marketplace.

Enumerate consistently across all six plugins, on the grounds that the real defect is the split style. Rejected: it takes an obligation that has produced three failures on three plugins and applies it to six. The measured outcome of the most recent attempt to enumerate carefully, with the defect fresh and two prior commits as precedent, is four skills unnamed.

Cap the description length, mirroring ADR-0020's 250/400-character tiers, on the theory that a short description has no room to enumerate. Rejected because length does not measure correspondence: gitea's failing description was 114 characters and asserted a skill that has never existed, while bin's 176-character enumeration is under the same cap. All six descriptions here, before and after, sit inside ADR-0020's tiers; the tier would have been silent through all three failures.

Delete the description to a bare name. Rejected: apm's Claude marketplace mapper emits description into marketplace.json, and it is the only prose a consumer sees before installing.

Point the description at the plugin's README.md. Rejected: a marketplace listing renders a string, not a link — and the README's own plugin list carries the same enumeration with the same staleness, so this relocates the defect rather than fixing it.

Consequences

Three descriptions are rewritten and the compiled output regenerated. Eight generated files change: plugins/{bin,git,gitea}/.claude-plugin/plugin.json, plugins/{bin,git,gitea}/.github/plugin/plugin.json, .claude-plugin/marketplace.json and its byte-identical .github/plugin/marketplace.json mirror. .agents/plugins/marketplace.json (the codex profile) is unchanged and correctly so — it carries no per-package description or version field at all, only name, source, policy and category.

Version bumps, all PATCH under the per_package strategy: bin 1.1.4 → 1.1.5, git 1.3.4 → 1.3.5, gitea 1.3.5 → 1.3.6, marketplace.version 0.4.4 → 0.4.5.

The root apm.yml top-level version: is restored to lockstep with marketplace.version, 0.4.2 → 0.4.5. These two fields have moved together in every one of the eleven commits that have ever touched root apm.yml — 0.3.2, 0.3.3, 0.3.4, 0.4.0, 0.4.1, 0.4.2 in both — until 65bac15 and de84d1b on this branch bumped marketplace.version to 0.4.3 and then 0.4.4 while leaving the top-level field at 0.4.2. This is a defect, not a style: apm.yml's own comment above the marketplace block records that the top-level version: is not inherited into the compiled output "despite being used elsewhere (e.g. by apm audit)", so the field is live and was silently two releases behind what the marketplace published. Closed here rather than tracked, because the correction is one line and the drift is three days old.

docs/spec/architecture.md's plugin table is unchanged and stays a routing table. It answers "where does a new skill go" for someone working inside this repo; the published description answers "should I install this" for someone outside it. The two now read similarly, and that is not duplication to collapse — they have different readers and different lifecycles, and the table already says so in its own preamble ("These are routing boundaries, not inventories"). One caveat for whoever next edits that page: its closing sentence sends a reader to the published description "for what a consumer actually gets", which was true against an enumeration and is now a pointer to a second boundary statement. Neither artifact carries an inventory after this change. That sentence is owned by a separate workstream in this change and is deliberately not edited here.

README.md's plugin bullet list becomes the only place an inventory lives, and it still enumerates. Its bin and git bullets mirror the retired descriptions almost verbatim. This ADR does not extend to it and does not require it to change: a README is a hand-read document where a list of what you get is the useful thing, it is not compiled into six files, and a stale line in it costs a reader a moment rather than misrepresenting a published package. The tradeoff that makes enumeration wrong in a marketplace manifest is precisely the one that makes it fine there.

Nothing in the ADR-0020 gate set changes. Its character and word tiers, its Vale rules and its three validators all read SKILL.md and *.agent.md frontmatter; none of them opens an apm.yml. The two contracts are adjacent and independent, and a future author retrofitting a skill under issue #99 is not touched by this ADR.

The failure mode this leaves open is a wrong boundary, and it is un-gated by design. If a fourth failure of this class occurs it will be a description that describes the wrong plugin — bb9158d's shape, the one enumeration never addressed. That is the trigger to revisit, and the thing to build then is a declared skill-to-boundary mapping, not a return to enumeration.