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/10/16 05:02:20 UTC
(magpie) 01/01: feat(setup): a first-run welcome guide for the security skills
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch feat/security-welcome-guide
in repository https://gitbox.apache.org/repos/asf/magpie.git
commit 3fe196782bc928324da7606808caa44bc8d8e669
Author: Jarek Potiuk <po...@apache.org>
AuthorDate: Fri Oct 16 06:01:12 2026 +0100
feat(setup): a first-run welcome guide for the security skills
The first time a security-family skill runs, the pre-flight checker now
returns a `welcome` finding carrying a short guide: the typical flow
(import, triage, sync, CVE, fix, announce) with an example request per
step, installing for yourself versus adopting for the project, the
conversational interface with examples, and how to change the default
workflows by describing the change and send it upstream with "upstream
this change to Magpie".
The agent shows it, then carries on with the task. Continue shows it
again (three times at most), Dismiss hides it until the next upgrade,
Don't show again hides it until `/magpie-setup:setup welcome` (or
"show the security welcome again") turns it back on; the choice lives
in the personal layer's reconciled.json. `setup_preflight.welcome show
--color` prints a coloured terminal version. The skill-to-family map
the checker needs is generated from frontmatter and kept in sync by
check-family-plugins.
Generated-by: Claude Opus 5
---
docs/mode-economics.md | 6 +
docs/quick-start/first-run.md | 6 +
docs/security/README.md | 6 +
docs/setup/marketplace.md | 11 +
plugins/magpie-setup/skills/setup/SKILL.md | 12 +-
.../skills/setup/setup_preflight/cli.py | 7 +
.../skills/setup/setup_preflight/core.py | 40 +-
.../skills/setup/setup_preflight/families.py | 183 +++++++++
.../setup/setup_preflight/guides/security.md | 67 +++
.../setup_preflight/sections/welcome-security.md | 32 ++
.../skills/setup/setup_preflight/welcome.py | 456 +++++++++++++++++++++
plugins/magpie-setup/skills/setup/welcome.md | 44 ++
tools/dev/check-family-plugins.py | 31 ++
tools/dev/render-preflight-fixtures.py | 5 +
tools/dev/tests/test_check_family_plugins.py | 32 ++
tools/setup-preflight/README.md | 35 ++
tools/setup-preflight/pyproject.toml | 1 +
tools/setup-preflight/tests/test_welcome.py | 336 +++++++++++++++
tools/skill-evals/README.md | 2 +-
tools/skill-evals/evals/setup/README.md | 4 +-
.../case-9-security-first-run/case-meta.json | 1 +
.../case-9-security-first-run/expected.json | 1 +
.../fixtures/case-9-security-first-run/report.md | 37 ++
.../fixtures/case-9-security-first-run/state.json | 15 +
.../setup/preflight-floor/fixtures/output-spec.md | 7 +-
tools/spec-loop/specs/adoption-and-setup.md | 12 +
26 files changed, 1377 insertions(+), 12 deletions(-)
diff --git a/docs/mode-economics.md b/docs/mode-economics.md
index 3512adee..9df79c03 100644
--- a/docs/mode-economics.md
+++ b/docs/mode-economics.md
@@ -105,6 +105,12 @@ The rules are 2,057 tokens across eight sections, held once in the tool. A
run that needs one pays for one — typically 120 to 580 tokens — and the
ordinary `{"verdict": "ok"}` pays for none.
+The security family's first-run welcome guide rides the same verdict:
+a `welcome` finding carrying the guide and its `welcome-security` rules, roughly 1,300 tokens.
+It is paid on at most three security-family runs per user (fewer once dismissed),
+and again only on the first run after an upgrade lifts a dismissal.
+`--no-welcome` leaves it out.
+
What is left in the block is the part a model is for: run the command,
stay silent on `ok`, follow the rules a finding carries, and never run
`/magpie-setup:setup adopt` unattended. What is left in neither is the
diff --git a/docs/quick-start/first-run.md b/docs/quick-start/first-run.md
index f53f71fd..585bb9ca 100644
--- a/docs/quick-start/first-run.md
+++ b/docs/quick-start/first-run.md
@@ -58,6 +58,12 @@ changes nothing any teammate can see.
What it will **not** do is proceed on a guess. It did not label anything, post
anything, or fall back to a default committer team.
+A family can also open its first run with a short welcome guide.
+The security family does:
+its [guide](../../plugins/magpie-setup/skills/setup/setup_preflight/guides/security.md)
+shows before the work starts, never instead of it,
+and ends with a choice to see it again, dismiss it until the next upgrade, or hide it for good.
+
## 2. It configures, deriving what it can

diff --git a/docs/security/README.md b/docs/security/README.md
index 7c422466..3ddbe56b 100644
--- a/docs/security/README.md
+++ b/docs/security/README.md
@@ -65,6 +65,12 @@ New to Magpie? The [quick start](../quick-start.md) walks the whole path in
one place — install, the first `/magpie-setup:setup` run, and a recording of it
happening — plus the other agents and the secure-isolation setup to run next.
+The first security skill you run opens with a one-minute
+[welcome guide](../../plugins/magpie-setup/skills/setup/setup_preflight/guides/security.md):
+the typical flow, configuring Magpie, what to ask it, and how to make it yours.
+Dismiss it, or hide it for good, from its last line;
+*"show the security welcome again"* brings it back.
+
### Before the first run
<!-- BEGIN generated: skill-config (tools/dev/check-skill-config.py --fix) -->
diff --git a/docs/setup/marketplace.md b/docs/setup/marketplace.md
index 4e216f84..f31b3eab 100644
--- a/docs/setup/marketplace.md
+++ b/docs/setup/marketplace.md
@@ -658,6 +658,17 @@ The same suggestion also comes back weekly by default, and the interval can be c
Run the skill directly at any time to check now.
Details: [Automatic reminders from the pre-flight](secure-agent-setup.md#automatic-reminders-from-the-pre-flight).
+**The first security skill you run shows a welcome guide.**
+The same pre-flight carries a short [first-run guide](../../plugins/magpie-setup/skills/setup/setup_preflight/guides/security.md) for the security family:
+the typical flow, how to configure Magpie, what to ask it, and how to make it yours.
+It ends with three choices.
+**Continue** shows it again next time (three times at most),
+**Dismiss** hides it until the next Magpie upgrade,
+and **Don't show again** hides it until you ask for it back —
+say *"show the security welcome again"*, which runs `/magpie-setup:setup welcome`.
+The choice is kept in `reconciled.json` in your personal layer.
+Mechanics: [`welcome.md`](../../plugins/magpie-setup/skills/setup/welcome.md).
+
## Versioning
The plugin version tracks the framework version in `pyproject.toml`, which is
diff --git a/plugins/magpie-setup/skills/setup/SKILL.md b/plugins/magpie-setup/skills/setup/SKILL.md
index edb62ddf..bd264328 100644
--- a/plugins/magpie-setup/skills/setup/SKILL.md
+++ b/plugins/magpie-setup/skills/setup/SKILL.md
@@ -16,12 +16,13 @@ when_to_use: >-
pre-flight asking for project configuration, goes to `config`: it
writes gitignored files and needs nobody's permission. "Adopt magpie
for this repo" goes to `adopt`: it commits files for every
- contributor and is not an install.
-argument-hint: "[install|config|adopt|unadopt|upgrade|worktree-init|verify|reconcile|override skill-name|uninstall]"
+ contributor and is not an install. "Show the security welcome
+ again" goes to `welcome`.
+argument-hint: "[install|config|adopt|unadopt|upgrade|worktree-init|verify|reconcile|override skill-name|welcome|uninstall]"
capability: capability:platform
-surface_hash: sha256:75d8f5a0d61a7be2
+surface_hash: sha256:e8e5acd7b77668c3
license: Apache-2.0
-measured_tokens: 4605
+measured_tokens: 4676
---
<!-- SPDX-License-Identifier: Apache-2.0
@@ -144,6 +145,7 @@ The skill dispatches by the first positional argument:
| `setup reconcile` | [`reconcile.md`](reconcile.md) | One-time project-wide sweep: checks anchors and `requires_config` for every configured or overridden skill, proposes fixes one by one, writes the `reconciled:` stamp. Any install method. **Main-checkout only when the stamp goes to the committed lock** (adopted); unrestricted when it goes to the local file. |
| `setup skill-sources` (aka `skill-sources add <id>`) | [`skill-sources.md`](skill-sources.md) | Fetch, verify, pin and symlink skills from the trusted sources listed in `<project-config>/skill-sources.md`. **Main-checkout only** — worktrees share the source snapshots via `worktree-init`. |
| `setup override <skill>` | [`overrides.md`](overrides.md) | Open or scaffold an override file. |
+| `setup welcome [family]` | [`welcome.md`](welcome.md) | Show a skill family's first-run welcome guide again, or turn it back on after a Dismiss or Don't show again. Writes only the personal layer's `reconciled.json`. |
| `setup uninstall` | [`uninstall.md`](uninstall.md) | Reverse the install: remove the snapshot, the local lock, symlinks, hook, doc sections, and this skill. Leaves `.apache-magpie.lock` — that is `unadopt`. Keeps `.apache-magpie-overrides/` unless `--purge-overrides` is passed. **Main-checkout only.** |
| `setup unadopt` | [`adopt.md` → Unadopt](adopt.md#unadopt) | Remove the committed floor lock `.apache-magpie.lock` and the `.claude/settings.json` wiring derived from it. **Keeps `.apache-magpie-overrides/`** unless `--purge-overrides` is passed. Leaves every install — yours and everyone else's — untouched. |
@@ -172,7 +174,7 @@ Unknown setup sub-action: `upgrede`.
Did you mean `upgrade`? → /magpie-setup:setup upgrade
Sub-actions: install, config, adopt, upgrade, worktree-init, verify,
-reconcile, skill-sources, override, uninstall, unadopt
+reconcile, skill-sources, override, welcome, uninstall, unadopt
```
- Suggest only a **close** match: an edit distance of one or two, or a prefix of the name.
diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/cli.py b/plugins/magpie-setup/skills/setup/setup_preflight/cli.py
index b1123c34..48391519 100644
--- a/plugins/magpie-setup/skills/setup/setup_preflight/cli.py
+++ b/plugins/magpie-setup/skills/setup/setup_preflight/cli.py
@@ -44,6 +44,7 @@ from .core import (
isolated_setup_findings,
skill_findings,
verify_findings,
+ welcome_findings,
)
from .lockfile import MalformedLock
@@ -126,6 +127,11 @@ def build_parser() -> argparse.ArgumentParser:
help="days between isolated-setup-update reminders (default: the "
"`isolated_setup_update_interval_days` config key, else 7); 0 disables the timer",
)
+ parser.add_argument(
+ "--no-welcome",
+ action="store_true",
+ help="omit the skill family's first-run welcome guide",
+ )
parser.add_argument(
"--no-rules",
action="store_true",
@@ -152,6 +158,7 @@ def main(argv: list[str] | None = None) -> int:
else:
project, cached = cached_project_findings(root, installed)
findings = [
+ *([] if args.no_welcome else welcome_findings(root, args.skill)),
*project,
*skill_findings(root, args.skill, args.surface_hash, args.requires),
*isolated_setup_findings(root, args.isolated_setup_interval_days),
diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/core.py b/plugins/magpie-setup/skills/setup/setup_preflight/core.py
index 412e0aaa..860f4ab4 100644
--- a/plugins/magpie-setup/skills/setup/setup_preflight/core.py
+++ b/plugins/magpie-setup/skills/setup/setup_preflight/core.py
@@ -94,7 +94,7 @@ PROJECT_CACHE_TTL_SECONDS = 900
class Finding:
"""One thing the agent has to act on, and where the rules for it live."""
- scope: str # "project" | "skill" | "machine" | "end-of-run"
+ scope: str # "project" | "skill" | "family" | "machine" | "end-of-run"
code: str
section: str # the `preflight-detail.md` section to read
facts: dict[str, object] = field(default_factory=dict)
@@ -262,17 +262,37 @@ def _resolves(root: Path, name: str) -> bool:
return resolve(root, name) is not None
+#: What the pre-flight itself keeps in a personal layer. A layer holding
+#: only these, with a stamp that records nothing but the welcome-guide
+#: choice, was created by answering the guide, not by configuring anything.
+_BOOKKEEPING = frozenset({STAMP_NAME, CACHE_NAME})
+
+
+def _layer_configured(layer: Path) -> bool:
+ if not layer.is_dir():
+ return False
+ names = {p.name for p in layer.iterdir()}
+ if STAMP_NAME not in names or not names <= _BOOKKEEPING:
+ return True
+ try:
+ stamp = json.loads((layer / STAMP_NAME).read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError):
+ return True
+ return not (isinstance(stamp, dict) and set(stamp) <= {"welcome"})
+
+
def configured_at_all(root: Path) -> bool:
"""Has anything ever been configured or adopted here?
The lock, the personal layer (wherever it lives for this project, or
the legacy in-tree directory), or the committed overrides. All absent
means there is nothing to reconcile, and the whole fingerprint
- comparison is skipped in silence.
+ comparison is skipped in silence. A personal layer that exists only
+ because the welcome guide's answer was recorded there does not count.
"""
if (root / LOCK_NAME).exists() or (root / OVERRIDES_DIR).exists():
return True
- return any(layer.is_dir() for layer in personal_layers(root))
+ return any(_layer_configured(layer) for layer in personal_layers(root))
def skill_findings(
@@ -343,6 +363,20 @@ def skill_findings(
return findings
+# --- family scope: the first-run welcome guide -------------------------------------
+
+
+def welcome_findings(root: Path, skill: str) -> list[Finding]:
+ """The skill's family guide, when it ships one and the user has not set it aside."""
+ from . import welcome
+
+ due = welcome.welcome_facts(root, skill)
+ if due is None:
+ return []
+ section, facts = due
+ return [Finding("family", "welcome", section, facts)]
+
+
# --- end-of-run scope ---------------------------------------------------------------
diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/families.py b/plugins/magpie-setup/skills/setup/setup_preflight/families.py
new file mode 100644
index 00000000..6866ca84
--- /dev/null
+++ b/plugins/magpie-setup/skills/setup/setup_preflight/families.py
@@ -0,0 +1,183 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Generated by `python -m setup_preflight.welcome write-constant`. Do not edit.
+
+Each skill's frontmatter `family:`, keyed by its frontmatter `name:` and by
+`magpie-<skills/ mirror name>`, for installs that carry no skills (see `welcome.py`).
+"""
+
+SKILL_FAMILIES: dict[str, str] = {
+ "activity-sweep": "contributor-growth",
+ "announce-draft": "release-management",
+ "archive-sweep": "release-management",
+ "audit-finding-fix": "repo-health",
+ "audit-report": "release-management",
+ "backlog-stats": "issue",
+ "calibrate": "contributor-growth",
+ "candidate-screen": "contributor-growth",
+ "ci-runner-audit": "repo-health",
+ "code-review": "pr-management",
+ "committer-onboarding": "contributor-growth",
+ "contributor-to-committer": "contributor-growth",
+ "cve-allocate": "security",
+ "deduplicate": "issue",
+ "dependency-audit": "repo-health",
+ "dependency-license-audit": "repo-health",
+ "fix-workflow": "issue",
+ "flaky-test-triage": "repo-health",
+ "good-first-issue-author": "mentoring",
+ "good-first-issue-sweep": "mentoring",
+ "identity-map": "contributor-growth",
+ "isolated-setup-doctor": "setup",
+ "isolated-setup-install": "setup",
+ "isolated-setup-update": "setup",
+ "isolated-setup-verify": "setup",
+ "issue-deduplicate": "security",
+ "issue-fix": "security",
+ "issue-import": "security",
+ "issue-import-from-md": "security",
+ "issue-import-from-pr": "security",
+ "issue-import-from-scan": "security",
+ "issue-import-via-forwarder": "security",
+ "issue-invalidate": "security",
+ "issue-sync": "security",
+ "issue-triage": "security",
+ "keys-sync": "release-management",
+ "license-compliance-audit": "repo-health",
+ "list-skills": "utilities",
+ "magpie-audit-finding-fix": "repo-health",
+ "magpie-ci-runner-audit": "repo-health",
+ "magpie-committer-onboarding": "contributor-growth",
+ "magpie-contributor-activity-sweep": "contributor-growth",
+ "magpie-contributor-calibrate": "contributor-growth",
+ "magpie-contributor-candidate-screen": "contributor-growth",
+ "magpie-contributor-identity-map": "contributor-growth",
+ "magpie-contributor-nomination": "contributor-growth",
+ "magpie-contributor-sentiment": "contributor-growth",
+ "magpie-contributor-to-committer": "contributor-growth",
+ "magpie-dependency-audit": "repo-health",
+ "magpie-dependency-license-audit": "repo-health",
+ "magpie-flaky-test-triage": "repo-health",
+ "magpie-good-first-issue-author": "mentoring",
+ "magpie-good-first-issue-sweep": "mentoring",
+ "magpie-issue-backlog-stats": "issue",
+ "magpie-issue-deduplicate": "issue",
+ "magpie-issue-fix-workflow": "issue",
+ "magpie-issue-reassess": "issue",
+ "magpie-issue-reassess-stats": "issue",
+ "magpie-issue-reproducer": "issue",
+ "magpie-issue-stale-sweep": "issue",
+ "magpie-issue-triage": "issue",
+ "magpie-license-compliance-audit": "repo-health",
+ "magpie-list-skills": "utilities",
+ "magpie-mentoring-welcome": "mentoring",
+ "magpie-newcomer-issue-explainer": "mentoring",
+ "magpie-onboarding-concierge": "contributor-growth",
+ "magpie-optimize-skill": "utilities",
+ "magpie-pairing-multi-agent-review": "pairing",
+ "magpie-pairing-self-review": "pairing",
+ "magpie-pr-management-code-review": "pr-management",
+ "magpie-pr-management-mentor": "pr-management",
+ "magpie-pr-management-quick-merge": "pr-management",
+ "magpie-pr-management-stack-review": "pr-management",
+ "magpie-pr-management-stats": "pr-management",
+ "magpie-pr-management-triage": "pr-management",
+ "magpie-pr-stale-sweep": "pr-management",
+ "magpie-pre-first-pr-check": "pr-management",
+ "magpie-release-announce-draft": "release-management",
+ "magpie-release-archive-sweep": "release-management",
+ "magpie-release-audit-report": "release-management",
+ "magpie-release-keys-sync": "release-management",
+ "magpie-release-prepare": "release-management",
+ "magpie-release-promote": "release-management",
+ "magpie-release-rc-cut": "release-management",
+ "magpie-release-verify-rc": "release-management",
+ "magpie-release-vote-draft": "release-management",
+ "magpie-release-vote-tally": "release-management",
+ "magpie-report-framework-issue": "utilities",
+ "magpie-reviewer-routing": "pr-management",
+ "magpie-security-cve-allocate": "security",
+ "magpie-security-issue-deduplicate": "security",
+ "magpie-security-issue-fix": "security",
+ "magpie-security-issue-import": "security",
+ "magpie-security-issue-import-from-md": "security",
+ "magpie-security-issue-import-from-pr": "security",
+ "magpie-security-issue-import-from-scan": "security",
+ "magpie-security-issue-import-via-forwarder": "security",
+ "magpie-security-issue-invalidate": "security",
+ "magpie-security-issue-sync": "security",
+ "magpie-security-issue-triage": "security",
+ "magpie-security-model-prepare": "security",
+ "magpie-security-model-update": "security",
+ "magpie-security-model-verify": "security",
+ "magpie-security-tracker-stats-dashboard": "security",
+ "magpie-setup": "setup",
+ "magpie-setup-isolated-setup-doctor": "setup",
+ "magpie-setup-isolated-setup-install": "setup",
+ "magpie-setup-isolated-setup-update": "setup",
+ "magpie-setup-isolated-setup-verify": "setup",
+ "magpie-setup-override-upstream": "setup",
+ "magpie-setup-privacy-llm": "setup",
+ "magpie-setup-shared-config-sync": "setup",
+ "magpie-setup-status": "setup",
+ "magpie-setup-upstream-fix": "setup",
+ "magpie-skill-reconciler": "utilities",
+ "magpie-workflow-security-audit": "repo-health",
+ "magpie-write-skill": "utilities",
+ "mentor": "pr-management",
+ "model-prepare": "security",
+ "model-update": "security",
+ "model-verify": "security",
+ "multi-agent-review": "pairing",
+ "newcomer-issue-explainer": "mentoring",
+ "nomination": "contributor-growth",
+ "onboarding-concierge": "contributor-growth",
+ "optimize-skill": "utilities",
+ "override-upstream": "setup",
+ "pr-stale-sweep": "pr-management",
+ "pr-triage": "pr-management",
+ "pre-first-pr-check": "pr-management",
+ "prepare": "release-management",
+ "privacy-llm": "setup",
+ "promote": "release-management",
+ "quick-merge": "pr-management",
+ "rc-cut": "release-management",
+ "reassess": "issue",
+ "reassess-stats": "issue",
+ "report-framework-issue": "utilities",
+ "reproducer": "issue",
+ "reviewer-routing": "pr-management",
+ "self-review": "pairing",
+ "sentiment": "contributor-growth",
+ "setup": "setup",
+ "shared-config-sync": "setup",
+ "skill-reconciler": "utilities",
+ "stack-review": "pr-management",
+ "stale-sweep": "issue",
+ "stats": "pr-management",
+ "status": "setup",
+ "tracker-stats-dashboard": "security",
+ "triage": "issue",
+ "upstream-fix": "setup",
+ "verify-rc": "release-management",
+ "vote-draft": "release-management",
+ "vote-tally": "release-management",
+ "welcome": "mentoring",
+ "workflow-security-audit": "repo-health",
+ "write-skill": "utilities",
+}
diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/guides/security.md b/plugins/magpie-setup/skills/setup/setup_preflight/guides/security.md
new file mode 100644
index 00000000..5ae2a9c0
--- /dev/null
+++ b/plugins/magpie-setup/skills/setup/setup_preflight/guides/security.md
@@ -0,0 +1,67 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# 🐦 Magpie here — your security-team sidekick
+
+A one-minute tour, then straight back to what you asked for.
+
+## 🔄 The typical flow
+
+1. 📥 **Import** new reports from `<security-list>` — *"import new reports"*
+2. 🧭 **Triage** — proposed dispositions for the team to agree on — *"triage the open issues"*
+3. 🔁 **Sync** — keeps each tracker in step with its mail thread and fix PRs; the everyday command — *"sync 123"*
+4. 🏷️ **Allocate the CVE** once the team agrees the report is valid — *"allocate a CVE for 123"*
+5. 🛠️ **Fix** in a public `<upstream>` PR that never gives away the security angle — *"try to fix 123"*
+6. 📣 **Publish & announce** — sync again: it walks you through the advisory and drafts the final reporter email — *"the fix for 123 is released, sync it"*
+
+Nothing is labelled, posted, or sent without your OK.
+
+## ⚙️ Configure it
+
+Two ways to run Magpie:
+
+- 🙋 **Installed** — just for you: personal configuration, nothing committed — `/magpie-setup:setup config`
+- 👥 **Adopted** — for your project: the configuration is stored in your repo and shared with every contributor — `/magpie-setup:setup adopt` (a maintainers' decision)
+
+On a pinned-snapshot install the command is the shorter `/magpie-setup config` (or `adopt`).
+
+The first time, a skill asks for what it cannot guess —
+your `<security-list>` address, the `<tracker>` repository, the CVE tool you use —
+and `/magpie-setup:setup config` fills it in.
+
+## 💬 Just ask
+
+The most powerful thing here is the conversation.
+Plain language works:
+
+- *"import new reports from the last 30 days"*
+- *"what's waiting for triage?"*
+- *"sync 123 and tell me what changed"*
+- *"draft the reply to the reporter for 123"*
+- *"which trackers are stuck waiting for a fix?"*
+- *"allocate a CVE for 123"*
+- *"the advisory for 123 went out — finish it"*
+
+## 🎨 Make it yours
+
+Magpie ships default settings and workflows.
+Change them by describing the change:
+
+- *"from now on, always cc the release manager on reporter replies"*
+- *"skip the board column for INFO-ONLY reports"*
+
+Magpie records it as an override for that skill (`/magpie-setup:setup override <skill>`).
+Worth sharing? Say *"upstream this change to Magpie"* —
+it makes the change generic and opens a PR to `apache/magpie` for you to review (`/magpie-setup:override-upstream`).
+
+## 👋 About this guide
+
+- **Continue** — show it again next time (three times at most)
+- **Dismiss** — hide it until the next Magpie upgrade
+- **Don't show again** — hide it for good; say *"show the security welcome again"* to bring it back
+
+🌈 Prefer it in colour? Run this yourself — the `!` prefix runs it as a shell command:
+
+```text
+! PYTHONPATH=".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie" python3 -m setup_preflight.welcome show --family security --color=always
+```
diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/sections/welcome-security.md b/plugins/magpie-setup/skills/setup/setup_preflight/sections/welcome-security.md
new file mode 100644
index 00000000..2b48b761
--- /dev/null
+++ b/plugins/magpie-setup/skills/setup/setup_preflight/sections/welcome-security.md
@@ -0,0 +1,32 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## welcome-security — the security family's first-run guide
+
+A security-family skill is running for one of the first times for this user here,
+and the welcome guide is due (`facts.reason`: `first-run`, `again`, or `upgraded` after a dismissal).
+`facts.guide` is the guide.
+
+1. **Show `facts.guide` to the user verbatim**, as Markdown, before the work they asked for.
+ Do not summarise, reword, trim, or add to it, and substitute nothing in it:
+ its `<security-list>`, `<tracker>` and `<upstream>` are meant to be read as written.
+2. **Offer the three choices in one line**:
+ **Continue** (show again next time) · **Dismiss** (hide until the next Magpie upgrade) · **Don't show again**.
+3. **Record `seen` at once**, which is what no answer means, then carry on with the user's request in the same turn.
+ Never block the requested work on the guide, and never wait for an answer before starting it.
+4. **When the user picks Dismiss or Don't show again** — now or later in the session — record that choice;
+ it replaces `seen`. Continue needs nothing further.
+
+```bash
+PYTHONPATH=".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie" \
+ python3 -m setup_preflight.welcome record --family security --choice <seen|dismiss|never>
+```
+
+`seen` brings the guide back on the next run, `facts.max_shown` recorded showings in all (`facts.shown` so far);
+`dismiss` hides it until the framework version changes; `never` hides it until re-enabled.
+Every write merges into the personal layer's `reconciled.json` under `welcome.security`, keeping every other key;
+never write it by hand.
+If the command exits non-zero, say nothing more about it and carry on.
+
+To bring the guide back, the user asks (*"show the security welcome again"*) and `/magpie-setup:setup welcome` runs
+`python3 -m setup_preflight.welcome enable --family security`.
diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/welcome.py b/plugins/magpie-setup/skills/setup/setup_preflight/welcome.py
new file mode 100644
index 00000000..3dbde43d
--- /dev/null
+++ b/plugins/magpie-setup/skills/setup/setup_preflight/welcome.py
@@ -0,0 +1,456 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""A skill family's first-run welcome guide: when to show it, and what was chosen.
+
+The first time a skill of a family that ships a guide (`guides/<family>.md`)
+runs for this user, the pre-flight reports a `welcome` finding carrying the
+guide. The agent shows it, offers three choices, and records the answer
+here, in the personal layer's `reconciled.json` under `welcome.<family>`:
+
+* **`seen`** — shown again on the next run, up to `MAX_SEEN` recorded
+ showings in all, then not again;
+* **`dismiss`** — hidden until the framework version changes;
+* **`never`** — hidden until `enable` clears it.
+
+Which family a skill belongs to comes from its frontmatter `family:`, which
+a marketplace install cannot read from here (the copy of this package in
+the personal layer carries no skills), so it is generated into
+`families.py` by `write-constant`, kept current by a prek hook.
+
+Run as a module:
+
+ python3 -m setup_preflight.welcome show --family security [--color[=auto|always|never]]
+ python3 -m setup_preflight.welcome record --family security --choice seen|dismiss|never
+ python3 -m setup_preflight.welcome enable --family security
+ python3 -m setup_preflight.welcome write-constant # framework repo only (prek)
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+from datetime import date
+from pathlib import Path
+from typing import TextIO
+
+from .isolated import NoPersonalLayer, _load_stamp, _stamp_path
+from .layers import personal_dir
+
+HERE = Path(__file__).resolve().parent
+GUIDES_DIR = HERE / "guides"
+SECTIONS_DIR = HERE / "sections"
+BLOCK = "welcome"
+CHOICES = ("seen", "dismiss", "never")
+#: How many recorded `seen` showings before the guide stops on its own.
+MAX_SEEN = 3
+
+_LICENCE_RE = re.compile(r"\A<!--\s*SPDX-License-Identifier.*?-->\s*", re.S)
+_PLUGIN_JSON = Path("plugins") / "magpie-setup" / ".claude-plugin" / "plugin.json"
+SNAPSHOT_DIR = ".apache-magpie"
+
+
+# --- which family, which guide ------------------------------------------------------
+
+
+def family_of(skill: str) -> str | None:
+ """The family of `skill`: its frontmatter `name:`, or `magpie-<mirror name>`.
+
+ Exact keys only. A bare mirror name can collide with another family's
+ frontmatter name (`skills/issue-triage` is the issue family's `triage`,
+ while `issue-triage` is the security family's), so mirror names are
+ keyed only with the `magpie-` prefix a pinned-snapshot install uses.
+ """
+ try:
+ from .families import SKILL_FAMILIES
+ except ImportError:
+ return None
+ return SKILL_FAMILIES.get(skill)
+
+
+def guides() -> list[str]:
+ return sorted(p.stem for p in GUIDES_DIR.glob("*.md"))
+
+
+def guide(family: str) -> str | None:
+ """The guide's Markdown without its licence header, or `None`."""
+ path = GUIDES_DIR / f"{family}.md"
+ if not path.is_file():
+ return None
+ return _LICENCE_RE.sub("", path.read_text(encoding="utf-8")).strip() + "\n"
+
+
+def section(family: str) -> str:
+ return f"welcome-{family}"
+
+
+# --- the version a dismissal is tied to ---------------------------------------------
+
+
+def _plugin_version(path: Path) -> str | None:
+ try:
+ loaded = json.loads(path.read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError):
+ return None
+ if not isinstance(loaded, dict) or loaded.get("name") != "magpie-setup":
+ return None
+ version = loaded.get("version")
+ return version if isinstance(version, str) and version else None
+
+
+def _package_fingerprint() -> str:
+ digest = hashlib.sha256()
+ for path in sorted(HERE.rglob("*")):
+ relative = path.relative_to(HERE)
+ if not path.is_file() or "__pycache__" in relative.parts or path.suffix == ".pyc":
+ continue
+ digest.update(relative.as_posix().encode())
+ digest.update(b"\0")
+ digest.update(path.read_bytes())
+ digest.update(b"\0")
+ return "checker:" + digest.hexdigest()[:16]
+
+
+def framework_stamp(root: Path) -> str:
+ """The framework version this checker belongs to, as one comparable string.
+
+ The `magpie-setup` plugin version when one can be read: beside this
+ package (a plugin or framework tree), in the project's own framework
+ tree, or in its pinned snapshot. Otherwise — the copy in the personal
+ layer of a marketplace install, which carries no manifest — the
+ fingerprint of this package, which `/magpie-setup:setup upgrade`
+ refreshes, so a dismissal lifts when an upgrade changes the checker.
+ """
+ for candidate in (
+ HERE.parents[2] / ".claude-plugin" / "plugin.json",
+ root / _PLUGIN_JSON,
+ root / SNAPSHOT_DIR / _PLUGIN_JSON,
+ ):
+ version = _plugin_version(candidate)
+ if version:
+ return version
+ return _package_fingerprint()
+
+
+# --- the decision -------------------------------------------------------------------
+
+
+def _state(root: Path, family: str) -> dict[str, object] | None:
+ raw = _load_stamp(root).get(BLOCK)
+ entry = raw.get(family) if isinstance(raw, dict) else None
+ return entry if isinstance(entry, dict) else None
+
+
+def _shown(state: dict[str, object] | None) -> int:
+ value = state.get("shown") if state else None
+ return value if isinstance(value, int) and value >= 0 else 0
+
+
+def reason_to_show(state: dict[str, object] | None, stamp: str) -> str | None:
+ """Why the guide is due (`first-run`, `again`, `upgraded`), or `None`."""
+ choice = state.get("choice") if state else None
+ if choice == "never":
+ return None
+ if choice == "dismiss":
+ return "upgraded" if state and state.get("version") != stamp else None
+ if choice == "seen":
+ return "again" if _shown(state) < MAX_SEEN else None
+ return "first-run"
+
+
+def welcome_facts(root: Path, skill: str) -> tuple[str, dict[str, object]] | None:
+ """`(section, facts)` when this skill's family guide is due, else `None`.
+
+ Silent when the skill has no family with a guide, and when there is no
+ personal layer to record a choice in (an unadopted project outside a
+ git repository): a guide that could never be dismissed would repeat on
+ every run.
+ """
+ family = family_of(skill)
+ if family is None:
+ return None
+ text = guide(family)
+ if text is None or not (SECTIONS_DIR / f"{section(family)}.md").is_file():
+ return None
+ if personal_dir(root) is None:
+ return None
+ state = _state(root, family)
+ reason = reason_to_show(state, framework_stamp(root))
+ if reason is None:
+ return None
+ return section(family), {
+ "family": family,
+ "reason": reason,
+ "shown": _shown(state),
+ "max_shown": MAX_SEEN,
+ "guide": text,
+ }
+
+
+# --- recording ----------------------------------------------------------------------
+
+
+def _write_stamp(root: Path, stamp: dict[str, object]) -> None:
+ path = _stamp_path(root)
+ path.parent.mkdir(parents=True, exist_ok=True)
+ tmp = path.with_suffix(".tmp")
+ tmp.write_text(json.dumps(stamp, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ tmp.replace(path)
+
+
+def record(root: Path, family: str, choice: str, today: date | None = None) -> dict[str, object]:
+ """Merge the user's choice into `welcome.<family>`; every other key is kept.
+
+ `seen` counts one more showing; `dismiss` and `never` leave the count
+ alone, so a `seen` recorded on display and replaced by the user's later
+ answer is still one showing.
+ """
+ if choice not in CHOICES:
+ raise ValueError(f"unknown choice {choice!r}; expected one of {CHOICES}")
+ stamp = _load_stamp(root)
+ raw = stamp.get(BLOCK)
+ block: dict[str, object] = dict(raw) if isinstance(raw, dict) else {}
+ previous = block.get(family)
+ shown = _shown(previous if isinstance(previous, dict) else None)
+ entry: dict[str, object] = {
+ "choice": choice,
+ "version": framework_stamp(root),
+ "at": (today or date.today()).isoformat(),
+ "shown": shown + 1 if choice == "seen" else shown,
+ }
+ block[family] = entry
+ stamp[BLOCK] = block
+ _write_stamp(root, stamp)
+ return entry
+
+
+def enable(root: Path, family: str) -> bool:
+ """Forget the choice, so the guide shows on the next run. `True` if one existed."""
+ stamp = _load_stamp(root)
+ raw = stamp.get(BLOCK)
+ if not isinstance(raw, dict) or family not in raw:
+ return False
+ block = dict(raw)
+ del block[family]
+ if block:
+ stamp[BLOCK] = block
+ else:
+ del stamp[BLOCK]
+ _write_stamp(root, stamp)
+ return True
+
+
+# --- showing it in a terminal -------------------------------------------------------
+
+_RESET = "\033[0m"
+_STYLES = {
+ "h1": "\033[1;35m",
+ "h2": "\033[1;36m",
+ "bold": "\033[1m",
+ "italic": "\033[3m",
+ "code": "\033[33m",
+ "quote": "\033[2m",
+ "block": "\033[32m",
+}
+_BOLD_RE = re.compile(r"\*\*(.+?)\*\*")
+_ITALIC_RE = re.compile(r"(?<![*\w])\*([^*\s][^*]*?)\*(?![*\w])")
+_CODE_RE = re.compile(r"`([^`]+)`")
+
+
+def use_color(mode: str, stream: TextIO, env: dict[str, str] | None = None) -> bool:
+ """Colour or not: `never`, `always` (unless NO_COLOR), `auto` (a tty, unless NO_COLOR).
+
+ NO_COLOR set to any non-empty value wins over everything (no-color.org).
+ """
+ environ = os.environ if env is None else env
+ if environ.get("NO_COLOR", ""):
+ return False
+ if mode == "always":
+ return True
+ if mode == "auto":
+ isatty = getattr(stream, "isatty", None)
+ return bool(isatty and isatty())
+ return False
+
+
+def _paint(style: str, text: str, color: bool) -> str:
+ return f"{_STYLES[style]}{text}{_RESET}" if color else text
+
+
+def _inline(text: str, color: bool) -> str:
+ text = _CODE_RE.sub(lambda m: _paint("code", m.group(1), color), text)
+ text = _BOLD_RE.sub(lambda m: _paint("bold", m.group(1), color), text)
+ return _ITALIC_RE.sub(lambda m: _paint("italic", m.group(1), color), text)
+
+
+def render_terminal(markdown: str, color: bool) -> str:
+ """The guide laid out for a terminal; escape codes only when `color`."""
+ out: list[str] = []
+ in_block = False
+ for line in markdown.splitlines():
+ if line.startswith("```"):
+ in_block = not in_block
+ continue
+ if in_block:
+ out.append(" " + _paint("block", line, color))
+ elif line.startswith("# "):
+ out.append(_paint("h1", line[2:], color))
+ elif line.startswith("## "):
+ out.append(_paint("h2", line[3:], color))
+ elif line.startswith("> "):
+ out.append(_paint("quote", "│ " + _inline(line[2:], False), color))
+ elif line.lstrip().startswith("- "):
+ indent = len(line) - len(line.lstrip())
+ out.append(" " * indent + " • " + _inline(line.lstrip()[2:], color))
+ else:
+ out.append(_inline(line, color))
+ return "\n".join(out).rstrip() + "\n"
+
+
+# --- the generated family map -------------------------------------------------------
+
+CONSTANT_PATH = HERE / "families.py"
+_FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\n", re.S)
+_KEY_RE = r"^{key}:\s*([A-Za-z0-9_.-]+)\s*$"
+_CONSTANT_HEADER = '''\
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Generated by `python -m setup_preflight.welcome write-constant`. Do not edit.
+
+Each skill's frontmatter `family:`, keyed by its frontmatter `name:` and by
+`magpie-<skills/ mirror name>`, for installs that carry no skills (see `welcome.py`).
+"""
+
+SKILL_FAMILIES: dict[str, str] = {
+'''
+
+
+def scan_families(base: Path) -> dict[str, str]:
+ """`{skill name: family}` from every plugin skill's frontmatter under `base`."""
+ found: dict[str, str] = {}
+ by_dir: dict[Path, str] = {}
+ for skill_md in sorted(base.glob("plugins/magpie-*/skills/*/SKILL.md")):
+ match = _FRONTMATTER_RE.match(skill_md.read_text(encoding="utf-8"))
+ if not match:
+ continue
+ name = re.search(_KEY_RE.format(key="name"), match.group(1), re.M)
+ family = re.search(_KEY_RE.format(key="family"), match.group(1), re.M)
+ if name and family:
+ found[name.group(1)] = family.group(1)
+ by_dir[skill_md.parent.resolve()] = family.group(1)
+ mirror = base / "skills"
+ if mirror.is_dir():
+ for link in sorted(mirror.iterdir()):
+ target = link.resolve()
+ if target in by_dir:
+ found.setdefault(f"magpie-{link.name}", by_dir[target])
+ return dict(sorted(found.items()))
+
+
+def render_constant(mapping: dict[str, str]) -> str:
+ body = "".join(f" {json.dumps(k)}: {json.dumps(v)},\n" for k, v in mapping.items())
+ return _CONSTANT_HEADER + body + "}\n"
+
+
+# --- the command --------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(prog="setup_preflight.welcome", description=__doc__.split("\n")[0])
+ sub = parser.add_subparsers(dest="action", required=True)
+ show = sub.add_parser("show", help="print a family's welcome guide")
+ show.add_argument("--family", required=True)
+ show.add_argument(
+ "--color",
+ nargs="?",
+ const="auto",
+ choices=["auto", "always", "never"],
+ help="terminal rendering; colour on a tty unless NO_COLOR (always: off a tty too)",
+ )
+ rec = sub.add_parser("record", help="record the user's answer to the guide")
+ rec.add_argument("--family", required=True)
+ rec.add_argument("--choice", required=True, choices=CHOICES)
+ rec.add_argument("--project-root", default=".", type=Path)
+ ena = sub.add_parser("enable", help="show the guide again on the next run")
+ ena.add_argument("--family", required=True)
+ ena.add_argument("--project-root", default=".", type=Path)
+ for name in ("write-constant", "check-constant"):
+ gen = sub.add_parser(name, help="framework repo only: the generated family map")
+ gen.add_argument("--project-root", default=".", type=Path)
+ args = parser.parse_args(argv)
+
+ if args.action in ("write-constant", "check-constant"):
+ mapping = scan_families(args.project_root)
+ if not mapping:
+ print(f"{args.action}: no plugin skills under {args.project_root}", file=sys.stderr)
+ return 2
+ wanted = render_constant(mapping)
+ have = CONSTANT_PATH.read_text(encoding="utf-8") if CONSTANT_PATH.exists() else ""
+ if have == wanted:
+ return 0
+ if args.action == "check-constant":
+ print(f"{CONSTANT_PATH.name} is stale; run write-constant", file=sys.stderr)
+ return 1
+ CONSTANT_PATH.write_text(wanted, encoding="utf-8")
+ print(f"{CONSTANT_PATH.name}: {len(mapping)} skills")
+ return 1 # a fixer that changed a file fails the hook, as prek expects
+
+ if guide(args.family) is None:
+ print(f"{args.action}: no welcome guide for {args.family!r}; have {guides()}", file=sys.stderr)
+ return 2
+
+ if args.action == "show":
+ text = guide(args.family) or ""
+ if args.color:
+ text = render_terminal(text, use_color(args.color, sys.stdout))
+ sys.stdout.write(text)
+ return 0
+
+ try:
+ if args.action == "record":
+ entry = record(args.project_root, args.family, args.choice)
+ print(json.dumps({BLOCK: {args.family: entry}}, indent=2, sort_keys=True))
+ return 0
+ cleared = enable(args.project_root, args.family)
+ except NoPersonalLayer as exc:
+ print(f"{args.action}: {exc}", file=sys.stderr)
+ return 2
+ print(json.dumps({"family": args.family, "enabled": True, "cleared": cleared}))
+ return 0
+
+
+if __name__ == "__main__": # pragma: no cover
+ raise SystemExit(main())
diff --git a/plugins/magpie-setup/skills/setup/welcome.md b/plugins/magpie-setup/skills/setup/welcome.md
new file mode 100644
index 00000000..1190a8fc
--- /dev/null
+++ b/plugins/magpie-setup/skills/setup/welcome.md
@@ -0,0 +1,44 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# welcome — show a skill family's first-run guide again
+
+A skill family can ship a short welcome guide that the pre-flight shows the first time one of its skills runs.
+Today that is the security family:
+[`setup_preflight/guides/security.md`](setup_preflight/guides/security.md).
+The pre-flight's `welcome` finding carries the guide and its rules;
+this sub-action is the user's way back to it after a Dismiss or a Don't show again.
+
+## Triggers
+
+Run it when the user asks for the guide back in any wording, for example:
+
+- *"show the security welcome again"*
+- *"turn the Magpie guide back on"*
+- *"I dismissed the welcome by mistake"*
+- *"show me the Magpie security guide"*
+
+## What to run
+
+Every command uses the personal layer's copy of the checker, as the pre-flight does:
+
+```bash
+PYTHONPATH=".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie" \
+ python3 -m setup_preflight.welcome <action> --family security
+```
+
+| Action | Effect |
+|---|---|
+| `enable` | Forget the recorded choice, so the next security skill shows the guide again. The default for a *"turn it back on"* request. |
+| `show` | Print the guide now. Show the output verbatim; it changes no state. The default for *"show me the guide"*. |
+| `show --color=always` | The same guide rendered for a terminal in colour. The agent's own reply cannot carry colour, so hand the user this line to run themselves with the `!` prefix; `NO_COLOR` turns the colour off, and plain `--color` colours only on a terminal. |
+| `record --choice seen\|dismiss\|never` | What the pre-flight's rules run after showing the guide. Not for this sub-action. |
+
+`enable` and `record` merge into the personal layer's `reconciled.json` under `welcome.<family>` and keep every other key.
+Never edit that key by hand.
+When no family is named and the user's request does not make one clear, use `security`, the only family with a guide.
+
+If the checker is missing, the personal layer has not been set up yet:
+run [`config`](config.md) first, which installs it.
+
+Report in one line what changed, for example *"The security welcome guide will show on your next security skill."*
diff --git a/tools/dev/check-family-plugins.py b/tools/dev/check-family-plugins.py
index 88d7fb76..bc9e46b1 100644
--- a/tools/dev/check-family-plugins.py
+++ b/tools/dev/check-family-plugins.py
@@ -26,6 +26,9 @@ Checks that every plugin is properly defined:
root manifest's shared metadata (version, author, homepage, repository,
license), and whose `skills/` directory contains exactly that family's skills
as single-hop symlinks into the shared `skills/<skill>` tree;
+- the skill → family map generated into the pre-flight checker
+ (`setup_preflight/families.py`, which decides whether a family's first-run
+ welcome guide applies) matches the frontmatter and the `skills/` mirror;
- every *substrate* plugin (`SUBSTRATE_PLUGINS` — a framework tool published as
its own plugin rather than a family of skills) has a well-formed manifest that
inherits the same shared metadata, declares the exact hook wiring the framework
@@ -46,6 +49,7 @@ import argparse
import json
import re
import shutil
+import subprocess
import sys
import tomllib
from pathlib import Path
@@ -832,6 +836,28 @@ def check_setup_preflight_package() -> list[str]:
return errors
+def welcome_families(action: str) -> list[str]:
+ """Run `setup_preflight.welcome` `check-constant` or `write-constant` here.
+
+ The family map is a pure function of the frontmatter, so it is checked and
+ regenerated with the rest of this script's frontmatter-derived output.
+ A tree without the checker package (a test fixture) has nothing to check.
+ """
+ if not (SETUP_PREFLIGHT_PACKAGE / "welcome.py").is_file():
+ return []
+ result = subprocess.run(
+ [sys.executable, "-m", "setup_preflight.welcome", action],
+ capture_output=True,
+ text=True,
+ env={"PYTHONPATH": str(SETUP_PREFLIGHT_PACKAGE.parent), "PYTHONDONTWRITEBYTECODE": "1"},
+ check=False,
+ )
+ if result.returncode == 0 or (action == "write-constant" and result.returncode == 1):
+ return []
+ detail = (result.stderr or result.stdout).strip()
+ return [f"{SETUP_PREFLIGHT_PACKAGE}/families.py: {detail} (regenerate with --fix)"]
+
+
def check(fam: dict[str, set[str]]) -> list[str]:
errors: list[str] = []
@@ -890,6 +916,7 @@ def check(fam: dict[str, set[str]]) -> list[str]:
if setup_data is not None and "check-upgrade.sh" not in json.dumps(setup_data.get("hooks", {})):
errors.append(f"{setup_manifest}: SessionStart hook does not reference check-upgrade.sh")
errors += check_setup_preflight_package()
+ errors += welcome_families("check-constant")
errors += check_setup_templates()
@@ -1160,6 +1187,10 @@ def fix(fam: dict[str, set[str]]) -> int:
)
market["plugins"] = keep
MARKETPLACE.write_text(json.dumps(market, indent=2) + "\n", encoding="utf-8")
+ if welcome_errs := welcome_families("write-constant"):
+ for e in welcome_errs:
+ print(f" - {e}", file=sys.stderr)
+ return 1
print("Regenerated per-family plugins + marketplace entries from frontmatter.")
return 0
diff --git a/tools/dev/render-preflight-fixtures.py b/tools/dev/render-preflight-fixtures.py
index b97e1d60..8012239b 100644
--- a/tools/dev/render-preflight-fixtures.py
+++ b/tools/dev/render-preflight-fixtures.py
@@ -31,6 +31,9 @@ verdict is rendered, never written:
on `PATH`).
* `requires` — `requires_config:` entries passed as `--requires`.
* `skill`, `hash` — the invoking skill's `name:` and `surface_hash:`.
+* `welcome` — `true` to include the skill family's first-run welcome guide.
+ Left out otherwise (`--no-welcome`), so a floor case is about the floor
+ and not about which family its skill happens to belong to.
Usage:
@@ -102,6 +105,8 @@ def run_checker(state: dict[str, object], repo_root: Path, scratch: Path) -> str
raise ValueError("`requires` must be a list")
for entry in requires:
args += ["--requires", str(entry)]
+ if state.get("welcome") is not True:
+ args.append("--no-welcome")
env = _env(scratch)
env["PYTHONPATH"] = str(repo_root / CHECKER)
diff --git a/tools/dev/tests/test_check_family_plugins.py b/tools/dev/tests/test_check_family_plugins.py
index 1dbfb921..ecb2e286 100644
--- a/tools/dev/tests/test_check_family_plugins.py
+++ b/tools/dev/tests/test_check_family_plugins.py
@@ -263,6 +263,38 @@ def test_a_preflight_package_linked_out_of_the_plugin_is_reported(tmp_path, monk
assert any("expected a symlink" in e for e in errors)
+def _welcome_tree(root: Path) -> None:
+ """A copy of the real checker beside one plugin skill, whose map is stale."""
+ import shutil
+
+ shutil.copytree(
+ REPO_ROOT / mod.SETUP_PREFLIGHT_PACKAGE,
+ root / mod.SETUP_PREFLIGHT_PACKAGE,
+ ignore=shutil.ignore_patterns("__pycache__"),
+ )
+ skill = root / "plugins" / "magpie-security" / "skills" / "issue-sync"
+ skill.mkdir(parents=True)
+ (skill / "SKILL.md").write_text("---\nname: issue-sync\nfamily: security\n---\n", encoding="utf-8")
+
+
+def test_the_real_welcome_family_map_is_in_sync(monkeypatch):
+ monkeypatch.chdir(REPO_ROOT)
+ assert mod.welcome_families("check-constant") == []
+
+
+def test_a_stale_welcome_family_map_is_reported_and_fixed(tmp_path, monkeypatch):
+ _welcome_tree(tmp_path)
+ monkeypatch.chdir(tmp_path)
+ assert any("families.py" in e for e in mod.welcome_families("check-constant"))
+ assert mod.welcome_families("write-constant") == []
+ assert mod.welcome_families("check-constant") == []
+
+
+def test_a_tree_without_the_checker_has_no_family_map_to_check(tmp_path, monkeypatch):
+ monkeypatch.chdir(tmp_path)
+ assert mod.welcome_families("check-constant") == []
+
+
# ---------------------------------------------------------------------------
# Plugin skill aliases — the family prefix comes off the symlink, not the source
# ---------------------------------------------------------------------------
diff --git a/tools/setup-preflight/README.md b/tools/setup-preflight/README.md
index da81bdf8..3a99ec6b 100644
--- a/tools/setup-preflight/README.md
+++ b/tools/setup-preflight/README.md
@@ -128,6 +128,41 @@ own fingerprint comparison.
**`skill`** findings differ per skill: its fingerprint against the
reconciliation stamp, and whether its `requires_config:` entries resolve.
+**`family`** findings are about the skill family the invoking skill belongs to.
+Today there is one: `welcome`, the family's first-run welcome guide,
+for a family that ships one (`setup_preflight/guides/<family>.md`, today `security`)
+with its rules in the `welcome-<family>` section.
+`facts.guide` carries the guide, so the agent shows it without another read.
+The family comes from `families.py`, a map of every skill's frontmatter `family:`
+generated by `python3 -m setup_preflight.welcome write-constant`
+and kept current by `check-family-plugins` (`--fix` regenerates it),
+because a marketplace install's copy of this package has no skills to read.
+The user's answer is recorded under `welcome.<family>` in the personal layer's `reconciled.json`:
+
+| Choice | Shown again |
+|---|---|
+| `seen` (Continue, or no answer) | on the next run, three recorded showings in all |
+| `dismiss` | after the framework version changes |
+| `never` | after `enable` |
+
+The version is the `magpie-setup` plugin's, read beside this package,
+in the project's framework tree or in its pinned snapshot;
+the personal-layer copy of a marketplace install has no manifest,
+so there it is a fingerprint of this package, which `/magpie-setup:setup upgrade` refreshes.
+The finding is skipped where there is no personal layer to record into,
+`--no-welcome` leaves it out, and a personal layer holding nothing but that record
+does not make the project count as configured.
+
+```bash
+python3 -m setup_preflight.welcome show --family security [--color[=auto|always|never]]
+python3 -m setup_preflight.welcome record --family security --choice seen|dismiss|never
+python3 -m setup_preflight.welcome enable --family security
+```
+
+`show --color` renders the guide for a terminal, in colour only on a tty;
+`--color=always` colours off a tty too (an agent's `!` shell command);
+`NO_COLOR` turns colour off either way.
+
**`machine`** findings are about the isolated (secure agent) setup on
this machine, reported only where it is used: `isolated-setup-changed`
when the fingerprint of the secure-setup files differs from the one the
diff --git a/tools/setup-preflight/pyproject.toml b/tools/setup-preflight/pyproject.toml
index f6dcb662..fe03c171 100644
--- a/tools/setup-preflight/pyproject.toml
+++ b/tools/setup-preflight/pyproject.toml
@@ -37,6 +37,7 @@ packages = ["src/setup_preflight"]
[tool.hatch.build.targets.wheel.force-include]
"src/setup_preflight/sections" = "setup_preflight/sections"
+"src/setup_preflight/guides" = "setup_preflight/guides"
[tool.ruff]
line-length = 110
diff --git a/tools/setup-preflight/tests/test_welcome.py b/tools/setup-preflight/tests/test_welcome.py
new file mode 100644
index 00000000..6f5b59eb
--- /dev/null
+++ b/tools/setup-preflight/tests/test_welcome.py
@@ -0,0 +1,336 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""When a family's first-run welcome guide is shown, and what the answer records."""
+
+from __future__ import annotations
+
+import io
+import json
+from datetime import date
+from pathlib import Path
+
+import pytest
+
+from setup_preflight import sections, welcome
+from setup_preflight.cli import main as preflight
+from setup_preflight.core import configured_at_all, skill_findings, welcome_findings
+
+from .conftest import personal, write_stamp
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+SECURITY_SKILL = "issue-sync"
+OTHER_SKILL = "pr-triage"
+
+
+def stamp(root: Path) -> dict:
+ return json.loads((personal(root) / "reconciled.json").read_text(encoding="utf-8"))
+
+
+def codes(root: Path, skill: str = SECURITY_SKILL) -> list[str]:
+ return [f.code for f in welcome_findings(root, skill)]
+
+
+@pytest.fixture
+def version(monkeypatch: pytest.MonkeyPatch) -> list[str]:
+ """The framework version the checker sees; tests move it by assignment."""
+ current = ["0.9.0"]
+ monkeypatch.setattr(welcome, "framework_stamp", lambda root: current[0])
+ return current
+
+
+# --- which skills ---------------------------------------------------------------------
+
+
+def test_a_security_skill_gets_the_guide_on_its_first_run(project: Path, version) -> None:
+ findings = welcome_findings(project, SECURITY_SKILL)
+ assert [(f.scope, f.code, f.section) for f in findings] == [("family", "welcome", "welcome-security")]
+ facts = findings[0].facts
+ assert facts["family"] == "security"
+ assert facts["reason"] == "first-run"
+ assert facts["shown"] == 0
+ assert facts["guide"] == welcome.guide("security")
+
+
+def test_a_skill_of_a_family_without_a_guide_gets_nothing(project: Path, version) -> None:
+ assert welcome.family_of(OTHER_SKILL) == "pr-management"
+ assert codes(project, OTHER_SKILL) == []
+
+
+def test_an_unknown_skill_gets_nothing(project: Path, version) -> None:
+ assert codes(project, "magpie-x") == []
+
+
+def test_mirror_names_resolve_only_with_their_prefix() -> None:
+ """`skills/issue-triage` is the issue family's `triage`; the security
+ family's frontmatter name is `issue-triage`. The bare name is the
+ frontmatter one, and the mirror is reached only as `magpie-<mirror>`."""
+ assert welcome.family_of("issue-triage") == "security"
+ assert welcome.family_of("magpie-issue-triage") == "issue"
+ assert welcome.family_of("magpie-security-issue-triage") == "security"
+
+
+def test_nowhere_to_record_means_no_guide(tmp_path: Path, version) -> None:
+ """An unadopted project outside git has no personal layer: a guide that
+ could never be dismissed would repeat on every run."""
+ assert welcome_findings(tmp_path, SECURITY_SKILL) == []
+
+
+def run(project: Path, *extra: str) -> None:
+ listing = project / "plugins.json"
+ listing.write_text("[]")
+ preflight(
+ ["--skill", SECURITY_SKILL, "--project-root", str(project), "--plugin-list", str(listing), *extra]
+ )
+
+
+def test_the_finding_rides_the_verdict_with_its_rules(project: Path, capsys, version) -> None:
+ run(project)
+ payload = json.loads(capsys.readouterr().out)
+ assert payload["verdict"] == "action"
+ assert payload["findings"][0]["section"] == "welcome-security"
+ assert payload["rules"]["welcome-security"].startswith("## welcome-security")
+
+
+def test_no_welcome_leaves_it_out(project: Path, capsys, version) -> None:
+ run(project, "--no-welcome")
+ assert json.loads(capsys.readouterr().out) == {"verdict": "ok"}
+
+
+# --- the three answers ----------------------------------------------------------------
+
+
+def test_seen_shows_again_and_stops_after_three(project: Path, version) -> None:
+ reasons = []
+ for _ in range(5):
+ found = welcome_findings(project, SECURITY_SKILL)
+ reasons.append(found[0].facts["reason"] if found else None)
+ if found:
+ welcome.record(project, "security", "seen")
+ assert reasons == ["first-run", "again", "again", None, None]
+ assert stamp(project)["welcome"]["security"]["shown"] == 3
+
+
+def test_a_later_answer_replaces_seen_without_counting_twice(project: Path, version) -> None:
+ welcome.record(project, "security", "seen")
+ entry = welcome.record(project, "security", "dismiss")
+ assert entry["choice"] == "dismiss"
+ assert entry["shown"] == 1
+
+
+def test_dismiss_hides_it_until_the_version_changes(project: Path, version) -> None:
+ welcome.record(project, "security", "dismiss")
+ assert codes(project) == []
+ version[0] = "0.10.0"
+ found = welcome_findings(project, SECURITY_SKILL)
+ assert [f.facts["reason"] for f in found] == ["upgraded"]
+
+
+def test_never_persists_across_versions(project: Path, version) -> None:
+ welcome.record(project, "security", "never")
+ version[0] = "1.0.0"
+ assert codes(project) == []
+
+
+def test_enable_clears_the_choice(project: Path, version) -> None:
+ welcome.record(project, "security", "never")
+ assert welcome.enable(project, "security") is True
+ assert codes(project) == ["welcome"]
+ assert "welcome" not in stamp(project)
+ assert welcome.enable(project, "security") is False
+
+
+def test_an_unknown_choice_is_refused(project: Path, version) -> None:
+ with pytest.raises(ValueError):
+ welcome.record(project, "security", "later")
+
+
+# --- what recording writes ------------------------------------------------------------
+
+
+def test_record_merges_into_the_stamp_without_touching_other_keys(project: Path, version) -> None:
+ original: dict[str, object] = {
+ "version": "0.8.0",
+ "skills": {"issue-sync": "sha256:aaaa"},
+ "acknowledged": {"sweep": "0.8.0"},
+ "isolated_setup": {"enabled": False},
+ "welcome": {"other": {"choice": "never"}},
+ }
+ write_stamp(project, original)
+ entry = welcome.record(project, "security", "dismiss", today=date(2026, 10, 16))
+ assert entry == {"choice": "dismiss", "version": "0.9.0", "at": "2026-10-16", "shown": 0}
+ after = stamp(project)
+ assert after["welcome"] == {"other": {"choice": "never"}, "security": entry}
+ assert {k: v for k, v in after.items() if k != "welcome"} == {
+ k: v for k, v in original.items() if k != "welcome"
+ }
+
+
+def test_enable_keeps_other_families_and_keys(project: Path, version) -> None:
+ write_stamp(project, {"skills": {"a": "b"}, "welcome": {"security": {"choice": "never"}, "x": {}}})
+ welcome.enable(project, "security")
+ assert stamp(project) == {"skills": {"a": "b"}, "welcome": {"x": {}}}
+
+
+def test_answering_the_guide_is_not_configuring_the_project(project: Path, version) -> None:
+ """The record creates the personal layer; that must not read as a
+ configured project and start proposing a reconciliation sweep."""
+ welcome.record(project, "security", "seen")
+ assert not configured_at_all(project)
+ assert skill_findings(project, SECURITY_SKILL, "sha256:abc", []) == []
+
+
+def test_a_layer_with_real_config_is_still_configured(project: Path, version) -> None:
+ welcome.record(project, "security", "seen")
+ (personal(project) / "project.md").write_text("# project\n", encoding="utf-8")
+ assert configured_at_all(project)
+
+
+def test_the_record_command_prints_the_entry(project: Path, capsys, version) -> None:
+ code = welcome.main(
+ ["record", "--family", "security", "--choice", "never", "--project-root", str(project)]
+ )
+ assert code == 0
+ assert json.loads(capsys.readouterr().out)["welcome"]["security"]["choice"] == "never"
+
+
+def test_recording_outside_a_git_repo_refuses(tmp_path: Path, capsys, version) -> None:
+ code = welcome.main(
+ ["record", "--family", "security", "--choice", "seen", "--project-root", str(tmp_path)]
+ )
+ assert code == 2
+
+
+def test_an_unknown_family_is_refused(capsys) -> None:
+ assert welcome.main(["show", "--family", "nope"]) == 2
+
+
+# --- the version a dismissal is tied to -----------------------------------------------
+
+
+def manifest(base: Path, name: str, version: str) -> None:
+ directory = base / "plugins" / "magpie-setup" / ".claude-plugin"
+ directory.mkdir(parents=True)
+ (directory / "plugin.json").write_text(json.dumps({"name": name, "version": version}))
+
+
+@pytest.fixture
+def copied_checker(project: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ """The checker as copied into a personal layer: no manifest beside it."""
+ here = project / ".git" / "apache-magpie" / "setup_preflight"
+ here.mkdir(parents=True)
+ (here / "core.py").write_text("# a copy\n")
+ monkeypatch.setattr(welcome, "HERE", here)
+ return here
+
+
+def test_the_stamp_is_the_setup_plugin_version_in_a_framework_tree(project: Path, copied_checker) -> None:
+ manifest(project, "magpie-setup", "1.2.3")
+ assert welcome.framework_stamp(project) == "1.2.3"
+
+
+def test_a_pinned_snapshot_supplies_the_version(project: Path, copied_checker) -> None:
+ manifest(project / ".apache-magpie", "magpie-setup", "1.2.4")
+ assert welcome.framework_stamp(project) == "1.2.4"
+
+
+def test_a_manifest_of_another_plugin_is_not_the_version(project: Path, copied_checker) -> None:
+ manifest(project, "magpie-other", "9.9.9")
+ assert welcome.framework_stamp(project).startswith("checker:")
+
+
+def test_running_from_the_plugin_reads_its_own_manifest(project: Path) -> None:
+ beside = welcome._plugin_version(welcome.HERE.parents[2] / ".claude-plugin" / "plugin.json")
+ if beside is None:
+ pytest.skip("not running from a magpie-setup plugin tree")
+ assert welcome.framework_stamp(project) == beside
+
+
+def test_without_a_manifest_the_stamp_is_the_checker_fingerprint(project: Path, copied_checker) -> None:
+ before = welcome.framework_stamp(project)
+ assert before.startswith("checker:")
+ (copied_checker / "core.py").write_text("# an upgraded copy\n")
+ assert welcome.framework_stamp(project) != before
+
+
+# --- showing it -----------------------------------------------------------------------
+
+
+class Tty(io.StringIO):
+ def isatty(self) -> bool:
+ return True
+
+
+def test_colour_needs_a_tty_unless_forced() -> None:
+ assert welcome.use_color("auto", Tty(), env={}) is True
+ assert welcome.use_color("auto", io.StringIO(), env={}) is False
+ assert welcome.use_color("always", io.StringIO(), env={}) is True
+ assert welcome.use_color("never", Tty(), env={}) is False
+
+
+def test_no_color_wins_over_everything() -> None:
+ assert welcome.use_color("always", Tty(), env={"NO_COLOR": "1"}) is False
+ assert welcome.use_color("auto", Tty(), env={"NO_COLOR": "1"}) is False
+ assert welcome.use_color("auto", Tty(), env={"NO_COLOR": ""}) is True
+
+
+def test_show_color_off_a_tty_prints_no_escapes(capsys, monkeypatch) -> None:
+ monkeypatch.delenv("NO_COLOR", raising=False)
+ assert welcome.main(["show", "--family", "security", "--color"]) == 0
+ out = capsys.readouterr().out
+ assert "\033[" not in out
+ assert "Magpie here" in out
+ assert "**" not in out
+ assert '*"' not in out, "italic markers survive the terminal rendering"
+ assert "`" not in out
+
+
+def test_show_color_always_paints_unless_no_color(capsys, monkeypatch) -> None:
+ monkeypatch.delenv("NO_COLOR", raising=False)
+ welcome.main(["show", "--family", "security", "--color=always"])
+ assert "\033[" in capsys.readouterr().out
+ monkeypatch.setenv("NO_COLOR", "1")
+ welcome.main(["show", "--family", "security", "--color=always"])
+ assert "\033[" not in capsys.readouterr().out
+
+
+def test_show_without_color_prints_the_markdown(capsys) -> None:
+ welcome.main(["show", "--family", "security"])
+ assert capsys.readouterr().out == welcome.guide("security")
+
+
+# --- what ships -----------------------------------------------------------------------
+
+
+def test_every_guide_has_its_rules_section() -> None:
+ assert welcome.guides(), "no guides shipped"
+ for family in welcome.guides():
+ assert welcome.section(family) in sections.available()
+
+
+def test_the_guide_has_no_licence_header_and_stays_short() -> None:
+ text = welcome.guide("security") or ""
+ assert not text.startswith("<!--")
+ assert len(text.splitlines()) <= 70
+
+
+@pytest.mark.skipif(not (REPO_ROOT / "plugins").is_dir(), reason="needs the framework tree")
+def test_the_shipped_family_map_matches_the_framework_tree() -> None:
+ """The prek hook keeps this in sync; a failure means it was bypassed."""
+ from setup_preflight.families import SKILL_FAMILIES
+
+ assert welcome.scan_families(REPO_ROOT) == SKILL_FAMILIES
diff --git a/tools/skill-evals/README.md b/tools/skill-evals/README.md
index dc694472..133ac417 100644
--- a/tools/skill-evals/README.md
+++ b/tools/skill-evals/README.md
@@ -11,7 +11,7 @@ Behavioral eval harness for Apache Magpie skills. Each eval suite tests a skill
Suites are currently implemented for:
-- **setup** — 114 cases across 27 steps (step-verify-drift, step-overrides-surface, step-override-bypass, step-m3-baseline-pick, step-m4-install-gates, step-m5-no-repo-offer, step-m5-companion-offer, step-upgrade-companion-offer, step-adopt-settings-merge, verify-default-set, uninstall-default-set, lock-marketplace-parse, adopt-write-floor, setup-prefill-from-floor, preflight-floor, upgrade-adoption-split, verify-floor, adopt-review-process, adopt-security-list, step-reconcile, step-veri [...]
+- **setup** — 115 cases across 27 steps (step-verify-drift, step-overrides-surface, step-override-bypass, step-m3-baseline-pick, step-m4-install-gates, step-m5-no-repo-offer, step-m5-companion-offer, step-upgrade-companion-offer, step-adopt-settings-merge, verify-default-set, uninstall-default-set, lock-marketplace-parse, adopt-write-floor, setup-prefill-from-floor, preflight-floor, upgrade-adoption-split, verify-floor, adopt-review-process, adopt-security-list, step-reconcile, step-veri [...]
- **setup-isolated-setup-install** — 19 cases across 5 steps (runtime-routing, step-snapshot-drift, step-scope-confirm, step-hardware-key, step-roborev-exclusion)
- **setup-privacy-llm** — 6 cases across 2 steps (step-1-resolve, step-4-gate)
- **setup-shared-config-sync** — 12 cases across 2 steps (step-3-decide-action, step-5-draft-commit)
diff --git a/tools/skill-evals/evals/setup/README.md b/tools/skill-evals/evals/setup/README.md
index f89c540d..1d145e01 100644
--- a/tools/skill-evals/evals/setup/README.md
+++ b/tools/skill-evals/evals/setup/README.md
@@ -5,7 +5,7 @@
Behavioral evals for the `setup` skill.
-## Suites (114 cases total)
+## Suites (115 cases total)
| Suite | Step | Cases | What it covers |
|---|---|---|---|
@@ -25,7 +25,7 @@ Behavioral evals for the `setup` skill.
| adopt-review-process | adopt.md § Step 4c | 5 | a fresh adopt finding two deviations in the confirmed documents where one is accepted and one rejected, and a release policy left alone because that family is not in the floor; a re-adoption reviewing only the one family the floor diff added; a re-adoption that adds no family, where edited process documents are still not re-read; a sentence that would weaken a merge confirmation gate, dropped and named while a label deviation beside it is [...]
| adopt-security-list | adopt.md § Step 4b | 4 | an ASF project whose dedicated security list is in its docs and on the ASF page (recommend `security@`); an ASF project with no dedicated list (no recommendation, `private@` only as a flagged fallback); a non-ASF project, which is not asked; and conflicting evidence between `SECURITY.md` and the ASF page (no recommendation, flagged fallback) |
| setup-prefill-from-floor | install.md § Step M0b | 4 | adopted (propose the floor), unadopted (framework defaults), a foreign marketplace called out, and a snapshot lock falling through |
-| preflight-floor | preflight-block.md § Pre-flight | 8 | at floor (silent), below floor (update), plugin missing (install), foreign marketplace (ask first, run nothing), no `claude` CLI (print), unadopted (propose setup), `apache/magpie` in an alarming context (update anyway, unasked), unreadable `claude plugin list --json` (silent, treated as unknown not absent) |
+| preflight-floor | preflight-block.md § Pre-flight | 9 | at floor (silent), below floor (update), plugin missing (install), foreign marketplace (ask first, run nothing), no `claude` CLI (print), unadopted (propose setup), `apache/magpie` in an alarming context (update anyway, unasked), unreadable `claude plugin list --json` (silent, treated as unknown not absent), first security-family run (show the welcome guide, record it, carry on) |
| upgrade-adoption-split | upgrade.md § Step 0b | 4 | not adopted (nothing staged), adopted (floor raised and staged), already ahead (floor unchanged), snapshot method (falls through) |
| verify-floor | verify.md § Adoption floor | 4 | no lock (not a fault), ahead of floor with extra plugins (not a fault), a shortfall (a fault), a floor plugin the marketplace no longer ships (a fault, not installed around) |
| step-reconcile | reconcile.md § The sweep | 3 | a clean sweep on a pinned-snapshot install (anchor present, config resolved — stamp written, nothing proposed), a renamed step heading stranding an override's anchor (one re-anchor proposal named), a marketplace install whose plugin cache is sandbox-denied (anchor resolution left `unchecked`, config resolution still completes) |
diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-security-first-run/case-meta.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-security-first-run/case-meta.json
new file mode 100644
index 00000000..88c1f39a
--- /dev/null
+++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-security-first-run/case-meta.json
@@ -0,0 +1 @@
+{"tags":["local-smoke"]}
diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-security-first-run/expected.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-security-first-run/expected.json
new file mode 100644
index 00000000..2adc36df
--- /dev/null
+++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-security-first-run/expected.json
@@ -0,0 +1 @@
+{"action": "welcome", "commands": [], "blocks": false}
diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-security-first-run/report.md b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-security-first-run/report.md
new file mode 100644
index 00000000..56ee255f
--- /dev/null
+++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-security-first-run/report.md
@@ -0,0 +1,37 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+There is no `.apache-magpie.lock`, no `.apache-magpie-overrides/` and no
+`.apache-magpie-local/` at the repo root, and no personal layer at
+`.git/apache-magpie/` either. The running agent is Claude Code
+with magpie-setup 0.4.0 and magpie-security 0.4.0 installed.
+
+The invoked skill's own frontmatter reads `name: issue-sync` and
+`surface_hash: sha256:2edc90a1b7f3440d`; it declares no `requires_config:`.
+This is the first security-family skill this user has run here.
+The user asked it to "sync 123".
+
+The pre-flight command printed:
+
+```json
+{
+ "findings": [
+ {
+ "code": "welcome",
+ "facts": {
+ "family": "security",
+ "guide": "# \ud83d\udc26 Magpie here \u2014 your security-team sidekick\n\nA one-minute tour, then straight back to what you asked for.\n\n## \ud83d\udd04 The typical flow\n\n1. \ud83d\udce5 **Import** new reports from `<security-list>` \u2014 *\"import new reports\"*\n2. \ud83e\udded **Triage** \u2014 proposed dispositions for the team to agree on \u2014 *\"triage the open issues\"*\n3. \ud83d\udd01 **Sync** \u2014 keeps each tracker in step with its mail thread and fix PRs; the [...]
+ "max_shown": 3,
+ "reason": "first-run",
+ "shown": 0
+ },
+ "scope": "family",
+ "section": "welcome-security"
+ }
+ ],
+ "rules": {
+ "welcome-security": "## welcome-security \u2014 the security family's first-run guide\n\nA security-family skill is running for one of the first times for this user here,\nand the welcome guide is due (`facts.reason`: `first-run`, `again`, or `upgraded` after a dismissal).\n`facts.guide` is the guide.\n\n1. **Show `facts.guide` to the user verbatim**, as Markdown, before the work they asked for.\n Do not summarise, reword, trim, or add to it, and substitute nothing in it:\n its ` [...]
+ },
+ "verdict": "action"
+}
+```
diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-security-first-run/state.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-security-first-run/state.json
new file mode 100644
index 00000000..38f93908
--- /dev/null
+++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-security-first-run/state.json
@@ -0,0 +1,15 @@
+{
+ "lock": null,
+ "plugins": [
+ [
+ "magpie-setup",
+ "0.4.0"
+ ],
+ [
+ "magpie-security",
+ "0.4.0"
+ ]
+ ],
+ "skill": "issue-sync",
+ "welcome": true
+}
diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/output-spec.md b/tools/skill-evals/evals/setup/preflight-floor/fixtures/output-spec.md
index 619a261a..51d98042 100644
--- a/tools/skill-evals/evals/setup/preflight-floor/fixtures/output-spec.md
+++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/output-spec.md
@@ -7,7 +7,7 @@ Return ONLY valid JSON with this structure:
```json
{
- "action": "silent" | "install" | "update" | "print-command" | "ask-first" | "configure",
+ "action": "silent" | "install" | "update" | "print-command" | "ask-first" | "configure" | "welcome",
"commands": [...],
"commands_shown": [...],
"blocks": true | false,
@@ -27,6 +27,11 @@ unlike a plugin install, which needs a session restart before the new version
is live. Adoption is never run — at most it is mentioned once, which
`mention_adopt` reports.
+`welcome` means the only thing the pre-flight did was show the skill family's
+first-run welcome guide, offer its three choices and record the answer before
+carrying on. That one **does not block** either, and recording the answer is
+not an install command.
+
`commands` is the list of install/update commands the pre-flight actually
**runs**, in the order it runs them. Reading installed state — `claude plugin
list --json` or the running agent's equivalent — does not count; only commands
diff --git a/tools/spec-loop/specs/adoption-and-setup.md b/tools/spec-loop/specs/adoption-and-setup.md
index fdd8c58b..465f522b 100644
--- a/tools/spec-loop/specs/adoption-and-setup.md
+++ b/tools/spec-loop/specs/adoption-and-setup.md
@@ -669,6 +669,18 @@ committed version with drift detection.
*what to do next* list (`install.md` Steps 9c, 9d and 9e), including
Thunderbird's *Repair Folder* for a draft that does not show up (eval
suite `tools/skill-evals/evals/setup/step-config-mail`).
+36. `tools/setup-preflight` has a **family** scope: a `welcome` finding
+ (rules section `welcome-<family>`, guide in `facts.guide`) on a skill
+ whose family ships `setup_preflight/guides/<family>.md` — today only
+ `security`. The skill's family is looked up in `families.py`, generated
+ from frontmatter and kept current by `check-family-plugins`. The answer
+ is recorded under `welcome.<family>` in the personal layer's
+ `reconciled.json` by `python3 -m setup_preflight.welcome record`, never
+ by hand: `seen` shows again up to three recorded showings, `dismiss`
+ until the framework version changes, `never` until
+ `welcome enable` (the `setup welcome` sub-action). The guide never
+ blocks the requested work, is skipped where there is no personal layer,
+ and a layer holding only that record does not count as configured.
## Validation