Apache Top Level Project

Get back your time, maintainer.

Apache Magpie is a carefully curated set of AI agent recipes, specially designed to handle the repetitive parts of running an open-source project — triaging issues and PRs, mentoring contributors, drafting fixes, managing security reports — so maintainers can spend their time on design, relationships, and the work that needs a human. The agent proposes; the human decides.

Free & open-source

Vendor neutral

ASF governed

PR SubmittedContributor opens a pull request

Done

Magpie TriagesAuto-label, categorize & prioritize

Stable

Mentor SuggestionsGuide contributors with feedback

Experimental

Draft ReviewGenerate review comments & notes

Stable

AutonomousOff by design until earlier modes prove out

Off

Explore the agentic modes

Why would you like to use Magpie?Pick the pain you feel today — each one maps to a family of skills you can adopt on its own. The agent proposes; you decide.

Worried an agent will leak your credentials or wreck your machine?Adopt the setup family Security reports pile up and every step needs an audit trail?Adopt the security family Your PR queue is out of control?Adopt the pr-management family Issue backlog is a mess of duplicates and stale reports?Adopt the issue family Repo hygiene quietly slipping — CI, deps, licenses, flaky tests?Adopt the repo-health family Cutting a release is a manual, error-prone slog?Adopt the release-management family New contributors get stuck and quietly drift away?Adopt the mentoring family Hard to grow contributors into committers?Adopt the contributor-growth family Want to build or maintain your own skills?Adopt the utilities family

Adopt a MagpieRunning Magpie in your project? Wear it. Add the badge to your README so visitors know your maintenance runs on Magpie.

Magpie

Markdown — links through img.shields.io so it always shows the current badge:

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

Maintainers firstHard guarantees behind every mode, drawn straight from our design principles.
The agent proposes; you stay in control.

Human-in-the-LoopEvery outward action needs explicit maintainer confirmation. External content is treated as data, never instructions.Principle

Full Audit LogEvery agent-authored action — comment, label, draft, PR — is logged and reversible where possible.Principle

Controlled Maintainer Development EnvironmentEvery system tool is pinned and aged through a cooldown window. Version bumps are reviewed PRs, not silent updates.Principle

Progressive Agentic ModesAgentic automations that adapt to your project. Start simple — each mode builds on the previous one, evolving as trust grows.

Agentic Triage Mode

Stable

Auto-label, categorize, and route incoming PRs and issues to the right reviewers instantly.

Auto-labeling

Priority scoring

Docs

Agentic Drafting Mode

Stable (security)

Draft a fix for a well-scoped problem and open a PR — every PR reviewed and merged by a human committer, never the agent.

Fix PRs

Human-merged

Docs

Agentic Mentoring Mode

Experimental

Joins issue and PR threads in a teaching register — clarifying questions, pointers to conventions, examples from prior PRs.

Conventions

Prior PRs

Docs

Agentic Pairing Mode

Experimental

Developer-side skills you run in your own dev loop — multi-agent review pipelines and self-review before you open a PR.

Self-review

Pre-flight

Docs

Agentic Autonomous Mode

Off

Limited fix-and-merge for objectively boring changes — lint, allow-listed dependency bumps, formatting. Deliberately off until the earlier modes have proven out, and never for security-class changes.

Auto-approve

Audit trail

Rollback

Docs

Pick the skill families you needModes describe how agents are used; skill families are how those capabilities ship. Adopt only the families that fit — symlinks for the picked families land in your skill directory.Most families work on any project, inside or outside the Apache Software Foundation. The ones marked with the Apache oak leaf () are ASF-specific — they encode Foundation processes like the release lifecycle and the contributor-to-committer path. We'd love to support other maintainership and governance models too; contributions are welcome.

9 skills

setup

Infrastructure

Isolated agent setup, framework adoption & maintenance, shared-config sync. The prerequisite every adopter starts from.Read the overview

12 skills

security

Triage · Drafting

The 16-step security-issue lifecycle — from security@ import through CVE allocation and publication, with state sync. Maintainer-only.Read the overview

5 skills

pr-management

Triage

Maintainer-facing PR-queue management — triage, queue stats, and deep code review.Read the overview

8 skills

issue

Triage · Drafting

Issue lifecycle — triage, bug reproduction, fix drafting, and backlog re-assessment against the current branch.Read the overview

6 skills · experimental

repo-health

Triage

Read-only maintenance audits — CI runner obsolescence, workflow security, stale or vulnerable dependencies, license/NOTICE drift, and flaky tests. Each proposes remedies for the maintainer to apply.Read the overview

10 skills

release-management

Triage · Drafting

The 14-step ASF release lifecycle — planning, RC cut & sign, [VOTE], tally, promote, [ANNOUNCE], archive, audit. The agent never holds the signing key or publishes.Read the overview

2 skills · experimental

mentoring

Mentoring

Contributor mentoring — spec and tone guide in place; first skill (pr-management-mentor) shipping.Read the overview

6 skills

contributor-growth

Mentoring · Triage

The contributor-to-committer path — welcome first-timers, keep the backlog newcomer-ready, track activity, assemble nomination evidence, and run post-vote onboarding.Read the overview

4 skills

utilities

Meta

Framework meta-skills — author or update skills (write-skill) and print a live index of every skill (list-skills).Read the overview

