Table of Contents generated with DocToc

• Apache Magpie
  • Install
  • Usage
  • Update / maintain
  • Skill families
    • External skill sources
  • Acknowledgements
  • Cross-references

Apache Magpie

Adopt a Magpie. Apache Magpie provides high-quality recipes for agent-assisted software project maintenance.

These recipes allow human maintainers working with AIs to efficiently handle the repetitive parts of running an open-source project: issue triage, PR review, mentoring contributors, managing security reports, and more.

Magpie is currently in development for ASF projects + Python Core team friendlies. Testers welcome!

[!IMPORTANT] The motivation, scope, and design commitments behind this work live in MISSION.md — the founding mission of the Apache Magpie Top-Level Project, originally filed as its establishment proposal. Read that for the why; this README is the how once you've decided to install.

Install

Start here → Quick start — two commands, in the agent you already use.

/plugin marketplace add apache/magpie              # Claude Code
/plugin install magpie-setup@apache-magpie         # always take this one
/plugin install magpie-pr-management@apache-magpie # + whichever families you need

Install one plugin per family you actually want — that keeps the always-on context cost proportional (~0.2–2.0k tokens a family). The all-in-one magpie plugin installs all 74 skills at ~8.6k always-on tokens and is not recommended unless you genuinely need every family.

Codex, VS Code / Copilot, and Gemini are one-liners too — the quick start has all four, plus what to run next to put the agent in its sandbox. Nothing is committed to your repository.

Fallback — the pinned snapshot install. Use it when a marketplace is not an option or not enough: your agent has no plugin mechanism, you need the signed ASF source release rather than a git clone, or the project wants every contributor and CI job pinned to one committed version with drift detection.

1. Download / pin a release
2. Set up the symlinks and git-ignores — see docs/setup/install-recipes.md
3. Ask your agent to complete the install: /magpie-setup install

The two are complementary, not exclusive.

Usage

Magpie is used by interacting with your AI agents. You'll use plain-language prompts like

review PR #5193

or

triage the latest security reports

or skill calls starting with a slash, like

/magpie-repo-health:dependency-audit

