Adopt Apache Magpie (agent-assisted maintainer workflows) + JMeter config

[milamberspace]

What

Adopts the Apache Magpie framework of
agent skills into JMeter, plus the JMeter-specific configuration, so
maintainers can run structured, auditable workflows (PR triage, issue
triage, stats dashboards, security-issue and release helpers) from their
own AI coding agent.

Draft / for discussion. Opened against my fork's trunk so the diff
and committed footprint are reviewable. It is not proposed to
apache/jmeter yet — see the dev@ DISCUSS thread.
Nothing is merged or run automatically.

Committed footprint (the important part)

19 files. The split:

• ~485 lines of JMeter-specific config + wiring: project.md, the
  pr-management-* config, .gitignore, a short README section, two
  relay symlinks, .apache-magpie.lock.
• The one committed magpie-setup bootstrap skill (~4.7k lines of
  Markdown docs, not code) — required so a fresh clone can re-fetch the
  framework.
• Not committed: the other 68 skills. They live in a gitignored
  snapshot (.apache-magpie/), fetched on demand. They never land in
  git and never sit in the agent's context window (skills load on demand;
  only a one-line description per skill is indexed).

Full removal is a single command: /magpie-setup unadopt.

What's wired for JMeter

• Families enabled: pr-management, issue, security. release-*
  is intentionally not wired yet.
• Config adapted to JMeter reality: no area:* labels (area grouping
  disabled), no GitHub security tracker / Projects board (those panels are
  N/A), real CI-check names mapped (Validation, Error Prone, the JDK ×
  vendor × OS test matrix), longer grace windows for our slow triage
  cadence.
• Backends: GitHub Issues, dev@/private@ via the ASF PonyMail
  archive, ASF Vulnogram CVE tooling.

How it stays low-risk

• Human-in-the-loop: every skill only proposes; a human confirms
  before any comment, label, merge, or commit. No bots posting on their
  own, no CI automation.
• Local & credential-scoped: runs in each maintainer's own agent under
  their own credentials. No shared service; no project data leaves the
  maintainer's control.
