magpie-setup

<!-- SPDX-License-Identifier: Apache-2.0 https://www.apache.org/legal/release-policy.html --> <!-- Placeholder convention (see ../../AGENTS.md#placeholder-convention-used-in-skill-files): <project-config> → adopter's `.apache-magpie-overrides/` directory <snapshot-dir> → `.apache-magpie/` (gitignored snapshot of the framework) <committed-lock> → `.apache-magpie.lock` (committed — project's pin) <local-lock> → `.apache-magpie.local.lock` (gitignored — per-machine record) <upstream> → adopter's public source repo (the repo this skill is being run in) <framework-source> → the apache-magpie source we download a snapshot from — one of: signed zip from ASF dist, git tag, git branch. See [`docs/setup/install-recipes.md`](../../docs/setup/install-recipes.md). --> # setup This skill is **the only framework artefact an adopter project commits**. Every other apache-magpie skill (security, pr-management, issue) is a gitignored symlink into the gitignored snapshot at `<snapshot-dir>` that this skill manages. The adoption model is **snapshot + agentic overrides + drift- aware updates** (not submodule, not marketplace, not vendored copy): - The framework is downloaded into `<snapshot-dir>` and **gitignored** in the adopter repo. The snapshot is a build artefact, not source. - Three install methods are supported (see [`docs/setup/install-recipes.md`](../../docs/setup/install-recipes.md) for verbatim copy-pasteable recipes): - **svn-zip** — released, signed zip from ASF distribution (recommended for production once releases ship). - **git-tag** — pinned to a specific git tag. - **git-branch** — tracks a branch tip (default: `main`, the WIP path). - **Two lock files** record the framework version. The committed one declares what the project pins to; the local one records what each machine actually fetched. Drift between them is surfaced and remediated by `/magpie-setup upgrade`. - Symlinks make the framework's skills callable as if they lived in the adopter repo. **Each symlink is named `magpie-<framework-skill>`** — every framework skill is installed under a `magpie-` prefix so it is namespaced and never collides with the adopter's own skills (e.g. the snapshot's `skills/pr-management-triage/` becomes `magpie-pr-management-triage`, invoked as `/magpie-pr-management-triage`). **`.agents/skills/` is the one canonical home**: its `magpie-*` entries link into `<snapshot-dir>/skills/<framework-skill>/`. Every other agent target (`.claude/skills/`, `.github/skills/`, …) gets a thin per-skill **relay** symlink that points back at the canonical entry (`.claude/skills/magpie-<n>` → `../../.agents/skills/magpie-<n>`) — no matter what layout the adopting project previously used (see [`agents.md`](agents.md)). The symlinks are **gitignored** because their targets disappear on a fresh clone before `/magpie-setup` runs. - Adopter-specific modifications to framework workflows live as agent-readable instructions under `.apache-magpie-overrides/<skill-name>.md` (committed). They invalidate or change steps the framework's skill would otherwise run. See [`overrides.md`](overrides.md) for the contract and [`docs/setup/agentic-overrides.md`](../../docs/setup/agentic-overrides.md) for the design rationale. **Local self-adoption (the framework checkout only).** The one repo that cannot be adopted via the snapshot mechanism is the Apache Magpie framework checkout itself — a remote snapshot of the framework into itself would be circular. Instead it **self-adopts** with `method:local`: each canonical `magpie-<skill>` in `.agents/skills/` is a **committed** symlink into the in-repo `../../skills/<skill>/` source, and every other active agent target ([`agents.md`](agents.md)) — `.claude/skills/` (Claude Code), `.github/skills/` (GitHub's skill loader), and any present holdout — gets a committed **relay** symlink (`magpie-<skill>` → `../../.agents/skills/magpie-<skill>`) — with no snapshot, no remote fetch, and no copy. This makes the framework's own skills callable while developing the framework, and every contributor gets them active on a fresh clone with no setup step. `adopt` detects the framework checkout structurally and routes there automatically (see [`install.md` → Local self-adoption](install.md#local-self-adoption-methodlocal)). ## The two lock files The framework's lock-file model splits **what the project pins to** (committed) from **what this machine actually fetched** (local). This split is the foundation of drift detection and the multi-installer support. ### `<committed-lock>` — `.apache-magpie.lock` Committed at the adopter repo root. The **project's pin**. Edited only by `/magpie-setup`; do not modify by hand. ```text # .apache-magpie.lock — committed; the project's pin. method: <git-branch | git-tag | svn-zip> url: <see per-method format below> # For method=git-branch: ref: main # For method=git-tag: ref: v1.0.0 # the tag name commit: <SHA> # the commit the tag pointed to when committed # For method=svn-zip: ref: 1.0.0 # the version number sha512: <hash> # the released zip's SHA-512 (for re-fetch verification) ``` The next adopter who runs `/magpie-setup install` reads this file and re-installs to the **same version** the project declared. This is the core of the "adopt once, all subsequent users get the same thing" promise. ### `<local-lock>` — `.apache-magpie.local.lock` Gitignored at the adopter repo root. The **local snapshot's fingerprint**. Records what this machine fetched and when. ```text # .apache-magpie.local.lock — gitignored; per-machine. source_method: <git-branch | git-tag | svn-zip> source_url: <URL the snapshot was actually fetched from> source_ref: <branch / tag / version actually fetched> fetched_commit: <commit SHA on disk now> fetched_at: <ISO-8601 timestamp> ``` The drift check on every framework-skill invocation compares this against `<committed-lock>` and surfaces any mismatch as a proposed `/magpie-setup upgrade`. ### Source locks — the same split, for trusted external sources Skills pulled from [trusted external sources](../../docs/skill-sources/README.md) use their **own** pair of locks with the identical committed-pin / local-fingerprint split, kept separate from the framework locks so a source re-pin never entangles a framework upgrade: - **`.apache-magpie.sources.lock`** (committed) — the project's per-source pins, one block per source keyed by `id` (`method`/`url`/`ref` + `commit`|`sha512`). - **`.apache-magpie.sources.local.lock`** (gitignored) — this machine's per-source fetch fingerprint. They are written and reconciled by [`skill-sources.md`](skill-sources.md) and re-fetched on `upgrade`; the format and drift semantics live there. ## Detail files in this directory | File | Purpose | |---|---| | [`install.md`](install.md) | First-time install walk-through — recognise existing-snapshot vs needs-bootstrap, write the two lock files, ask the user which skill families and MCP servers to install, create the gitignored symlinks, scaffold `.apache-magpie-overrides/`, install the post-checkout hook, update project docs. The default sub-action. | | [`upgrade.md`](upgrade.md) | Refresh the gitignored snapshot per the committed lock, reconcile any agentic overrides + symlinks against the new framework structure, surface conflicts. Drives the on-drift remediation flow. | | [`verify.md`](verify.md) | Read-only health check — snapshot present + intact, both lock files in sync, symlinks point at live targets, `.gitignore` correct, `.apache-magpie-overrides/` exists, drift status (committed vs local), the `setup` skill itself is current. | | [`skill-sources.md`](skill-sources.md) | Fetch/verify skills from trusted external sources listed in `<project-config>/skill-sources.md`, pin them in the committed `.apache-magpie.sources.lock`, and symlink the provided skills in exactly like framework skills. The runnable half of [trusted external skill sources](../../docs/skill-sources/README.md); the install gate is the adopter trust list. | | [`agents.md`](agents.md) | The agent-target registry — *which* directories framework-skill symlinks land in across vendors, and the **canonical-plus-relay** model: `.agents/skills/` is the one canonical home (links into the snapshot/source); every other target (`claude-code`, `github`, holdout natives like Windsurf / Goose) gets a per-skill relay symlink into `.agents/skills/`. Defines active-target selection, SKILL.md format portability, and the Claude-Code-only layer (sandbox/hooks). The source of truth every sub-action consults for the target set. | | [`overrides.md`](overrides.md) | Agentic-override file management — open / scaffold an override for a framework skill, list existing overrides, help reconcile when the framework changes the underlying skill's structure on upgrade. | | [`uninstall.md`](uninstall.md) | Reverse the adoption — remove snapshot, locks, symlinks, post-checkout hook, `.gitignore` entries, the adoption sections in `README.md` / `AGENTS.md` / `CONTRIBUTING.md`, and the committed `setup` skill itself. Preserves `.apache-magpie-overrides/` by default; `--purge-overrides` removes it too. Surfaces the full removal plan before any write. | ## Golden rules **Golden rule 1 — never modify the snapshot.** The `<snapshot-dir>` is a build artefact, gitignored, and **read- only** from an adopter's perspective. Every modification an adopter wants must go into `.apache-magpie-overrides/` (where it is *committed* and survives the next `upgrade`). The skill, and any other framework skill consulting overrides at run-time, **never** writes to `<snapshot-dir>`. **Golden rule 2 — `<committed-lock>` is the project's pin; `<local-lock>` is per-machine truth.** They serve different purposes and live in different places: - `<committed-lock>` declares what version the *project* uses. Edited by the adopter who runs `/magpie-setup install` first (or who later runs `/magpie-setup upgrade` and accepts the new pin). Bumping it is a deliberate project-level action; the bump shows up in the `git diff` of the PR that proposed it. - `<local-lock>` records what *this machine* installed. Updated silently by `/magpie-setup install` and `/magpie-setup upgrade`. Per-developer, per-checkout, per-worktree. **Golden rule 3 — drift surfaces, drift gets remediated.** Every framework skill (and `/magpie-setup verify`) checks `<committed-lock>` vs `<local-lock>` at the top of its run. On mismatch the skill surfaces the gap and proposes `/magpie-setup upgrade`. The user accepts or defers; if they accept, `upgrade`: 1. Deletes `<snapshot-dir>` outright. 2. Re-installs per the *committed* lock (the new version the project chose). 3. Refreshes the gitignored framework-skill symlinks — adds any new framework skills the user's family pick covers, removes any framework skills that were renamed away or removed. 4. Reconciles agentic overrides against the new framework structure (surfaces conflicts; never auto-rewrites). 5. Updates `<local-lock>` to the new fetch. **Golden rule 4 — `.gitignore` keeps the adopter repo clean.** Gitignored in the adopter repo: - `<snapshot-dir>` (the entire framework snapshot — gigabytes potentially). - `<local-lock>` (per-machine state). - `.apache-magpie-local/` (personal, per-developer override directory — see Golden rule 7). - The `magpie-*` symlinks `setup adopt` creates in every active target dir — the canonical ones in `.agents/skills/` (they target the gitignored snapshot) and the relays in `.claude/skills/` / `.github/skills/` / holdouts (they target the canonical entries) — both would dangle in a fresh clone. The one exception un-ignored in each dir is `magpie-setup`. - `.apache-magpie-sources/` (the gitignored fetch of every trusted external skill source) and `.apache-magpie.sources.local.lock` (per-machine source-fetch fingerprint), when the adopter trusts any source. See [`skill-sources.md`](skill-sources.md). **Committed**: this skill (`setup`, as the canonical `.agents/skills/magpie-setup/` plus its relays), the `<committed-lock>`, the **`.apache-magpie.sources.lock`** per-source pins (the project's committed vouch for each trusted source), the `.apache-magpie-overrides/` directory, the `.gitignore` entries themselves, any project-doc updates the `adopt` sub-action makes. **Golden rule 5 — `.agents/skills/` is canonical; everything else just relays into it.** Regardless of how an adopting project previously organised its `.claude/skills/` or `.github/skills/`, `adopt` always wires the framework the same way: the canonical `magpie-*` links live in `.agents/skills/`, and every other active target (`.claude`, `.github`, holdouts) gets per-skill relay symlinks pointing back at the canonical entries (`.claude/skills/magpie-<n>` → `../../.agents/skills/magpie-<n>`). The adopter's own native (non-`magpie-`) skills in those dirs are left untouched. See [`agents.md`](agents.md). **Golden rule 6 — copy this skill, symlink the rest; all under the `magpie-` prefix.** This skill (source `skills/setup/`) is the **only** framework skill that gets **copied** into an adopter repo — committed as the canonical `.agents/skills/magpie-setup/`, with committed relay symlinks to it from `.claude/skills/magpie-setup` and `.github/skills/magpie-setup`. All other framework skills are **symlinked** (canonical link into the gitignored snapshot, plus relays), each named `magpie-<framework-skill>` (e.g. `magpie-security-issue-import` → `<snapshot-dir>/skills/security-issue-import/`). The `magpie-` prefix namespaces every framework skill so it never collides with an adopter's own skills. Mixing copy and symlink — copying a security skill, for instance — creates a maintenance hazard: copies drift from the framework's source- of-truth, and the drift-detection mechanism (which assumes the framework version is the one in `<snapshot-dir>`) silently mis-applies. **Golden rule 7 — agentic overrides are read at run-time.** Every framework skill that supports overrides starts its run by consulting **two** directories in precedence order (first hit wins): 1. `.apache-magpie-local/<this-skill>.md` — personal, gitignored. Per-developer overrides that are never committed. 2. `.apache-magpie-overrides/<this-skill>.md` — committed, project-wide. Overrides shared with every contributor. Both files are plain markdown the agent interprets — no templating engine, no patch tool. The additive-only guardrail applies to both: neither may weaken the framework's safety, confidentiality, or privacy baseline. See [`docs/setup/agentic-overrides.md`](../../docs/setup/agentic-overrides.md) for the full contract including the lookup protocol. **Golden rule 8 — family membership is declared in frontmatter; two families are *always* installed, the rest are opt-in.** Every framework skill declares its family in a `family:` key in its `SKILL.md` frontmatter (e.g.