feat(marketplace): distribute Magpie 0.2.0 via agent marketplaces + auto-upgrade hook#907
Open
potiuk wants to merge 14 commits into
Open
feat(marketplace): distribute Magpie 0.2.0 via agent marketplaces + auto-upgrade hook#907potiuk wants to merge 14 commits into
potiuk wants to merge 14 commits into
Conversation
Package the framework as a single 'magpie' plugin (skills: ./skills, all 70) and add the manifests each agent marketplace needs, referencing the existing skills tree with no vendored copies: - Claude Code: .claude-plugin/marketplace.json + plugin.json - Codex CLI: .codex-plugin/plugin.json + .agents/plugins/marketplace.json - Copilot: marketplace.json (repo root) - Gemini CLI: gemini-extension.json (skills auto-discovered) - microsoft/apm: apm.yml (type: skill; multiplexes to Claude/Cursor/Codex/Copilot/Gemini) Adds docs/setup/marketplaces.md (per-agent install, incl. Kiro/OpenCode git-install and the Windsurf/Goose non-mappings), positions the marketplace path as a discovery/trial channel alongside /magpie-setup, keeps the ASF source release canonical, and wires the version-bearing manifests into version_manifest_files so release-prepare keeps them in sync. Refs apache#518.
Add a Claude Code SessionStart hook (hooks/check-upgrade.sh, wired via the plugin's hooks block) that detects when the marketplace has updated the Magpie plugin to a new version and prompts the user to run `/magpie-setup upgrade` to reconcile the snapshot, agentic overrides, and 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, so the trigger is automatic while the changes stay confirmed. Claude Code-only; Codex/Gemini have no equivalent lifecycle hook.
Extend the update-detection prompt beyond Claude Code: - Make hooks/check-upgrade.sh agent-neutral (resolves CLAUDE_/CODEX_ plugin root+data env vars; reads version from whichever plugin manifest is present). - Codex CLI: wire the same script via the plugin's hooks block (schema best-effort, flagged for verification before publish). - Gemini CLI: ship GEMINI.md extension context (contextFileName) instructing the agent to compare the extension version to a recorded marker and prompt for /magpie-setup upgrade on change — Gemini has no lifecycle hook. Documented per-agent in docs/setup/marketplaces.md.
potiuk
force-pushed
the
feat/marketplace-distribution-0.2.0
branch
from
July 19, 2026 03:32
4864c08 to
1ecaade
Compare
potiuk
marked this pull request as ready for review
July 19, 2026 11:47
…l (adopt alias) Folds the top-level README simplification from apache#901 (by @meonkeys) into the 0.2.0 marketplace work, and shifts the primary term to 'install' now that marketplace installation exists: - Keeps Adam's simplified Install / Usage / Update / Skill-families structure. - Install section covers both paths: agent marketplace (easiest, nothing committed) and the committed snapshot via /magpie-setup. - 'install' is the primary verb/command; '/magpie-setup adopt' stays an alias; 'Adopt a Magpie' remains the landing-page slogan; 'adopter'/'adopter repo' kept as the ecosystem noun. - Repoints inbound doc links from the removed README#adopting-the-framework anchor to README#install and updates their labels. Supersedes the standalone apache#901 (its Fix apache#899 goal already merged via apache#905). Credit to @meonkeys for the simplification.
This was referenced Jul 19, 2026
Closed
Keep 'adopt' for the project relationship and 'install/installation' for the process, per the terminology model: a project adopts Magpie into its source; /magpie-setup installs the snapshot.
…e Install section
…marketplace Expand docs/setup/marketplaces.md from a one-line-per-agent table into step-by-step instructions for installing Magpie from the apache/magpie GitHub repo-as-marketplace: add marketplace, install, verify, invoke, update — for Claude Code, Codex, Copilot, Gemini, Cursor, apm, Kiro, OpenCode. States plainly that the GitHub repo is the marketplace (no vendor official directory needed) and how to pin a tag vs track main. Verify-flagged the still-evolving CLIs (Codex/Copilot/apm/Cursor).
…en cost Live-tested that Claude Code's plugin 'skills' field rejects paths outside the plugin dir, so per-family plugins reference the shared skills/ tree via single-hop symlinks (no copies, single source of truth). - Add 10 family plugins under plugins/magpie-<family>/ (security, release- management, setup, pr-management, issue, repo-health, contributor-growth, utilities, mentoring, pairing), each a .claude-plugin/plugin.json + a skills/ dir of symlinks into ../../../skills/<skill>. - marketplace.json now lists the all-in-one 'magpie' plugin plus the 10 families. Family plugin.jsons omit version and inherit it from the marketplace entry (centralised versioning). - Verified via real installs: e.g. magpie-security = 12 skills / ~3.9k always-on, magpie-pairing = 2 / ~0.6k, vs the all-in-one 70 / ~21.7k. - Namespacing confirmed clean: /magpie-<family>:<skill> (dir name, no magpie- frontmatter double-prefix). Docs: docs/setup/marketplaces.md gains the all-in-one-vs-per-family guidance and per-family token costs.
…caveat - tools/dev/check-family-plugins.py: validates that plugins/magpie-<family>/ match the skills' family: frontmatter (each family's skills present as single-hop symlinks into skills/, and listed in marketplace.json). Catches a new skill, a changed family, or a stale symlink. --fix regenerates them. - Wire it as a local prek hook (runs when a SKILL.md, a family plugin, or the marketplace manifest changes). - docs/setup/marketplaces.md: document that per-family plugins rely on git symlinks — on Windows enable core.symlinks + Developer Mode, or use the all-in-one magpie plugin (no symlinks). Verified symlinks survive a GitHub clone on macOS.
Spell out that you can install either the all-in-one magpie plugin or any number of per-family plugins (and mix families), with the pros/cons of each: simplicity + Windows-safe (no symlinks) vs proportional always-on token cost.
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
…o the portable non-marketplace install Add a WARNING callout: plugin/marketplace mechanisms across the agentic CLIs (Claude Code, Codex, Copilot, Gemini, apm) are experimental and change between releases. The non-marketplace /magpie-setup install from the signed SVN release or the GitHub repo is always available, harness-neutral, and portable — it works on every agentic CLI via the universal .agents/skills/ layout, not just the ones with a marketplace.
…hods Same skill, different invocation name: portable /magpie-setup install bakes a magpie- prefix into each skill (invoked /magpie-<name>), whereas a marketplace plugin namespaces with plugin:skill and keeps the bare name (/magpie:<name> for the all-in-one, /magpie-<family>:<name> for a family plugin). Adds a comparison table + examples and notes that repo cross-references use the portable form.
Resolves the 3 CodeQL 'file is not always closed' alerts (35/36/37) flagged on apache#907. Rewrite the family-plugin validator with pathlib — Path.read_text / write_text open-and-close by construction, so no dangling handles — and the same read/write/symlink logic reads cleaner. Behaviour unchanged (check/--fix verified: passes, idempotent, catches drift).
Extend check-family-plugins to confirm every plugin is properly defined: - all-in-one 'magpie' manifest names itself, declares skills: ./skills, and wires the hooks/check-upgrade.sh SessionStart hook (which must exist); - every marketplace.json entry resolves to a matching, uniquely-named plugin.json (catches dangling sources, name mismatches, duplicates); - each per-family manifest is well-formed (name/skills/description) in addition to the existing symlink-vs-frontmatter check. Also trigger the hook on .claude-plugin/plugin.json and hooks/check-upgrade.sh changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
magpieplugin whoseskillspoints at the existing./skillstree — no file moves, no vendored copies, no symlinks (PRINCIPLES §13 intact). The marketplace path is positioned as a discovery/trial channel alongside/magpie-setupfull adoption; the canonical release stays the signed ASF source artefact ondist.apache.org.Manifests added (one plugin, referenced by each ecosystem)
.claude-plugin/marketplace.json,.claude-plugin/plugin.jsongemini-extension.json(skills auto-discovered).codex-plugin/plugin.json,.agents/plugins/marketplace.jsonmarketplace.json(repo root)apm.yml(type: skill, multiplexes to Claude/Cursor/Codex/Copilot/Gemini)SKILL.mdgit-installWindsurf/GooseSKILL.mdpath (documented)Plus
docs/setup/marketplaces.md(per-agent install + the non-mappings) andversion_manifest_fileswiring sorelease-preparekeeps the manifest versions in sync withpyproject.toml.Auto-upgrade detection
A Claude Code
SessionStarthook (hooks/check-upgrade.sh) detects when the marketplace updated the plugin to a new version and prompts/magpie-setup upgradeto 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
name: magpie-<x>frontmatter, so under a plugin namedmagpieinvocation may double up (/magpie:magpie-release-vote-tally). Test against a live install; if so, we either drop themagpie-frontmatter prefix or rename the plugin.Opened as draft pending that live validation.