Install recipes

June 3, 2026 · View on GitHub

Three copy-pasteable shell recipes for fetching the framework into a new adopter project's repo. Each recipe is the bootstrap that gets setup into the repo; once it is in place, the rest of the adoption (skill-family pick, framework symlinks, project doc note, gitignored runtime state) runs through /magpie-setup interactively.

Pick the recipe that matches your distribution preference:

Method	When to use	Reproducibility
svn-zip	Production adopters once the framework ships official ASF releases. Signed + checksummed.	Frozen by version
git-tag	Pinning a specific framework version (e.g. for testing a release candidate, or for a cautious adopter who tracks named releases only).	Frozen by tag
git-branch	WIP path — track the framework's `main` branch directly. The default during the framework's pre-release phase.	Tracks branch tip

Adopter convention — pick the right cp step per your existing skills layout (see .claude/skills/magpie-setup/conventions.md for the full taxonomy):

A — flat (.claude/skills/<n>/SKILL.md directly): copy setup into .claude/skills/magpie-setup/.

B — double-symlinked (per-skill .claude/skills/<n> → .github/skills/<n>/ symlinks): copy the content into .github/skills/magpie-setup/ AND symlink .claude/skills/magpie-setup → ../../.github/skills/magpie-setup.

D — single directory symlink (one of .claude/skills / .github/skills is itself a directory symlink to the other): copy the content into the canonical side only — .github/skills/magpie-setup/ for D.1 (canonical .github/skills/) or .claude/skills/magpie-setup/ for D.2 (canonical .claude/skills/). The opposite side is the same directory via the symlink, so there is nothing to wire up.

The setup skill itself is the only framework artefact you commit. Every other framework skill is wired in by the setup adopt flow as gitignored symlinks into the gitignored snapshot.

Method 1 — released zip from ASF distribution