• Deterministic guardrails: a PreToolUse hook blocks premature
  "ready", maintainer pings, and Co-Authored-By trailers. The hook is
  wired into the gitignored, per-machine .claude/settings.local.json by
  /magpie-setup (nothing hook-related is committed — see
  setup: write the agent-guard hook to gitignored settings.local.json instead of committing it to settings.json apache/magpie#824).

Example output (read-only, nothing posted)

PR-backlog dashboard generated from our 70 open PRs by the
pr-management-stats skill:
https://gistpreview.github.io/?b22eb23da618ff3b17a4e4e921375d72

Commits

• Add Apache Magpie (snapshot + committed magpie-setup)
• Finish apache-magpie adoption (locks, symlinks, overrides, hook, docs)
• Add Apache JMeter project manifest
• Add pr-management-triage config for JMeter

🤖 Generated with Claude Code

[vlsi]

What is this? Why creating a hook without agent-guard.py?

[milamberspace]

Good catch. Two parts, then the fix.

What it is: .claude/settings.json wires Magpie's deterministic agent-guard — a Claude Code PreToolUse hook that blocks risky gh/git commands before they run (a commit carrying a Co-Authored-By trailer, an @-mention that would ping a maintainer, marking a PR "ready" while CI is still pending, force-pushing an empty PR…). It's a safety rail, not project logic.

Why agent-guard.py isn't in the PR: same rule as the 68 skills — it's framework code, gitignored on purpose, synced from the Magpie snapshot by /magpie-setup (re-collected on upgrade). We don't vendor it into JMeter's history; only magpie-setup + config are committed.

But your underlying point is valid: the committed wiring referenced a script that isn't there until /magpie-setup runs, so on a fresh clone the hook would try to exec a missing file on every Bash call — and a PreToolUse error can block the tool. That's a footgun.

Fixed in 6ec2d88: the committed command is now a no-op until the script exists —

[ -f "$CLAUDE_PROJECT_DIR/.claude/hooks/agent-guard.py" ] && python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/agent-guard.py" || true

I'll also upstream this to apache/magpie (via setup-upstream-fix), since it affects every adopter. If you'd rather not commit the wiring at all, the alternative is to let /magpie-setup write it into the gitignored settings.local.json instead — happy to switch to that if you prefer.

[milamberspace]

Upstreamed: the guard is now proposed for every adopter in apache/magpie#786 — it updates the committed hook snippet in skills/setup/adopt.md and tools/agent-guard/README.md to the same [ -f … ] && … || true form. Once that merges and we /magpie-setup upgrade, our local 6ec2d88 becomes redundant and can be dropped. Thanks again for catching it.

[vlsi]

Who and what keeps this up to date?

[milamberspace]

Fair question — same one you raised on dev@, so here it is inline too.

These are slow-moving facts (upstream repo, default branch, mailing lists, label names, CI-check names) — a label rename or a new CI job touches one line. Keeping them current isn't a separate chore:

• /magpie-setup upgrade reconciles these overrides against framework changes and surfaces any drift for review, and setup-upstream-fix pushes our own fixes back upstream.
• When JMeter itself changes something referenced here (renames a label, adds a CI check), whoever makes that change updates the one line — exactly like .asf.yaml or CODEOWNERS.
• The skills read this file at runtime, so an obviously-stale value surfaces on the next run.

So: "who" = the maintainers who use the skills, like any config; "what" = reconcile-on-upgrade plus normal review. Not a standing maintenance burden.

[vlsi]

The CI matrix changes very often. The stale context is worse than no context.

whoever makes that change updates the one line — exactly like .asf.yaml

I would prefer Magpie to source information from .asf.yaml rather than forcing everybody to duplicate the info.

[milamberspace]

Good point — you're right, and I've changed it.

I collapsed the CI-check map to a single generic pointer (a6a8908): there are no per-check-name patterns to maintain anymore, so nothing goes stale when the matrix changes. Every failing check just points at gradle.md — and since the old rows all pointed there anyway, we lose nothing. Stale context is worse than no context.

On sourcing from .asf.yaml: agreed in spirit, with one caveat — .asf.yaml doesn't actually carry the CI-check names (those live in .github/workflows/ + matrix.mjs), so it couldn't have fed this particular file. Where it does help is the stable project fields (repo, mailing lists via notifications:, labels), and those rarely change. The remaining project.md values here (repo, default branch, dev@/private@, the CNA org id) are stable too, so the staleness risk is essentially gone.

That said, your underlying request — Magpie should derive adopter config from existing sources instead of making everyone duplicate it — is a good framework-level idea, not a JMeter-local one, so I filed it upstream: apache/magpie#815 (same path as the hook fix → apache/magpie#786). Thanks for pushing on this.

[vlsi]

Franlky, I do not see reasons to document ci check names in magpie and/or in other places

[milamberspace]

Done — dropped the per-check-name patterns entirely (a6a8908); the CI-check map is now a single generic pointer to gradle.md, so there are no check names to keep in sync. I also filed the broader "derive adopter config from existing sources instead of duplicating" idea upstream: apache/magpie#815.

[vlsi]

I do not care much about the contents of magpie-setup skill, however I would like to keep only really important entries in agents.md.

[vlsi]

Does this work with windows?

[milamberspace]

Good catch — the [ -f … ] && … || true form is POSIX-only and would break under Windows PowerShell. Fixed in 3d302c3 with a pure-Python existence check that no-ops when the script is absent (fresh clone) and runs the guard otherwise — cross-platform, no shell conditional:

python3 -c "import os,sys,subprocess; p=os.path.join(os.environ.get('CLAUDE_PROJECT_DIR',''),'.claude','hooks','agent-guard.py'); sys.exit(subprocess.call([sys.executable,p]) if os.path.isfile(p) else 0)"

The earlier POSIX form landed upstream in apache/magpie#786 (already merged), so I'll open a follow-up there to make it cross-platform too.

[vlsi]

Can magpie add the hook entry to claude/settings.local.json on setup?

[milamberspace]

Follow-up opened: apache/magpie#823 makes the committed hook cross-platform (the pure-python3 -c form) upstream too.

[milamberspace]

Done — good call; not committing the wiring at all is cleaner than any guard.

• Dropped .claude/settings.json from this PR (bea19ec) and gitignored .claude/settings.local.json as the hook's home (ff2b836).
• Filed the framework change upstream: setup: write the agent-guard hook to gitignored settings.local.json instead of committing it to settings.json apache/magpie#824 — /magpie-setup writes the hook into settings.local.json at the same moment it syncs agent-guard.py. Because the wiring then only ever exists once the script is present, there's no fresh-clone footgun and no cross-platform shell trick needed: a plain python3 ".../agent-guard.py" works on POSIX and Windows alike. That supersedes my cross-platform PR fix(agent-guard): make the fresh-clone hook guard cross-platform (Windows) apache/magpie#823.

The guard is simply inactive in JMeter until apache#824 lands — fine for an opt-in, pending adoption.

[vlsi]

Please do not include excessive items to agents.md.
They will be injected in all the agent context, so it would distract agent attention and it would consume tokens.
As magpie is optional, I see no reason to mention it here

[milamberspace]

Agreed — removed the whole apache-magpie section from AGENTS.md in 3d302c3, back to just the Security model line. You're right: AGENTS.md is injected into every agent context and Magpie is opt-in, so it shouldn't sit there. The adoption / setup summary stays in README.md (which is not always-injected).

[vlsi]

This does not belong to agents.md either

[vlsi]

I am afraid PR triage and issue triage does require JMeter knowledge, so advising people to install magpie and start triaging PRs might be too much.

It might be ok as a section in CONTRIBUTING.md.

WDYT of listing the rules regarding agent-assisted contribution in the root readme (or contributing.md) instead?