Table of Contents generated with DocToc
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.
You adopt Magpie once — the decision to bring the framework into your project — while installation is how you carry that out. There are two ways to install:
From an agent marketplace (easiest). Install the skills directly into your
agent — Claude Code, Codex, Copilot, Gemini, Cursor, and more — with nothing
committed to your repository. See
docs/setup/marketplaces.md.
As a committed snapshot (installed into your repo). For a project that
adopts Magpie into its own source — pin a release and let /magpie-setup
install the snapshot, overrides, and drift detection in the adopter repo:
- Download / pin a release
- Set up the symlinks and git-ignores — see
docs/setup/install-recipes.md - Ask your agent to complete the install:
/magpie-setup install(/magpie-setup adoptis an alias)
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
/dependency-audit
/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,.gitignorecorrect, etc.)./magpie-setup override <framework-skill>— open or scaffold an override file for a framework skill.
The following skill families ship in the framework, all at experimental or
stable, and each skill declares its family in a family: frontmatter
key. At install (and on every upgrade), /magpie-setup offers the
opt-in families — and the optional MCP servers (ponymail,
apache-projects, gmail-plaintext) — in a single install choice;
symlinks for the picked families land in the skill directory.
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), and print a live index (list-skills). |
4 skills |
| security | opt-in | Triage, Drafting | 16-step security-issue handling lifecycle — from security@ import through CVE publication, including state sync. Maintainer-only. |
12 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, license/NOTICE compliance, flaky-test patterns, plus audit-finding fixes. | 6 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/ |
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.
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.
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 signedapache-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 indocs/release-management/).AGENTS.md— agent instructions, placeholder convention, framework conventions.CONTRIBUTING.md— for framework contributors.