feat(marketplace): distribute Magpie 0.2.0 via agent marketplaces + auto-upgrade hook

[potiuk]

Prepares Apache Magpie 0.2.0 for release through existing agent-skill marketplaces, and wires automatic upgrade detection. Refs #518.

Approach

Package the whole framework as a single magpie plugin whose skills points at the existing ./skills tree — no file moves, no vendored copies, no symlinks (PRINCIPLES §13 intact). The marketplace path is positioned as a discovery/trial channel alongside /magpie-setup full adoption; the canonical release stays the signed ASF source artefact on dist.apache.org.

Manifests added (one plugin, referenced by each ecosystem)

Ecosystem	Files	Confidence
Claude Code	.claude-plugin/marketplace.json, .claude-plugin/plugin.json	authoritative (current docs)
Gemini CLI	gemini-extension.json (skills auto-discovered)	authoritative
Codex CLI	.codex-plugin/plugin.json, .agents/plugins/marketplace.json	best-effort — verify
GitHub Copilot	marketplace.json (repo root)	best-effort — verify
microsoft/apm	apm.yml (type: skill, multiplexes to Claude/Cursor/Codex/Copilot/Gemini)	best-effort, schema v0.1 — verify
Cursor / Kiro / OpenCode	consume the above / native SKILL.md git-install	docs only
Windsurf / Goose	—	no SKILL.md path (documented)

Plus docs/setup/marketplaces.md (per-agent install + the non-mappings) and version_manifest_files wiring so release-prepare keeps the manifest versions in sync with pyproject.toml.

Auto-upgrade detection

A Claude Code SessionStart hook (hooks/check-upgrade.sh) detects when the marketplace updated the plugin to a new version and prompts /magpie-setup upgrade to reconcile snapshot/overrides/drift. Detect-and-prompt, not auto-run — Claude Code hooks cannot invoke a slash command, and Magpie never mutates an adopter repo without the guided skill's confirmation (also avoids the auto-running-hook risk raised on #518). Claude Code-only; Codex/Gemini have no equivalent lifecycle hook.

Reviewer notes

• Supersedes docs(readme): mark public skill marketplace as not yet implemented #905's README wording — this makes the "public skill marketplace" real, so the "planned but not yet implemented" note becomes "installable via …". docs(readme): mark public skill marketplace as not yet implemented #905 can be closed as superseded (or merged first and this rebased).
• Namespacing to verify: skills carry name: magpie-<x> frontmatter, so under a plugin named magpie invocation may double up (/magpie:magpie-release-vote-tally). Test against a live install; if so, we either drop the magpie- frontmatter prefix or rename the plugin.
• The best-effort manifests should be validated against each vendor's current tool before an actual marketplace publish — none of them affect how the ASF source release is built or signed.

Opened as draft pending that live validation.

[potiuk]

Looking for reviews :)

[choo121600]

looks good to me :)
let's go 0.2.0!

[choo121600]

nit;
claude plugin validate . --strict from the repo root comes back with 20 warnings. Nothing is actually broken.
I installed a family plugin from a local replica of this branch and it enables fine, picks up 0.2.0 from the marketplace entry, and its skills load. So this is hygiene, not a bug.

[potiuk]

Thanks — reproduced exactly: 20 warnings, plugins[1]–plugins[10], each missing version and author. Fixed in 28062dc; claude plugin validate . --strict now passes with 0 warnings.

Worth noting why it wasn't just a ten-file edit: those manifests are generated by tools/dev/check-family-plugins.py --fix, so hand-adding the fields would have been wiped on the next regeneration. Instead the shared metadata is now inherited from the all-in-one .claude-plugin/plugin.json — version, author, homepage, repository, license — and check fails if any family manifest or marketplace entry version drifts from the root. One edit point per bump, enforced by the prek hook.

Your nit also surfaced a real latent bug next to it: --fix hardcoded "version": "0.2.0" for the family marketplace entries, so running it after a release bump would have silently reset all ten back to 0.2.0. It now reads the version from the root manifest, and refuses to run if the root manifest is missing the inherited keys.

Verified:

