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).

Amended by ADR-0024 (2026-09-14). The decision stands unchanged — a published description states a boundary and never enumerates skills — but three of the four compile targets named below no longer exist. 718c79a deleted every per-plugin .claude-plugin/plugin.json and .github/plugin/plugin.json; 0dffff3 deleted the repo-wide .github/plugin/marketplace.json mirror; and .agents/plugins/marketplace.json with the codex profile producing it was removed 2026-09-13. A description is still authored twice — plugins/<name>/apm.yml and root apm.yml's marketplace.packages[] — but now compiles into one file, .claude-plugin/marketplace.json. Read the "four generated files" in Context and the "eight generated files" in Consequences as historical counts, true when written. The blast radius shrank; the staleness hazard that motivated this ADR did not.

Amended 2026-09-16: the root marketplace.packages[] copy of each description was removed; the package apm.yml is now the single source. See the amendment before Consequences.

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 four generated files per plugin edit: the plugin's .claude-plugin/plugin.json and .github/plugin/plugin.json, plus the repo-wide .claude-plugin/marketplace.json and its .github/plugin/marketplace.json mirror. (.agents/plugins/marketplace.json, apm's codex profile, carried no per-package description or version at all and was unaffected — that file and the profile producing it were removed 2026-09-13; see the amendment above.) 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. The three ADR-0020 validators (scripts/skill-size-check.sh and skill-audit's and agent-audit's validate.sh — two since ADR-0025 merged the audit pair into factory-audit, whose single auto-detecting validate.sh carries both) gate on SKILL.md and agent frontmatter; they do open apm.yml, but only to read dependencies.apm when resolving the boundary-target universe — none of them reads the description: key, and their hook globs match SKILL.md and *.agent.md only. 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 those four 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.

Correction (2026-09-14): that gate list is down to one, and it was never two. scripts/sync-plugin-content.sh --check --all does not exist — 718c79a deleted the script and its check-plugin-content-sync hook with the flat mirror (ADR-0024). Of the two names left, apm audit --ci was never a drift gate at all: against this repo it checks only that each apm.yml parses and that a manifest declaring dependencies has a consistent apm.lock.yaml, and it reads no description. So the sole surviving gate that compares compiled output against apm.yml is apm pack --check-versions --check-clean --dry-run, run by the apm-pack-check-clean pre-push hook — and with the per-plugin manifests gone it propagates a description into exactly one file, .claude-plugin/marketplace.json, not four. This narrows the mechanism and changes nothing about the finding: propagation is still not verification, and nothing anywhere reads the description key for sense.

And the obligation is unbounded. Under enumeration, adding one skill to bin, git or gitea means editing two copies of a prose string on top of the version bumps and regeneration any skill addition already owes under this repo's release policy (plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md). The bumps are not the marginal cost — the prose edit is, and it is the half nothing checks. A skill rename triggers the same, for a string no consumer can tell went stale. 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.

(Note, 2026-09-13: mattpocock-skills has since been removed from the root marketplace. This section's scope statement is retained as the reasoning behind the boundary; the entry it describes no longer exists.)

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 96 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.

Amendment (2026-09-16): the root copy is removed — the package apm.yml is the single source

The Decision's rule that "the two copies … stay identical" is retired by removing the second copy. The six description: lines under root apm.yml's marketplace.packages[] are deleted, the same way 2def060 deleted the six version: lines beside them. plugins/<name>/apm.yml's description: is now the only place a package's published description is authored.

The rule's own justification — "the root entry is what reaches the compiled marketplace" — was true only while the root entry set the field. apm's Claude marketplace mapper resolves a local-path entry's description curator-first: the entry's value wins when present, and when it is absent the value is read from the package's own apm.yml (apm_cli/marketplace/output_mappers.py, the is_local branch calling _apply_field_with_precedence with source_label="package apm.yml"). The root copy was therefore an override, not a mirror. Nothing enforced the identity rule, and on drift apm silently published the root value. Removing the copy removes the drift rather than leaving it unchecked.

All six root copies were byte-identical to their package's apm.yml when they were removed. After the removal, apm pack regenerated .claude-plugin/marketplace.json with every description unchanged, and apm pack --check-versions --check-clean --dry-run passes. The consequence for the "unbounded obligation" in Context is that a description edit is now one edit, not two. The package version bump and the catalog patch bump it earns are unchanged (plugins/kyberforge/.apm/skills/apm-workflow/references/configure.md).

This applies to local-path (source: ./…) entries only. A remote entry has no local package apm.yml to fall back to. Its description:, when set, is still the published text, and when it is absent apm uses whatever its best-effort remote metadata fetch returns.

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 commit that has 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. Lockstep is not folklore: it is stated at plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md. This is a defect, not a style: apm.yml's comment inside 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, so that sentence was rewritten in the same branch to point at plugins/<name>/.apm/skills/ and README.md instead.

README.md's plugin bullet list becomes the only place an inventory lives, and it still enumerates. That is deliberate, but it makes the list load-bearing in a way it was not before, so its bin, git and gitea bullets were completed in the same branch to name every skill those plugins ship. This ADR does not otherwise extend to it: a README is a hand-read document where a list of what you get is the useful thing, it is not compiled into four 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.