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 gitignored files, and it stages nothing.
Every skill here resolves project-specific values from the adopter‘s <project-config>/ directory — which is .apache-magpie-local/ (gitignored, yours) first, 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 readiness tracker that maps a contributor‘s GitHub activity against the adopter’s declared committer/PMC thresholds; surfaces a traffic-light brief (Not yet / Approaching / Ready to nominate) plus the specific evidence gaps that remain. (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 readiness-tracking skill. Takes a GitHub handle, fetches their public activity on <upstream>, and maps it against the adopter's declared committer or PMC thresholds from committer-readiness.md. Returns a traffic-light verdict (Not yet / Approaching / Ready to nominate) plus a gap table showing exactly what evidence the contributor still needs. 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). Complements good-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.