Simplify readme - #901
Closed
meonkeys wants to merge 5 commits into
Closed
Conversation
Just a suggestion. I started this patch to fix the duplication of the words "creation and maintenance of software related to" and then ended up rewriting the whole thing, mostly based on the (IMHO better) wording I found at https://magpie.apache.org .
This is a readme, not an architecture showcase. I pared it down to more of a "quick start" type of doc. Lots of the text is duplicated in gory detail elsewhere in the docs / skills. "Public marketplace skill" didn't mean anything special to me so I went with just "in testing" (when I said "Testers welcome!"). I didn't find the unfamiliar "adoption" terminology helpful either. Culled, and replaced with the much more standard (IMHO) "install". If we really want to use new/nonstandard words, we should include a glossary. After making changes I ran doctoc. I used doctoc v2.5.0. fix apache#899
Member
|
please fix the prek/conflicts |
potiuk
added a commit
to potiuk/magpie
that referenced
this pull request
Jul 19, 2026
…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.
Member
|
Thanks @meonkeys — this simplification is a real improvement, and I've folded it into #907 (the 0.2.0 marketplace PR), where the README also gains the marketplace install path and leads with "install" (with "adopt" kept as an alias and "Adopt a Magpie" as the slogan). Your Install/Usage/Update structure is preserved. Since #899 (this PR's |
potiuk
added a commit
to potiuk/magpie
that referenced
this pull request
Aug 13, 2026
…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.
potiuk
added a commit
to potiuk/magpie
that referenced
this pull request
Aug 17, 2026
…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.
potiuk
added a commit
that referenced
this pull request
Aug 18, 2026
…uto-upgrade hook (#907) * feat(marketplace): distribute Magpie 0.2.0 via agent plugin marketplaces 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 #518. * feat(marketplace): auto-detect plugin updates and prompt for upgrade 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. * feat(marketplace): prompt Codex and Gemini users to run upgrade 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. * docs(readme): fold #901 README simplification; lead with install (adopt alias) Folds the top-level README simplification from #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 #901 (its Fix #899 goal already merged via #905). Credit to @meonkeys for the simplification. * docs(readme): project adopts Magpie; installation is the mechanism 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. * docs(readme): explain adopt (relationship) vs install (process) in the Install section * docs(marketplaces): detailed per-agent install steps from the GitHub 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). * feat(marketplace): split into per-family plugins to cut always-on token 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. * build(prek): add check-family-plugins hook; document Windows symlink 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. * docs(marketplaces): explain all-in-one vs per-family install trade-offs 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. * docs(marketplaces): flag marketplace support as experimental; point to 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. * docs(marketplaces): explain skill-name differences across install methods 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. * fix(security): close files in check-family-plugins; use pathlib Resolves the 3 CodeQL 'file is not always closed' alerts (35/36/37) flagged on #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). * build(prek): validate all plugin manifests, not just family symlinks 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. * fix(marketplace): give family plugins version + author metadata `claude plugin validate . --strict` reported 20 warnings — each of the ten per-family plugin manifests was missing `version` and `author`. Nothing was broken (a family plugin installs and enables fine), but --strict treats the warnings as errors, so the repo root failed validation. Rather than hand-edit ten generated files, make the shared metadata inherited: `tools/dev/check-family-plugins.py` now copies `version`, `author`, `homepage`, `repository`, and `license` from the all-in-one `.claude-plugin/plugin.json` into every family manifest, and `check` fails if any of them — or a marketplace entry version — drifts from the root. This also removes the hardcoded `"version": "0.2.0"` in `--fix`, which would have silently reset the family marketplace entries to 0.2.0 after a release bump. A bump now has one edit point (the root manifest) plus `python3 tools/dev/check-family-plugins.py --fix` to propagate; the prek hook catches a missed propagation. Documented in the release config's `version_manifest_files` notes and docs/setup/marketplaces.md. `claude plugin validate . --strict` now passes with 0 warnings. * fix(marketplace): mirror pyproject's dev version in every manifest Every plugin manifest claimed version `0.2.0` while `pyproject.toml` sits at `0.2.0.dev0` (the post-0.1.0 bump, #906). Only `0.1.0` is tagged, so the manifests were advertising a release that does not exist yet — and the docs claimed they were "kept in sync with pyproject.toml", which they were not. Make `pyproject.toml`'s `project.version` the single authority and mirror it verbatim, `.devN` suffix included. The version now flows outward in two hops, neither hand-edited: pyproject.toml -> .claude-plugin/plugin.json, .codex-plugin/plugin.json, gemini-extension.json, apm.yml -> the 10 generated family manifests + 11 marketplace entries `check` fails on drift at either hop; `--fix` propagates both. A release bump is now one edit plus one command. Mirroring the PEP 440 string rather than translating it to a semver prerelease (`0.2.0-dev.0`) is deliberate: `release-prepare` step 2a bumps `version_manifest_files` by literal search/replace, which only works if every manifest carries the identical string — and dev versions are never published to a marketplace, so the suffix never reaches a consumer. `claude plugin validate --strict` accepts it, and hooks/check-upgrade.sh compares versions as opaque strings. Version rewrites are textual substitutions, not json.dumps() round-trips, so bumping does not reformat these hand-authored manifests (escaping em-dashes, expanding inline objects); each write is verified by re-parsing. Verified: `claude plugin validate . --strict` passes; simulating a bump to 0.3.0 propagates to all 25 version sites and is idempotent; prek passes (end-of-file-fixer skipped locally — sandbox denies it a write to an unrelated file). * feat(marketplace): support Agent Plugins 1.0 alongside the client manifests Agent Plugins 1.0.0 was published on 2026-08-06 — a vendor-neutral standard for packaging Agent Skills and MCP servers, from a TSC drawn from Amazon, Cursor, Microsoft, OpenAI and Vercel, with Google since joined. Support is GA in VS Code, Copilot CLI, the Copilot app and the Copilot SDK as of 2026-08-12. This PR predates it, so it packaged for five client-specific formats and none of the standard. Add the AP1 manifest without disturbing any of them: - New root `plugin.json` — the AP1 manifest, pinning the canonical `$schema`. VS Code auto-detects the plugin format from the root manifest and reads that field as the AP1 marker; without it the same file is treated as a legacy Copilot manifest. Conformance needed no file moves: AP1 fixes skills at `skills/<name>/SKILL.md`, which is already the layout, and its schema is closed, so it carries metadata only — no `skills` path, no `hooks` block. - `check-family-plugins.py` validates the new manifest (pinned `$schema`, name pattern, the closed ten-field set, `author` sub-keys, metadata inherited from the Claude manifest) and adds it to the version-mirroring set, so a bump stays one edit plus `--fix`. - Wire it into the prek hook's `files:` pattern and `version_manifest_files`. Verified: validates clean against the published `plugin.schema.json`; 70 skills resolve under the AP1 discovery rule; no symlink under `skills/` escapes the plugin root; `claude plugin validate . --strict` still passes; all 23 prek hooks green. Also fixes three defects found while checking each manifest against its vendor's current documentation: - `hooks/check-upgrade.sh` wrote its upgrade prompt to **stderr** and exited 0. For a `SessionStart` hook exiting 0 it is stdout that is added to the session context; stderr only reaches the debug log. Since the version marker was written first, the next session saw no change and stayed silent too — so the prompt was delivered exactly zero times. Now on stdout, and tested across all three transitions. - The marker's fallback directory was `$root/.magpie-state`, inside a git working tree that nothing ignores and that a plugin update can replace wholesale. `CLAUDE_PLUGIN_DATA` is real and documented, but `CODEX_PLUGIN_DATA` is not; fall back to `$XDG_STATE_HOME/magpie` instead, never into the checkout. - `.codex-plugin/plugin.json` invoked the hook via `${CODEX_PLUGIN_ROOT}`, which Codex does not export. It exports `PLUGIN_ROOT`/`PLUGIN_DATA` and the `CLAUDE_*` pair for compatibility. Docs: `marketplaces.md` gains a section on the two manifest families and which client reads which, an install path for VS Code/Copilot, a per-manifest verification table replacing the prose "best-effort" note, and the recorded limitation that the per-family plugins cannot be AP1 packages — their skill symlinks deliberately escape the family root, and materialising them would mean vendored copies that PRINCIPLES §13 rules out. AP1 clients install the all-in-one plugin, whose `skills/` is the real tree. Also notes openai/codex#16430, under which Codex may not fire plugin-local hooks yet, and drops a duplicated SPDX header. * fix(marketplace): close the open items from the review of #907 Four findings from Justin's review, plus the one they turned up. `--fix` destroyed anything it did not generate. It ran `shutil.rmtree()` over every `plugins/magpie-*` before regenerating. That is safe only while those directories hold nothing but a generated manifest and symlinks; the first time a family grows a `commands/`, an `agents/`, or a README, the next `--fix` would delete it without a word. It now enumerates what regeneration owns — `.claude-plugin/plugin.json` and symlinks under `skills/` — and refuses, naming the file, on anything else. The scan runs over all ten families *before* the first delete, so a stray file in the last one cannot leave the first nine destroyed. `--fix` could write a marketplace with only the family entries. The all-in-one entry is carried over rather than regenerated, so `[p | ... for p in market["plugins"] if p["name"] == "magpie"]` silently yielded `[]` if that entry was ever absent or renamed — and the destructive rewrite landed before `check` could catch it on the next run. It now bails with a message that says what to restore. The same line raised a bare `KeyError` on a malformed catalog instead of the tidy error the rest of the script produces; both lookups are guarded. The Codex and Copilot catalogs were covered by nothing. Neither `.agents/plugins/marketplace.json` nor the root `marketplace.json` was read by `check`, by `--fix`, or by the prek hook's `files:` pattern. `check` now verifies both list the all-in-one plugin and *only* that, and both are in the hook pattern. Only-that is the right rule rather than an omission to fix: the family plugins reach their skills through symlinks that resolve outside the family's own root, which Agent Plugins 1.0 forbids, so offering them to Codex or Copilot would advertise something those clients cannot install. `marketplaces.md` says so in both install sections. `uv.lock` was listed under `version_manifest_files` beside manifests that `--fix` propagates, though `ECOSYSTEM_MANIFESTS` does not include it and neither `--fix` nor the prek check touches it. Noted as refreshed by `uv lock`, which the Step 2a bump already runs. The `<tracker>` placeholder in a skill description is conformant, and this is the one finding that needed checking rather than fixing. It is not one skill: 41 of the 70 descriptions carry the framework's `<placeholder>` syntax, so "rewrite it" would mean unpicking the convention in AGENTS.md. The Agent Skills specification — which AP1 defers to for skill validity — constrains `description` on length alone (1–1024 characters, non-empty) and says nothing about angle brackets; the character-class rules apply to `name`, which every skill satisfies. Longest description is 953 characters. Recorded in `marketplaces.md` so the question does not get re-opened from scratch. Verified: each of the three destructive paths aborts with the tree intact (ten families still present, marketplace byte-identical); the catalog rule fires on a planted family entry; `--fix` stays idempotent; all 23 prek hooks green.
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.
Summary
Fix #899.
This PR builds on #898. Please merge that one first, or if that one won't be merged just LMK and I'll rebase on
main. Because of this, the "Files changed" tab won't make sense. You can review only the changes for this PR at meonkeys@ba9bce0Type of change
.claude/skills/<name>/) — eval fixtures updated belowtools/<system>/*.md)tools/*/withpyproject.toml)docs/,README.md,CONTRIBUTING.md)projects/_template/)prek, workflows, validators)After making changes I ran doctoc. I used doctoc v2.5.0.
Test plan
not applicable
RFC-AI-0004 compliance
not applicable, AFAICT
Linked issues
None. This is a drive-by PR but I'll stick around to absorb feedback, discuss, improve, etc.
Notes for reviewers (optional)
I joined the
#magpieSlack channel in case you want to ping me in there. My handle ismeonkeysin there as well.