magpie

KO | EN

gitlite — search

#hacktoberfest #android #php #javascript #java #dotnetnuke #python #dnn #dnncms #ios #css #game

★ 82 Open GitHub ↗

Agent-assisted maintainership and development framework for Apache projects — Triage, Mentoring, Drafting (agent-authored fixes with human review), and Pairing (developer-side dev-cycle) skills shipping; Agentic Autonomous (auto-merge) on the roadmap.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Apache Magpie](#apache-magpie)
  - [How adoption works](#how-adoption-works)
  - [Adopting the framework](#adopting-the-framework)
    - [1. Bootstrap (copy-pasteable shell)](#1-bootstrap-copy-pasteable-shell)
    - [2. Skill takeover](#2-skill-takeover)
    - [Subsequent contributors](#subsequent-contributors)
    - [Drift detection](#drift-detection)
  - [Skill families](#skill-families)
    - [External skill sources](#external-skill-sources)
  - [Maintenance](#maintenance)
  - [Acknowledgements](#acknowledgements)
  - [Cross-references](#cross-references)

# Apache Magpie

[![Magpie](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/apache/magpie/main/assets/badge.json)](https://magpie.apache.org/)

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 distributed per the [ASF release policy](https://www.apache.org/legal/release-policy.html)
(see [release-distribution](https://infra.apache.org/release-distribution.html)
for the canonical mechanism); you adopt it by pinning a release.

> [!NOTE]
> A **public skill marketplace is planned but not yet implemented.**
> Today you adopt Magpie directly from the released source, not from a
> marketplace.

> [!IMPORTANT]
> The motivation, scope, and design commitments behind this work
> live in [`MISSION.md`](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 adopt.

## How adoption works

The framework uses a **snapshot + agentic-override** adoption
model. An adopter project commits a single skill —
[`setup`](skills/setup/SKILL.md) —
into their repo. That skill manages everything else:

1. **Snapshot.** `setup` downloads the framework into
   a **gitignored** `<adopter>/.apache-magpie/` directory.
   The snapshot is a build artefact, not source — refreshed
   by `/magpie-setup upgrade`, never committed.
2. **Symlinks.** `setup` symlinks the framework's
   skills (security, pr-management, the rest of setup) under
   one canonical home — `.agents/skills/` (the path shared by
   Codex, Cursor, Gemini CLI, Copilot, …) — and gives every
   other agent dir (`.claude/skills/`, `.github/skills/`, …) a
   thin per-skill **relay** symlink pointing back at the
   canonical entry. This is the same regardless of how the
   adopter previously organised those dirs. The symlinks are
   **also gitignored** — they ultimately target the gitignored
   snapshot, so they would dangle on a fresh clone before
   `/magpie-setup` runs.
3. **Overrides.** Adopter-specific modifications to framework
   workflows live as agent-readable markdown under
   `<adopter>/.apache-magpie-overrides/<skill>.md`,
   **committed** in the adopter repo. The framework's skills
   consult those files at run-time and apply the overrides
   before executing default behaviour. See
   [`docs/setup/agentic-overrides.md`](docs/setup/agentic-overrides.md)
   for the contract.

**No git submodules. No marketplace (yet). No vendored copies of
framework skills.** Just one committed skill (the bootstrap),
a gitignored snapshot, and agent-readable override files.

## Adopting the framework

Two phases — a **shell bootstrap** that gets `setup`
into your repo, then the **skill takeover** that wires up the
rest interactively.

### 1. Bootstrap (copy-pasteable shell)

Pick an install method and follow the verbatim recipe in
[**`docs/setup/install-recipes.md`**](docs/setup/install-recipes.md):

| Method | When to use | Reproducibility |
|---|---|---|
| `svn-zip` | Production once ASF official releases ship to `dist.apache.org` (signed + checksummed) | Frozen by version |
| `git-tag` | Pin a specific framework version | Frozen by tag |
| `git-branch` (default `main`) | WIP path — track the framework's `main` directly for the latest unreleased changes. | Tracks tip |

Each recipe is a single shell block that:

1. Adds `.apache-magpie/`, `.apache-magpie.local.lock`, and
   the framework-skill symlinks to `.gitignore`.
2. Downloads + verifies + extracts the framework into
   `.apache-magpie/` (gitignored — build artefact, not
   source).
3. Copies the
   [`setup`](skills/setup/SKILL.md)
   skill into the canonical `.agents/skills/magpie-setup/` and
   adds a relay symlink to it from each agent dir you use
   (`.claude/skills/magpie-setup`, `.github/skills/magpie-setup`).

After the recipe completes, the framework snapshot is on
disk and the bootstrap skill is in your repo.

### 2. Skill takeover

Tell your agent: **"adopt apache/magpie in my repo"**
(or invoke `/magpie-setup` directly). The skill walks
through the rest:

- writes `.apache-magpie.lock` (committed) — the project's
  pin: install method + URL + ref + verification anchor;
- writes `.apache-magpie.local.lock` (gitignored) — what
  this machine actually fetched + when;
- asks which skill families (`security`, `pr-management`) to
  symlink in;
- creates the gitignored framework-skill symlinks;
- scaffolds `.apache-magpie-overrides/` (committed) for any
  local workflow modifications;
- installs a `post-checkout` git hook so worktrees re-create
  runtime state automatically;
- updates your project documentation with a brief mention.

After the skill finishes, you commit the small, focused
diff — the bootstrap skill, the `.gitignore` entries, the
two lock files (committed + gitignore exclusion for the
local one), the overrides scaffold, the doc note — and you're
done. Open a PR.

### Subsequent contributors

Future contributors who clone your repo just say "adopt
Magpie in this repo" (or invoke `/magpie-setup`).
The skill reads `.apache-magpie.lock` (already committed)
and re-installs to the same version your project pinned. No
need to redo the manual recipe — the committed lock is the
project's source-of-truth.

### Drift detection

Every framework skill compares the gitignored
`.apache-magpie.local.lock` against the committed
`.apache-magpie.lock` at the top of its run. If they have
drifted (project lead bumped the pin, or the local install
is stale on a `main`-tracking adopter), the skill surfaces
the gap and proposes `/magpie-setup upgrade`. `upgrade`
deletes the gitignored snapshot, re-installs per the
committed pin, refreshes the gitignored symlinks, and
reconciles any agentic overrides — see
[`docs/setup/install-recipes.md`](docs/setup/install-recipes.md)
and
[`skills/setup/upgrade.md`](skills/setup/upgrade.md)
for the full flow.

## Skill families

Ten skill families ship in the framework, all at `experimental` or
`stable`, and each skill declares its family in a `family:` frontmatter
key. At adoption (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 adopter's 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`](docs/modes.md) for what each mode
means and which modes are still proposed vs. shipping today.

| Family | Type | Modes | Purpose | Detail |
|---|---|---|---|---|
| [**setup**](docs/setup/README.md) | always-on | (infra) | Isolated agent setup, framework adoption + maintenance, shared-config sync. The prerequisite — at minimum the `setup` skill itself runs out of this family. | 9 skills, [`docs/setup/`](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**](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/) |
| [**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) |
| [**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) |
| [**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/) |
| [**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/) |
| [**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) |
| [**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) |
| [**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) |

### External skill sources

Beyond the in-tree families, an adopter can pull a skill or whole family
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/`](docs/skill-sources/README.md),
[`PRINCIPLES.md` §13](PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies),
and [`RFC-AI-0006`](docs/rfcs/RFC-AI-0006.md).

## Maintenance

After the initial adoption, the same skill handles ongoing
maintenance:

- `/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.

## 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`](NOTICE).

## Cross-references

- [`MISSION.md`](MISSION.md) — founding mission of the established TLP: motivation, scope, design commitments, initial PMC composition target.
- [`docs/setup/agentic-overrides.md`](docs/setup/agentic-overrides.md) — the contract between adopters who write overrides and framework skills that read them.
- [`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.).
- [`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.
- [`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)).
- [`AGENTS.md`](AGENTS.md) — agent instructions, placeholder convention, framework conventions.
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — for framework contributors.

magpie

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README