Skip to content

README.md

Latest commit

 

History

History
231 lines (175 loc) · 14.3 KB

README.md

File metadata and controls

231 lines (175 loc) · 14.3 KB
Raw

Table of Contents generated with DocToc

PR management skill family

Scope. Works on any project, ASF or not — no Apache-Software-Foundation-specific assumptions baked in.

Maintainer-facing PR-queue management for projects with a public contributor PR queue. Nine skills that compose into a complete triage + review + mentoring + hygiene pass:

  1. Agentic Triage — sweep open PRs, classify against the project's quality criteria, propose a disposition (draft / comment / close / rebase / rerun / mark ready / ping), execute on maintainer confirmation.
  2. Stats — read-only summary tables of the open PR backlog, grouped by area label, so the maintainer can see where queue pressure is sitting before / after a triage sweep.
  3. Code review — deep, line-aware code review one PR at a time. Reads the diff, applies the project's review criteria, drafts an APPROVE / REQUEST_CHANGES / COMMENT review with inline comments, posts on confirmation.
  4. Quick-merge — express-lane screener for trivial, low-risk PRs (docs, changelog, translations, tests) that pass every quality gate; surfaces ranked candidates with diff summaries and the exact merge command for the maintainer to run. Never merges itself — automated merge is the framework's deliberately-deferred Agentic Autonomous mode.
  5. Mentor — joins a PR (or issue) thread in a teaching register: clarifying questions, pointers to project conventions and docs, an explanation of why a change is being asked for. Waits for explicit maintainer confirmation before posting; never gatekeeps. Lives in the Mentoring mode but operates on the same PR surface as skills 1–4.
  6. Stale-sweep — identify open PRs past a configurable inactivity threshold, classify as NUDGE or CLOSE-STALE, post one comment per PR on maintainer confirmation.
  7. Pre-first-PR check — pre-flight a contributor's first PR against project conventions before it reaches a human reviewer; surfaces formatting, test, and documentation gaps.
  8. Reviewer routing — suggest the best-fit reviewer(s) for a new PR based on path ownership, recent review history, and current load.
  9. Stack review — review a GitHub stacked pull request as one unit: chain currency, file-by-layer matrix, removed-definition seams, narrative drift, and code read by tier with a coverage table. Drafts one rolling COMMENT on the lowest open layer and names the layers that deserve a code-review pass. Never approves.

Why a framework skill family? These skills were originally maintained inside one ASF project's developer-tooling repo as breeze pr auto-triage and breeze pr stats — useful for any ASF project with a meaningful contributor-PR queue, but locked behind that project's local toolchain. Lifting them into the framework lets other adopters reuse the playbook with their own adopter-config files for project-specific knobs (committers team handle, area-label prefix, comment-template wording, CI-check → doc-URL map, review-criteria source files).

Tip

Why this family

  • A maintainer's review queue, sorted by what actually needs you today
  • Deep, sequential review of one PR at a time, with the draft review shown before it is posted
  • Nothing is posted, merged or closed without your explicit confirmation on that PR

Install & first runs

Install just this family — one plugin, 9 skills. Maintainer-facing PR-queue management.

Once you have added the marketplace:

/plugin install magpie-pr-management@apache-magpie

New to Magpie? The quick start 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.

Before the first run

An animated /magpie-setup:setup config run for the pr-management family: the check failing, the values derived from the repository, one question for the rest, and personal files written

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:setup config scaffolds and fills these locally (/magpie-setup config on a pinned-snapshot install). Nothing is staged, nothing is committed, and it works on a repository that has never adopted Magpie.

For the project: /magpie-setup: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
mentoring-config.md Tone knobs and hand-off protocol for the thread-level mentoring skill. mentor
pr-management-code-review-criteria.md List of project's review-criteria source files (repo-wide AGENTS.md, code-review docs, per-area AGENTS.md), security-model calibration doc, backport-branch pattern, section-anchor URLs. code-review, stack-review
pr-management-config.md Committers team handle, area-label prefix, project-specific labels (ready for maintainer review, etc.), grace windows. pr-stale-sweep, pr-triage, quick-merge, stats
pr-management-quick-merge-config.md Thresholds, path globs, and the merge-command template for the express lane. quick-merge
pr-management-triage-comment-templates.md Comment-body URLs (PR quality criteria, two-stage triage rationale), AI-attribution footer wording, project display name. pr-triage
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. code-review, mentor, pr-stale-sweep, pr-triage, pre-first-pr-check, quick-merge, reviewer-routing, stack-review
reviewer-roster.md Who reviews what. reviewer-routing