New to agents? Learn hereBuilding software with an AI agent is a new skill, even for people who have written code for years. It isn't harder than other coding — it's different: behaviour is probabilistic, prompts and skills are code, and you test with evals rather than single checks.Magpie's maintainer-education stream teaches you that craft one page at a time — no AI background needed. Work through the three groups in order, or jump to the one you need; two hands-on references sit alongside them all. Every release ships the learning material for the skills it contains (PRINCIPLE 18).

Working with agents

Get oriented before you build

What agents are Working with agents Choosing models

Authoring skills

Write, harden, and test a skill

Your first skill Writing safe skills Debugging a skill Writing portable skills Eval-driven development

Going further

Run at scale and give back

Agentic & autonomous work English as a programming language Contributing back

References

— use alongside any group

Pattern catalogueReady-to-copy skill and prompt patterns

TutorialsA hands-on 90-minute build-and-eval lab

Privacy and Security at every levelEvery interaction is auditable, every decision is transparent, and every action respects the principle of least privilege.

Security docs Privacy docs

Sandboxed by DefaultFilesystem, network, and tool-permission rules enforced at the harness layer. Sandbox bypasses warn loudly, never silently.Docs

Privacy-Aware RoutingPrivate content flows only to LLMs your PMC has explicitly approved, with a recorded data-residency contract.Docs

PII RedactionThird-party PII is redacted to stable identifiers before any content reaches an LLM context.Docs

Vendor NeutralityMagpie's workflows never name a vendor. Skills declare a capability; a tool fulfils it; every vendor binding lives in a tool behind a contract — across six independent axes: LLM backend, agentic runtime, forge/tracker, communication channels, source control, and project governance. Swapping a backend is a config change, never a rewrite of the workflows.

10/10Capability contracts100% work across 2+ vendors

69/69Skillscarry no vendor lock-in

22/22Agent harness100% harness-neutral

Live figures from the framework repo — every axis already works across more than one vendor or is neutral by construction; we keep adding backends and organisations so the numbers stay honest.

How Magpie achieves vendor neutrality Browse tools & capabilities

Swap LLM providers freelyAnthropic, OpenAI, Bedrock, or local Ollama/vLLM — skills target a capability floor, not a provider SDK. No lock-in.

Works across agent CLIs & ecosystemsSkills follow the open AGENTS.md standard, so they run across agent CLIs and ecosystems — Claude Code, Codex, and others — rather than being tied to one vendor's tool.

Forge, tracker & VCS behind contractsGitHub and Jira today; GitLab, Gitea, Bugzilla, and non-Git VCS (SVN, Mercurial, …) are documented, labelled extension points — each one adapter, not a fork.

All organisations are welcomeMagpie isn't hardwired to the Apache Software Foundation. A governing body — a foundation, a company, or an informal maintainer collective — is an organization that bundles its governance vocabulary, backend defaults, and identity (logo included). A project declares organization: ASF (or independent, or your own) once and inherits the rest — so the same skill runs unchanged for an ASF project and a non-ASF one.

Organizations, not a hardcoded ASFASF and independent ship in-tree; author your own for your foundation or company. Governance vocabulary, backend choices, and identity live once and every project inherits them.See the organizations

Non-ASF adopters are first-classThe independent baseline needs no foundation: DCO sign-off, GitHub-native security and releases, no mailing-list backends. It's a starting point, not an afterthought.How neutrality works

Three homes for every extensionA skill, adapter, or whole organization can live in-tree (upstreamed to everyone), in your adopter repo, or in an external repo you reference — wired in deliberately, never auto-installed.The three homes

Extend by project, org, or individualAdd a backend by writing one adapter against a documented contract; the workflows never change. Keep it private or contribute it back under Apache-2.0 — one PR away.Who extends what

Add your organizationRunning Magpie under a different foundation or company? Propose an organization bundle so every project under it inherits your defaults — start the conversation on the developer mailing list.Email the dev list

Extending Magpie (project / org / individual)Authoring an external skill source Organizations, tools & capabilities

Built in the open, the Apache WayApache Magpie is a project of The Apache Software Foundation, built in public and run by its community following the Apache Way — consensus-driven, vendor-neutral, and earned on merit.
Decisions happen on open channels, and everyone is welcome to take part.Day-to-day work happens on GitHub (issues & pull requests) and in Slack for quick questions — but every significant discussion and decision also lands on the developer mailing list. Prefer not to use GitHub or Slack? You can follow along and take part fully over email alone: the dev list is the one channel that reaches everyone.

New to Apache?How the Foundation works Becoming a committer Communication & etiquette Community Development (ComDev)

Developer mailing listDesign discussion, proposals, and the formal [VOTE]s that reach consensus all happen on dev@magpie.apache.org. If it didn't happen on the list, it didn't happen.

Subscribe Browse the archive

Slack — #magpieReal-time chat with maintainers and contributors in the #magpie channel on the ASF Slack — questions, pairing, and quick design back-and-forth.

Join the ASF Slack Open #magpie

Start contributingNew here? The contributing guide walks through setup, conventions, and your first pull request. The agent proposes; humans review and merge — and we mentor newcomers along the way.

Browse issues Contributing guide

The people behind Magpie22 committers & PMC members steering the project.

Hey maintainer …

Want to get your time back?Join the growing community of open-source projects using Apache Magpie to scale their review processes without burning out their maintainers.