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/19 20:47:03 UTC
(magpie) branch main updated: feat(setup): first-run welcome guide for the contributor-growth family (#1658) (#1702)
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 cb92631d feat(setup): first-run welcome guide for the contributor-growth family (#1658) (#1702)
cb92631d is described below
commit cb92631da8b1424c1abc2b5ceb2af095e8472e46
Author: Vardhman Gupta <11...@users.noreply.github.com>
AuthorDate: Tue Oct 20 02:16:58 2026 +0530
feat(setup): first-run welcome guide for the contributor-growth family (#1658) (#1702)
* feat(setup): first-run welcome guide for the contributor-growth family (#1658)
Adds a concise first-run welcome guide for the contributor-growth skill family (activity-sweep, calibrate, candidate-screen, committer-onboarding, contributor-to-committer, identity-map, nomination, onboarding-concierge, and sentiment), following the pattern established in #1653 and #1663.
- Adds plugins/magpie-setup/skills/setup/setup_preflight/guides/contributor-growth.md
- Highlights typical flow across 7 steps and notes private list / calibrated thresholds
- Links the guide from docs/contributor-growth/README.md under Install & first runs
- Adds case-11-contributor-growth-first-run preflight-floor fixture and updates case-9
- Expands test_welcome.py test coverage and updates total eval case counts
* docs(setup): name the contributor-growth config files; test the next run
The guide's "Configure it" section described private-list access and
thresholds without naming a file to configure. It now names the file
each skill reads (`committer-readiness.md`, `contributor-nomination-config.md`,
the onboarding and sentiment configs, and `privacy-llm.md` for the
private-list reads), and says `setup config` configures rather than
"personal install".
Every other family guide has a test that the family's skills resolve to
it and that it follows the general guide on the next run; this family
now has one too. The case-11 fixture that embeds the guide is
re-rendered.
Generated-by: Claude Opus 5
---------
Co-authored-by: Jarek Potiuk <po...@apache.org>
---
docs/contributor-growth/README.md | 6 +++
.../setup_preflight/guides/contributor-growth.md | 57 ++++++++++++++++++++++
tools/setup-preflight/tests/test_welcome.py | 51 +++++++++++++++++--
tools/skill-evals/README.md | 2 +-
tools/skill-evals/evals/setup/README.md | 4 +-
.../case-meta.json | 1 +
.../expected.json | 1 +
.../case-15-contributor-growth-first-run/report.md | 37 ++++++++++++++
.../state.json | 24 +++++++++
.../fixtures/case-9-first-magpie-run/report.md | 2 +-
10 files changed, 176 insertions(+), 9 deletions(-)
diff --git a/docs/contributor-growth/README.md b/docs/contributor-growth/README.md
index 0910fe23..7fac5a8c 100644
--- a/docs/contributor-growth/README.md
+++ b/docs/contributor-growth/README.md
@@ -85,6 +85,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 contributor-growth skill you run opens with a one-minute
+[welcome guide](../../plugins/magpie-setup/skills/setup/setup_preflight/guides/contributor-growth.md):
+the typical flow, what needs configuring, what to ask it, and how to make it yours.
+Dismiss it, or hide it for good, from its last line;
+*"show the contributor-growth welcome again"* or `/magpie-setup:welcome-guide contributor-growth` brings it back.
+
### Before the first run
<!-- BEGIN generated: skill-config (tools/dev/check-skill-config.py --fix) -->
diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/guides/contributor-growth.md b/plugins/magpie-setup/skills/setup/setup_preflight/guides/contributor-growth.md
new file mode 100644
index 00000000..076d885d
--- /dev/null
+++ b/plugins/magpie-setup/skills/setup/setup_preflight/guides/contributor-growth.md
@@ -0,0 +1,57 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# ๐ฆ Magpie here โ your contributor-growth sidekick
+
+A one-minute tour, then straight back to what you asked for.
+
+## ๐ The typical flow
+
+1. ๐ **Activity sweep** across code, reviews, and issues โ *"sweep activity for <handle>"*
+2. ๐ชช **Identity map** across GitHub, mailing lists, and chat handles โ *"map identities for <handle>"*
+3. ๐ **Compare activity with reference levels** as plain numbers โ *"track <handle>'s path to committer"*
+4. ๐ **Nomination brief** compiling evidence for a private list discussion โ *"build nomination brief for <handle>"*
+5. ๐ **Candidate screen** across recent contributors without ranking โ *"screen contributor candidates"*
+6. ๐ค **Committer onboarding** walkthrough for ICLA and account setup โ *"onboard new committer <handle>"*
+7. ๐ฌ **Sentiment check** to identify contributor friction or disengagement โ *"check contributor sentiment"*
+
+Nothing is ranked, decided, or posted without your OK.
+
+## โ๏ธ Configure it
+
+Each skill reads `project.md`, plus the file for its own job:
+
+- ๐ **Reference levels** โ `committer-readiness.md` for the path-to-committer comparison, calibration and candidate screen; information only, never a readiness verdict
+- ๐ **Nominations** โ `contributor-nomination-config.md` for briefs, calibration and screening
+- ๐ **Private governance** โ calibration reads past votes on `<private-list>`, so it also needs an approved model in `privacy-llm.md`; nothing from it reaches a public surface
+- ๐ค **Onboarding and sentiment** โ `committer-onboarding-config.md`, `onboarding-concierge-config.md` and `contributor-sentiment-config.md`
+
+Configure it for yourself with `/magpie-setup:setup config`.
+Project adoption with `/magpie-setup:setup adopt` is a maintainer decision.
+
+## ๐ฌ Just ask
+
+Talk to Magpie in plain language:
+
+- *"sweep activity for <handle> over the last 6 months"*
+- *"map identities for <handle>"*
+- *"how does <handle>'s activity compare with reference levels?"*
+- *"assemble a nomination brief for <handle>"*
+- *"calibrate committer reference levels from past nominations"*
+- *"screen active contributors for mentoring candidates"*
+- *"guide a newcomer through first-time contributor onboarding"*
+- *"guide committer onboarding for <handle>"*
+- *"are contributors encountering friction in PR reviews?"*
+
+## ๐จ Make it yours
+
+Every workflow, threshold, and community policy can be tailored.
+Describe what your project needs:
+
+- *"evaluate activity across 12 months rather than 6"*
+- *"tune committer onboarding steps for our project"*
+
+Your requests save as local skill overrides.
+Think an adjustment benefits other projects? Asking *"Upstream this change to Magpie"* prepares a contribution PR for review.
+
+<!-- welcome footer: generated from guides/_footer.md -->
diff --git a/tools/setup-preflight/tests/test_welcome.py b/tools/setup-preflight/tests/test_welcome.py
index 051310a2..5bcb3981 100644
--- a/tools/setup-preflight/tests/test_welcome.py
+++ b/tools/setup-preflight/tests/test_welcome.py
@@ -144,6 +144,27 @@ def test_the_pr_management_family_guide_comes_on_the_next_run(project: Path, ver
assert due(project, "pr-triage") == [("general", "again")]
+def test_the_contributor_growth_family_guide_comes_on_the_next_run(project: Path, version) -> None:
+ for skill in (
+ "activity-sweep",
+ "calibrate",
+ "candidate-screen",
+ "committer-onboarding",
+ "contributor-to-committer",
+ "identity-map",
+ "nomination",
+ "onboarding-concierge",
+ "sentiment",
+ ):
+ assert welcome.family_of(skill) == "contributor-growth"
+
+ assert due(project, "activity-sweep") == [("general", "first-run")]
+ welcome.record(project, "general", "seen")
+ assert due(project, "activity-sweep") == [("contributor-growth", "first-run")]
+ welcome.record(project, "contributor-growth", "seen")
+ assert due(project, "activity-sweep") == [("general", "again")]
+
+
def test_at_most_one_guide_per_run(project: Path, version) -> None:
for _ in range(8):
found = welcome_findings(project, SECURITY_SKILL)
@@ -441,14 +462,31 @@ def test_show_without_color_prints_the_markdown(capsys) -> None:
def test_the_rules_section_and_all_guides_ship() -> None:
assert welcome.SECTION in sections.available()
- assert {"general", "security", "utilities", "mentoring", "pairing", "issue", "pr-management"} <= set(
- welcome.guides()
- )
+ assert {
+ "general",
+ "security",
+ "utilities",
+ "mentoring",
+ "pairing",
+ "issue",
+ "pr-management",
+ "contributor-growth",
+ } <= set(welcome.guides())
assert welcome.family_guides() == [g for g in welcome.guides() if g != "general"]
@pytest.mark.parametrize(
- "name", ["general", "security", "utilities", "mentoring", "pairing", "issue", "pr-management"]
+ "name",
+ [
+ "general",
+ "security",
+ "utilities",
+ "mentoring",
+ "pairing",
+ "issue",
+ "pr-management",
+ "contributor-growth",
+ ],
)
def test_each_guide_is_short_and_ends_with_the_way_back(name: str) -> None:
text = welcome.guide(name) or ""
@@ -475,7 +513,8 @@ def test_the_footer_is_shared_and_filled_in_per_guide() -> None:
pairing = welcome.guide("pairing") or ""
issue = welcome.guide("issue") or ""
pr_management = welcome.guide("pr-management") or ""
- for text in (security, general, utilities, mentoring, pairing, issue, pr_management):
+ contributor_growth = welcome.guide("contributor-growth") or ""
+ for text in (security, general, utilities, mentoring, pairing, issue, pr_management, contributor_growth):
assert "{{" not in text
assert "welcome footer: generated" not in text
assert "`/magpie-setup:welcome-guide security`" in security
@@ -492,6 +531,8 @@ def test_the_footer_is_shared_and_filled_in_per_guide() -> None:
assert "--family issue --color=always" in issue
assert "`/magpie-setup:welcome-guide pr-management`" in pr_management
assert "--family pr-management --color=always" in pr_management
+ assert "`/magpie-setup:welcome-guide contributor-growth`" in contributor_growth
+ assert "--family contributor-growth --color=always" in contributor_growth
def test_list_prints_every_guide(capsys) -> None:
diff --git a/tools/skill-evals/README.md b/tools/skill-evals/README.md
index b57a9909..a10b9168 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** โ 134 cases across 30 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** โ 135 cases across 30 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 e91f703c..fd0369db 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 (134 cases total)
+## Suites (135 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 | 14 | 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 Magpie run (show the general welcome guide, record it, carry on), first utilities run (show the utilities welcome gui [...]
+| preflight-floor | preflight-block.md ยง Pre-flight | 15 | 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 Magpie run (show the general welcome guide, record it, carry on), first utilities run (show the utilities welcome gui [...]
| 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-15-contributor-growth-first-run/case-meta.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-15-contributor-growth-first-run/case-meta.json
new file mode 100644
index 00000000..88c1f39a
--- /dev/null
+++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-15-contributor-growth-first-run/case-meta.json
@@ -0,0 +1 @@
+{"tags":["local-smoke"]}
diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-15-contributor-growth-first-run/expected.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-15-contributor-growth-first-run/expected.json
new file mode 100644
index 00000000..2adc36df
--- /dev/null
+++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-15-contributor-growth-first-run/expected.json
@@ -0,0 +1 @@
+{"action": "welcome", "commands": [], "blocks": false}
diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-15-contributor-growth-first-run/report.md b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-15-contributor-growth-first-run/report.md
new file mode 100644
index 00000000..313d1cb9
--- /dev/null
+++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-15-contributor-growth-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. The running agent is Claude Code
+with magpie-setup 0.4.0 and magpie-contributor-growth 0.4.0 installed.
+
+The user has already seen the initial general welcome guide on an earlier run.
+The invoked skill's own frontmatter reads `name: contributor-to-committer` and
+`surface_hash: sha256:bdf92c88a304ddea`; it belongs to the contributor-growth family.
+This is the first time a contributor-growth skill has run here.
+The user asked it to "track path to committer".
+
+The pre-flight command printed:
+
+```json
+{
+ "findings": [
+ {
+ "code": "welcome",
+ "facts": {
+ "family": "contributor-growth",
+ "guide": "# \ud83d\udc26 Magpie here \u2014 your contributor-growth sidekick\n\nA one-minute tour, then straight back to what you asked for.\n\n## \ud83d\udd04 The typical flow\n\n1. \ud83d\udcca **Activity sweep** across code, reviews, and issues \u2014 *\"sweep activity for <handle>\"*\n2. \ud83e\udeaa **Identity map** across GitHub, mailing lists, and chat handles \u2014 *\"map identities for <handle>\"*\n3. \ud83d\udcc8 **Compare activity with reference levels** as plain numb [...]
+ "max_shown": 3,
+ "reason": "first-run",
+ "shown": 0
+ },
+ "scope": "family",
+ "section": "welcome"
+ }
+ ],
+ "rules": {
+ "welcome": "## welcome \u2014 a first-run welcome guide is due\n\nA welcome guide is due on this run: `facts.family` names it\n(`general`, for the first Magpie skill this user runs here, or the skill's own family),\nand `facts.reason` says why (`first-run`, `again`, or `upgraded` after a dismissal).\n`facts.guide` is the guide. The checker shows at most one guide per run and has already picked it.\n\n1. **Show `facts.guide` to the user verbatim**, as Markdown, before the work they as [...]
+ },
+ "verdict": "action"
+}
+```
diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-15-contributor-growth-first-run/state.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-15-contributor-growth-first-run/state.json
new file mode 100644
index 00000000..1f207cf5
--- /dev/null
+++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-15-contributor-growth-first-run/state.json
@@ -0,0 +1,24 @@
+{
+ "hash": "sha256:bdf92c88a304ddea",
+ "lock": null,
+ "plugins": [
+ [
+ "magpie-setup",
+ "0.4.0"
+ ],
+ [
+ "magpie-contributor-growth",
+ "0.4.0"
+ ]
+ ],
+ "reconciled": {
+ "welcome": {
+ "general": {
+ "choice": "seen",
+ "shown": 1
+ }
+ }
+ },
+ "skill": "contributor-to-committer",
+ "welcome": true
+}
diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-first-magpie-run/report.md b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-first-magpie-run/report.md
index 74e45747..5fb8803d 100644
--- a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-first-magpie-run/report.md
+++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-first-magpie-run/report.md
@@ -20,7 +20,7 @@ The pre-flight command printed:
"code": "welcome",
"facts": {
"family": "general",
- "guide": "# \ud83d\udc26 Hello from Magpie \u2014 your project's maintainer sidekick\n\nOne minute, then straight back to what you asked for.\n\n## \ud83d\ude80 Getting started\n\n- \ud83d\udce6 **Install** from your agent's marketplace (Claude Code shown):\n `/plugin marketplace add apache/magpie`,\n then `/plugin install magpie-setup@apache-magpie` and one `/plugin install magpie-<family>@apache-magpie` per family you want\n- \ud83d\ude4b **Configure it for yourself** \u2014 [...]
+ "guide": "# \ud83d\udc26 Hello from Magpie \u2014 your project's maintainer sidekick\n\nOne minute, then straight back to what you asked for.\n\n## \ud83d\ude80 Getting started\n\n- \ud83d\udce6 **Install** from your agent's marketplace (Claude Code shown):\n `/plugin marketplace add apache/magpie`,\n then `/plugin install magpie-setup@apache-magpie` and one `/plugin install magpie-<family>@apache-magpie` per family you want\n- \ud83d\ude4b **Configure it for yourself** \u2014 [...]
"max_shown": 3,
"reason": "first-run",
"shown": 0