[potiuk]

Summary

• First-time users (feedback from the Community Over Code hackathon) had no overview of how to start, of install versus adopt, or of the fact that they can just ask in plain language. Magpie now shows short welcome guides, then carries on with the task.
• General guide, shown the first time any Magpie skill runs: install, configure for yourself or adopt for the project, update by hand or turn on automatic plugin updates, just ask (nothing happens without your OK), and "you are the creator": describe what a skill should do and it becomes an override; "upstream this change to Magpie" makes it generic and opens a PR. It lists the family guides available.
• Security guide, shown on a later run of a security skill: the typical flow (import → triage → sync → CVE → fix → announce), one example request per step. At most one guide per run, the general one first.
• Both come from the existing pre-flight checker as a welcome finding, so no SKILL.md pre-flight block changes. Continue shows a guide again (three times at most), Dismiss hides it until the next upgrade, Don't show again hides it until turned back on. The choice lives in the personal layer's reconciled.json.
• New /magpie-setup:welcome-guide [<family>] skill shows any guide on demand and turns a hidden one back on (named welcome-guide because welcome is the mentoring family's skill); every guide ends by naming it. --color prints a coloured terminal version.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Python package (tools/*/ with pyproject.toml)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• CI / dev loop (prek, workflows, validators)

Test plan

• tools/setup-preflight: pytest (33 new welcome tests: first run, non-security skill, each choice, three-showings limit, dismiss lifted by an upgrade, enable, record merging into reconciled.json, --color with NO_COLOR and non-tty), mypy
• tools/dev: the skill-to-family map is generated from frontmatter; check-family-plugins reports a stale map and --fix regenerates it
• Eval setup/preflight-floor case 9 (first Magpie run shows the general guide); new suite setup-welcome-guide/step-1-show (no argument, a known family, an unknown name); render-preflight-fixtures --check clean
• Precedence tests: never more than one guide per run; general first; a hidden general guide does not hold back a family guide
• check-doc-sync (80 skills), check-shared-blocks, check-duplication (shared footer in guides/_footer.md)
• skill-evals pytest; skill-surface-hash and skill-token-count restamped for the setup skill only; typos clean
• prek run --all-files — left to CI (prepared outside a checkout)

RFC-AI-0004 compliance

• HITL — the guide never blocks the requested work, and nothing is written except the user's choice
• Vendor neutrality — placeholders only in the guide
• Conversational + correctable — the guide itself points users at overrides and upstreaming

Linked issues

Notes for reviewers (optional)

• A dismissal is tied to the magpie-setup plugin version; on a marketplace install, whose personal-layer checker copy has no manifest, it falls back to a fingerprint of the package, which upgrade refreshes.
• A personal layer holding only the welcome record does not count as "configured", so a never-configured project is not pushed into the reconciliation sweep.

---

Generative AI disclosure: prepared with Claude Code (Claude Opus 5); reviewed by the author.

🤖 Generated with Claude Code