docs(spec-loop): specify marketplace distribution, index every spec

[potiuk]

Summary

Closes the gap #1162 recorded rather than papered over: the plugin marketplace
surface had no spec at all. Adds marketplace-distribution.md, and — found
while registering it — fixes the spec indexes, which were listing about
two-thirds of the specs that exist.

The new spec

tools/spec-loop/specs/marketplace-distribution.md covers:

• Two manifest families, because the ecosystems have not converged: the
  vendor-neutral Agent Plugins 1.0 root plugin.json with its pinned $schema
  and closed ten-field set — which is why a Claude-only component path
  cannot leak into it — and the five client-specific manifests
  (.claude-plugin/, .codex-plugin/ + .agents/plugins/, the root
  marketplace.json, gemini-extension.json, apm.yml).
• Ten Claude-Code-only per-family plugins, and why the Codex and Copilot
  catalogs list only the all-in-one plugin: advertising a family plugin there
  would offer those clients something they cannot install.
• The generator/CI gate. check-family-plugins.py is both --fix and the
  prek hook, with pyproject.toml's project.version as the single authority
  every manifest mirrors verbatim.

Three contract points are the reason this is worth specifying at all:

1. The dev suffix is load-bearing and has to move. The marketplace is
   served from main, so adopters install dev versions as the normal case, and
   claude plugin update compares version strings, not commit SHAs. A frozen
   .devN leaves an adopter told they are "already at the latest version"
   however far behind they have fallen — recoverable only by
   claude plugin marketplace update plus a full uninstall and reinstall of
   every plugin, which nobody discovers unaided.
2. Family membership comes from family: frontmatter, never a name prefix.
   pr-stale-sweep, pre-first-pr-check and reviewer-routing are all
   family: pr-management without carrying the prefix.
3. The same skill is invoked by three different names depending on install
   method, and all three are correct. This reads like a bug until you know why.

Status is experimental, not stable: only the Claude Code manifests have
been exercised against a live install. The rest conform to their vendors'
published documentation and nothing more, and the Known gaps say so — including
that nothing checks the dev stamp is fresh, which is the one failure mode that
is silent in exactly the wrong direction.

Spec indexes were incomplete

Registering the new spec surfaced that ten specs were absent from both
overview.md and README.md — including security-model-preparation from
#1156 and every per-family spec (issue-management-family,
pr-management-family, repo-health-family, contributor-growth,
good-first-issue-sweep), plus organization-adapters, codex-runtime and
spec-gap-staleness. All ten are now listed in both, verified by re-scanning
rather than assuming the edit was complete.

Also

docs/setup/marketplaces.md said 41 of 70 skill description fields carry
placeholder syntax. Recounted from live frontmatter: 45 of 74. (The claim
matters because the page uses it to argue the placeholders are spec-conformant
rather than a portability risk — the Agent Skills spec constrains description
on length only.)

Test plan

• prek run --all-files passes (exit 0)
• spec-validate tools/spec-loop/specs/ — no violations
• Zero specs missing from either index, re-scanned after the edit
• Every contract claim verified against the implementation
  (check-family-plugins.py, the manifests themselves) or against
  docs/setup/marketplaces.md, not inferred

Notes for reviewers

The adoption-and-setup.md Known-gaps bullet added in #1162 is replaced by a
pointer to the new spec, so the two surfaces cross-reference rather than one
claiming the other is missing.

Worth a second opinion on the experimental status. It is defensible either
way — the manifests are generated and CI-enforced, which argues stable; but
five of six ecosystems have never been live-installed, which is what I weighted.

🤖 Generated with Claude Code

https://claude.ai/code/session_01So3JRGXrbqSGrohtZuHWKg