(the family-plugin form, assuming the recommended marketplace install above — see Skill names differ by install method if you're on the pinned-snapshot fallback instead).

Update / maintain

Marketplace install (the recommended path above):

• /plugin marketplace update apache-magpie then /plugin update <plugin>@apache-magpie — refresh the marketplace metadata, then bump the installed plugin(s) to its latest.
• Add or drop families by installing or uninstalling their plugin — there is no separate "pick families" step once you're on a marketplace install.

Pinned-snapshot install (the fallback):

• /magpie-setup upgrade — refresh the snapshot to a newer framework version + reconcile any overrides against the new framework structure.
• /magpie-setup verify — read-only health check (snapshot intact, symlinks live, .gitignore correct, etc.).
• /magpie-setup override <framework-skill> — open or scaffold an override file for a framework skill.

Skill families

The following skill families ship in the framework, all at experimental or stable, and each skill declares its family in a family: frontmatter key. On the recommended marketplace install, you choose families by which per-family plugin(s) you install (see Install above) — install or uninstall a plugin at any time to add or drop a family. On the pinned-snapshot fallback, /magpie-setup offers the opt-in families — and the optional MCP servers (ponymail, apache-projects, gmail-plaintext) — in a single install choice, and symlinks for the picked families land in the skill directory. Either way, the two always-on families (setup, utilities) are wired unconditionally and never prompted for.

The Modes column maps each family to the MISSION agent-assistance taxonomy — see docs/modes.md for what each mode means and which modes are still proposed vs. shipping today.

Family	Type	Modes	Purpose	Detail
setup	always-on	(infra)	Isolated agent setup, framework install + maintenance, shared-config sync. The prerequisite — at minimum the setup skill itself runs out of this family.	9 skills, docs/setup/
utilities	always-on	(meta)	Framework meta-skills: author skills (write-skill), restructure them (optimize-skill), reconcile skill state (skill-reconciler), report framework issues (report-framework-issue), and print a live index (list-skills).	5 skills
security	opt-in	Triage, Drafting	16-step security-issue handling lifecycle — from security@ import through CVE publication, including state sync — plus producing, verifying, and maintaining the project's own security model. Maintainer-only.	15 skills, docs/security/
pr-management	opt-in	Triage	Maintainer-facing PR-queue management — triage, stats, deep code review, express-lane merge, stale-sweep, reviewer routing, and pre-first-PR checks.	8 skills, docs/pr-management/
issue	opt-in	Triage, Drafting	General-issue lifecycle: triage, reproduction, fix drafting, reassess, stale-sweep, deduplication, and backlog reporting.	8 skills, docs/issue-management/
release-management	opt-in	Triage, Drafting	14-step ASF release lifecycle, planning issue, RC cut + sign, [VOTE] thread, tally, promote, [ANNOUNCE], archive, audit log. Agent never holds the RM's signing key and never publishes the release. Experimental, all 10 skills shipped.	10 skills, docs/release-management/
repo-health	opt-in	Triage	Read-only repository-health audits: obsolete runner labels, Actions workflow security, dependency vulnerabilities, dependency licence review, license/NOTICE compliance, flaky-test patterns, plus audit-finding fixes.	7 skills, docs/repo-health/
pairing	opt-in	Pairing	Pair a change with a structured self-review or a multi-agent adversarial review before it lands.	2 skills, docs/pairing/
mentoring	opt-in	Mentoring	Newcomer-facing mentoring — first-contact welcome, newcomer-issue explanations, and good-first-issue authoring + backlog curation. Experimental.	4 skills, docs/mentoring/
contributor-growth	opt-in	Triage, Mentoring	The path-to-committer track: activity sweeps, nomination briefs, contributor-sentiment signals, readiness tracking, and committer / post-vote onboarding.	6 skills, docs/contributor-growth/

External skill sources

Skill families or individual skills can be pulled from a trusted external source — a repo other than apache/magpie that ships Magpie-shaped skills (with their evals and tests). Where a skill directory would sit, a skills/<name>/source.md redirect names a pinned, verified source the adopter has vouched for; /magpie-setup fetches it into the gitignored snapshot and wires it in exactly like a framework skill. Nothing is fetched unless the adopter commits the pin — see docs/skill-sources/, PRINCIPLES.md §13, and RFC-AI-0006.

Acknowledgements

Apache Magpie was first developed and proven inside Apache Airflow, and was maintained for a time as the apache/airflow-steward repository under the Airflow PMC before being renamed and established as its own project. It also incorporates early skill work contributed by way of the Apache Groovy community. All of that code carries the same rightsholder — Copyright The Apache Software Foundation, under the Apache License 2.0 — so it is not a third-party inclusion; the required attribution lines from the originating projects' NOTICE files are reproduced in NOTICE.

Cross-references

• MISSION.md — founding mission of the established TLP: motivation, scope, design commitments, initial PMC composition target.
• docs/setup/agentic-overrides.md — the contract between adopters who write overrides and framework skills that read them.
• docs/prerequisites.md — what a maintainer needs installed before invoking any framework skill (Claude Code, Gmail MCP, GitHub auth, browser, uv, etc.).
• docs/source-release-contents.md — what ships in the signed apache-magpie-<version>-source.zip (and what is excluded), with the rationale for the repository-root metadata/config files it keeps.
• docs/release-management/manual-release-process.md — the concrete, as-executed runbook for cutting a Magpie release by hand on the current hybrid SVN-dist + ATR-vote backend (with the abstract per-backend runbooks and the 14-step lifecycle alongside it in docs/release-management/).
• AGENTS.md — agent instructions, placeholder convention, framework conventions.
• CONTRIBUTING.md — for framework contributors.