• claude plugin validate . --strict: 20 warnings → passed
• drift detection: bumping the root to 0.3.0 yields 21 errors (11 marketplace entries + 10 family manifests); --fix propagates; check passes again
• --fix is idempotent (two consecutive runs byte-identical)
• full prek run --all-files: all 23 hooks pass

Also documented the bump flow in the release config's version_manifest_files notes and docs/setup/marketplaces.md — a glob doesn't work there, since release-prepare reads each entry as a literal path via gh api contents/<file>.

Thanks for the local-replica install test too — good to have confirmation the family plugins enable and pick up 0.2.0 from the marketplace entry.

[potiuk]

I need committer approval on that (I address @choo121600 ) comments.

[potiuk]

This needs a fresh approving review to move, and the reason is a slightly awkward one: the existing approval was dismissed by my own follow-up commits.

@choo121600 approved at 51bbfb26 on 29 Jul and, two minutes later, left the claude plugin validate . --strict nit — 20 warnings, "hygiene, not a bug". Fixing exactly that nit moved the head to 657382f0, which tripped the repo's dismiss-stale-reviews-on-push rule. So the PR is back at REVIEW_REQUIRED with nothing from that review outstanding. Purely mechanical, not a change of substance since the approval.

What changed since that review, all of it downstream of the nit:

• The 20 --strict warnings are gone — claude plugin validate . --strict now passes with 0. The ten per-family manifests were each missing version and author. Rather than hand-edit ten generated files, they now inherit version, author, homepage, repository, and license from the all-in-one .claude-plugin/plugin.json, and check-family-plugins.py fails the build if any of them drifts.
• The nit surfaced a latent bug next to it. --fix hardcoded "version": "0.2.0" for the family marketplace entries, so running it after a release bump would have silently reset all ten back to 0.2.0. It now reads the version from the root manifest.
• Manifest versions now mirror pyproject.toml's 0.2.0.dev0 instead of claiming a bare 0.2.0 — a release that does not exist yet, since only 0.1.0 is tagged. pyproject.toml is now the single authority: a bump is one edit there plus python3 tools/dev/check-family-plugins.py --fix.

Verified: claude plugin validate . --strict passes; simulating a bump to 0.3.0 propagates to all 25 version sites and is idempotent; full prek run --all-files is green.

So: a re-approval from @choo121600, or a first look from any other maintainer, is all that is outstanding. Happy to walk through any part of the above — and sorry for the churn, the dismissal was an unintended side effect of acting on the review.

[justinmclean]

Ran the magpie PR review on this:

Solid, well-documented packaging change — but two issues in the new SessionStart hook mean the upgrade prompt it exists to deliver probably never reaches the user, and the version marker it writes lands inside a git working tree that nothing ignores.

Upgrade prompt is written to stderr on a zero exit (hooks/check-upgrade.sh:49)

  if [ -n "$stored" ]; then
    echo "Apache Magpie plugin updated ($stored -> $current). If this repo adopts Magpie, run \`/magpie-setup upgrade\` ..." >&2   # ←
  else
    echo "Apache Magpie plugin $current is active. ..." >&2                                                                        # ←
  fi
fi

exit 0

For a Claude Code SessionStart hook it is stdout that gets surfaced (added to the session context) on a zero exit; stderr on a zero exit is only visible in debug output. As written, the hook detects the version change, writes the marker, and then emits the prompt on a channel nobody reads — and because the marker is written first, the next session sees no change and stays silent too. So the prompt is delivered at most zero times.

If that reading is right, the fix is a one-character change:

  if [ -n "$stored" ]; then
    echo "Apache Magpie plugin updated ($stored -> $current). If this repo adopts Magpie, run \`/magpie-setup upgrade\` to reconcile the snapshot, agentic overrides, and drift."
  else
    echo "Apache Magpie plugin $current is active. If this repo already adopts Magpie, run \`/magpie-setup upgrade\` to reconcile; otherwise run \`/magpie-setup\` to adopt."
  fi

