{
  "markdown": "<!-- SPDX-License-Identifier: Apache-2.0\n     https://www.apache.org/licenses/LICENSE-2.0 -->\n\n<!-- START doctoc generated TOC please keep comment here to allow auto update -->\n<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->\n**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n- [Apache Magpie](#apache-magpie)\n  - [Install](#install)\n  - [Usage](#usage)\n  - [Update / maintain](#update--maintain)\n  - [Skill families](#skill-families)\n    - [External skill sources](#external-skill-sources)\n  - [Acknowledgements](#acknowledgements)\n  - [Cross-references](#cross-references)\n\n<!-- END doctoc generated TOC please keep comment here to allow auto update -->\n\n<!-- SPDX-License-Identifier: Apache-2.0\n     https://www.apache.org/legal/release-policy.html -->\n\n# Apache Magpie\n\n[![Magpie](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/apache/magpie/main/assets/badge.json)](https://magpie.apache.org/)\n\n**Adopt a Magpie.** Apache Magpie provides high-quality recipes for\nagent-assisted software project maintenance.\n\nThese recipes allow human maintainers working with AIs to efficiently handle\nthe repetitive parts of running an open-source project: issue triage, PR\nreview, mentoring contributors, managing security reports, and more.\n\nMagpie is currently in development for ASF projects + Python Core team\nfriendlies. Testers welcome!\n\n> [!IMPORTANT]\n> The motivation, scope, and design commitments behind this work\n> live in [`MISSION.md`](MISSION.md) — the founding mission of the\n> Apache Magpie Top-Level Project, originally filed as its\n> establishment proposal. Read that for the *why*; this README is\n> the *how* once you've decided to install.\n\n## Install\n\nYou **adopt** Magpie once — the decision to bring the framework into your\nproject — while **installation** is how you carry that out. There are two\nways to install:\n\n**From an agent marketplace (easiest).** Install the skills directly into your\nagent — Claude Code, Codex, Copilot, Gemini, Cursor, and more — with nothing\ncommitted to your repository. See\n[`docs/setup/marketplaces.md`](docs/setup/marketplaces.md).\n\n**As a committed snapshot (installed into your repo).** For a project that\nadopts Magpie into its own source — pin a release and let `/magpie-setup`\ninstall the snapshot, overrides, and drift detection in the adopter repo:\n\n1. [Download / pin a release](https://magpie.apache.org/downloads/)\n2. Set up the symlinks and git-ignores — see\n   [`docs/setup/install-recipes.md`](docs/setup/install-recipes.md)\n3. Ask your agent to complete the install: `/magpie-setup install`\n   (`/magpie-setup adopt` is an alias)\n\n## Usage\n\nMagpie is used by interacting with your AI agents. You'll use plain-language\nprompts like\n\n> review PR #5193\n\nor\n\n> triage the latest security reports\n\nor skill calls starting with a slash, like\n\n> /dependency-audit\n\n## Update / maintain\n\n- `/magpie-setup upgrade` — refresh the snapshot to a newer\n  framework version + reconcile any overrides against the new\n  framework structure.\n- `/magpie-setup verify` — read-only health check (snapshot\n  intact, symlinks live, `.gitignore` correct, etc.).\n- `/magpie-setup override <framework-skill>` — open or\n  scaffold an override file for a framework skill.\n\n## Skill families\n\nThe following skill families ship in the framework, all at `experimental` or\n`stable`, and each skill declares its family in a `family:` frontmatter\nkey. At install (and on every upgrade), `/magpie-setup` offers the\n**opt-in** families — and the optional **MCP servers** (`ponymail`,\n`apache-projects`, `gmail-plaintext`) — in a single install choice;\nsymlinks for the picked families land in the skill directory.\nThe two **always-on** families (`setup`, `utilities`) are wired\nunconditionally and never prompted for.\n\nThe **Modes** column maps each family to the MISSION agent-assistance\ntaxonomy — see [`docs/modes.md`](docs/modes.md) for what each mode\nmeans and which modes are still proposed vs. shipping today.\n\n| Family | Type | Modes | Purpose | Detail |\n|---|---|---|---|---|\n| [**setup**](docs/setup/README.md) | 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/`](docs/setup/) |\n| **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 |\n| [**security**](docs/security/README.md) | 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/`](docs/security/) |\n| [**pr-management**](docs/pr-management/README.md) | 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/`](docs/pr-management/README.md) |\n| [**issue**](docs/issue-management/README.md) | opt-in | Triage, Drafting | General-issue lifecycle: triage, reproduction, fix drafting, reassess, stale-sweep, deduplication, and backlog reporting. | 8 skills, [`docs/issue-management/`](docs/issue-management/README.md) |\n| [**release-management**](docs/release-management/README.md) | 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/`](docs/release-management/) |\n| [**repo-health**](docs/repo-health/README.md) | 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/`](docs/repo-health/) |\n| [**pairing**](docs/pairing/README.md) | opt-in | Pairing | Pair a change with a structured self-review or a multi-agent adversarial review before it lands. | 2 skills, [`docs/pairing/`](docs/pairing/README.md) |\n| [**mentoring**](docs/mentoring/README.md) | opt-in | Mentoring | Newcomer-facing mentoring — first-contact welcome, newcomer-issue explanations, and good-first-issue authoring + backlog curation. **Experimental**. | 4 skills, [`docs/mentoring/`](docs/mentoring/README.md) |\n| [**contributor-growth**](docs/contributor-growth/README.md) | 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/`](docs/contributor-growth/README.md) |\n\n### External skill sources\n\nSkill families or individual skills can be pulled\nfrom a **trusted external source** — a repo other than `apache/magpie` that\nships Magpie-shaped skills (with their evals and tests). Where a skill\ndirectory would sit, a `skills/<name>/source.md` **redirect** names a\npinned, verified source the adopter has vouched for; `/magpie-setup` fetches\nit into the gitignored snapshot and wires it in exactly like a framework\nskill. Nothing is fetched unless the adopter commits the pin — see\n[`docs/skill-sources/`](docs/skill-sources/README.md),\n[`PRINCIPLES.md` §13](PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies),\nand [`RFC-AI-0006`](docs/rfcs/RFC-AI-0006.md).\n\n## Acknowledgements\n\nApache Magpie was first developed and proven inside **Apache Airflow**, and was\nmaintained for a time as the `apache/airflow-steward` repository under the\nAirflow PMC before being renamed and established as its own project. It also\nincorporates early skill work contributed by way of the **Apache Groovy**\ncommunity. All of that code carries the same rightsholder — Copyright The Apache\nSoftware Foundation, under the Apache License 2.0 — so it is not a third-party\ninclusion; the required attribution lines from the originating projects' NOTICE\nfiles are reproduced in [`NOTICE`](NOTICE).\n\n## Cross-references\n\n- [`MISSION.md`](MISSION.md) — founding mission of the established TLP: motivation, scope, design commitments, initial PMC composition target.\n- [`docs/setup/agentic-overrides.md`](docs/setup/agentic-overrides.md) — the contract between adopters who write overrides and framework skills that read them.\n- [`docs/prerequisites.md`](docs/prerequisites.md) — what a maintainer needs installed before invoking any framework skill (Claude Code, Gmail MCP, GitHub auth, browser, `uv`, etc.).\n- [`docs/source-release-contents.md`](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.\n- [`docs/release-management/manual-release-process.md`](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/`](docs/release-management/README.md)).\n- [`AGENTS.md`](AGENTS.md) — agent instructions, placeholder convention, framework conventions.\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — for framework contributors.\n",
  "bytes": 9570,
  "sha": "8ea36997856817305b619f7bcdfee78ee82c2f3b045c1f8f72520cf6546dc7c1",
  "repo_slug": "apache/magpie",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_apache_magpie_6b8655bc/readme"
}