Optional. Each has a documented fallback; absent, the skill still runs.

File What it carries Read by
pr-management-triage-ci-check-map.md CI-check name pattern → category name + doc-URL mapping for the violations comment. pr-triage
privacy-llm.md Which model tier may see which class of content, for projects routing foundation-private information away from third-party models. pr-triage, reviewer-routing
release-trains.md Active release branches, release-manager attribution per cut, rotation rosters, security-team roster. reviewer-routing
stale-sweep-config.md Grace windows and exemption labels for stale sweeps. Absent, the framework defaults apply. pr-stale-sweep

Works well with

Third-party packages, none of them required: this family works with none of them installed, and Magpie neither bundles nor depends on any. They are named because they are what a maintainer goes looking for next, and because the answer differs by agent.

Code Review — Anthropic

Automated pull-request review through several specialised agents, scored by confidence.

With this family: pr-management-code-review walks a maintainer through reviewing one PR at a time and drafts the review they post. This is the other half — a broad automated pass whose findings that review can weigh.

Available on Claude Code only.

roborev — Kenn Software (community, MIT)

A local CLI and daemon that reviews every commit in the background with the coding agent you already use, and feeds the findings back for a fix-and-re-review loop before you push.

With this family: pr-management-code-review reviews other people's PRs; roborev reviews your own branch before it becomes one, so the PRs you open arrive with the mechanical findings already fixed.

Available on Claude Code, OpenAI Codex CLI, VS Code / GitHub Copilot, Google Gemini CLI, Cursor.

On Claude Code under Magpie's secure agent setup, roborev cannot read ~/.roborev/ and fails on every call; Step B of setup-isolated-setup-install wires the exclusion and the prompt that keep it safe outside the sandbox, and Step B.2 optionally lets its post-commit hook review the agent's own commits. Without Homebrew, see https://roborev.io/docs/installation/ for the other installers.

Install commands per agent are in Companion skill packages.

Try these first

Illustrative shapes, not real transcripts — your output will differ. Nothing below sends, merges, or posts anything without you confirming it.

Review a PR in depth.

> review PR #5193

  PR #5193  'Add retry to the S3 client'  +212 -18, 6 files
  2 blocking:   retry loop swallows KeyboardInterrupt (client.py:88)
                no test for the exhausted-retries path
  3 non-blocking nits. Review comment drafted, not posted.

Triage the whole queue.

/magpie-pr-management:pr-triage

A triage run proposing one action each for four PRs — mark ready, ask if still active, ask for a rebase, promote out of draft — each needing confirmation

See where the queue is stuck.

/magpie-pr-management:stats

A stats run: a FAIR health rating, this week's and last week's open/close counts, the three areas under most pressure, and the triage funnel

Skills

Skill Purpose
pr-management-triage First-pass triage. Successor to breeze pr auto-triage.
pr-management-stats Read-only summary tables grouped by area label.
pr-management-code-review Deep code review, one PR at a time.
pr-management-quick-merge Express-lane screener for trivial, low-risk PRs in the ready for maintainer review queue; surfaces ranked candidates with diff summaries and the exact merge command. Read-only on the queue; the one optional mutation (APPROVE) requires explicit per-PR confirmation.
pr-management-mentor Draft a teaching-register comment on a single GitHub issue or PR thread (clarifying questions, project-convention pointers, rationale explanations); waits for explicit maintainer confirmation before posting. mode: Mentoring — see also docs/mentoring/README.md.
pr-stale-sweep Sweep open PRs for inactivity past a configurable threshold; classify as NUDGE or CLOSE-STALE and post one comment per PR on confirmation.
pre-first-pr-check Pre-flight a contributor's first PR against project conventions before it reaches a human reviewer.
reviewer-routing Suggest the best-fit reviewer(s) for a new PR based on path ownership, recent review history, and current load.
pr-management-stack-review Review a GitHub stacked pull request as one unit — chain, file-by-layer matrix, removed-definition seams, narrative drift, code by tier with a coverage table. One rolling COMMENT on the lowest open layer; never approves; hands each layer to pr-management-code-review.

Cross-references