---

title: Adoption & setup status: stable kind: feature mode: infra source: > README.md § How adoption works / Adopting the framework / Maintenance. Implemented by the setup family (setup and siblings) and the snapshot + agentic-override model. acceptance:

• An adopter commits exactly one skill (setup); everything else is a gitignored snapshot plus committed override + lock files.
• The committed lock pins install method + URL + ref so a fresh clone re-installs the same framework version.
• Drift between the committed pin and the local install is detected and surfaced with an upgrade proposal.
• A gitignored .apache-magpie-local/ supplies per-person overrides that layer above the committed .apache-magpie-overrides/, cannot weaken the safety baseline, and can be ignored for a single run via a one-shot default switch.

---

Adoption & setup

What it does

Gets the framework into an adopter repo and keeps it current using a snapshot + agentic-override model: one committed bootstrap skill, a gitignored framework snapshot (a build artefact, never committed), gitignored skill symlinks, and committed agent-readable override files.

Where it lives

• Skill: setup (adopt, verify, upgrade, override).
• Skills: setup-isolated-setup-install / -update / -verify / -doctor (the sandbox harness; -doctor probes live restrictions — SSH agent / Yubikey reachability, localhost port binding, filesystem restrictions), setup-override-upstream (promote a stabilised override into a framework PR), setup-shared-config-sync.
• Skill: setup-status — renders a Markdown adoption dashboard: install method and pin, drift between local and committed locks, which skills are wired in the current repo.
• Docs: docs/setup/ (install recipes, agentic-overrides contract, prerequisites).
• Lock files: .apache-magpie.lock (committed pin) and .apache-magpie.local.lock (gitignored, what this machine fetched).

Behaviour & contract

• One committed skill, no submodules, no vendored framework copies. The snapshot lives in a gitignored .apache-magpie/.
• .agents/skills/ is the canonical home for framework-skill symlinks (the path shared by Codex, Cursor, Gemini CLI, Copilot, …); every other agent dir (.claude/skills/, .github/skills/, holdouts) gets per-skill relay symlinks into it. This is uniform — there is no per-project skills-dir convention to detect.
• Committed lock is the source of truth. A fresh contributor runs /magpie-setup and re-installs to the project's pinned version.
• Drift detection at the top of every framework skill: if the gitignored local lock has drifted from the committed pin, the skill proposes /magpie-setup upgrade.
• Overrides are agent-readable Markdown under .apache-magpie-overrides/, consulted at runtime and merged before default behaviour ([pairing/correctability is the model]).
• Overrides are additive, never authority inversion. An override may supply adopter-specific process details, paths, labels, or wording, but it must not replace or weaken the framework's safety, confidentiality, privacy, or external-content-as-data baseline. If an override conflicts with those baseline rules, the framework rule wins and the conflict is surfaced.
• Personal, gitignored overrides live under .apache-magpie-local/, a per-person sibling to the committed .apache-magpie-overrides/ that is never committed. It is read at runtime under the same additive-only guardrail as any override: it may carry a person's paths, wording, or capability/MCP enablement (for example a release manager enabling a Policy MCP that other members leave off), but it cannot weaken the safety, confidentiality, or privacy baseline. Precedence, first hit wins: .apache-magpie-local/ -> .apache-magpie-overrides/ -> organization defaults -> framework default. Adoption adds the .gitignore entry; on a repo that has not adopted Magpie, the user adds that one line by hand so the directory stays untracked. This is the surface that makes hybrid setups work: one person can run Magpie against a shared or non-adopting repo without committing anything or requiring teammates to opt in.
• One-shot default run. A per-invocation switch runs a skill against framework defaults for that session only, ignoring both .apache-magpie-local/ and .apache-magpie-overrides/, without editing or removing either file. The safety baseline still applies.

Out of scope

• The runtime behaviour of the modes themselves.
• Editing the adopter's .claude/settings.json beyond what the install recipe declares.

Acceptance criteria

1. Adoption commits only the bootstrap skill + lock/override scaffold.
2. The committed lock re-installs the same version on a fresh clone.
3. Drift between local and committed locks is surfaced with an upgrade.
4. Override files can be discovered and surfaced to skills without editing upstream skill bodies, and override text cannot weaken the safety/confidentiality baseline.
5. A gitignored .apache-magpie-local/ is read as a per-person override surface that layers above .apache-magpie-overrides/ (personal-local -> committed -> organization -> framework default, first hit wins), under the same additive-only guardrail, and works on a repo that has not adopted Magpie once its .gitignore line is present.
6. A one-shot switch runs a skill against framework defaults for a single session, ignoring both override surfaces without deleting them, and the safety baseline still applies.

Validation

test -f docs/setup/README.md
uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-validate

Known gaps

• stable; gaps appear as new agent targets to add to the registry (agents.md) or new override surfaces — recorded by the plan pass.
• Not yet built: the .apache-magpie-local/ personal override surface (acceptance 5) and the one-shot default-run switch (acceptance 6). Both are intended behaviour recorded here and tracked as work items magpie-local-convention and override-bypass-one-shot in the plan. The three hybrid-setup how-tos that build on the local surface are tracked alongside them.