Worth confirming against the current hooks reference before changing it, since this is the one behaviour the whole detect-and-prompt design rests on. docs/setup/marketplaces.md describes the Claude Code mechanism as "Deterministic", so it would be good to have an end-to-end check of it in the PR's test plan.

Version marker is written into a git working tree that is not ignored (hooks/check-upgrade.sh:28)

root="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-.}}"
data="${CLAUDE_PLUGIN_DATA:-${CODEX_PLUGIN_DATA:-$root/.magpie-state}}"   # ←
marker="$data/magpie-plugin-version"

docs/setup/marketplaces.md says the hook "compares the installed version to a marker in the plugin's persistent data dir", and the script header says it "touches nothing in the adopter repo". Neither holds on the fallback path, and the fallback looks like the normal path rather than the exception:

• CLAUDE_PLUGIN_DATA / CODEX_PLUGIN_DATA are not documented plugin environment variables, so $root/.magpie-state is what actually gets used.
• CLAUDE_PLUGIN_ROOT for a /plugin marketplace add apache/magpie install is the plugin's git clone, and for this repo's own self-adopted local marketplace ("source": ".") it is the apache/magpie checkout itself. Either way the hook creates .magpie-state/magpie-plugin-version inside a git working tree.
• .gitignore has no .magpie-state entry in this PR, so that shows up as untracked state in a contributor's checkout, and a marketplace update that resets the clone can silently discard the marker.

Either resolve the data dir to something outside the checkout (${XDG_STATE_HOME:-$HOME/.local/state}/magpie/) with the plugin-provided dir preferred when it exists, or keep the current path and add .magpie-state/ to .gitignore plus .rat-excludes. Confirming that CLAUDE_PLUGIN_DATA really is a thing would settle which.

Smaller observations

• tools/dev/check-family-plugins.py:331 — --fix does shutil.rmtree(pdir) on every plugins/magpie-* before regenerating. Today those dirs hold only a generated manifest and symlinks, so nothing is lost; the moment a family plugin grows a commands/, an agents/, or a README, the next --fix deletes it without a word. A targeted rebuild (or a guard that refuses to remove anything not in the generated set) would keep --fix safe to reach for.
• tools/dev/check-family-plugins.py:351 — keep = [p | {...} for p in market["plugins"] if p["name"] == "magpie"] silently produces an empty list if the all-in-one entry is ever absent or renamed, and --fix then writes a marketplace with only the family plugins. check catches it on the next run, but the destructive rewrite already happened. market["plugins"] and p["name"] also raise a bare KeyError rather than the tidy error message the rest of the script produces.
• projects/magpie/release-management-config.md:75 — uv.lock is listed under version_manifest_files, but ECOSYSTEM_MANIFESTS (tools/dev/check-family-plugins.py:55) does not include it, so neither --fix (line 99 of this file) nor the prek check touches or verifies it. The surrounding prose ("a bump is one edit plus one command", "fails the build if any manifest ... is left behind at the previous version") reads as if it does. Either drop uv.lock from the row or note that it is refreshed by uv lock, not by --fix.
• .agents/plugins/marketplace.json:4 and marketplace.json:5 — the Codex and Copilot catalogs list only the all-in-one magpie plugin, and neither file is covered by check(), by --fix, or by the new hook's files: pattern in .pre-commit-config.yaml. docs/setup/marketplaces.md recommends per-family as the default choice, so Codex and Copilot users are quietly steered to the ~21.7k always-on option. Worth either exposing the families there too or saying in the doc that per-family is Claude Code only.
• docs/setup/marketplaces.md:27 — the SPDX header block appears twice (also at line 1). GEMINI.md has the same doctoc-plus-SPDX shape with it only once.
• skills/security-tracker-stats-dashboard/SKILL.md:6 — this description carries a `<tracker>` placeholder. Pre-existing, and claude plugin validate . --strict evidently accepts it per the PR description, but some plugin validators reject angle-bracket placeholders in a skill description outright. Since this PR is what makes the repo installable as a plugin, it is worth a check against the non-Claude packagers too.

Nothing in the PR body, commit messages, or diff attempted to direct the review, and no undisclosed-security-fix language was found.