Status: forthcoming. ASF release distribution (https://dist.apache.org/repos/dist/release/<project>/) is the canonical home for ASF-blessed releases per the release-policy and infra release-distribution guidelines. This recipe will be the recommended path once the framework ships its first official release; until then, use Method 3 — git-branch.

# === Magpie bootstrap — Method 1: signed zip from ASF dist ===
# Replace <PROJECT> with the host adopter's ASF dist subdirectory
# (e.g. `airflow` once releases land at
# https://dist.apache.org/repos/dist/release/airflow/).
# Replace <VERSION> with the framework version you want.

cd /path/to/your/repo

VERSION=<VERSION>
PROJECT=<PROJECT>
DIST_BASE=https://dist.apache.org/repos/dist/release/${PROJECT}
ZIP=apache-steward-${VERSION}-source-release.zip

# 1. Download zip + signature + checksum, verify, extract to .apache-magpie/
curl -fsSLO ${DIST_BASE}/${ZIP}
curl -fsSLO ${DIST_BASE}/${ZIP}.sha512
curl -fsSLO ${DIST_BASE}/${ZIP}.asc
sha512sum -c ${ZIP}.sha512
# Optional but recommended — verify the OpenPGP signature against the
# project KEYS file (see https://infra.apache.org/release-signing.html):
#   curl -fsSLO ${DIST_BASE}/KEYS
#   gpg --import KEYS
#   gpg --verify ${ZIP}.asc ${ZIP}

mkdir -p .apache-magpie
unzip -q ${ZIP} -d .apache-magpie
mv .apache-magpie/apache-steward-${VERSION}/* \
   .apache-magpie/apache-steward-${VERSION}/.[!.]* \
   .apache-magpie/ 2>/dev/null
rmdir .apache-magpie/apache-steward-${VERSION}
rm -f ${ZIP} ${ZIP}.sha512 ${ZIP}.asc

# 2. Copy the `setup` skill into your skills dir.
#    Pick ONE branch based on your existing convention.
#
#    A — flat layout (default):
mkdir -p .claude/skills
cp -r .apache-magpie/skills/setup .claude/skills/magpie-setup
#
#    B — double-symlinked layout (per-skill symlinks):
# mkdir -p .github/skills .claude/skills
# cp -r .apache-magpie/skills/setup .github/skills/magpie-setup
# ln -sf ../../.github/skills/magpie-setup .claude/skills/magpie-setup
#
#    D.1 — single directory symlink, canonical .github/skills/:
#    (.claude/skills is itself a symlink → ../.github/skills/)
# cp -r .apache-magpie/skills/setup .github/skills/magpie-setup
#    (No second copy needed — .claude/skills/magpie-setup resolves
#     to .github/skills/magpie-setup via the directory symlink.)
#
#    D.2 — single directory symlink, canonical .claude/skills/:
#    (.github/skills is itself a symlink → ../.claude/skills/)
# cp -r .apache-magpie/skills/setup .claude/skills/magpie-setup

# 3. Add gitignore entries (idempotent — re-run is safe)
cat >> .gitignore <<'GITIGNORE'

# Magpie — gitignored snapshot of the framework, refreshed
# by /magpie-setup upgrade. Build artefact, not source.
/.apache-magpie/

# Per-machine local-pin file. Records what THIS machine fetched and
# when. Compared against the committed .apache-magpie.lock to
# detect drift.
/.apache-magpie.local.lock

# Symlinks created by /magpie-setup into the gitignored snapshot.
# Pattern A (flat) → keep only the .claude/skills/ block below.
# Pattern B (per-skill double-symlinked) → keep BOTH blocks (one
#   physical symlink per layer needs its own ignore line).
# Pattern D.1 (.claude/skills → .github/skills/) → keep only the
#   .github/skills/ block — git does not descend into the directory
#   symlink, so .claude/skills/ ignore lines are unnecessary.
# Pattern D.2 (.github/skills → .claude/skills/) → keep only the
#   .claude/skills/ block (same reason, opposite orientation).
/.claude/skills/security-*
/.claude/skills/pr-management-*
/.claude/skills/issue-*
/.claude/skills/setup-isolated-setup-*
/.claude/skills/setup-shared-config-sync
/.claude/skills/list-*
/.github/skills/security-*
/.github/skills/pr-management-*
/.github/skills/issue-*
/.github/skills/setup-isolated-setup-*
/.github/skills/setup-shared-config-sync
/.github/skills/list-*
GITIGNORE

# 4. Tell your agent: "follow /magpie-setup to finish adopting Magpie."
#    The skill will write .apache-magpie.lock (committed) and
#    .apache-magpie.local.lock (gitignored), ask which skill family
#    to wire up, create the gitignored framework-skill symlinks, and
#    update your project docs.

Method 2 — git tag

# === Magpie bootstrap — Method 2: pinned git tag ===
# Replace <TAG> with the framework tag you want
# (e.g. `v1.0.0` once tags exist on apache/airflow-steward).

cd /path/to/your/repo

TAG=<TAG>
git clone --depth=1 \
    --branch ${TAG} \
    https://github.com/apache/airflow-steward.git \
    .apache-magpie

# Copy the `setup` skill — pick A / B / D (see Method 1 step 2)
mkdir -p .claude/skills
cp -r .apache-magpie/skills/setup .claude/skills/magpie-setup
# OR for double-symlinked (B):
# cp -r .apache-magpie/skills/setup .github/skills/magpie-setup
# ln -sf ../../.github/skills/magpie-setup .claude/skills/magpie-setup
# OR for single directory-symlink (D) — copy to canonical side only;
# the .claude/skills ↔ .github/skills directory symlink does the rest.

# Add gitignore entries (same block as Method 1 step 3 — see there)

# Tell your agent: "follow /magpie-setup to finish adopting Magpie."

Method 3 — git branch (defaults to `main`)

The default WIP path while the framework is pre-release.

# === Magpie bootstrap — Method 3: git branch (default: main) ===
cd /path/to/your/repo

BRANCH=main   # or another branch you want to track
git clone --depth=1 \
    --branch ${BRANCH} \
    https://github.com/apache/airflow-steward.git \
    .apache-magpie

# Copy the `setup` skill — pick A / B / D (see Method 1 step 2)
mkdir -p .claude/skills
cp -r .apache-magpie/skills/setup .claude/skills/magpie-setup
# OR for double-symlinked (B):
# cp -r .apache-magpie/skills/setup .github/skills/magpie-setup
# ln -sf ../../.github/skills/magpie-setup .claude/skills/magpie-setup
# OR for single directory-symlink (D) — copy to canonical side only;
# the .claude/skills ↔ .github/skills directory symlink does the rest.

# Add gitignore entries (same block as Method 1 step 3 — see there)

# Tell your agent: "follow /magpie-setup to finish adopting Magpie."

After any recipe — let the skill take over

Once the recipe completes, setup is in your repo and the snapshot is on disk (gitignored). Tell your agent:

follow .claude/skills/magpie-setup to adopt Magpie

(or invoke /magpie-setup directly). The skill walks through the rest:

Pick the skill families to symlink in (security, pr-management, issue).
Write the lock files:
- .apache-magpie.lock (committed) — the project's pin (the method + URL + ref you used in the recipe). Future adopters of this same repo re-install per this pin.
- .apache-magpie.local.lock (gitignored) — what THIS machine actually fetched (commit SHA, timestamp).
Create the symlinks for chosen skill families (gitignored — they target the gitignored snapshot).
Scaffold .apache-magpie-overrides/ (committed) for any local workflow modifications.
Install a post-checkout git hook so worktrees re-create the gitignored runtime state.
Update your project documentation with a brief mention of the framework adoption.

After this, adopters fresh-cloning the repo can run /magpie-setup and get the framework provisioned per your project's committed .apache-magpie.lock — no need to redo the manual recipe.

Subsequent runs and drift detection

Every framework skill — and /magpie-setup verify — compares the local lock against the committed lock at the top of its run. If they have drifted (e.g. the project lead bumped .apache-magpie.lock to a newer ref, 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 lock, refreshes the gitignored symlinks (adding any new framework skills, removing any that were renamed away), and updates the local lock. See setup/upgrade.md for the full flow.

Migrating a pre-Magpie (`apache-steward`) adopter

A repo that adopted the framework before it was renamed from apache-steward to Apache Magpie is on the old layout: a committed .claude/skills/setup-steward/ skill, an .apache-steward/ snapshot, .apache-steward.lock / .apache-steward-overrides/, un-prefixed framework symlinks, and ~/.config/apache-steward/. The framework no longer ships an automated migration for this layout — migrate by hand:

Remove the legacy in-repo artefacts: .apache-steward* (snapshot, locks, overrides), any un-prefixed framework symlinks under the skills dir, and the committed .claude/skills/setup-steward/ skill.
Re-adopt from scratch with /magpie-setup (see setup/adopt.md) so the current .apache-magpie* layout and magpie--prefixed symlinks are written fresh. Preserve any .apache-steward-overrides/*.md you want to keep by moving them into the new .apache-magpie-overrides/ first.
Move ~/.config/apache-steward/ (per-user) to ~/.config/apache-magpie/, and update any ~/.config/apache-steward/ entry in your Claude Code sandbox allowlist (project .claude/settings.local.json / .claude/settings.json or user-scope ~/.claude/settings.json) to ~/.config/apache-magpie/ — otherwise sandboxed framework tools cannot read the moved credentials.