You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/09/10 09:14:47 UTC
(magpie) branch main updated: feat(plugins): fix Codex install, default-install a set, pre-flight every skill (#1193)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/magpie.git
The following commit(s) were added to refs/heads/main by this push:
new 227fcbaa feat(plugins): fix Codex install, default-install a set, pre-flight every skill (#1193)
227fcbaa is described below
commit 227fcbaaf8ff4ad01c9fe902fe663a8af5a1b07c
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Thu Sep 10 11:14:40 2026 +0200
feat(plugins): fix Codex install, default-install a set, pre-flight every skill (#1193)
Five changes that all trace back to the same gap: nothing checked what the
plugin manifests actually claim, and nothing checked whether an installed
plugin had been set up.
- **Codex install was broken.** `.agents/plugins/marketplace.json` carried
invented `policy` values (`manual`, `none`). Codex's enums are closed and
SCREAMING_SNAKE, and it rejects the *whole catalogue* on an unknown
variant — so `codex plugin marketplace add apache/magpie` failed and
nothing installed. Fixed to `AVAILABLE`, verified live against codex
0.154.0, and `check-family-plugins.py` now validates both policy enums so
the class of bug cannot return. The manifests had been checked against
vendor docs but never live-installed.
- **A stale published claim.** The all-in-one plugin advertised ~21.7k
always-on tokens; the measured figure is ~8.6k.
- **A default-installed set.** A project can commit `enabledPlugins` so a
contributor arrives with `magpie-setup`, `magpie-utilities` and
`magpie-agent-guard` already on. Documented per harness, including why
only Claude Code can express it: per-family plugins are Claude Code-only,
so Codex could only default-install all ten families, and Gemini has no
workspace-extension mechanism at all (verified against the CLI).
- **JetBrains IDEs.** Documented as a host, not a distribution target —
plugin state lives in one user-scope store shared by every host of the
same CLI, so installing in a terminal covers the IDE. Junie remains a
separate harness port (#321).
- **A shared setup pre-flight in every skill.** `locks.md` already claimed a
drift check ran "on every framework-skill invocation"; nothing implemented
it. It cannot be a hook (no code runs on plugin install/upgrade on most
harnesses) and cannot be an include (a family plugin's symlinks may not
escape its root under AP1), so it is one source propagated into 65 skill
bodies by `check-skill-preflight.py --fix`, with a hook preventing drift.
The `setup` family is exempt — those skills perform the setup.
Also excludes `hooks/` from the in-place pre-commit fixers: the sandbox
write-denies hook scripts, which aborted `prek run --all-files` on a file
that needed no fix.
Generated-by: Claude Code (Opus 5)
---
.agents/plugins/marketplace.json | 13 +-
.claude-plugin/marketplace.json | 28 ++--
.claude-plugin/plugin.json | 2 +-
.claude/settings.json | 10 ++
.codex-plugin/plugin.json | 2 +-
.pre-commit-config.yaml | 49 ++++--
CONTRIBUTING.md | 7 +
apm.yml | 2 +-
docs/setup/marketplaces.md | 131 ++++++++++++++-
gemini-extension.json | 2 +-
plugin.json | 2 +-
.../magpie-agent-guard/.claude-plugin/plugin.json | 2 +-
.../.claude-plugin/plugin.json | 2 +-
plugins/magpie-issue/.claude-plugin/plugin.json | 2 +-
.../magpie-mentoring/.claude-plugin/plugin.json | 2 +-
plugins/magpie-pairing/.claude-plugin/plugin.json | 2 +-
.../.claude-plugin/plugin.json | 2 +-
.../.claude-plugin/plugin.json | 2 +-
.../magpie-repo-health/.claude-plugin/plugin.json | 2 +-
plugins/magpie-security/.claude-plugin/plugin.json | 2 +-
plugins/magpie-setup/.claude-plugin/plugin.json | 2 +-
.../magpie-utilities/.claude-plugin/plugin.json | 2 +-
.../magpie-vetted-ops/.claude-plugin/plugin.json | 2 +-
pyproject.toml | 2 +-
skills/audit-finding-fix/SKILL.md | 45 ++++++
skills/ci-runner-audit/SKILL.md | 45 ++++++
skills/committer-onboarding/SKILL.md | 45 ++++++
skills/contributor-activity-sweep/SKILL.md | 45 ++++++
skills/contributor-nomination/SKILL.md | 45 ++++++
skills/contributor-sentiment/SKILL.md | 45 ++++++
skills/contributor-to-committer/SKILL.md | 45 ++++++
skills/dependency-audit/SKILL.md | 45 ++++++
skills/dependency-license-audit/SKILL.md | 45 ++++++
skills/flaky-test-triage/SKILL.md | 45 ++++++
skills/good-first-issue-author/SKILL.md | 45 ++++++
skills/good-first-issue-sweep/SKILL.md | 45 ++++++
skills/issue-backlog-stats/SKILL.md | 45 ++++++
skills/issue-deduplicate/SKILL.md | 45 ++++++
skills/issue-fix-workflow/SKILL.md | 45 ++++++
skills/issue-reassess-stats/SKILL.md | 45 ++++++
skills/issue-reassess/SKILL.md | 45 ++++++
skills/issue-reproducer/SKILL.md | 45 ++++++
skills/issue-stale-sweep/SKILL.md | 45 ++++++
skills/issue-triage/SKILL.md | 45 ++++++
skills/license-compliance-audit/SKILL.md | 45 ++++++
skills/list-skills/SKILL.md | 45 ++++++
skills/mentoring-welcome/SKILL.md | 45 ++++++
skills/newcomer-issue-explainer/SKILL.md | 45 ++++++
skills/onboarding-concierge/SKILL.md | 45 ++++++
skills/optimize-skill/SKILL.md | 45 ++++++
skills/pairing-multi-agent-review/SKILL.md | 45 ++++++
skills/pairing-self-review/SKILL.md | 45 ++++++
skills/pr-management-code-review/SKILL.md | 45 ++++++
skills/pr-management-mentor/SKILL.md | 45 ++++++
skills/pr-management-quick-merge/SKILL.md | 45 ++++++
skills/pr-management-stats/SKILL.md | 45 ++++++
skills/pr-management-triage/SKILL.md | 45 ++++++
skills/pr-stale-sweep/SKILL.md | 45 ++++++
skills/pre-first-pr-check/SKILL.md | 45 ++++++
skills/release-announce-draft/SKILL.md | 45 ++++++
skills/release-archive-sweep/SKILL.md | 45 ++++++
skills/release-audit-report/SKILL.md | 45 ++++++
skills/release-keys-sync/SKILL.md | 45 ++++++
skills/release-prepare/SKILL.md | 45 ++++++
skills/release-promote/SKILL.md | 45 ++++++
skills/release-rc-cut/SKILL.md | 45 ++++++
skills/release-verify-rc/SKILL.md | 45 ++++++
skills/release-vote-draft/SKILL.md | 45 ++++++
skills/release-vote-tally/SKILL.md | 45 ++++++
skills/report-framework-issue/SKILL.md | 45 ++++++
skills/reviewer-routing/SKILL.md | 45 ++++++
skills/security-cve-allocate/SKILL.md | 45 ++++++
skills/security-issue-deduplicate/SKILL.md | 45 ++++++
skills/security-issue-fix/SKILL.md | 45 ++++++
skills/security-issue-import-from-md/SKILL.md | 45 ++++++
skills/security-issue-import-from-pr/SKILL.md | 45 ++++++
skills/security-issue-import-from-scan/SKILL.md | 45 ++++++
.../security-issue-import-via-forwarder/SKILL.md | 45 ++++++
skills/security-issue-import/SKILL.md | 45 ++++++
skills/security-issue-invalidate/SKILL.md | 45 ++++++
skills/security-issue-sync/SKILL.md | 45 ++++++
skills/security-issue-triage/SKILL.md | 45 ++++++
skills/security-model-prepare/SKILL.md | 45 ++++++
skills/security-model-update/SKILL.md | 45 ++++++
skills/security-model-verify/SKILL.md | 45 ++++++
skills/security-tracker-stats-dashboard/SKILL.md | 45 ++++++
skills/skill-reconciler/SKILL.md | 45 ++++++
skills/workflow-security-audit/SKILL.md | 45 ++++++
skills/write-skill/SKILL.md | 45 ++++++
tools/dev/README.md | 3 +-
tools/dev/check-family-plugins.py | 64 +++++++-
tools/dev/check-skill-preflight.py | 178 +++++++++++++++++++++
tools/dev/preflight-block.md | 40 +++++
tools/sandbox-lint/expected.json | 10 ++
uv.lock | 2 +-
95 files changed, 3445 insertions(+), 51 deletions(-)
diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
index defdb437..02051c62 100644
--- a/.agents/plugins/marketplace.json
+++ b/.agents/plugins/marketplace.json
@@ -1,12 +1,19 @@
{
"name": "apache-magpie",
- "interface": { "displayName": "Apache Magpie" },
+ "interface": {
+ "displayName": "Apache Magpie"
+ },
"plugins": [
{
"name": "magpie",
- "source": { "source": "local", "path": "." },
+ "source": {
+ "source": "local",
+ "path": "."
+ },
"category": "maintenance",
- "policy": { "installation": "manual", "authentication": "none" }
+ "policy": {
+ "installation": "AVAILABLE"
+ }
}
]
}
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index d954c8d3..5d35ce2c 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -9,79 +9,79 @@
{
"name": "magpie",
"source": ".",
- "version": "0.2.0.dev202609092258",
- "description": "All Apache Magpie skills (all 10 families; ~21.7k always-on tokens)."
+ "version": "0.2.0.dev202609100826",
+ "description": "All Apache Magpie skills (all 10 families; ~8.6k always-on tokens)."
},
{
"name": "magpie-agent-guard",
"source": "./plugins/magpie-agent-guard",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie \u2014 deterministic pre-execution command guard: a PreToolUse hook that denies shell commands which would break a hard framework rule. Runs from the installed plugin, so no repository or worktree needs a local copy."
},
{
"name": "magpie-vetted-ops",
"source": "./plugins/magpie-vetted-ops",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie \u2014 vetted-ops: a dispatcher for fixed, policy-scoped forge operations, so a session needs one allowlist entry instead of a dozen wildcard `ask` rules. Runs from the installed plugin, which is what keeps the operation catalogue out of reach of the agent that calls it."
},
{
"name": "magpie-contributor-growth",
"source": "./plugins/magpie-contributor-growth",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie contributor-growth family (6 skills)."
},
{
"name": "magpie-issue",
"source": "./plugins/magpie-issue",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie issue family (8 skills)."
},
{
"name": "magpie-mentoring",
"source": "./plugins/magpie-mentoring",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie mentoring family (4 skills)."
},
{
"name": "magpie-pairing",
"source": "./plugins/magpie-pairing",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie pairing family (2 skills)."
},
{
"name": "magpie-pr-management",
"source": "./plugins/magpie-pr-management",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie pr-management family (8 skills)."
},
{
"name": "magpie-release-management",
"source": "./plugins/magpie-release-management",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie release-management family (10 skills)."
},
{
"name": "magpie-repo-health",
"source": "./plugins/magpie-repo-health",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie repo-health family (7 skills)."
},
{
"name": "magpie-security",
"source": "./plugins/magpie-security",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie security family (15 skills)."
},
{
"name": "magpie-setup",
"source": "./plugins/magpie-setup",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie setup family (9 skills)."
},
{
"name": "magpie-utilities",
"source": "./plugins/magpie-utilities",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie utilities family (5 skills)."
}
]
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 66623641..7cffd098 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "magpie",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie — a reusable, governance-agnostic framework of agentic skills for maintaining open-source projects: release management, security triage, PR and issue workflows, contributor growth, and repo health.",
"author": { "name": "Apache Magpie", "url": "https://magpie.apache.org/" },
"homepage": "https://magpie.apache.org/",
diff --git a/.claude/settings.json b/.claude/settings.json
index f6ced830..89962227 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -139,5 +139,15 @@
"Bash(git push --force-with-lease *)",
"Bash(gh *)"
]
+ },
+ "extraKnownMarketplaces": {
+ "apache-magpie": {
+ "source": { "source": "github", "repo": "apache/magpie" }
+ }
+ },
+ "enabledPlugins": {
+ "magpie-setup@apache-magpie": true,
+ "magpie-utilities@apache-magpie": true,
+ "magpie-agent-guard@apache-magpie": true
}
}
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 45e51abd..f2f36581 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "magpie",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie — agentic skills for maintaining open-source projects.",
"skills": "./skills",
"hooks": {
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c20c510a..495385f8 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -94,20 +94,26 @@ repos:
# The next three hooks are *fixers*: they open every matched file
# in read-write mode (to normalise it in place) before checking
# whether a fix is even needed. The secure-agent sandbox
- # write-denies two tracked path sets — the agent's own config
- # (`.claude/settings.json`) and the self-adoption skill relays
- # (`.claude/skills/*` symlinks) — because agents must never modify
- # them. So on `prek run --all-files` (which `agent-pre-commit.sh`
- # and the CI mirror both run) the read-write `open()` on those
- # paths is denied and the whole run aborts, even though the files
- # need no fix. Exclude them: `.claude/settings.json` is gated by
- # the sandbox-lint baseline and the skill symlinks are validated by
- # `symlink-lint`, so neither loses coverage by skipping EOF /
- # whitespace / line-ending normalisation here. This keeps prek a
- # single invocation that runs cleanly in-sandbox with no bypass.
+ # write-denies three tracked path sets — the agent's own config
+ # (`.claude/settings.json`), the self-adoption skill relays
+ # (`.claude/skills/*` symlinks), and the plugin hook scripts
+ # (`hooks/`) — because agents must never modify them. A hook script
+ # runs automatically on a harness event, so an agent that could
+ # rewrite one could arrange to run arbitrary code on the next
+ # session start; the deny is the point, not an oversight. So on
+ # `prek run --all-files` (which `agent-pre-commit.sh` and the CI
+ # mirror both run) the read-write `open()` on those paths is denied
+ # and the whole run aborts, even though the files need no fix.
+ # Exclude them: `.claude/settings.json` is gated by the
+ # sandbox-lint baseline, the skill symlinks are validated by
+ # `symlink-lint`, and `hooks/check-upgrade.sh` is checked for
+ # existence and correct wiring by `check-family-plugins.py`, so
+ # none of them loses coverage by skipping EOF / whitespace /
+ # line-ending normalisation here. This keeps prek a single
+ # invocation that runs cleanly in-sandbox with no bypass.
- id: end-of-file-fixer
name: Make sure that there is an empty line at the end
- exclude: &sandbox_write_denied ^\.claude/(settings\.json|skills/)
+ exclude: &sandbox_write_denied ^(\.claude/(settings\.json|skills/)|hooks/)
- id: mixed-line-ending
name: Detect if mixed line ending is used (\r vs. \r\n)
exclude: *sandbox_write_denied
@@ -295,6 +301,25 @@ repos:
entry: python3 tools/dev/check-family-plugins.py --fix
files: ^(skills/.*/SKILL\.md|plugins/.*|\.claude-plugin/(marketplace|plugin)\.json|\.codex-plugin/plugin\.json|\.agents/plugins/marketplace\.json|(plugin|marketplace)\.json|gemini-extension\.json|apm\.yml|pyproject\.toml|hooks/check-upgrade\.sh)$
pass_filenames: false
+ # The shared setup pre-flight every skill runs before it acts. It cannot be
+ # a hook: on most harnesses *no code runs at all* when a plugin is installed
+ # or upgraded (AP1 defines no hook component; Claude Code's SessionStart hook
+ # is wired only into the all-in-one plugin), so the check has to be
+ # instructions the agent reads on invocation. It cannot be an include either:
+ # a family plugin symlinks `skills/<skill>` and AP1 forbids a symlink
+ # escaping the plugin root, so a shared file would be unreachable from the
+ # install shape most adopters use. That leaves one source and 65 generated
+ # copies, which is exactly the drift this hook exists to prevent — edit
+ # `tools/dev/preflight-block.md` and let `--fix` propagate it. The `setup`
+ # family is exempt: those skills perform the setup the block asks for.
+ - repo: local
+ hooks:
+ - id: check-skill-preflight
+ name: check-skill-preflight (shared pre-flight block in every SKILL.md)
+ language: system
+ entry: python3 tools/dev/check-skill-preflight.py --fix
+ files: ^(skills/[^/]+/SKILL\.md|tools/dev/preflight-block\.md)$
+ pass_filenames: false
# Documentation claims that must track the tree. Four mechanical checks,
# each added after the drift it catches was found by hand:
# - every tools/spec-loop/specs/*.md is listed in BOTH index files
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c16ae5d5..57360666 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -400,6 +400,13 @@ authoritative runtime matrix. The current state per harness:
| JetBrains Junie | Not yet ported | [#321](https://github.com/apache/magpie/issues/321) |
| OpenHands | Not yet ported | [#322](https://github.com/apache/magpie/issues/322) |
+The table lists **harnesses** — the agent that reads the skills — not the
+editors they run in. A JetBrains IDE, for instance, hosts an agent rather than
+being one: `JetBrains Junie` above is JetBrains' *own* agent and is genuinely
+not ported, but running Claude Code inside IntelliJ IDEA or PyCharm is the
+fully-supported Claude Code row, with nothing extra to install. See
+[the JetBrains section of `marketplaces.md`](docs/setup/marketplaces.md#jetbrains-ides-intellij-idea-pycharm-goland-).
+
MCP servers used by the reference runtimes today: Slack, Gmail,
Google Calendar, Google Drive, plus framework-internal ones for
the ponymail / incubator-mail / incubator-reports surfaces. MCP-
diff --git a/apm.yml b/apm.yml
index 073f401b..8f1133f9 100644
--- a/apm.yml
+++ b/apm.yml
@@ -6,7 +6,7 @@
# Gemini). Schema is v0.1 and may change — verify against the current
# https://microsoft.github.io/apm/ before publishing.
name: magpie
-version: 0.2.0.dev202609092258
+version: 0.2.0.dev202609100826
type: skill
description: >-
Apache Magpie — a reusable, governance-agnostic framework of agentic skills
diff --git a/docs/setup/marketplaces.md b/docs/setup/marketplaces.md
index f02885b1..cea92517 100644
--- a/docs/setup/marketplaces.md
+++ b/docs/setup/marketplaces.md
@@ -18,7 +18,11 @@
- [microsoft/apm (multiplexer)](#microsoftapm-multiplexer)
- [Kiro (AWS)](#kiro-aws)
- [OpenCode](#opencode)
+ - [JetBrains IDEs (IntelliJ IDEA, PyCharm, GoLand, …)](#jetbrains-ides-intellij-idea-pycharm-goland-)
- [Not supported](#not-supported)
+ - [Auto-install: arriving Magpie-ready](#auto-install-arriving-magpie-ready)
+ - [What each harness supports](#what-each-harness-supports)
+ - [Claude Code: the default set](#claude-code-the-default-set)
- [Automatic upgrade detection](#automatic-upgrade-detection)
- [Versioning](#versioning)
- [Verification status](#verification-status)
@@ -237,6 +241,7 @@ Quick reference:
| **microsoft/apm** | `apm install apache/magpie` (compiles to Claude/Cursor/Codex/Copilot/Gemini) | `apm.yml` |
| **Kiro** | install per-skill from a GitHub subdirectory, or the AP1 package | root `plugin.json` (AP1), native `skills/<name>/SKILL.md` |
| **OpenCode** | clone skills into `.opencode/skills/`, or use a community installer | native `skills/<name>/SKILL.md` |
+| **JetBrains IDEs** (IntelliJ, PyCharm, …) | nothing of its own — install for the agent you run inside the IDE, e.g. Claude Code's `/plugin marketplace add apache/magpie` | none; a host, not a distribution target |
Detailed steps per agent follow.
@@ -407,6 +412,44 @@ OpenCode reads native Agent Skills from `.opencode/skills/`. Either:
- use a community installer (e.g. the `opencode-skills-collection` npm
package) pointed at this repo.
+### JetBrains IDEs (IntelliJ IDEA, PyCharm, GoLand, …)
+
+A JetBrains IDE is a **host for an agent, not a distribution target of its
+own** — which is why it appears in no table above and ships no manifest in this
+repo. Nothing here needs installing *for* IntelliJ; you install for the agent
+you run inside it.
+
+With the **Claude Code plugin for JetBrains**, the install is the ordinary
+Claude Code one, run from the IDE's Claude Code window:
+
+```text
+/plugin marketplace add apache/magpie
+/plugin install magpie-setup@apache-magpie
+/plugin install magpie-utilities@apache-magpie
+```
+
+You do not have to run it twice. Claude Code keeps its plugin state in one
+user-scope store — `~/.claude/plugins/` (`known_marketplaces.json` and
+`installed_plugins.json`) — and every host that launches the same CLI reads it:
+the terminal, the VS Code extension, and the JetBrains plugin alike. Install
+from any one of them and the skills are there in the others. The same holds for
+the [auto-install](#auto-install-arriving-magpie-ready) block: it lives in the
+project's `.claude/settings.json`, so opening that project in IntelliJ picks it
+up exactly as opening it in a terminal does.
+
+Project-scope installs are keyed by the project's **path**, so a repo opened at
+the same path in the IDE and in a terminal shares them; a second clone
+elsewhere is a separate project and installs separately.
+
+> [!NOTE]
+> This is about running *Claude Code* (or another agent with a JetBrains
+> plugin) inside a JetBrains IDE. **JetBrains' own agent, Junie, is a separate
+> harness port** — tracked as
+> [#321](https://github.com/apache/magpie/issues/321) and listed *Not yet
+> ported* in [`CONTRIBUTING.md`](../../CONTRIBUTING.md) and
+> [`vendor-neutrality.md`](../vendor-neutrality.md). Junie does not read
+> Magpie's skills today.
+
### Not supported
- **Windsurf** — has no skills/rules marketplace; project rules are plain
@@ -416,6 +459,92 @@ OpenCode reads native Agent Skills from `.opencode/skills/`. Either:
(MCP) servers, not `SKILL.md` skills. Distributing Magpie there would
require wrapping skills behind an MCP server (a rebuild, not packaging).
+## Auto-install: arriving Magpie-ready
+
+Everything above is a person typing an install command. A project can instead
+commit the wiring, so a contributor who clones it and opens their agent finds
+Magpie already there. **Only Claude Code can actually do this**, and the
+difference is structural rather than a gap someone forgot to fill.
+
+### What each harness supports
+
+| Harness | Auto-install | Mechanism |
+|---|---|---|
+| **Claude Code** | ✅ per-family | `extraKnownMarketplaces` + `enabledPlugins` in the project's `.claude/settings.json` |
+| **OpenAI Codex CLI** | ⚠️ all-or-nothing | `policy.installation: "INSTALLED_BY_DEFAULT"` in `.agents/plugins/marketplace.json` — installs **all ten families**, so Magpie does not use it |
+| **VS Code / GitHub Copilot** | ❌ | No repo-side mechanism. The catalogue advertises; it cannot pre-install |
+| **Google Gemini CLI** | ❌ | Install is explicit-only. Gemini does **not** load a workspace `.gemini/extensions/` directory — verified against the CLI, which reports "No extensions installed" for a repo-local extension |
+| **JetBrains IDEs** | ✅ inherited | Whatever the agent running inside the IDE supports. With Claude Code's JetBrains plugin that is the row above — the project's `.claude/settings.json` applies unchanged, because plugin state is one user-scope store shared by every host of the same CLI |
+
+The Codex and Copilot rows are the same constraint that keeps those catalogues
+listing only the all-in-one plugin: a family plugin reaches its skills through
+symlinks that resolve outside its own root, which Agent Plugins 1.0 forbids, so
+**per-family is a Claude Code feature**. Codex can therefore only default-install
+*everything*, which contradicts the load-only-what-you-use argument this page
+makes — so the catalogue pins `installation: "AVAILABLE"`, and
+`check-family-plugins.py` fails the build if that value drifts.
+
+> [!WARNING]
+> Codex parses its catalogue strictly and its policy values are closed
+> SCREAMING_SNAKE enums (`NOT_AVAILABLE` / `AVAILABLE` /
+> `INSTALLED_BY_DEFAULT`, and `ON_INSTALL` / `ON_USE` for the optional
+> `authentication`). An unknown variant does not mis-label the plugin — it
+> makes `codex plugin marketplace add` reject the **whole file**, so nothing
+> installs. This catalogue shipped invented values (`manual`, `none`) for a
+> release before anyone ran the command.
+
+### Claude Code: the default set
+
+Add to the project's `.claude/settings.json` — committed, so it applies to
+everyone who trusts the repo:
+
+```json
+{
+ "extraKnownMarketplaces": {
+ "apache-magpie": {
+ "source": { "source": "github", "repo": "apache/magpie" }
+ }
+ },
+ "enabledPlugins": {
+ "magpie-setup@apache-magpie": true,
+ "magpie-utilities@apache-magpie": true,
+ "magpie-agent-guard@apache-magpie": true
+ }
+}
+```
+
+Three plugins, for two different reasons.
+
+`setup` and `utilities` are the framework's two **always-on families** — the
+same pair the pinned-snapshot install wires unconditionally, with no way to ask
+for them or opt out. Between them a newcomer gets `/magpie-setup` to adopt and
+maintain the framework and `/magpie-utilities:list-skills` to discover
+everything else, at the smallest always-on cost. Every other family stays
+opt-in, which is the point.
+
+`magpie-agent-guard` is not a family at all — it is a
+[substrate plugin](#choosing-a-plugin-all-in-one-vs-per-family), a `PreToolUse`
+hook that denies shell commands which would break a hard framework rule
+(pinging maintainers, a `Co-Authored-By` trailer, marking a PR ready
+prematurely, leaking security language onto a public thread, emptying a PR via
+force-push). It is in the default set because a guard nobody remembered to
+install guards nothing: it costs no always-on context — it is a hook, not
+skills — and it is most valuable in exactly the sessions where nobody was
+thinking about it. It only ever *denies*, so the failure mode of having it on
+is a blocked command with a stated reason, not a silent action.
+
+> [!NOTE]
+> The guard runs from the installed plugin, so no repository or worktree needs
+> a local copy — and a contributor who has not enabled it is not protected by
+> it. That asymmetry is the argument for defaulting it on rather than
+> documenting it as optional.
+
+Pin the marketplace to a released tag by using `"repo": "apache/magpie@0.2.0"`
+if the project would rather not track `main`.
+
+Contributors keep the last word: a plugin enabled this way still appears in
+`/plugin`, and anyone can disable it locally.
+
## Automatic upgrade detection
When the marketplace updates the plugin to a new version, Magpie prompts you
@@ -502,7 +631,7 @@ documentation**; what varies is whether it has also been exercised against a
|---|---|---|
| root `plugin.json` | [Agent Plugins 1.0.0 spec](https://github.com/agentplugins/agent-plugins-spec/blob/main/spec/1.0.0.md) + [`plugin.schema.json`](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json) | Conforms to the published closed schema; enforced by `check-family-plugins.py`. Not yet live-installed |
| `.claude-plugin/*` | Claude Code plugins reference | Verified live — `claude plugin validate . --strict` passes with 0 warnings; a family plugin installs and loads from a local marketplace replica |
-| `.codex-plugin/plugin.json`, `.agents/plugins/marketplace.json` | Codex plugin docs (`Package your plugin`) | Matches the documented entry point, field set, and repo-marketplace path. Not yet live-installed; see the plugin-local hooks caveat above |
+| `.codex-plugin/plugin.json`, `.agents/plugins/marketplace.json` | Codex plugin docs (`Package your plugin`) + the `codex` binary's own enums | **Verified live** — `codex plugin marketplace add` + `plugin list` against codex 0.154.0. The first live run is what caught the invented `policy` values the documentation check could not; the enums are now enforced by `check-family-plugins.py`. See the plugin-local hooks caveat above |
| root `marketplace.json` | Copilot / VS Code plugin marketplace docs | Legacy-format catalog, explicitly still supported alongside AP1. Not yet live-installed |
| `gemini-extension.json` | Gemini CLI extensions docs | Follows the published schema. Google has joined the AP1 TSC but has published no migration for this file — keep both |
| `apm.yml` | `microsoft/apm` schema **v0.1** | Pre-1.0 and the most likely to churn; re-check before publish |
diff --git a/gemini-extension.json b/gemini-extension.json
index 870c4b05..950dbd74 100644
--- a/gemini-extension.json
+++ b/gemini-extension.json
@@ -1,6 +1,6 @@
{
"name": "magpie",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie — agentic skills for maintaining open-source projects. Skills are auto-discovered from ./skills.",
"contextFileName": "GEMINI.md"
}
diff --git a/plugin.json b/plugin.json
index eb33aab4..c3ea051d 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,7 +1,7 @@
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "magpie",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"description": "Apache Magpie — a reusable, governance-agnostic framework of agentic skills for maintaining open-source projects: release management, security triage, PR and issue workflows, contributor growth, and repo health.",
"author": { "name": "Apache Magpie", "url": "https://magpie.apache.org/" },
"homepage": "https://magpie.apache.org/",
diff --git a/plugins/magpie-agent-guard/.claude-plugin/plugin.json b/plugins/magpie-agent-guard/.claude-plugin/plugin.json
index bc7d3354..398537b2 100644
--- a/plugins/magpie-agent-guard/.claude-plugin/plugin.json
+++ b/plugins/magpie-agent-guard/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "magpie-agent-guard",
"description": "Apache Magpie \u2014 deterministic pre-execution command guard: a PreToolUse hook that denies shell commands which would break a hard framework rule. Runs from the installed plugin, so no repository or worktree needs a local copy.",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"author": {
"name": "Apache Magpie",
"url": "https://magpie.apache.org/"
diff --git a/plugins/magpie-contributor-growth/.claude-plugin/plugin.json b/plugins/magpie-contributor-growth/.claude-plugin/plugin.json
index 8a1b5877..4d2d3656 100644
--- a/plugins/magpie-contributor-growth/.claude-plugin/plugin.json
+++ b/plugins/magpie-contributor-growth/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "magpie-contributor-growth",
"description": "Apache Magpie \u2014 path-to-committer: activity sweeps, nominations, sentiment, readiness, committer/post-vote onboarding.",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"author": {
"name": "Apache Magpie",
"url": "https://magpie.apache.org/"
diff --git a/plugins/magpie-issue/.claude-plugin/plugin.json b/plugins/magpie-issue/.claude-plugin/plugin.json
index 19914c79..cc983af7 100644
--- a/plugins/magpie-issue/.claude-plugin/plugin.json
+++ b/plugins/magpie-issue/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "magpie-issue",
"description": "Apache Magpie \u2014 issue lifecycle: triage, reproduction, fix drafting, reassess, stale-sweep, dedup, backlog stats.",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"author": {
"name": "Apache Magpie",
"url": "https://magpie.apache.org/"
diff --git a/plugins/magpie-mentoring/.claude-plugin/plugin.json b/plugins/magpie-mentoring/.claude-plugin/plugin.json
index 9a8c6737..32f3684a 100644
--- a/plugins/magpie-mentoring/.claude-plugin/plugin.json
+++ b/plugins/magpie-mentoring/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "magpie-mentoring",
"description": "Apache Magpie \u2014 newcomer mentoring: welcome, newcomer-issue explanations, good-first-issue authoring + sweep.",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"author": {
"name": "Apache Magpie",
"url": "https://magpie.apache.org/"
diff --git a/plugins/magpie-pairing/.claude-plugin/plugin.json b/plugins/magpie-pairing/.claude-plugin/plugin.json
index 577e37c6..8d3389c2 100644
--- a/plugins/magpie-pairing/.claude-plugin/plugin.json
+++ b/plugins/magpie-pairing/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "magpie-pairing",
"description": "Apache Magpie \u2014 pair a change with a structured self-review or a multi-agent adversarial review.",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"author": {
"name": "Apache Magpie",
"url": "https://magpie.apache.org/"
diff --git a/plugins/magpie-pr-management/.claude-plugin/plugin.json b/plugins/magpie-pr-management/.claude-plugin/plugin.json
index df389019..35b7c421 100644
--- a/plugins/magpie-pr-management/.claude-plugin/plugin.json
+++ b/plugins/magpie-pr-management/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "magpie-pr-management",
"description": "Apache Magpie \u2014 PR-queue management: triage, stats, deep code review, quick-merge, stale-sweep, reviewer routing, pre-first-PR checks.",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"author": {
"name": "Apache Magpie",
"url": "https://magpie.apache.org/"
diff --git a/plugins/magpie-release-management/.claude-plugin/plugin.json b/plugins/magpie-release-management/.claude-plugin/plugin.json
index 37508cc4..bac6b2d9 100644
--- a/plugins/magpie-release-management/.claude-plugin/plugin.json
+++ b/plugins/magpie-release-management/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "magpie-release-management",
"description": "Apache Magpie \u2014 ASF release lifecycle: plan, RC cut/sign, vote, tally, promote, announce, archive, audit.",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"author": {
"name": "Apache Magpie",
"url": "https://magpie.apache.org/"
diff --git a/plugins/magpie-repo-health/.claude-plugin/plugin.json b/plugins/magpie-repo-health/.claude-plugin/plugin.json
index 336d90dc..0cbdf1a0 100644
--- a/plugins/magpie-repo-health/.claude-plugin/plugin.json
+++ b/plugins/magpie-repo-health/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "magpie-repo-health",
"description": "Apache Magpie \u2014 read-only repo-health audits: runner labels, workflow security, dependency/license/NOTICE, flaky tests, audit-finding fixes.",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"author": {
"name": "Apache Magpie",
"url": "https://magpie.apache.org/"
diff --git a/plugins/magpie-security/.claude-plugin/plugin.json b/plugins/magpie-security/.claude-plugin/plugin.json
index e796cda8..d3bacb6e 100644
--- a/plugins/magpie-security/.claude-plugin/plugin.json
+++ b/plugins/magpie-security/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "magpie-security",
"description": "Apache Magpie \u2014 security-issue handling lifecycle \u2014 import through CVE publication, triage, sync, dedup, invalidate. Maintainer-only.",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"author": {
"name": "Apache Magpie",
"url": "https://magpie.apache.org/"
diff --git a/plugins/magpie-setup/.claude-plugin/plugin.json b/plugins/magpie-setup/.claude-plugin/plugin.json
index d32943c0..39866a16 100644
--- a/plugins/magpie-setup/.claude-plugin/plugin.json
+++ b/plugins/magpie-setup/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "magpie-setup",
"description": "Apache Magpie \u2014 framework install/maintenance: install (adopt), upgrade, verify, override, status, secure-agent setup, shared-config sync.",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"author": {
"name": "Apache Magpie",
"url": "https://magpie.apache.org/"
diff --git a/plugins/magpie-utilities/.claude-plugin/plugin.json b/plugins/magpie-utilities/.claude-plugin/plugin.json
index 01cd237f..df0601e5 100644
--- a/plugins/magpie-utilities/.claude-plugin/plugin.json
+++ b/plugins/magpie-utilities/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "magpie-utilities",
"description": "Apache Magpie \u2014 framework meta-skills: write-skill, optimize-skill, skill-reconciler, list-skills.",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"author": {
"name": "Apache Magpie",
"url": "https://magpie.apache.org/"
diff --git a/plugins/magpie-vetted-ops/.claude-plugin/plugin.json b/plugins/magpie-vetted-ops/.claude-plugin/plugin.json
index f73cc8ce..e4e681a4 100644
--- a/plugins/magpie-vetted-ops/.claude-plugin/plugin.json
+++ b/plugins/magpie-vetted-ops/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "magpie-vetted-ops",
"description": "Apache Magpie \u2014 vetted-ops: a dispatcher for fixed, policy-scoped forge operations, so a session needs one allowlist entry instead of a dozen wildcard `ask` rules. Runs from the installed plugin, which is what keeps the operation catalogue out of reach of the agent that calls it.",
- "version": "0.2.0.dev202609092258",
+ "version": "0.2.0.dev202609100826",
"author": {
"name": "Apache Magpie",
"url": "https://magpie.apache.org/"
diff --git a/pyproject.toml b/pyproject.toml
index 22b4f4dd..11fb8384 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -32,7 +32,7 @@
# Package name matches the project's canonical name. Not published to
# PyPI — this name only frames the framework root as a uv-managed project.
name = "apache-magpie"
-version = "0.2.0.dev202609092258"
+version = "0.2.0.dev202609100826"
description = "Reusable, governance-agnostic framework of agentic skills for maintaining open-source projects."
requires-python = ">=3.11"
diff --git a/skills/audit-finding-fix/SKILL.md b/skills/audit-finding-fix/SKILL.md
index b1785d61..389cc831 100644
--- a/skills/audit-finding-fix/SKILL.md
+++ b/skills/audit-finding-fix/SKILL.md
@@ -42,6 +42,51 @@ license: Apache-2.0
# audit-finding-fix
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill drafts fixes for non-security audit-tool findings in
`<upstream>`. It accepts a batch of findings from `<audit-tool>`
— lint violations, type errors, dead-code warnings, doc-coverage
diff --git a/skills/ci-runner-audit/SKILL.md b/skills/ci-runner-audit/SKILL.md
index 34f0680d..01c9ec59 100644
--- a/skills/ci-runner-audit/SKILL.md
+++ b/skills/ci-runner-audit/SKILL.md
@@ -35,6 +35,51 @@ license: Apache-2.0
# ci-runner-audit
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill runs a read-only GitHub Actions runner audit. It produces
TSV evidence for maintainers to review before deciding whether to edit
workflow files.
diff --git a/skills/committer-onboarding/SKILL.md b/skills/committer-onboarding/SKILL.md
index 61659a34..c149f250 100644
--- a/skills/committer-onboarding/SKILL.md
+++ b/skills/committer-onboarding/SKILL.md
@@ -42,6 +42,51 @@ license: Apache-2.0
# committer-onboarding
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill walks the nominator (the person who proposed the vote)
through every action required after a committer or PMC vote
passes, from validating the result through to the welcome
diff --git a/skills/contributor-activity-sweep/SKILL.md b/skills/contributor-activity-sweep/SKILL.md
index 17d064a8..61eca264 100644
--- a/skills/contributor-activity-sweep/SKILL.md
+++ b/skills/contributor-activity-sweep/SKILL.md
@@ -35,6 +35,51 @@ license: Apache-2.0
# contributor-activity-sweep
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
> **GitHub projects only.** This skill assumes the project's primary
> development activity is on GitHub and uses the GitHub CLI (`gh`) for
> all data collection. Most ASF projects use GitHub, but some remain on
diff --git a/skills/contributor-nomination/SKILL.md b/skills/contributor-nomination/SKILL.md
index 4f6ac32c..e3fd4f68 100644
--- a/skills/contributor-nomination/SKILL.md
+++ b/skills/contributor-nomination/SKILL.md
@@ -35,6 +35,51 @@ license: Apache-2.0
# contributor-nomination
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
> **GitHub projects only.** This skill assumes the project's primary
> development activity is on GitHub and uses the GitHub CLI (`gh`) for
> all data collection. Most ASF projects use GitHub, but some remain on
diff --git a/skills/contributor-sentiment/SKILL.md b/skills/contributor-sentiment/SKILL.md
index 682df242..9938d8e7 100644
--- a/skills/contributor-sentiment/SKILL.md
+++ b/skills/contributor-sentiment/SKILL.md
@@ -37,6 +37,51 @@ license: Apache-2.0
# contributor-sentiment
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Read-only skill that measures whether a Magpie-assisted project is
**healthier for contributors, not just faster**. Output is a structured
report the RFC-AI-0004 gate can consume to decide if a skill family is
diff --git a/skills/contributor-to-committer/SKILL.md b/skills/contributor-to-committer/SKILL.md
index d4cfbe9c..4e43317c 100644
--- a/skills/contributor-to-committer/SKILL.md
+++ b/skills/contributor-to-committer/SKILL.md
@@ -34,6 +34,51 @@ license: Apache-2.0
# contributor-to-committer
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
> **GitHub projects only.** This skill uses the GitHub CLI (`gh`) for
> all activity data. Projects not on GitHub can use the off-GitHub
> signal section and the gap table, but will need to supply all counts
diff --git a/skills/dependency-audit/SKILL.md b/skills/dependency-audit/SKILL.md
index 111fdb63..47e03bdb 100644
--- a/skills/dependency-audit/SKILL.md
+++ b/skills/dependency-audit/SKILL.md
@@ -35,6 +35,51 @@ license: Apache-2.0
# dependency-audit
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill runs a read-only dependency vulnerability audit against a
repository checkout or a named GitHub repository. It surfaces known
vulnerabilities that have available patches and groups findings for
diff --git a/skills/dependency-license-audit/SKILL.md b/skills/dependency-license-audit/SKILL.md
index e156baed..11b6b7b5 100644
--- a/skills/dependency-license-audit/SKILL.md
+++ b/skills/dependency-license-audit/SKILL.md
@@ -38,6 +38,51 @@ license: Apache-2.0
# dependency-license-audit
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill runs a read-only license audit of a project's dependency tree.
It resolves each dependency's declared license from ecosystem metadata and
classifies each result against a configured policy. For ASF adopters the
diff --git a/skills/flaky-test-triage/SKILL.md b/skills/flaky-test-triage/SKILL.md
index 58bcda4b..240ef632 100644
--- a/skills/flaky-test-triage/SKILL.md
+++ b/skills/flaky-test-triage/SKILL.md
@@ -36,6 +36,51 @@ license: Apache-2.0
# flaky-test-triage
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill detects intermittent test failures in a GitHub repository by
analysing CI run history. It computes per-job failure rates and classifies
jobs as flaky (intermittent), consistently broken, or clean. The output is
diff --git a/skills/good-first-issue-author/SKILL.md b/skills/good-first-issue-author/SKILL.md
index 2e5d0f71..90ef411d 100644
--- a/skills/good-first-issue-author/SKILL.md
+++ b/skills/good-first-issue-author/SKILL.md
@@ -39,6 +39,51 @@ license: Apache-2.0
# good-first-issue-author
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
**Status: experimental.** A Agentic Mentoring
([conversational mentoring](../../docs/mentoring/spec.md)) skill that
attacks onboarding latency from the supply side: it manufactures the
diff --git a/skills/good-first-issue-sweep/SKILL.md b/skills/good-first-issue-sweep/SKILL.md
index 356ddf84..a3a814a5 100644
--- a/skills/good-first-issue-sweep/SKILL.md
+++ b/skills/good-first-issue-sweep/SKILL.md
@@ -37,6 +37,51 @@ license: Apache-2.0
# good-first-issue-sweep
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
**Status: experimental.** A Mentoring skill that finds the on-ramp
capacity already sitting in the open issue backlog. Many projects have
open bugs or small improvements that would make fine first tasks for a
diff --git a/skills/issue-backlog-stats/SKILL.md b/skills/issue-backlog-stats/SKILL.md
index 837b7fa0..3104c074 100644
--- a/skills/issue-backlog-stats/SKILL.md
+++ b/skills/issue-backlog-stats/SKILL.md
@@ -38,6 +38,51 @@ license: Apache-2.0
# issue-backlog-stats
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Read-only skill that answers "what should the maintainer **do** about the
open general-issue backlog right now". Primary output is a **dashboard**
with sections mirroring [`pr-management-stats`](../pr-management-stats/SKILL.md)
diff --git a/skills/issue-deduplicate/SKILL.md b/skills/issue-deduplicate/SKILL.md
index 9fb2c6f0..c981a943 100644
--- a/skills/issue-deduplicate/SKILL.md
+++ b/skills/issue-deduplicate/SKILL.md
@@ -39,6 +39,51 @@ license: Apache-2.0
# issue-deduplicate
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill merges two open `<issue-tracker>` issues that describe
the same root-cause bug or feature request. The outcome is a single
issue ("the **kept** issue") that carries both reporters' context,
diff --git a/skills/issue-fix-workflow/SKILL.md b/skills/issue-fix-workflow/SKILL.md
index 1ddb614d..6135df51 100644
--- a/skills/issue-fix-workflow/SKILL.md
+++ b/skills/issue-fix-workflow/SKILL.md
@@ -38,6 +38,51 @@ license: Apache-2.0
# issue-fix-workflow
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill drafts a code fix for a single `<issue-tracker>` issue
that has already been triaged as actionable (classification `BUG`
or `FEATURE-REQUEST` per [`issue-triage`](../issue-triage/SKILL.md)).
diff --git a/skills/issue-reassess-stats/SKILL.md b/skills/issue-reassess-stats/SKILL.md
index d6c26de6..8bdafd1d 100644
--- a/skills/issue-reassess-stats/SKILL.md
+++ b/skills/issue-reassess-stats/SKILL.md
@@ -35,6 +35,51 @@ license: Apache-2.0
# issue-reassess-stats
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Read-only dashboard skill over the `verdict.json` artefacts
produced by [`issue-reassess`](../issue-reassess/SKILL.md)
campaigns. Surfaces a health rating, classification distribution,
diff --git a/skills/issue-reassess/SKILL.md b/skills/issue-reassess/SKILL.md
index b4cc6f6d..f1e53cf6 100644
--- a/skills/issue-reassess/SKILL.md
+++ b/skills/issue-reassess/SKILL.md
@@ -39,6 +39,51 @@ license: Apache-2.0
# issue-reassess
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Use this skill when the task is a **campaign** over a bounded set
of resolved or end-of-life `<issue-tracker>` issues: pick the
candidate set, run each reporter's reproducer against
diff --git a/skills/issue-reproducer/SKILL.md b/skills/issue-reproducer/SKILL.md
index 19ef31fa..52190643 100644
--- a/skills/issue-reproducer/SKILL.md
+++ b/skills/issue-reproducer/SKILL.md
@@ -39,6 +39,51 @@ license: Apache-2.0
# issue-reproducer
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Use this skill when the job is to **take an issue-described problem
and actually run it**: find the reproducer code, work out what shape
it's in, adapt it to a runnable form, and execute it against the
diff --git a/skills/issue-stale-sweep/SKILL.md b/skills/issue-stale-sweep/SKILL.md
index a1235b05..06633244 100644
--- a/skills/issue-stale-sweep/SKILL.md
+++ b/skills/issue-stale-sweep/SKILL.md
@@ -39,6 +39,51 @@ license: Apache-2.0
# issue-stale-sweep
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is the **stale-issue sweep** for the project's general issue
tracker. It identifies open issues that have had no new comment or update
activity past a configurable inactivity threshold, classifies each as
diff --git a/skills/issue-triage/SKILL.md b/skills/issue-triage/SKILL.md
index c9379b63..fe8b9058 100644
--- a/skills/issue-triage/SKILL.md
+++ b/skills/issue-triage/SKILL.md
@@ -38,6 +38,51 @@ license: Apache-2.0
# issue-triage
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is the **initial-triage discussion-starter** for issues
on the project's general issue tracker. For each open issue in the
configured candidate pool, it reads the issue body and comments,
diff --git a/skills/license-compliance-audit/SKILL.md b/skills/license-compliance-audit/SKILL.md
index ae9ca679..ff927a4d 100644
--- a/skills/license-compliance-audit/SKILL.md
+++ b/skills/license-compliance-audit/SKILL.md
@@ -36,6 +36,51 @@ license: Apache-2.0
# license-compliance-audit
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill runs a read-only license compliance audit against a repository
or a local checkout. It surfaces missing or inconsistent license artifacts
for maintainer review; no files are modified, no commits are created, and
diff --git a/skills/list-skills/SKILL.md b/skills/list-skills/SKILL.md
index a7000408..8b6fc577 100644
--- a/skills/list-skills/SKILL.md
+++ b/skills/list-skills/SKILL.md
@@ -38,6 +38,51 @@ license: Apache-2.0
# list-skills
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Print a human-readable index of the skills installed for this
repository. The index is generated on every run from live
`SKILL.md` frontmatter — there is no cached copy to keep in sync.
diff --git a/skills/mentoring-welcome/SKILL.md b/skills/mentoring-welcome/SKILL.md
index 80f24040..50fe14fe 100644
--- a/skills/mentoring-welcome/SKILL.md
+++ b/skills/mentoring-welcome/SKILL.md
@@ -33,6 +33,51 @@ license: Apache-2.0
# mentoring-welcome
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
**Status: experimental.** A Agentic Mentoring
([conversational mentoring](../../docs/mentoring/spec.md)) skill that
greets a first-time contributor with orientation context on their very
diff --git a/skills/newcomer-issue-explainer/SKILL.md b/skills/newcomer-issue-explainer/SKILL.md
index ce191ea2..cbacbf54 100644
--- a/skills/newcomer-issue-explainer/SKILL.md
+++ b/skills/newcomer-issue-explainer/SKILL.md
@@ -34,6 +34,51 @@ license: Apache-2.0
# newcomer-issue-explainer
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
**Status: experimental.** An Agentic Mentoring
([conversational mentoring](../../docs/mentoring/spec.md)) skill that
explains an existing good-first-issue to a newcomer contributor in
diff --git a/skills/onboarding-concierge/SKILL.md b/skills/onboarding-concierge/SKILL.md
index 034ab2d9..f5539b57 100644
--- a/skills/onboarding-concierge/SKILL.md
+++ b/skills/onboarding-concierge/SKILL.md
@@ -37,6 +37,51 @@ license: Apache-2.0
# onboarding-concierge
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
**Status: experimental.** A Agentic Mentoring
([conversational mentoring](../../docs/mentoring/spec.md)) skill that turns
the project's `CONTRIBUTING.md` into a responsive answer surface for newcomer
diff --git a/skills/optimize-skill/SKILL.md b/skills/optimize-skill/SKILL.md
index 357d6369..a08c850f 100644
--- a/skills/optimize-skill/SKILL.md
+++ b/skills/optimize-skill/SKILL.md
@@ -43,6 +43,51 @@ license: Apache-2.0
# optimize-skill
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Take one existing framework skill — or a maintainer-supplied set of
them — and make it leaner without changing what it does. The skill
diagnoses a target against the optimization catalogue distilled from
diff --git a/skills/pairing-multi-agent-review/SKILL.md b/skills/pairing-multi-agent-review/SKILL.md
index 31ed9440..a5621ea3 100644
--- a/skills/pairing-multi-agent-review/SKILL.md
+++ b/skills/pairing-multi-agent-review/SKILL.md
@@ -37,6 +37,51 @@ license: Apache-2.0
# pairing-multi-agent-review
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is the **multi-agent review pipeline** for the Agentic Pairing mode family.
It fans a local diff through three independent, axis-focused review passes
and merges their findings into one structured report.
diff --git a/skills/pairing-self-review/SKILL.md b/skills/pairing-self-review/SKILL.md
index 2b445a0a..e59630e4 100644
--- a/skills/pairing-self-review/SKILL.md
+++ b/skills/pairing-self-review/SKILL.md
@@ -33,6 +33,51 @@ license: Apache-2.0
# pairing-self-review
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is the **pre-flight self-review** entry point for the Agentic Pairing mode family.
It runs in the developer's own dev loop — after local changes are ready but before
opening a PR — and returns a structured review report. The report replaces
diff --git a/skills/pr-management-code-review/SKILL.md b/skills/pr-management-code-review/SKILL.md
index 3bc29e90..37015606 100644
--- a/skills/pr-management-code-review/SKILL.md
+++ b/skills/pr-management-code-review/SKILL.md
@@ -30,6 +30,51 @@ license: Apache-2.0
# pr-management-code-review
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill walks a maintainer through **deep, line-aware review**
of open pull requests, **one PR at a time**. Its job is to answer
two questions per PR:
diff --git a/skills/pr-management-mentor/SKILL.md b/skills/pr-management-mentor/SKILL.md
index 949e15c6..66f468ea 100644
--- a/skills/pr-management-mentor/SKILL.md
+++ b/skills/pr-management-mentor/SKILL.md
@@ -37,6 +37,51 @@ license: Apache-2.0
# pr-management-mentor
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
**Status: experimental.** First prototype of Agentic Mentoring
([conversational mentoring](../../docs/mentoring/spec.md)). The
skill exists to make the spec executable on a single thread at
diff --git a/skills/pr-management-quick-merge/SKILL.md b/skills/pr-management-quick-merge/SKILL.md
index 789a768a..0696f79d 100644
--- a/skills/pr-management-quick-merge/SKILL.md
+++ b/skills/pr-management-quick-merge/SKILL.md
@@ -43,6 +43,51 @@ license: Apache-2.0
# pr-management-quick-merge
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill answers one question for the `ready for maintainer review` queue:
> *Which of these PRs are so small and so low-risk that the maintainer can
diff --git a/skills/pr-management-stats/SKILL.md b/skills/pr-management-stats/SKILL.md
index 06c7f5ab..d7f202a5 100644
--- a/skills/pr-management-stats/SKILL.md
+++ b/skills/pr-management-stats/SKILL.md
@@ -30,6 +30,51 @@ license: Apache-2.0
# pr-management-stats
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Read-only skill that answers "what should the maintainer **do** about the
open-PR backlog right now". Primary output is a **dashboard** with five
sections:
diff --git a/skills/pr-management-triage/SKILL.md b/skills/pr-management-triage/SKILL.md
index 36a2b401..ac2de741 100644
--- a/skills/pr-management-triage/SKILL.md
+++ b/skills/pr-management-triage/SKILL.md
@@ -37,6 +37,51 @@ license: Apache-2.0
# pr-management-triage
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill walks a maintainer through **first-pass triage** of
open pull requests. Its job is to answer, for each candidate PR,
one question:
diff --git a/skills/pr-stale-sweep/SKILL.md b/skills/pr-stale-sweep/SKILL.md
index dfdace9c..787b19fc 100644
--- a/skills/pr-stale-sweep/SKILL.md
+++ b/skills/pr-stale-sweep/SKILL.md
@@ -37,6 +37,51 @@ license: Apache-2.0
# pr-stale-sweep
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is the **stale-PR sweep** for the project's pull request
queue. It identifies open PRs that have had no new commit, comment, or
update activity past a configurable inactivity threshold, classifies
diff --git a/skills/pre-first-pr-check/SKILL.md b/skills/pre-first-pr-check/SKILL.md
index da9c13f9..ca56ecf0 100644
--- a/skills/pre-first-pr-check/SKILL.md
+++ b/skills/pre-first-pr-check/SKILL.md
@@ -35,6 +35,51 @@ license: Apache-2.0
# pre-first-pr-check
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is the **newcomer pre-flight checklist** for the Agentic Pairing mode family.
It runs in the contributor's own dev loop — after local commits are ready but before
opening a PR — and checks the contribution mechanics that first-time contributors most
diff --git a/skills/release-announce-draft/SKILL.md b/skills/release-announce-draft/SKILL.md
index 96ee51ba..3d809d10 100644
--- a/skills/release-announce-draft/SKILL.md
+++ b/skills/release-announce-draft/SKILL.md
@@ -47,6 +47,51 @@ license: Apache-2.0
# release-announce-draft
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill drafts the `[ANNOUNCE]` email and opens the site-bump PR for
an Apache-convention promoted release. It is Step 11 of the
[release-management lifecycle](../../docs/release-management/process.md).
diff --git a/skills/release-archive-sweep/SKILL.md b/skills/release-archive-sweep/SKILL.md
index c3d5dc5b..ccfea373 100644
--- a/skills/release-archive-sweep/SKILL.md
+++ b/skills/release-archive-sweep/SKILL.md
@@ -42,6 +42,51 @@ license: Apache-2.0
# release-archive-sweep
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill scans the project's distribution area, identifies releases that
exceed the configured retention rule, and emits the backend-shaped command
set for the RM to archive them. It is Step 12 of the
diff --git a/skills/release-audit-report/SKILL.md b/skills/release-audit-report/SKILL.md
index 5a974000..248c1b75 100644
--- a/skills/release-audit-report/SKILL.md
+++ b/skills/release-audit-report/SKILL.md
@@ -42,6 +42,51 @@ license: Apache-2.0
# release-audit-report
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill assembles a structured per-release record and proposes a PR
that appends it to the project's audit log. It is Step 13 of the
[release-management lifecycle](../../docs/release-management/process.md).
diff --git a/skills/release-keys-sync/SKILL.md b/skills/release-keys-sync/SKILL.md
index daa816c1..af378948 100644
--- a/skills/release-keys-sync/SKILL.md
+++ b/skills/release-keys-sync/SKILL.md
@@ -44,6 +44,51 @@ license: Apache-2.0
# release-keys-sync
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill ensures the Release Manager's public GPG key appears in the
project's KEYS file before RC artefacts are signed. It is Step 3 of the
[release-management lifecycle](../../docs/release-management/process.md).
diff --git a/skills/release-prepare/SKILL.md b/skills/release-prepare/SKILL.md
index 91edb702..ba1f9da7 100644
--- a/skills/release-prepare/SKILL.md
+++ b/skills/release-prepare/SKILL.md
@@ -48,6 +48,51 @@ license: Apache-2.0
# release-prepare
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill drafts the three preparation artefacts in the
[release-management lifecycle](../../docs/release-management/process.md):
diff --git a/skills/release-promote/SKILL.md b/skills/release-promote/SKILL.md
index ad556ae3..efbf4e45 100644
--- a/skills/release-promote/SKILL.md
+++ b/skills/release-promote/SKILL.md
@@ -41,6 +41,51 @@ license: Apache-2.0
# release-promote
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill emits the backend-shaped promotion command set for a release
that has passed its vote. It is Step 10 of the
[release-management lifecycle](../../docs/release-management/process.md).
diff --git a/skills/release-rc-cut/SKILL.md b/skills/release-rc-cut/SKILL.md
index 4ccee4c7..18b3f3d2 100644
--- a/skills/release-rc-cut/SKILL.md
+++ b/skills/release-rc-cut/SKILL.md
@@ -41,6 +41,51 @@ license: Apache-2.0
# release-rc-cut
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill emits the paste-ready command sequences that cut an RC:
tag the release commit, build artefacts, sign each artefact, generate
checksums, and stage to the adopter's distribution backend. It is
diff --git a/skills/release-verify-rc/SKILL.md b/skills/release-verify-rc/SKILL.md
index f6ebcd2d..858e280c 100644
--- a/skills/release-verify-rc/SKILL.md
+++ b/skills/release-verify-rc/SKILL.md
@@ -45,6 +45,51 @@ license: Apache-2.0
# release-verify-rc
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is Step 6 of the
[release-management lifecycle](../../docs/release-management/process.md):
read-only verification of a staged release candidate before the
diff --git a/skills/release-vote-draft/SKILL.md b/skills/release-vote-draft/SKILL.md
index 2f990dae..3bf4b22c 100644
--- a/skills/release-vote-draft/SKILL.md
+++ b/skills/release-vote-draft/SKILL.md
@@ -44,6 +44,51 @@ license: Apache-2.0
# release-vote-draft
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill drafts the `[VOTE]` email and planning-issue comment for an
Apache-convention RC vote. It is Step 7 of the
[release-management lifecycle](../../docs/release-management/process.md).
diff --git a/skills/release-vote-tally/SKILL.md b/skills/release-vote-tally/SKILL.md
index c9936c81..07520885 100644
--- a/skills/release-vote-tally/SKILL.md
+++ b/skills/release-vote-tally/SKILL.md
@@ -44,6 +44,51 @@ license: Apache-2.0
# release-vote-tally
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill tallies the votes (or equivalent approval signals) for an
Apache-convention RC and drafts the `[RESULT] [VOTE]` email. It is
Step 9 of the
diff --git a/skills/report-framework-issue/SKILL.md b/skills/report-framework-issue/SKILL.md
index 471953eb..b3d1c34a 100644
--- a/skills/report-framework-issue/SKILL.md
+++ b/skills/report-framework-issue/SKILL.md
@@ -45,6 +45,51 @@ license: Apache-2.0
# report-framework-issue
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Turn a problem an adopter hits **while using Magpie itself** into a
clean, public-safe GitHub issue on the framework repo
(`apache/magpie`). The adopter is running the framework against
diff --git a/skills/reviewer-routing/SKILL.md b/skills/reviewer-routing/SKILL.md
index e764dc61..b3a70d42 100644
--- a/skills/reviewer-routing/SKILL.md
+++ b/skills/reviewer-routing/SKILL.md
@@ -39,6 +39,51 @@ license: Apache-2.0
# reviewer-routing
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill removes the "who should look at this?" pause that stalls a
fresh PR or issue before any review begins. Given an open issue or PR it
scores the project's configured reviewer roster and proposes one primary
diff --git a/skills/security-cve-allocate/SKILL.md b/skills/security-cve-allocate/SKILL.md
index f476d717..8a1d4032 100644
--- a/skills/security-cve-allocate/SKILL.md
+++ b/skills/security-cve-allocate/SKILL.md
@@ -43,6 +43,51 @@ license: Apache-2.0
# security-cve-allocate
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Walks a security team member through the CVE-allocation step of the
[handling process](../../README.md) for a given
[`<tracker>`](https://github.com/<tracker>)
diff --git a/skills/security-issue-deduplicate/SKILL.md b/skills/security-issue-deduplicate/SKILL.md
index a46d887a..a86c48ed 100644
--- a/skills/security-issue-deduplicate/SKILL.md
+++ b/skills/security-issue-deduplicate/SKILL.md
@@ -37,6 +37,51 @@ license: Apache-2.0
# security-issue-deduplicate
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Merges two `<tracker>` tracking issues that describe the
same underlying vulnerability. The output is a single tracker
("the **kept** issue") that carries every reporter's credit, every
diff --git a/skills/security-issue-fix/SKILL.md b/skills/security-issue-fix/SKILL.md
index eb95f88d..7a30a1aa 100644
--- a/skills/security-issue-fix/SKILL.md
+++ b/skills/security-issue-fix/SKILL.md
@@ -38,6 +38,51 @@ license: Apache-2.0
# security-issue-fix
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill automates the "attempt a fix" step of the security handling
process for issues in [`<tracker>`](https://github.com/<tracker>).
It composes with the [`security-issue-sync`](../security-issue-sync/SKILL.md)
diff --git a/skills/security-issue-import-from-md/SKILL.md b/skills/security-issue-import-from-md/SKILL.md
index 1f305b77..5f51b8c8 100644
--- a/skills/security-issue-import-from-md/SKILL.md
+++ b/skills/security-issue-import-from-md/SKILL.md
@@ -36,6 +36,51 @@ license: Apache-2.0
# security-issue-import-from-md
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is the **batch on-ramp** of the security-issue handling
process for the case where the security team has a markdown file
containing one or more pre-formatted security findings — typically
diff --git a/skills/security-issue-import-from-pr/SKILL.md b/skills/security-issue-import-from-pr/SKILL.md
index b08bcc08..fe58dd5f 100644
--- a/skills/security-issue-import-from-pr/SKILL.md
+++ b/skills/security-issue-import-from-pr/SKILL.md
@@ -36,6 +36,51 @@ license: Apache-2.0
# security-issue-import-from-pr
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is an alternative on-ramp of the security-issue handling
process for the case where the report **never arrived on
`<security-list>`**. A contributor opened a public fix
diff --git a/skills/security-issue-import-from-scan/SKILL.md b/skills/security-issue-import-from-scan/SKILL.md
index ccb6be4e..193dc17e 100644
--- a/skills/security-issue-import-from-scan/SKILL.md
+++ b/skills/security-issue-import-from-scan/SKILL.md
@@ -38,6 +38,51 @@ license: Apache-2.0
# security-issue-import-from-scan
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is the **scanner on-ramp** of the security-issue handling
process. It converts a security scanner's multi-finding output into
security work — but, unlike the human-report on-ramps, it **never
diff --git a/skills/security-issue-import-via-forwarder/SKILL.md b/skills/security-issue-import-via-forwarder/SKILL.md
index 26fbf7a6..69e86d81 100644
--- a/skills/security-issue-import-via-forwarder/SKILL.md
+++ b/skills/security-issue-import-via-forwarder/SKILL.md
@@ -46,6 +46,51 @@ license: Apache-2.0
# security-issue-import-via-forwarder
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is the **forwarder-aware extension** of the security-
issue import / invalidate / sync flow. It does not duplicate the
parent skills' classification logic; it specialises the small
diff --git a/skills/security-issue-import/SKILL.md b/skills/security-issue-import/SKILL.md
index b54691a4..d262454c 100644
--- a/skills/security-issue-import/SKILL.md
+++ b/skills/security-issue-import/SKILL.md
@@ -38,6 +38,51 @@ license: Apache-2.0
# security-issue-import
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is the **on-ramp** of the security-issue handling process.
It converts an inbound `<security-list>` email thread into
an `<tracker>` tracking issue that follows the repo's issue
diff --git a/skills/security-issue-invalidate/SKILL.md b/skills/security-issue-invalidate/SKILL.md
index fe96f0db..5ce27645 100644
--- a/skills/security-issue-invalidate/SKILL.md
+++ b/skills/security-issue-invalidate/SKILL.md
@@ -42,6 +42,51 @@ license: Apache-2.0
# security-issue-invalidate
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is the **terminal-disposition apply step** for the
`invalid` close on an `<tracker>` tracker. It does not host the
discussion that decides invalidity — that happens at Step 5 of the
diff --git a/skills/security-issue-sync/SKILL.md b/skills/security-issue-sync/SKILL.md
index b902da9b..eed5ee8c 100644
--- a/skills/security-issue-sync/SKILL.md
+++ b/skills/security-issue-sync/SKILL.md
@@ -37,6 +37,51 @@ license: Apache-2.0
# security-issue-sync
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill reconciles a single security issue in
[`<tracker>`](https://github.com/<tracker>) with:
diff --git a/skills/security-issue-triage/SKILL.md b/skills/security-issue-triage/SKILL.md
index c4eb924a..717b53c7 100644
--- a/skills/security-issue-triage/SKILL.md
+++ b/skills/security-issue-triage/SKILL.md
@@ -40,6 +40,51 @@ license: Apache-2.0
# security-issue-triage
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill is the **initial-triage discussion-starter** for security
tracker issues. For each [`<tracker>`](https://github.com/<tracker>)
issue carrying the `needs triage` label, it reads the body + comments,
diff --git a/skills/security-model-prepare/SKILL.md b/skills/security-model-prepare/SKILL.md
index b8c6b17f..6d2cc584 100644
--- a/skills/security-model-prepare/SKILL.md
+++ b/skills/security-model-prepare/SKILL.md
@@ -31,6 +31,51 @@ license: Apache-2.0
# Security model prepare
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Most projects have a security model. Very few have written it down. It lives in
the maintainers' heads, in a decade of "wontfix — that's not our threat model"
replies, and in the shape of the API. This skill's job is to get that into a
diff --git a/skills/security-model-update/SKILL.md b/skills/security-model-update/SKILL.md
index 70f0b2c2..b779843f 100644
--- a/skills/security-model-update/SKILL.md
+++ b/skills/security-model-update/SKILL.md
@@ -38,6 +38,51 @@ license: Apache-2.0
# Security model update
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
A security model written once and never revisited decays in a specific,
predictable way: the project keeps making decisions, and the document keeps not
reflecting them. Six months of triage is six months of the team stating its
diff --git a/skills/security-model-verify/SKILL.md b/skills/security-model-verify/SKILL.md
index dd0308ca..d68c9fae 100644
--- a/skills/security-model-verify/SKILL.md
+++ b/skills/security-model-verify/SKILL.md
@@ -34,6 +34,51 @@ license: Apache-2.0
# Security model verify
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
A published security model earns its keep in two ways, and this skill checks
both. It has to be **findable** by whatever is going to consult it — a scanner,
a triaging agent, a downstream integrator reading the repo cold — and it has to
diff --git a/skills/security-tracker-stats-dashboard/SKILL.md b/skills/security-tracker-stats-dashboard/SKILL.md
index 69998c1e..3de19e6e 100644
--- a/skills/security-tracker-stats-dashboard/SKILL.md
+++ b/skills/security-tracker-stats-dashboard/SKILL.md
@@ -34,6 +34,51 @@ license: Apache-2.0
# security-tracker-stats-dashboard
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Read-only skill that renders a self-contained HTML page summarising
the state of `<tracker>` over time. The skill wraps the
[`tools/security-tracker-stats-dashboard/`](../../tools/security-tracker-stats-dashboard/README.md)
diff --git a/skills/skill-reconciler/SKILL.md b/skills/skill-reconciler/SKILL.md
index 18406f04..9da65e7d 100644
--- a/skills/skill-reconciler/SKILL.md
+++ b/skills/skill-reconciler/SKILL.md
@@ -38,6 +38,51 @@ license: Apache-2.0
# skill-reconciler
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
Compare two near-duplicate skills and classify every difference as
`ALLOWED`, `DRIFT`, or `SAFETY-BASELINE`. The three classes operationalise
MISSION's stance that duplication is fine where it buys decoupling
diff --git a/skills/workflow-security-audit/SKILL.md b/skills/workflow-security-audit/SKILL.md
index 0ca160ea..8c611a46 100644
--- a/skills/workflow-security-audit/SKILL.md
+++ b/skills/workflow-security-audit/SKILL.md
@@ -36,6 +36,51 @@ license: Apache-2.0
# workflow-security-audit
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill runs a read-only GitHub Actions workflow security audit using
[`zizmor`](https://woodruffw.github.io/zizmor/), the Actions security
scanner already wired into the framework's pre-commit suite. It surfaces
diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md
index 0bb91788..0d6c2db4 100644
--- a/skills/write-skill/SKILL.md
+++ b/skills/write-skill/SKILL.md
@@ -34,6 +34,51 @@ license: Apache-2.0
# write-skill
+<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
+
+<!-- END MAGPIE PREFLIGHT -->
+
This skill walks the user through authoring a new skill for the
Apache Magpie framework, or refactoring an existing one to pick
up the framework's current conventions.
diff --git a/tools/dev/README.md b/tools/dev/README.md
index 8aab0123..6607f41c 100644
--- a/tools/dev/README.md
+++ b/tools/dev/README.md
@@ -46,6 +46,7 @@ installable for other members to depend on it.
| Script | What it does |
|---|---|
| [`check-doc-sync.py`](check-doc-sync.py) | Guards the documentation claims that track the tree and rot silently: spec-index completeness (every `tools/spec-loop/specs/*.md` listed in **both** `overview.md` and `README.md`), the per-family skill counts in the root `README.md`, the per-mode counts in `docs/modes.md`'s *Modes at a glance* table, the bare catalogue totals in `docs/setup/marketplaces.md`, and that every script here is named in this file. |
+| [`check-skill-preflight.py`](check-skill-preflight.py) | Keeps the shared setup pre-flight block identical in every `skills/*/SKILL.md`, generated from the single source at [`preflight-block.md`](preflight-block.md). The check has to live in each skill body: no code runs on plugin install/upgrade on most harnesses, and a shared include would escape the family plugin root that AP1 forbids leaving — so one source, many generated copies, with `--fix` propagating and the hook preventing dr [...]
| [`check-family-plugins.py`](check-family-plugins.py) | Validates the marketplace plugins against the skills' `family:` frontmatter — version parity across every ecosystem manifest, Agent Plugins 1.0 conformance, and one well-formed per-family plugin whose `skills/` symlinks match the family exactly. `--fix` regenerates them, which is how the prek hook runs it. |
| [`check-placeholders.sh`](check-placeholders.sh) | Fails the build on hardcoded project references in skill and tool docs, which must use `<PROJECT>` / `<project>` / `<tracker>` / `<upstream>` instead. Carries both casings and matches spaced variants. |
| [`check-workspace-members.py`](check-workspace-members.py) | Catches a new `tools/<name>/pyproject.toml` that was never added to `[tool.uv.workspace] members` — an omission that silently drops the tool from both the pre-commit hooks and the CI pytest matrix. Also verifies each member's tests actually run: both surfaces key off `[tool.pytest.ini_options]`, so a project can carry a full `tests/` directory and be executed by nothing. Reports tests-without-config, config-without-tests, and [...]
@@ -60,7 +61,7 @@ a human has to remember to update while thinking about something else.
## Prerequisites
-- **Runtime:** Bash + coreutils; `check-workspace-members.py`, `check-family-plugins.py`, `check-doc-sync.py`, and `add-license-headers.py` run under `python3` (standard library only).
+- **Runtime:** Bash + coreutils; `check-workspace-members.py`, `check-family-plugins.py`, `check-doc-sync.py`, `check-skill-preflight.py`, and `add-license-headers.py` run under `python3` (standard library only).
- **CLIs:** `uv` (the workspace checks run `uv run`), `git`, and `prek` (or `pre-commit`) — these scripts wire up the framework's hooks.
- **Credentials / auth:** None.
- **Network:** Local checks; `uv` may resolve workspace dependencies from PyPI (`pypi.org`, `files.pythonhosted.org`) on first sync.
diff --git a/tools/dev/check-family-plugins.py b/tools/dev/check-family-plugins.py
index 402e86a8..55effb67 100644
--- a/tools/dev/check-family-plugins.py
+++ b/tools/dev/check-family-plugins.py
@@ -90,10 +90,34 @@ AP1_AUTHOR_FIELDS = frozenset({"name", "email", "url"})
# directories would mean vendored copies of every skill — PRINCIPLES §13. So
# per-family is a Claude Code feature, and this check keeps the other catalogs
# from drifting into advertising something their clients cannot install.
+CODEX_CATALOG = Path(".agents/plugins/marketplace.json") # Codex CLI repo marketplace
CLIENT_CATALOGS = (
- Path(".agents/plugins/marketplace.json"), # Codex CLI repo marketplace
+ CODEX_CATALOG,
Path("marketplace.json"), # GitHub Copilot / VS Code
)
+
+# Codex's per-plugin `policy` block. Both enums are closed and SCREAMING_SNAKE,
+# and Codex parses the catalogue strictly: an unknown variant is not a
+# mis-labelled plugin but a rejected *file* — `codex plugin marketplace add`
+# fails with `unknown variant`, so nothing in the marketplace installs at all.
+# This catalogue shipped with the invented values `manual` / `none` for a
+# release, because every check here read names and versions and none read the
+# policy values. Verified against codex 0.154.0.
+#
+# `installation` decides whether adding the marketplace also installs the
+# plugin. It stays AVAILABLE: INSTALLED_BY_DEFAULT here would install the
+# all-in-one plugin — all ten families — on every Codex machine that adds the
+# marketplace, which is the opposite of the per-family default the framework
+# argues for, and Codex cannot express that default (see
+# `check_client_catalogs`). `authentication` is optional and names *when* a
+# plugin asks the user to authenticate; Magpie asks for no credential of its
+# own, so it is absent rather than set to a "no auth" value, which the enum
+# has no way to spell.
+CODEX_POLICY_ENUMS = {
+ "installation": frozenset({"NOT_AVAILABLE", "AVAILABLE", "INSTALLED_BY_DEFAULT"}),
+ "authentication": frozenset({"ON_INSTALL", "ON_USE"}),
+}
+CODEX_REQUIRED_INSTALLATION = "AVAILABLE"
# `name`: 1–64 chars, lowercase alphanumeric plus `-`/`.`, no `--`/`..`,
# alphanumeric at both ends.
AP1_NAME_RE = re.compile(r"^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$")
@@ -452,6 +476,44 @@ def check_client_catalogs() -> list[str]:
f"plugins are Claude Code-only (their skill symlinks resolve outside the "
f"family plugin root, which Agent Plugins 1.0 forbids)"
)
+ if path == CODEX_CATALOG:
+ errors.extend(check_codex_policy(path, entries))
+ return errors
+
+
+def check_codex_policy(path: Path, entries: list) -> list[str]:
+ """Codex `policy` values are closed enums; an unknown one rejects the file."""
+ errors: list[str] = []
+ for entry in entries:
+ if not isinstance(entry, dict):
+ continue
+ name = entry.get("name", "?")
+ policy = entry.get("policy")
+ if policy is None:
+ continue
+ if not isinstance(policy, dict):
+ errors.append(f"{path}: '{name}' has a 'policy' that is not an object")
+ continue
+ for field, allowed in CODEX_POLICY_ENUMS.items():
+ if field not in policy:
+ continue
+ value = policy[field]
+ if value not in allowed:
+ errors.append(
+ f"{path}: '{name}' policy.{field} is {value!r} — Codex accepts only "
+ f"{', '.join(sorted(allowed))}. An unknown variant makes "
+ f"`codex plugin marketplace add` reject the whole catalogue"
+ )
+ if unknown := sorted(set(policy) - set(CODEX_POLICY_ENUMS)):
+ errors.append(f"{path}: '{name}' policy has unknown field(s) {', '.join(unknown)}")
+ installation = policy.get("installation")
+ if installation is not None and installation != CODEX_REQUIRED_INSTALLATION:
+ errors.append(
+ f"{path}: '{name}' policy.installation is {installation!r} — the Codex "
+ f"catalogue lists only the all-in-one plugin, so anything but "
+ f"{CODEX_REQUIRED_INSTALLATION!r} would install all ten families by "
+ f"default (or hide the plugin entirely)"
+ )
return errors
diff --git a/tools/dev/check-skill-preflight.py b/tools/dev/check-skill-preflight.py
new file mode 100755
index 00000000..70e31adc
--- /dev/null
+++ b/tools/dev/check-skill-preflight.py
@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# https://www.apache.org/licenses/LICENSE-2.0
+"""Keep the shared setup pre-flight block present and identical in every
+`skills/*/SKILL.md`.
+
+Every framework skill has to answer the same question before it does anything:
+*has this project actually been set up for the framework version now installed?*
+`skills/setup/locks.md` already states that a drift check runs "on every
+framework-skill invocation" — but nothing put that check in front of the agent,
+so it ran nowhere.
+
+It cannot be a hook. On most harnesses **no code executes when a plugin is
+installed or upgraded**: Agent Plugins 1.0 defines no hook component at all, and
+Claude Code's `SessionStart` hook is wired only into the all-in-one plugin, so a
+per-family or non-Claude install has no automated moment to check anything. The
+check therefore has to be *agentic* — instructions the agent reads when the
+skill is invoked — which means it has to live in the skill body.
+
+It also cannot be an include. A family plugin contains
+`plugins/magpie-<family>/skills/<skill>` symlinked to `skills/<skill>`, and
+Agent Plugins 1.0 forbids a symlink whose final target escapes the plugin root,
+so a shared file at `skills/_shared/` would be unreachable from exactly the
+install shape most adopters use (the same constraint that keeps per-family
+plugins Claude Code-only). Every skill needs its own copy of the text.
+
+So: **one source, many generated copies.** `tools/dev/preflight-block.md` is the
+only place the wording is edited; this script propagates it into a delimited
+block in each `SKILL.md`, and the pre-commit hook runs it with `--fix`, so
+editing the source is the whole workflow and drift is repaired rather than
+merely reported. The duplication costs nothing at rest: a `SKILL.md` *body* is
+read only when the skill is invoked, unlike the frontmatter that
+`estimate-skill-tokens.py` measures.
+
+The block is inserted immediately after the skill's first body-level `#`
+heading, so it is the first instruction the agent reads.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+SKILLS = Path("skills")
+SOURCE = Path("tools/dev/preflight-block.md")
+
+BEGIN = "<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->"
+END = "<!-- END MAGPIE PREFLIGHT -->"
+# Matches the whole delimited region including a trailing blank line, so a
+# repeated --fix neither duplicates the block nor accumulates whitespace.
+BLOCK_RE = re.compile(
+ re.escape(BEGIN) + r".*?" + re.escape(END) + r"\n*",
+ re.S,
+)
+FRONTMATTER_RE = re.compile(r"^---\n.*?\n---\n", re.S)
+HEADING_RE = re.compile(r"^# .*$", re.M)
+FAMILY_RE = re.compile(r"^family:[ \t]*(\S+)[ \t]*$", re.M)
+
+# The `setup` family is exempt, and the exemption is the point rather than an
+# oversight: these are the skills that *perform* the setup. A pre-flight telling
+# the agent to run `/magpie-setup` before running `/magpie-setup` is a loop, and
+# `setup-isolated-setup-install` in particular has to work on a repo that has
+# deliberately adopted nothing yet. Membership is read from the live `family:`
+# frontmatter, so the exemption cannot drift from the family it names.
+EXEMPT_FAMILIES = frozenset({"setup"})
+
+
+def family_of(text: str) -> str | None:
+ match = FAMILY_RE.search(text)
+ return match.group(1) if match else None
+
+
+def block_text() -> str:
+ """The generated region: delimiters around the source file's body."""
+ raw = SOURCE.read_text()
+ # Drop the source file's own licence header — each SKILL.md already carries
+ # one, and a second would render inside the skill body.
+ body = re.sub(r"^<!--\s*SPDX-License-Identifier.*?-->\n+", "", raw, flags=re.S)
+ return f"{BEGIN}\n\n{body.strip()}\n\n{END}\n"
+
+
+def apply(path: Path, block: str) -> tuple[bool, str | None]:
+ """Return (changed, error). Rewrites `path` only when it differs."""
+ text = path.read_text()
+ stripped = BLOCK_RE.sub("", text)
+
+ match = FRONTMATTER_RE.match(stripped)
+ if not match:
+ return False, f"{path}: no YAML frontmatter"
+ heading = HEADING_RE.search(stripped, match.end())
+ if not heading:
+ return False, f"{path}: no body-level '# ' heading to anchor the block to"
+
+ cut = heading.end()
+ # Exactly one blank line between the heading and the block.
+ rest = stripped[cut:].lstrip("\n")
+ updated = f"{stripped[:cut]}\n\n{block}\n{rest}"
+ if updated == text:
+ return False, None
+ path.write_text(updated)
+ return True, None
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument(
+ "--fix",
+ action="store_true",
+ help="write the block into every SKILL.md instead of only reporting",
+ )
+ args = parser.parse_args()
+
+ if not SOURCE.is_file():
+ print(f"{SOURCE}: missing — it is the only source of the block", file=sys.stderr)
+ return 1
+
+ block = block_text()
+ skills = sorted(SKILLS.glob("*/SKILL.md"))
+ if not skills:
+ print(f"{SKILLS}: no SKILL.md files found", file=sys.stderr)
+ return 1
+
+ errors: list[str] = []
+ changed: list[Path] = []
+ exempt: list[Path] = []
+ for path in skills:
+ text = path.read_text()
+ if family_of(text) in EXEMPT_FAMILIES:
+ exempt.append(path)
+ # An exempt skill must not carry a stale block from before it was
+ # exempted, so removing one is part of keeping the set in sync.
+ if BLOCK_RE.search(text):
+ if args.fix:
+ path.write_text(BLOCK_RE.sub("", text))
+ changed.append(path)
+ else:
+ errors.append(f"{path}: carries the pre-flight block but its family is exempt")
+ continue
+ if args.fix:
+ did, err = apply(path, block)
+ if err:
+ errors.append(err)
+ elif did:
+ changed.append(path)
+ else:
+ found = BLOCK_RE.search(text)
+ if not found:
+ errors.append(f"{path}: missing the shared pre-flight block")
+ elif found.group(0).rstrip("\n") != block.rstrip("\n"):
+ errors.append(f"{path}: pre-flight block differs from {SOURCE}")
+
+ if errors:
+ print("Skill pre-flight block is out of sync:", file=sys.stderr)
+ for error in errors:
+ print(f" - {error}", file=sys.stderr)
+ if not args.fix:
+ print(
+ f"\nRun `python3 {Path(__file__).name} --fix` — or edit {SOURCE}, "
+ f"which is the only place the wording should change.",
+ file=sys.stderr,
+ )
+ return 1
+ if changed:
+ print(f"Updated the pre-flight block in {len(changed)} skill(s):")
+ for path in changed:
+ print(f" - {path}")
+ return 1
+ print(
+ f"Pre-flight block in sync across {len(skills) - len(exempt)} skills "
+ f"({len(exempt)} exempt: {', '.join(sorted(p.parent.name for p in exempt))})."
+ )
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/dev/preflight-block.md b/tools/dev/preflight-block.md
new file mode 100644
index 00000000..35f5e12b
--- /dev/null
+++ b/tools/dev/preflight-block.md
@@ -0,0 +1,40 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Pre-flight — is this project set up?](#pre-flight--is-this-project-set-up)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Pre-flight — is this project set up?
+
+Do this **first, before anything else in this skill**, and do it silently: on
+the happy path it costs three file checks and prints nothing.
+
+A marketplace install delivers *skills only*. Nothing in it configures this
+repository, and on most harnesses **no code runs at all** when a plugin is
+installed or upgraded — there is no post-install step to rely on. Claude Code's
+`SessionStart` hook covers only the all-in-one plugin, so for every other
+install this check is the one thing standing between a stale or unadopted repo
+and a skill that acts on wrong assumptions.
+
+1. **Is a lock present?** If `.apache-magpie.lock` exists, this project uses the
+ pinned-snapshot install. Compare it with `.apache-magpie.local.lock`:
+ - local lock missing → the snapshot was never fetched on this machine;
+ - `ref` / `commit` differ → this machine is on a different framework version
+ than the project pins.
+2. **No lock?** Then this is the marketplace install (or nothing at all). Look
+ for a `<project-config>/` directory. If there is none, the project has not
+ been adopted and every `<placeholder>` in this skill is unresolved.
+3. **Anything unresolved above → stop and propose `/magpie-setup`** (or
+ `/magpie-setup upgrade` for a version mismatch). Say which of the three
+ checks failed and what you found. Do **not** run setup unattended and do
+ **not** continue this skill on a guess: a skill that proceeds against an
+ unadopted repo writes to the wrong tracker.
+
+Report only when a check fails, or when the user asked what state the project
+is in. `/magpie-setup verify` is the full diagnostic — this is deliberately the
+cheap subset that is worth paying for on every invocation.
diff --git a/tools/sandbox-lint/expected.json b/tools/sandbox-lint/expected.json
index f6ced830..89962227 100644
--- a/tools/sandbox-lint/expected.json
+++ b/tools/sandbox-lint/expected.json
@@ -139,5 +139,15 @@
"Bash(git push --force-with-lease *)",
"Bash(gh *)"
]
+ },
+ "extraKnownMarketplaces": {
+ "apache-magpie": {
+ "source": { "source": "github", "repo": "apache/magpie" }
+ }
+ },
+ "enabledPlugins": {
+ "magpie-setup@apache-magpie": true,
+ "magpie-utilities@apache-magpie": true,
+ "magpie-agent-guard@apache-magpie": true
}
}
diff --git a/uv.lock b/uv.lock
index c8f27545..91e16b93 100644
--- a/uv.lock
+++ b/uv.lock
@@ -120,7 +120,7 @@ wheels = [
[[package]]
name = "apache-magpie"
-version = "0.2.0.dev202609092258"
+version = "0.2.0.dev202609100826"
source = { virtual = "." }
[package.dev-dependencies]