Table of Contents generated with DocToc

• Apache Magpie
  • How adoption works
  • Adopting the framework
    • 1. Bootstrap (copy-pasteable shell)
    • 2. Skill takeover
    • Subsequent contributors
    • Drift detection
  • Skill families
  • Maintenance
  • Cross-references

Apache Magpie

Heads-up — the project is named Apache Magpie; the GitHub
slug rename is still pending.
The framework's name is Apache Magpie. The current
apache/airflow-steward slug carries airflow for legacy
reasons, but the framework is project-agnostic (it stewards
multiple ASF project workflows, not just Airflow's), so the
working group steering it chose a name that reflects that.

Magpie was selected by the founding PMC and confirmed
available via PODLINGSEARCH. Three alternates were carried
as historical backups during the bikeshed — Beacon, Guild,
and Lichen — but Magpie cleared the name search and is the
final name; the alternates are no longer in play.

Until the rename lands on the GitHub side, every clone URL and
CI integration still uses the legacy apache/airflow-steward
slug — all path examples in this README and the linked docs use
that slug verbatim. The rename will only change the GitHub
repository slug; existing checkouts will keep working with a
single git remote set-url.

A reusable, project-agnostic framework for ASF-project automation.
Currently in development for ASF projects + Python Core team
friendlies. Not a public marketplace skill — adoption is by
invitation while the framework is pre-release; once we ship via
the ASF release policy,
the marketplace path opens up. See
release-distribution
for the canonical distribution mechanism we will adopt.

[!IMPORTANT]
The motivation, scope, and design commitments behind this work
live in MISSION.md — the draft project-
establishment proposal for an Apache Top-Level Project built on
this framework. 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 —
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
   for the contract.

No git submodules. No marketplace. 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:

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
   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/airflow-steward 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
and
skills/setup/upgrade.md
for the full flow.

Skill families

Four skill families ship in the framework (plus one experimental
family, mentoring; one proposed family, release-management; and
two meta utilities). Pick whichever families the adopter wants to
use; symlinks for the picked families land in the adopter's skill
directory.

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.

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.

Cross-references

• MISSION.md — draft project-establishment proposal: 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.).
• AGENTS.md — agent instructions, placeholder convention, framework conventions.
• CONTRIBUTING.md — for framework contributors.