{"id":51425154,"url":"https://github.com/apache/magpie","last_synced_at":"2026-07-05T02:01:00.886Z","repository":{"id":354517197,"uuid":"1223894967","full_name":"apache/magpie","owner":"apache","description":"Agent-assisted maintainership and development framework for Apache projects — Triage and Drafting (agent-authored fixes with human review); Mentoring, Pairing (developer-side dev-cycle), and Auto-merge on the roadmap.","archived":false,"fork":false,"pushed_at":"2026-07-04T22:48:39.000Z","size":9058,"stargazers_count":53,"open_issues_count":53,"forks_count":39,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-07-05T00:12:33.363Z","etag":null,"topics":["agent-skills","apache","automation","claude-code","cve","security","vulnerability-disclosure","vulnerability-management"],"latest_commit_sha":null,"homepage":"https://magpie.apache.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apache.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security/README.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-28T18:59:46.000Z","updated_at":"2026-07-04T22:48:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/apache/magpie","commit_stats":null,"previous_names":["apache/airflow-steward","apache/magpie"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/apache/magpie","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fmagpie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fmagpie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fmagpie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fmagpie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apache","download_url":"https://codeload.github.com/apache/magpie/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fmagpie/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35141083,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","apache","automation","claude-code","cve","security","vulnerability-disclosure","vulnerability-management"],"created_at":"2026-07-05T02:00:39.154Z","updated_at":"2026-07-05T02:01:00.875Z","avatar_url":"https://github.com/apache.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n- [Apache Magpie](#apache-magpie)\n  - [How adoption works](#how-adoption-works)\n  - [Adopting the framework](#adopting-the-framework)\n    - [1. Bootstrap (copy-pasteable shell)](#1-bootstrap-copy-pasteable-shell)\n    - [2. Skill takeover](#2-skill-takeover)\n    - [Subsequent contributors](#subsequent-contributors)\n    - [Drift detection](#drift-detection)\n  - [Skill families](#skill-families)\n    - [External skill sources](#external-skill-sources)\n  - [Maintenance](#maintenance)\n  - [Cross-references](#cross-references)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\u003c!-- SPDX-License-Identifier: Apache-2.0\n     https://www.apache.org/legal/release-policy.html --\u003e\n\n# Apache Magpie\n\nA reusable, project-agnostic framework for ASF-project automation.\nCurrently in development for ASF projects + Python Core team\nfriendlies. **Not** a public marketplace skill — adoption is by\ninvitation while the framework is pre-release; once we ship via\nthe [ASF release policy](https://www.apache.org/legal/release-policy.html),\nthe marketplace path opens up. See\n[release-distribution](https://infra.apache.org/release-distribution.html)\nfor the canonical distribution mechanism we will adopt.\n\n\u003e [!IMPORTANT]\n\u003e The motivation, scope, and design commitments behind this work\n\u003e live in [`MISSION.md`](MISSION.md) — the **draft** project-\n\u003e establishment proposal for an Apache Top-Level Project built on\n\u003e this framework. Read that for the *why*; this README is the\n\u003e *how* once you've decided to adopt.\n\n## How adoption works\n\nThe framework uses a **snapshot + agentic-override** adoption\nmodel. An adopter project commits a single skill —\n[`setup`](skills/setup/SKILL.md) —\ninto their repo. That skill manages everything else:\n\n1. **Snapshot.** `setup` downloads the framework into\n   a **gitignored** `\u003cadopter\u003e/.apache-magpie/` directory.\n   The snapshot is a build artefact, not source — refreshed\n   by `/magpie-setup upgrade`, never committed.\n2. **Symlinks.** `setup` symlinks the framework's\n   skills (security, pr-management, the rest of setup) under\n   one canonical home — `.agents/skills/` (the path shared by\n   Codex, Cursor, Gemini CLI, Copilot, …) — and gives every\n   other agent dir (`.claude/skills/`, `.github/skills/`, …) a\n   thin per-skill **relay** symlink pointing back at the\n   canonical entry. This is the same regardless of how the\n   adopter previously organised those dirs. The symlinks are\n   **also gitignored** — they ultimately target the gitignored\n   snapshot, so they would dangle on a fresh clone before\n   `/magpie-setup` runs.\n3. **Overrides.** Adopter-specific modifications to framework\n   workflows live as agent-readable markdown under\n   `\u003cadopter\u003e/.apache-magpie-overrides/\u003cskill\u003e.md`,\n   **committed** in the adopter repo. The framework's skills\n   consult those files at run-time and apply the overrides\n   before executing default behaviour. See\n   [`docs/setup/agentic-overrides.md`](docs/setup/agentic-overrides.md)\n   for the contract.\n\n**No git submodules. No marketplace. No vendored copies of\nframework skills.** Just one committed skill (the bootstrap),\na gitignored snapshot, and agent-readable override files.\n\n## Adopting the framework\n\nTwo phases — a **shell bootstrap** that gets `setup`\ninto your repo, then the **skill takeover** that wires up the\nrest interactively.\n\n### 1. Bootstrap (copy-pasteable shell)\n\nPick an install method and follow the verbatim recipe in\n[**`docs/setup/install-recipes.md`**](docs/setup/install-recipes.md):\n\n| Method | When to use | Reproducibility |\n|---|---|---|\n| `svn-zip` | Production once ASF official releases ship to `dist.apache.org` (signed + checksummed) | Frozen by version |\n| `git-tag` | Pin a specific framework version | Frozen by tag |\n| `git-branch` (default `main`) | WIP path — track the framework's `main` directly. The default during the framework's pre-release phase. | Tracks tip |\n\nEach recipe is a single shell block that:\n\n1. Adds `.apache-magpie/`, `.apache-magpie.local.lock`, and\n   the framework-skill symlinks to `.gitignore`.\n2. Downloads + verifies + extracts the framework into\n   `.apache-magpie/` (gitignored — build artefact, not\n   source).\n3. Copies the\n   [`setup`](skills/setup/SKILL.md)\n   skill into the canonical `.agents/skills/magpie-setup/` and\n   adds a relay symlink to it from each agent dir you use\n   (`.claude/skills/magpie-setup`, `.github/skills/magpie-setup`).\n\nAfter the recipe completes, the framework snapshot is on\ndisk and the bootstrap skill is in your repo.\n\n### 2. Skill takeover\n\nTell your agent: **\"adopt apache/magpie in my repo\"**\n(or invoke `/magpie-setup` directly). The skill walks\nthrough the rest:\n\n- writes `.apache-magpie.lock` (committed) — the project's\n  pin: install method + URL + ref + verification anchor;\n- writes `.apache-magpie.local.lock` (gitignored) — what\n  this machine actually fetched + when;\n- asks which skill families (`security`, `pr-management`) to\n  symlink in;\n- creates the gitignored framework-skill symlinks;\n- scaffolds `.apache-magpie-overrides/` (committed) for any\n  local workflow modifications;\n- installs a `post-checkout` git hook so worktrees re-create\n  runtime state automatically;\n- updates your project documentation with a brief mention.\n\nAfter the skill finishes, you commit the small, focused\ndiff — the bootstrap skill, the `.gitignore` entries, the\ntwo lock files (committed + gitignore exclusion for the\nlocal one), the overrides scaffold, the doc note — and you're\ndone. Open a PR.\n\n### Subsequent contributors\n\nFuture contributors who clone your repo just say \"adopt\nMagpie in this repo\" (or invoke `/magpie-setup`).\nThe skill reads `.apache-magpie.lock` (already committed)\nand re-installs to the same version your project pinned. No\nneed to redo the manual recipe — the committed lock is the\nproject's source-of-truth.\n\n### Drift detection\n\nEvery framework skill compares the gitignored\n`.apache-magpie.local.lock` against the committed\n`.apache-magpie.lock` at the top of its run. If they have\ndrifted (project lead bumped the pin, or the local install\nis stale on a `main`-tracking adopter), the skill surfaces\nthe gap and proposes `/magpie-setup upgrade`. `upgrade`\ndeletes the gitignored snapshot, re-installs per the\ncommitted pin, refreshes the gitignored symlinks, and\nreconciles any agentic overrides — see\n[`docs/setup/install-recipes.md`](docs/setup/install-recipes.md)\nand\n[`skills/setup/upgrade.md`](skills/setup/upgrade.md)\nfor the full flow.\n\n## Skill families\n\nEight skill families ship in the framework, all at `experimental` or\n`stable`. Pick whichever families the adopter wants to use; symlinks for\nthe picked families land in the adopter's skill directory.\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 | Modes | Purpose | Detail |\n|---|---|---|---|\n| [**setup**](docs/setup/README.md) | (infra) | Isolated agent setup, framework adoption + maintenance, shared-config sync. The prerequisite — at minimum the `setup` skill itself runs out of this family. | 8 skills, [`docs/setup/`](docs/setup/) |\n| [**security**](docs/security/README.md) | 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) | Triage | Maintainer-facing PR-queue management — triage, stats, deep code review, and express-lane merge surfacing. | 4 skills, [`docs/pr-management/`](docs/pr-management/README.md) |\n| [**release-management**](docs/release-management/README.md) | 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| [**mentoring**](docs/mentoring/README.md) | Mentoring | Contributor mentoring — first-contact welcome, teaching-register PR/issue comments, newcomer-ready backlog curation, and readiness tracking along the contributor-to-committer path. **Experimental** — shape may change as adopter pilots and contributor-sentiment evaluation land. | 5 skills, [`docs/mentoring/`](docs/mentoring/README.md) |\n| [**issue**](docs/issue-management/README.md) | Triage, Drafting | General-issue lifecycle: triage, reproduction, fix drafting, stale-sweep, deduplication, and backlog reporting. | 8 skills, [`docs/issue-management/`](docs/issue-management/README.md) |\n| [**contributor-growth**](docs/contributor-growth/README.md) | Triage, Mentoring | Skills spanning the contributor-to-committer path: first-contact welcome, on-ramp issue authoring, activity tracking, nomination brief, post-vote onboarding. | 5 skills, [`docs/contributor-growth/`](docs/contributor-growth/README.md) |\n| [**repo-health**](docs/repo-health/README.md) | Triage | Read-only repository-health audits: obsolete runner labels, Actions workflow security, dependency vulnerabilities, license/NOTICE compliance, flaky-test patterns. | 5 skills, [`docs/repo-health/`](docs/repo-health/) |\n| **utilities** | (meta) | Framework meta-skills: author or update skills (`write-skill`), restructure existing skills (`optimize-skill`), print a live index of all available skills (`list-skills`). | 3 skills |\n\n### External skill sources\n\nBeyond the in-tree families, an adopter can pull a skill or whole family\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/\u003cname\u003e/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## Maintenance\n\nAfter the initial adoption, the same skill handles ongoing\nmaintenance:\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 \u003cframework-skill\u003e` — open or\n  scaffold an override file for a framework skill.\n\n## Cross-references\n\n- [`MISSION.md`](MISSION.md) — **draft** project-establishment proposal: 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- [`AGENTS.md`](AGENTS.md) — agent instructions, placeholder convention, framework conventions.\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — for framework contributors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fmagpie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapache%2Fmagpie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fmagpie/lists"}