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>           → per file, first hit wins: the personal layer
                                  (`.apache-magpie-local/` when adopted, falling back to the
                                  main checkout's in a linked worktree;
                                  `<git-common-dir>/apache-magpie/` when only installed) then
                                  `.apache-magpie-overrides/` (committed, project-wide)
     <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/quick-start/other-install-methods.md). -->

setup

The marketplace install is the default. One marketplace add, then one plugin install per skill family, and nothing is written to the repo. setup with no arguments proposes it; the other methods are fallbacks for where a marketplace cannot reach. Walk-through: install.md → Step M0b, which reads any committed floor first. Per-agent reference: docs/setup/marketplace.md.

The install paths

A project can have contributors on either path, but one machine takes only one (Golden rule 10).

The pinned-snapshot machinery — what the snapshot is, the fetch methods, symlink naming, the overrides scaffold — is in snapshot-model.md. A marketplace install needs none of it.

The two lock files

(Pinned-snapshot path only — a marketplace install has no lock files.) The committed <committed-lock> records what the project pins to; the gitignored <local-lock> records what this machine fetched. Drift detection and multi-installer support rest on that split. Trusted external skill sources use their own pair with the same semantics. Formats, fields, and drift rules: locks.md.

Detail files in this directory

The Sub-actions table maps every invocation to the file it loads. Three more are reference files the sub-actions consult: locks.md (lock files and the reconciled: stamp), agents.md (agent-target registry, canonical-plus-relay model), and snapshot-model.md (pinned-snapshot machinery and the five golden rules that bind only there). failure-modes.md is for when something has already gone wrong.

Golden rules

Golden rule 1 — never modify the snapshot. <snapshot-dir> is a gitignored build artefact and read-only to adopters. Every change an adopter wants goes into .apache-magpie-overrides/, where it is committed and survives the next upgrade. Neither this skill nor any framework skill reading overrides ever writes to <snapshot-dir>.

Golden rule 5 — .agents/skills/ is canonical; everything else just relays into it. Whatever layout the project had before, adopt 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 back to them (.claude/skills/magpie-<n> → ../../.agents/skills/magpie-<n>). The adopter's own non-magpie- skills in those directories are left alone. See agents.md.

Golden rule 7 — agentic overrides are read at run-time — lookup order and guardrail in overrides.md.

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: frontmatter key (e.g. family: repo-health). The sub-actions read that key from the snapshot to build the adopt/upgrade install choice and to wire each family's symlinks. Never infer family from the skill-name prefix — families such as repo-health and contributor-growth span several prefixes. The family vocabulary is validated by skill-and-tool-validator (ALLOWED_FAMILIES) and listed for adopters in README.md → Skill families.

Two families are wired unconditionally on every adopt / upgrade / worktree-init run, without asking: setup (every family: setup skill except the bootstrap setup itself, which is copied per Rule 6) and utilities. Both are read from frontmatter like any other family — do not keep a list here.

Golden rule 10 — marketplace first; the snapshot install is a fallback, not the default. Rules 1–9 govern the pinned-snapshot machinery; this rule decides which path a run takes. Unless the user passed an explicit method:, install proposes the marketplace install, with the exact commands for the agent in front of it. It proposes the snapshot only for one of these reasons, named out loud:

• the agent has no plugin / extension mechanism, or its marketplace install has already failed for this user;
• the project needs the signed ASF source artefact (svn-zip), not a marketplace clone of the repo;
• the project wants one committed pin — every contributor and CI job on one framework version, with drift detection;
• the repo is the framework checkout itself (method:local).

Never lay the snapshot on top of a working marketplace install "to be safe". It loads a second copy of every skill, doubling the always-on token cost, and /magpie-<skill> (snapshot) and /magpie-<family>:<skill> (plugin) then resolve to two different versions of the same skill. Where a repo genuinely needs the pin, the snapshot replaces the marketplace install on that machine — uninstall the plugins first.

Five rules bind only on the pinned-snapshot path — the lock files, drift remediation, .gitignore, copy-versus-symlink, and reloading setup after a self-update (rule 9). They are in snapshot-model.md with the machinery they govern; a marketplace install is not subject to them.

Sub-actions

The skill dispatches by the first positional argument:

Main-checkout-only is marked per row above. Those sub-actions compare git rev-parse --git-dir with --git-common-dir and, in a worktree, refuse and point back at the main checkout. The marker has two reasons: upgrade and the snapshot fallback of install/uninstall are pinned-snapshot operations, while adopt/unadopt write committed files. A marketplace install touches no repo state and runs anywhere.

reconcile is restricted only when the project is adopted, because its stamp then goes to the committed lock. A configured-but-unadopted project writes reconciled.json in its personal layer, <git-common-dir>/apache-magpie/, and has no worktree restriction (reconcile.md Step 0).

adopt and upgrade always chain into worktree-init on every linked worktree. It is a no-op with no worktrees and idempotent where they already look wired, which is how broken symlinks and newly always-on families get repaired — nobody has to re-run anything per worktree.

A missing snapshot with a committed lock turns any sub-action into the recover-snapshot path: re-install per the lock, then continue.