Table of Contents generated with DocToc
Scope. Works on any project, ASF or not — no Apache-Software-Foundation-specific assumptions baked in.
Maintainer-facing skills that join contributor threads in a teaching
register, author newcomer-ready issues, curate the existing backlog for
newcomers, orient first-time contributors, explain issue context to
newcomers, and track a contributor's readiness path to committer nomination.
Six skills shipped at experimental.
MISSION names Agentic Mentoring as the highest-value project-side mode and the one off-the-shelf agent tooling skips. The framework lands the spec — tone guide, hand-off protocol, adopter contract — and the skill implementations together, so the project's tone choices are reviewable independently of runtime behaviour and can be evolved without editing the skill body.
Tip
Why this family
- First-time contributors get a real welcome that names what their PR changed, not a template
- An issue explained to a newcomer in a teaching register — what breaks, where, and how to check
- Good first issues that are actually finishable, and the ones that only need a sentence to become so
Install just this family — one plugin, 4 skills. Newcomer-facing mentoring — welcome, explain, and curate first issues.
Once you have added the marketplace:
/plugin install magpie-mentoring@apache-magpie
New to Magpie? The quick start walks the whole path in
one place — install, the first /magpie-setup run, and a recording of it
happening — plus the other agents and the secure-isolation setup to run next.
Illustrative — the real run derives more and asks better. What is true is the shape: it runs itself, it writes only your personal layer, and it stages nothing.
Every skill here resolves project-specific values from the adopter's
<project-config>/ directory — which is
your personal layer first — .apache-magpie-local/ (gitignored) in a
project that adopted Magpie, <git-common-dir>/apache-magpie/ in one
that did not — then .apache-magpie-overrides/ (committed, the project's).
For yourself: /magpie-setup config scaffolds and fills these locally.
Nothing is staged, nothing is committed, and it works on a repository that
has never adopted Magpie.
For the project: /magpie-setup adopt
commits them for every contributor, either scaffolded directly or promoted
from what you configured locally.
Required. Without these a skill would act on a guess, so it stops and says which file is missing.
| File | What it carries | Read by |
|---|---|---|
good-first-issue-config.md |
What counts as a good first issue here: labels, size limits, and the areas safe to hand to a newcomer. | good-first-issue-author, good-first-issue-sweep |
issue-tracker-config.md |
Tracker URL, project key, auth model, default query templates. | good-first-issue-author, good-first-issue-sweep |
project.md |
Project manifest. Identity, repositories, mailing lists, tools enabled, CVE tooling, GitHub project-board + issue-template field declarations. The single file every skill reads to resolve project-scoped references. | good-first-issue-author, good-first-issue-sweep, newcomer-issue-explainer, welcome |
Optional. Each has a documented fallback; absent, the skill still runs.
| File | What it carries | Read by |
|---|---|---|
mentoring-welcome-config.md |
Wording and triggers for first-time-contributor welcomes. | welcome |
newcomer-issue-explainer-config.md |
How much context an explanation carries, and the register it is written in. | newcomer-issue-explainer |
Illustrative shapes, not real transcripts — your output will differ. Nothing below sends, merges, or posts anything without you confirming it.
Welcome a first-time contributor.
/magpie-mentoring:welcome
Curate the good-first-issue backlog.
/magpie-mentoring:good-first-issue-sweep
Explain an issue to a newcomer.
/magpie-mentoring:newcomer-issue-explainer
| Skill | Purpose | Status |
|---|---|---|
pr-management-mentor |
Draft a teaching-register comment on a single GitHub issue or PR thread; waits for maintainer confirmation before posting. | experimental |
good-first-issue-author |
Draft one net-new good first issue from a supplied gap or small task; a suitability gate and R1–R9 readiness checklist gate the draft; waits for maintainer confirmation before filing via gh. |
experimental |
mentoring-welcome |
Draft a first-contact orientation comment for a first-time contributor on a newly opened issue or PR; detects first-time authorship via the GitHub author_association field; skips repeat contributors. |
experimental |
newcomer-issue-explainer |
Explain a single issue's context, relevant code paths, and expected approach to a newcomer who has claimed it; teaching register, never gatekeeps. | experimental |
good-first-issue-sweep |
Sweep the open issue backlog for existing issues that could be labelled as good first issues; scores each against the G1–G7 suitability rubric and classifies as READY / NEAR-MISS / SKIP; proposes labels only after explicit maintainer confirmation. | experimental |
contributor-to-committer |
Read-only brief showing a contributor's GitHub activity next to the adopter's committer/PMC reference levels as plain numbers with the difference; surfaces information only — no ranking, status, or readiness verdict, the PMC decides. (family: contributor-growth — cross-listed here for the mentoring path continuity.) |
experimental |
All six skills are read-only on tracker state or draft-then-confirm: no skill posts, labels, closes, or files anything without explicit maintainer confirmation in-session.
pr-management-mentor— the thread-level Agentic Mentoring skill. Reads an issue or PR thread, decides whether a teaching-register intervention is warranted (clarifying question, convention pointer, paired example from a prior PR), drafts the comment, and waits for maintainer confirmation before posting. Never reviews code, routes PRs, or authors fixes — those are Agentic Triage and Agentic Drafting respectively.good-first-issue-author— the issue on-ramp skill. Takes a maintainer- supplied gap or small task, applies a suitability gate (too large, security- sensitive, or requiring a design decision → decline), runs through R1–R9 readiness criteria, and drafts one self-contained issue a newcomer can pick up without prior repo context: scope, code pointers, contributing-doc links, acceptance criteria, and a rough effort estimate.mentoring-welcome— the first-contact skill. Triggered immediately after a first-time contributor opens an issue or PR. Drafts a lightweight orientation comment (contributing-guide link, community-norm pointers, expected next steps). Skips silently for repeat contributors and security-sensitive threads.newcomer-issue-explainer— the issue-context skill. When a newcomer claims a good-first-issue, explains the relevant code paths, project context, and expected approach in a teaching register.contributor-to-committer— the activity-brief skill. Takes a GitHub handle, fetches their public activity on<upstream>, and shows it next to the adopter's committer or PMC reference levels fromcommitter-readiness.md, as plain numbers with the difference. It only surfaces information: no status, band, ranking, or readiness verdict — the PMC decides. Read-only; never opens a nomination thread, sends a message, or modifies any record.good-first-issue-sweep— the backlog-curation skill. Sweeps the open issue backlog and scores each issue against the G1–G7 suitability rubric (scope, self-containment, code pointer, small effort, no security sensitivity, no architectural decision, no deprecation decision). Classifies each as READY (propose the GFI label), NEAR-MISS (surface specific edits that would make it GFI-ready), or SKIP (not suitable). Complementsgood-first-issue-author: the sweep stocks the on-ramp queue from existing work; the author creates net-new issues from supplied gaps. Read-only; proposes labels only after explicit maintainer confirmation.
The generated table under Before the first run lists every file these skills read. The spec's adopter-contract section documents the keys inside each one.
Experimental. Six skills shipped. No adopter has run the full contributor-to-committer interaction path under evaluation conditions yet; shape may change between framework versions.
To provide pilot feedback, copy
docs/pilot-report-template.md into your
project notes, fill in each section, and optionally validate the filled-in
report with:
uv run --project tools/pilot-report-validator pilot-report-validate <your-report.md>MISSION.md§ Agentic Mentoring — mode definition, contributor-empowerment framing.docs/modes.md§ Mentoring — current implementation status.spec.md— full Agentic Mentoring spec: tone guide, hand-off protocol, adopter contract.projects/_template/README.md— adopter scaffold index.docs/setup/agentic-overrides.md— the override mechanism every skill in this family supports.