setup-preflight
Capability: substrate:setup
Harness: agnostic
Resolve a project’s Magpie setup state, and one skill’s fingerprint, into a machine-readable verdict.
Every framework skill has to answer the same question before it runs: is this project set up for the framework version now installed? That question used to be answered by prose the agent re-read on every invocation of every skill. Most of it was not judgement at all — read a lock, compare two hashes, order two versions, subtract two dates — so it is answered here instead, once, deterministically, and testably.
What stays prose is what a model is actually for: which proposal to make,
how to word it, and the prohibitions. Those live in each skill’s
preflight-detail.md, and a finding names the section that applies.
Prerequisites
- Runtime — Python 3.11+. Standard library only, deliberately: the
module is copied into the user’s personal configuration layer and run
with bare
python3, where nothing else is available. - CLIs — none required. The running harness’s own listing command
(detected from its environment markers, e.g.
claude plugin list --jsonunder Claude Code) is consulted when present; its absence or the absence of any harness marker is a supported state, not an error.isolated_verifyalso runsgit,claude --version, and on Linuxbwrap --versionandsocat -V, each optional. - Credentials / auth — none.
- Network — none. Every input is a file in the project.
- Optional —
--plugin-listaccepts a listing the caller already read, so the tool never has to shell out.
Why it is installed into the project
The obvious home is the plugin, and it does not work. Under the sandbox
the framework itself recommends, ~/.claude/plugins/cache/ is
read-denied, so a script shipped in the plugin can be read by the agent’s
file tool but never executed by a shell — and a sandboxed marketplace
install is exactly the environment the reconciliation check was written
for. So /magpie-setup:setup config copies this module under the
per-user ~/.cache/apache-magpie/preflight/, with or without version
control, and /magpie-setup:setup update refreshes that copy against the
framework version now installed. Where exactly depends on where the copy
comes from (layers.checker_install_dir):
- From a known framework location (
layers.framework_roots, resolved, and never inside the project) — a harness’s plugin install, or the framework copy under the user’s home — it goes in the sharedchecker_diritself and serves every project without a copy of its own. The lastconfigorupdatefrom a plugin decides its version; it reads each project’s own lock and configuration, so it serves projects pinned to different versions. - From anywhere else — a pinned snapshot at
<project>/.apache-magpie/, which a tarball can carry as easily as a real install, or any other directory, since the rule fails closed — it goes inprojects/<key>/(layers.project_checker_home), where<key>is the first 16 hex digits of the SHA-256 of the project root’s resolved path, and serves that project alone. Code from inside one tree never reaches the shared directory, so a crafted tree can run nothing in any other project. Symlinks are resolved on both sides before the comparison. Beside it,root-idrecords the resolved root’sst_devandst_ino(layers.record_root_identity): the path outlives the project, so the block andlayers.import_diruse the copy only while the tree at that path is the one it was installed for, and otherwise fall back to the shared copy.
uninstall removes a project’s own projects/<key>/ copy with its
snapshot; it never touches the shared copy, which serves other projects.
Pre-flight imports the checker only from outside the opened project. Every skill runs it as
PYTHONPATH="$(python3 -I -c 'import hashlib,os,sys;h,d,m,i=sys.argv[1:];r=os.path.realpath(os.curdir);s=os.stat(r);p=os.path.join(h,d,hashlib.sha256(r.encode()).hexdigest()[:16]);f=os.path.join(p,i);print(p if os.path.isdir(os.path.join(p,m)) and os.path.isfile(f) and open(f).read().split()==[str(s.st_dev),str(s.st_ino)] else h)' "$HOME/.cache/apache-magpie/preflight" projects setup_preflight root-id)" \
python3 -P -m setup_preflight …
The first python3 -I picks the directory — this project’s own when it
holds a checker, else the shared one (layers.import_dir) — with the
standard library alone: -I keeps the working directory, PYTHONPATH and
the user site off sys.path, so choosing never runs project code. Then
-P (Python 3.11+) keeps the working directory off sys.path for the
checker itself, and no directory inside the project is on PYTHONPATH —
not the gitignored .apache-magpie-local/ of an adopted project, which a
repository can still force-add, not the legacy in-tree one of an
unadopted project, and not the project’s .git/ or .svn/ either. A git
commit cannot carry a .git/, but a Subversion checkout versions one like
any directory, and a tarball can carry a .git/ or a .svn/ (with its
wc.db) that git and layers.py accept as real. Otherwise a project
that shipped a setup_preflight/ package would have its code run by every
skill’s pre-flight before any confirmation, and opening it would be enough
to run its code. The personal configuration still lives where
layers.py says; only the executable lives outside every project.
The key is computed in the block rather than in a bootstrap module because a bootstrap would itself have to live in the shared directory, which a snapshot-only machine never fills; the one-liner needs nothing installed.
That has a consequence worth stating plainly: pre-flight may run config
unattended, so an unattended run can place an executable under the
user’s ~/.cache/apache-magpie/preflight/. It is framework code of the
same provenance as the framework the adopter installed, it is never
committed, and it is per-user — but it is a step beyond writing
configuration files.
Invocation
PYTHONPATH="<checker_dir>" python3 -P -m setup_preflight \
--skill magpie-pr-management-triage \
--hash sha256:9f1c4e… \
--requires pr-management-config.md
In the framework checkout, the same thing through the workspace:
uv run --directory tools/setup-preflight --project . setup-preflight --skill … --hash …
Output
{ "verdict": "ok" }
…or a list of findings, each naming its scope and the
preflight-detail.md section whose rules apply:
{
"verdict": "action",
"findings": [
{ "scope": "project", "code": "below-floor", "section": "step-3", "facts": {…} },
{ "scope": "skill", "code": "fingerprint-moved", "section": "step-4", "facts": {…} }
]
}
Exit status is 0 whenever a verdict was reached, findings included. A finding is the answer, not a failure. A non-zero exit means the check could not run, and the caller falls back to the detail file rather than assuming the project is fine.
The scopes
project findings are true of the checkout and identical for every
skill invoked in it — the lock, snapshot drift, the marketplace floor.
They are memoised in <personal-layer>/.preflight-cache.json, keyed
on the lock files’ identity and the plugin listing and expiring after 15
minutes, so the second and later skills in a session pay only for their
own fingerprint comparison.
skill findings differ per skill: its fingerprint against the
reconciliation stamp, and whether its requires_config: entries resolve.
family findings are about the invoking skill as a Magpie skill and as a member of its family.
Today there is one: welcome, a first-run welcome guide, with its rules in the welcome section.
setup_preflight/guides/general.md is due on the first run of any Magpie skill,
and guides/<family>.md (today security) on the first run of a skill in that family.
At most one guide per run: a first showing beats a repeat, and between equals the general guide goes first,
so the family guide’s first showing comes on the run after the general one.
facts.family names the guide (general or the family) and facts.guide carries it,
so the agent shows it without another read;
the general guide’s list of family guides is generated from the files in guides/.
The family comes from families.py, a map of every skill’s frontmatter family:
generated by python3 -m setup_preflight.welcome write-constant
and kept current by check-family-plugins (--fix regenerates it),
because a marketplace install’s copy of this package has no skills to read.
The user’s answer is recorded under welcome.<guide> (welcome.general, welcome.security) in the personal layer’s reconciled.json:
| Choice | Shown again |
|---|---|
seen (Continue, or no answer) |
on the next run, three recorded showings in all |
dismiss |
after the framework version changes |
never |
after enable |
The version is the magpie-setup plugin’s, read beside this package,
in the project’s framework tree or in its pinned snapshot;
the personal-layer copy of a marketplace install has no manifest,
so there it is a fingerprint of this package, which /magpie-setup:setup update refreshes.
The finding is skipped where there is no personal layer to record into,
--no-welcome leaves it out, and a personal layer holding nothing but that record
does not make the project count as configured.
python3 -m setup_preflight.welcome list
python3 -m setup_preflight.welcome show --family general [--color[=auto|always|never]]
python3 -m setup_preflight.welcome record --family security --choice seen|dismiss|never
python3 -m setup_preflight.welcome enable --family security
show --color renders the guide for a terminal, in colour only on a tty;
--color=always colours off a tty too (an agent’s ! shell command);
NO_COLOR turns colour off either way.
The welcome-guide skill
(/magpie-setup:welcome-guide [<family>]) is the user-facing way to run show and enable.
machine findings are about the isolated (secure agent) setup on
this machine, reported only where it is used: isolated-setup-changed
when the fingerprint of the secure-setup files differs from the one the
last setup-isolated-setup-update run recorded, and
isolated-setup-update-due when that run or its last reminder is older
than isolated_setup_update_interval_days (default 7). The fingerprint
is computed from the framework source when the checkout has it, and
otherwise read from the generated isolated_fingerprint.py, which the
isolated-setup-fingerprint prek hook keeps current.
python3 -m setup_preflight.isolated record-update | record-reminder
writes the stamp.
python3 -m setup_preflight.upgrade gather prints, read-only, what
setup-upgrade decides its catalogue reads from: layers, configured,
the install branch (local, marketplace, snapshot, none),
listing_known, the project-scope findings, shadowed (personal files with
a committed file of the same path, and whether they are identical) and
isolated (state, changed since the last recorded update run, due,
and attention, the two combined for a setup in use).
A reminder that was only shown does not count as a check that ran.
end-of-run is the periodic /magpie-setup:setup verify suggestion, which
is settled when the run finishes rather than before it starts.
Two rules that are the reason this is code
Unknown is never absent. A plugin listing that could not be read is
None, not {}. Inside a sandboxed session the plugin cache is
read-denied and the running harness’s own listing prints [], which
reads exactly like “nothing installed”; acting on it would propose
installing a project’s entire floor on every sandboxed run. An empty
parsed listing is treated as unknown for the same reason — it is
indistinguishable from the denied case.
A dev build is a version like any other. Nothing strips or rounds a
.devN segment. 0.2.0.dev202609110041 is below 0.2.0, and 0.10.0
is above 0.9.0 — the two orderings a string comparison gets wrong in
opposite directions.
Delegation
delegation.py resolves which skill does a Magpie skill’s work when the
project delegates it to its own skill:
it reads the delegate: frontmatter block from <override-name>.md along
the override chain, the first layer that declares one winning, and
validates it strictly — an unknown key, a malformed line, a missing or
out-of-repository project skill, a Magpie skill named as the delegate, or a
merge that would skip: a pre-flight, golden-rule, confirmation, scrub or
privacy step is refused whole, and the framework default runs.
The pre-flight runs it on every invocation, uncached (it reads a handful of
small files), and adds skill-scope findings, all naming step-13:
delegated— the invoked skill is delegated;factsis the resolution;delegate-refused— its delegate was declared and refused, withreason;handoff-delegates— the other delegated skills it may hand off to.
None appear when nothing is delegated, so the ordinary verdict stays ok.
The pre-flight passes a frontmatter name:; override files carry the
skills/<name> entry’s name. skill_names.py maps one to the other and is
generated: python3 -m setup_preflight.delegation write-names rewrites it,
and a test fails when it is stale.
python3 -m setup_preflight.delegation resolve security-issue-triage
python3 -m setup_preflight.delegation list
python3 -m setup_preflight.delegation render --skill security-issue-triage \
--delegate triage-reports --mode merge --step "magpie:Step 1 — Gather" --step "project:Reproduce"
Discovery
discovery.py is the deterministic half of
setup delegate:
it lists the project’s own skills (.claude/skills/, .agents/skills/,
.github/skills/, never magpie-* links or anything resolving outside the
repository), scores each against Magpie’s skills by set overlap of names,
description + when_to_use, and step headings, and drafts a merged step
list from the two skills’ headings. It writes nothing, and project skill
text is only tokenised and quoted.
python3 -m setup_preflight.discovery --project-root . --magpie-skills .apache-magpie/skills
python3 -m setup_preflight.discovery --project-root . --magpie-catalogue <file.json>
Isolated-setup verification
isolated_verify.py is the mechanical half of
setup-isolated-setup-verify
for Claude Code.
It decides checks 1 to 6, the static half of 8, and 11 from the merged settings files, the hook scripts, the shell rc files and the version commands,
and evaluates the conditions that make checks 9, 10, 12, 13, 15, 16, 17 and 19 apply (n/a when one does not).
The live probes (check 7, check 8’s read and write) and the checks that need judgement stay with the skill.
python3 -P -m setup_preflight.isolated_verify check --project-root . [--framework <magpie-checkout>]
It prints facts and one findings entry per check, 1 to 19, with a status
(pass, fail, warn, n/a, unchecked, unknown or manual) and its evidence.
unknown means an input could not be read from where it ran, usually the sandbox’s read-deny on the home directory:
unreadable names it, and see the section of the skill’s
manual-checks.md
or conditional-checks.md the agent finishes it with.
It writes nothing and reaches no network; besides reading files it runs git, claude --version, and on Linux bwrap --version and socat -V,
and it prints no shell rc line other than the matched source and alias lines.
Tests
uv run --directory tools/setup-preflight --project . python -m pytest
Each test is named for the rule it pins. A failure is a change to what every skill does before it runs, not merely a refactor.