You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/09/08 02:05:46 UTC
(magpie) branch main updated: docs(spec-loop): specify marketplace distribution, index every spec (#1163)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/magpie.git
The following commit(s) were added to refs/heads/main by this push:
new abda5c15 docs(spec-loop): specify marketplace distribution, index every spec (#1163)
abda5c15 is described below
commit abda5c152d03c64c394e56a0b14b949ad480c12e
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Tue Sep 8 04:05:40 2026 +0200
docs(spec-loop): specify marketplace distribution, index every spec (#1163)
Closes the gap #1162 recorded rather than papered over: the plugin
marketplace surface had no spec at all.
`marketplace-distribution.md` covers the two manifest families (the
vendor-neutral Agent Plugins 1.0 root manifest with its closed ten-field
schema, and the five client-specific ones), the ten Claude-Code-only
per-family plugins, and the generator/CI gate that keeps them in step
with `family:` frontmatter.
The load-bearing part is the versioning rule. The marketplace is served
from `main`, so adopters install dev versions as the normal case, and
`claude plugin update` compares version strings rather than commit SHAs
— a frozen `.devN` suffix leaves an adopter told they are "already at the
latest version" indefinitely, recoverable only by a full uninstall and
reinstall. Recorded with the reason, along with the fact that nothing
checks the stamp is fresh, which is the one failure mode that is silent
in exactly the wrong direction.
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, which the Known gaps
now say.
While registering it: ten specs were absent from both index files
(`overview.md` and `README.md`) — among them `security-model-preparation`
from #1156 and every per-family spec. All ten are now listed in both, so
the indexes are complete.
Also corrects `docs/setup/marketplaces.md`, which said 41 of 70 skill
descriptions carry placeholder syntax; recounted from live frontmatter it
is 45 of 74.
Generated-by: Claude Code (Opus 5)
---
docs/setup/marketplaces.md | 2 +-
tools/spec-loop/specs/README.md | 13 +-
tools/spec-loop/specs/adoption-and-setup.md | 13 +-
tools/spec-loop/specs/marketplace-distribution.md | 151 ++++++++++++++++++++++
tools/spec-loop/specs/overview.md | 10 ++
5 files changed, 178 insertions(+), 11 deletions(-)
diff --git a/docs/setup/marketplaces.md b/docs/setup/marketplaces.md
index 7abbc3aa..cbb577e4 100644
--- a/docs/setup/marketplaces.md
+++ b/docs/setup/marketplaces.md
@@ -509,7 +509,7 @@ documentation**; what varies is whether it has also been exercised against a
The skills themselves are checked against the
[Agent Skills specification](https://agentskills.io/specification), which AP1
defers to. Worth stating explicitly, because it looks like a problem and is
-not: 41 of the 70 `description` fields contain the framework's
+not: 45 of the 74 `description` fields contain the framework's
`<placeholder>` syntax (`<tracker>`, `<upstream>`, …). The spec constrains
`description` on **length only** — 1–1024 characters, non-empty — and places no
restriction on angle brackets; the character-class rules apply to `name`, which
diff --git a/tools/spec-loop/specs/README.md b/tools/spec-loop/specs/README.md
index b6ce3929..9d6170b3 100644
--- a/tools/spec-loop/specs/README.md
+++ b/tools/spec-loop/specs/README.md
@@ -42,7 +42,18 @@ Start with [`overview.md`](overview.md), then:
[`spec-loop-runner.md`](spec-loop-runner.md),
[`security-reporting.md`](security-reporting.md),
[`reviewer-routing.md`](reviewer-routing.md),
- [`skill-reconciler.md`](skill-reconciler.md).
+ [`skill-reconciler.md`](skill-reconciler.md),
+ [`security-model-preparation.md`](security-model-preparation.md),
+ [`marketplace-distribution.md`](marketplace-distribution.md),
+ [`organization-adapters.md`](organization-adapters.md),
+ [`issue-management-family.md`](issue-management-family.md),
+ [`pr-management-family.md`](pr-management-family.md),
+ [`repo-health-family.md`](repo-health-family.md),
+ [`contributor-growth.md`](contributor-growth.md),
+ [`good-first-issue-sweep.md`](good-first-issue-sweep.md),
+ [`codex-runtime.md`](codex-runtime.md),
+ [`maintainer-education.md`](maintainer-education.md),
+ [`spec-gap-staleness.md`](spec-gap-staleness.md).
(Agentic Autonomous, the fifth MISSION mode, is deliberately off and has no
spec — see the note in [`overview.md`](overview.md).)
diff --git a/tools/spec-loop/specs/adoption-and-setup.md b/tools/spec-loop/specs/adoption-and-setup.md
index 7f61a843..3ab3e65e 100644
--- a/tools/spec-loop/specs/adoption-and-setup.md
+++ b/tools/spec-loop/specs/adoption-and-setup.md
@@ -121,15 +121,10 @@ uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-valid
## Known gaps
-- **Marketplace distribution is unspecified.** No spec covers the plugin
- marketplace surface — the per-family manifests, the root catalogues, or the
- `0.2.0.dev<YYYYMMDDHHMM>` version-stamping rule that `docs/setup/marketplaces.md`
- documents. That rule is load-bearing: the marketplace is served from `main`,
- so adopters do install dev versions, and `claude plugin update` compares
- version strings rather than commit SHAs — a frozen suffix leaves an adopter
- told they are "already at the latest version" indefinitely, recoverable only
- by a full uninstall and reinstall. Worth its own spec rather than a bullet
- here.
+- **Marketplace distribution is a sibling surface**, specified separately in
+ [`marketplace-distribution.md`](marketplace-distribution.md). An adopter takes
+ the framework either through the snapshot install described here or through a
+ plugin from that surface; the skills delivered are the same tree.
- `stable`; gaps appear as new agent targets to add to the registry
([`agents.md`](../../../skills/setup/agents.md)) or new override
diff --git a/tools/spec-loop/specs/marketplace-distribution.md b/tools/spec-loop/specs/marketplace-distribution.md
new file mode 100644
index 00000000..0286cb95
--- /dev/null
+++ b/tools/spec-loop/specs/marketplace-distribution.md
@@ -0,0 +1,151 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+---
+title: Marketplace distribution (plugin manifests and versioning)
+status: experimental
+kind: feature
+mode: infra
+source: >
+ docs/setup/marketplaces.md. The manifest set at .claude-plugin/,
+ .codex-plugin/, .agents/plugins/, plugins/magpie-*/, and the repo-root
+ plugin.json / marketplace.json / apm.yml / gemini-extension.json.
+ Enforced by tools/dev/check-family-plugins.py.
+acceptance:
+ - Every ecosystem manifest mirrors pyproject.toml's project.version
+ verbatim, including the .devN suffix.
+ - Every skill family has a plugins/magpie-<family>/ plugin whose skills/
+ directory contains exactly that family's skills as single-hop symlinks.
+ - Manifests are generated from pyproject.toml and the all-in-one manifest,
+ never hand-edited; the generator is idempotent and CI fails on drift.
+---
+
+# Marketplace distribution
+
+## What it does
+
+Publishes the framework as installable plugins across several agent
+ecosystems, so an adopter who does not want the
+[`/magpie-setup` snapshot install](adoption-and-setup.md) can take the skills
+through their client's own plugin mechanism instead.
+
+This is the *distribution* surface. It changes nothing about how a skill
+behaves — the same `skills/<name>/SKILL.md` tree is what every install method
+delivers.
+
+## Where it lives
+
+Two manifest families, because the ecosystems have not converged:
+
+- **Agent Plugins 1.0** — the vendor-neutral root `plugin.json`, pinned to
+ `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`. Its schema is
+ **closed**: exactly ten permitted fields, so a client-specific component path
+ cannot leak in. The spec requires it at the repository root, so its location
+ is not a choice.
+- **Client-specific** — `.claude-plugin/plugin.json` + `marketplace.json`
+ (Claude Code, the only family that carries `hooks` and per-family plugins),
+ `.codex-plugin/plugin.json` with `.agents/plugins/marketplace.json` (Codex),
+ the root `marketplace.json` (Copilot / VS Code legacy catalog),
+ `gemini-extension.json`, and `apm.yml` (`microsoft/apm`, schema v0.1).
+
+Plus `plugins/magpie-<family>/` — ten Claude-Code-only plugins, one per skill
+family, each a manifest and a `skills/` directory of single-hop symlinks into
+the shared `skills/<skill>` tree.
+
+`tools/dev/check-family-plugins.py` is both the generator (`--fix`) and the
+CI gate. `docs/setup/marketplaces.md` is the adopter-facing page.
+
+## Behaviour & contract
+
+- **`pyproject.toml` `project.version` is the single authority.** Every
+ ecosystem manifest mirrors it verbatim, `.devN` suffix included. Nothing is
+ hand-edited: `project.version` feeds the ecosystem manifests, and
+ `.claude-plugin/plugin.json` in turn feeds the ten per-family manifests and
+ the marketplace entries, which also inherit `author`, `homepage`,
+ `repository`, and `license`.
+
+- **Between releases the version carries a moving dev suffix, and it is
+ load-bearing.** The manifests read `0.2.0.dev<YYYYMMDDHHMM>`, never a bare
+ `0.2.0` — a bare version would advertise a release that does not exist. The
+ marketplace is served straight from the `main` branch, so adopters *do*
+ install dev versions; that is the normal case. `claude plugin update`
+ compares **version strings, not commit SHAs**, so while the suffix stays
+ frozen an adopter is told they are "already at the latest version" however
+ far behind `main` their copy has fallen, and the only recovery is
+ `claude plugin marketplace update` plus a full uninstall and reinstall of
+ every plugin — which nobody discovers unaided. The stamp is minute-resolution
+ **UTC** so bumps from contributors in different timezones sort in the order
+ they were made.
+
+- **Bump when the work needs to reach installed copies**, not per PR — a
+ per-PR bump puts every contributor in conflict with every other over one
+ line. Before pointing anyone at `claude plugin update`, before announcing a
+ change adopters should take, or when merged work has piled up behind a stale
+ stamp.
+
+- **Family membership comes from `family:` frontmatter, never from a skill's
+ name prefix.** A family plugin's `skills/` directory must contain exactly the
+ skills declaring that family — several do not carry the family's name
+ (`pr-stale-sweep`, `pre-first-pr-check` and `reviewer-routing` are all
+ `family: pr-management`).
+
+- **The per-family plugins are Claude Code only.** The Codex and Copilot
+ catalogs list the all-in-one plugin and nothing else; advertising a family
+ plugin there would offer those clients something they cannot install.
+
+- **The same skill is invoked by a different name per install method**, and all
+ three are correct: `/magpie-<name>` under the portable snapshot install
+ (where the `magpie-` prefix *is* the namespace), `/magpie:<name>` under the
+ all-in-one marketplace plugin, and `/magpie-<family>:<name>` under a family
+ plugin (where `plugin:skill` supplies the namespace).
+
+- **Placeholder syntax in a skill `description` is conformant, not a
+ portability risk.** 45 of the 74 descriptions contain `<tracker>`,
+ `<upstream>` and friends. The Agent Skills specification constrains
+ `description` on length only (1–1024 characters, non-empty); its
+ character-class rules apply to `name`, which every skill satisfies.
+
+## Out of scope
+
+- The snapshot install and its lock/override model — that is
+ [`adoption-and-setup.md`](adoption-and-setup.md).
+- Publishing to any vendor's hosted registry. Every catalog here is served
+ from this repository; nothing is pushed anywhere.
+- The ASF source release. None of these manifests change how the release
+ artefact is built or signed.
+
+## Acceptance criteria
+
+1. `check-family-plugins.py` passes: version parity across every ecosystem
+ manifest, AP1 conformance for the root `plugin.json` (pinned `$schema`,
+ name pattern, closed ten-field set), one well-formed plugin per declared
+ family, and symlink sets matching `family:` frontmatter exactly.
+2. `--fix` regenerates every manifest from `pyproject.toml` and is idempotent —
+ a second run is a no-op.
+3. A version bump is a one-line edit to `pyproject.toml` plus a regeneration.
+4. The Codex and Copilot catalogs list only the all-in-one plugin.
+
+## Validation
+
+```bash
+python3 tools/dev/check-family-plugins.py
+uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-validate
+```
+
+For the Claude Code family, `claude plugin validate . --strict`.
+
+## Known gaps
+
+- **Only the Claude Code manifests are verified against a live install.** The
+ rest — AP1 root `plugin.json`, the Codex pair, the Copilot catalog,
+ `gemini-extension.json`, `apm.yml` — conform to their vendors' published
+ documentation but have not been exercised end-to-end. Re-check each against
+ current vendor docs before a marketplace publish.
+- **`apm.yml` targets `microsoft/apm` schema v0.1**, pre-1.0 and the most
+ likely of the set to churn.
+- **Gemini has no migration path off `gemini-extension.json`.** Google has
+ joined the AP1 TSC but published nothing, so both files stay.
+- **Nothing checks the dev-suffix stamp is fresher than the last release**, so
+ a bump that is forgotten fails silently in the one way that matters: adopters
+ keep being told they are up to date. The staleness is only visible by reading
+ the timestamp.
diff --git a/tools/spec-loop/specs/overview.md b/tools/spec-loop/specs/overview.md
index 3b522d62..fa1adc3c 100644
--- a/tools/spec-loop/specs/overview.md
+++ b/tools/spec-loop/specs/overview.md
@@ -58,6 +58,16 @@ Each mode is an independently toggleable set of skills. Maturity mirrors
| Reviewer routing (experimental, Agentic Triage) | [reviewer-routing.md](reviewer-routing.md) |
| Cross-project skill reconciler (experimental, infra) | [skill-reconciler.md](skill-reconciler.md) |
| Maintainer-education stream (proposed — release-blocking per PRINCIPLE 18) | [maintainer-education.md](maintainer-education.md) |
+| Security-model preparation (produce / verify / update the project's own model) | [security-model-preparation.md](security-model-preparation.md) |
+| Marketplace distribution (plugin manifests, per-family plugins, versioning) | [marketplace-distribution.md](marketplace-distribution.md) |
+| Organizations (governance + backend defaults grouped per org) | [organization-adapters.md](organization-adapters.md) |
+| Issue-management family | [issue-management-family.md](issue-management-family.md) |
+| PR-management family | [pr-management-family.md](pr-management-family.md) |
+| Repo-health audits | [repo-health-family.md](repo-health-family.md) |
+| Contributor-growth family | [contributor-growth.md](contributor-growth.md) |
+| Good-first-issue backlog sweep | [good-first-issue-sweep.md](good-first-issue-sweep.md) |
+| Codex first-class skill runtime | [codex-runtime.md](codex-runtime.md) |
+| Spec-gap staleness verification (proposed) | [spec-gap-staleness.md](spec-gap-staleness.md) |
## The non-negotiables every area inherits