Labels and capabilities
This page is the canonical reference for the label taxonomy used on
issues and pull requests in this framework repository
(apache/magpie). It also defines the capability model
that classifies what each skill or tool in the framework actually
does, independent of which subject area it sits under.
Every issue and pull request opened against this repository should
carry at least one family:* label and at least one
capability:* label. New tools and new skills must declare their
capability up front (see The rule).
Scope caveat. This taxonomy applies to this framework repository. Skills that create issues or PRs on an adopter’s tracker (e.g.
security-issue-import,security-issue-fix,issue-fix-workflow) use the adopter’s own label scheme — adopters are free to mirror this taxonomy in their own repo but are not required to.
Label dimensions
The repository’s labels fall into four orthogonal dimensions. An issue or PR typically carries one label from each dimension that applies.
1. family:* — subject
What part of the framework does this touch?
Ten of these labels mirror the canonical skill-family vocabulary —
the closed set every skill declares in its family: frontmatter key,
enforced as ALLOWED_FAMILIES by
skill-and-tool-validator and
summarised in README.md → Skill families.
Two of them (setup, utilities) are the always-on families wired on
every install; the other eight are opt-in (see
skills/setup/SKILL.md Golden rule 8).
| Label | Type | Covers |
|---|---|---|
family:setup |
always-on | setup plus the setup-* skills — framework adoption / upgrade / verify, isolated-agent sandbox setup, shared-config sync (docs/setup/) |
family:utilities |
always-on | Framework meta-skills: write-skill, optimize-skill, skill-reconciler, report-framework-issue, list-skills, pre-release-sweep (docs/utilities/) |
family:security |
opt-in | security-issue-*, security-cve-allocate, security-model-*, security-tracker-stats-dashboard (docs/security/) |
family:issue |
opt-in | issue-* skills (issue-triage, issue-reproducer, issue-fix-workflow, issue-reassess, issue-reassess-stats, issue-stale-sweep, issue-deduplicate, issue-backlog-stats) (docs/issue-management/) |
family:pr-management |
opt-in | pr-management-* skills plus pr-stale-sweep, pre-first-pr-check, reviewer-routing (docs/pr-management/) |
family:release-management |
opt-in | release-* skills — planning, RC cut, [VOTE] draft + tally, promote, [ANNOUNCE], archive sweep, audit report, keys sync (docs/release-management/) |
family:repo-health |
opt-in | Repository maintenance audits and follow-up fixes: ci-runner-audit, workflow-security-audit, workflow-optimization, dependency-vulnerability-audit, dependency-license-audit, license-compliance-audit, flaky-test-triage, audit-finding-fix (docs/repo-health/) |
family:pairing |
opt-in | pairing-self-review, pairing-multi-agent-review (docs/pairing/) |
family:mentoring |
opt-in | mentoring-welcome, newcomer-issue-explainer, good-first-issue-author, good-first-issue-sweep (docs/mentoring/) |
family:contributor-growth |
opt-in | The path-to-committer track: contributor-activity-sweep, contributor-sentiment, contributor-to-committer, contributor-nomination, contributor-calibrate, contributor-candidate-screen, committer-onboarding, contributor-identity-map, onboarding-concierge (docs/contributor-growth/) |
Five further family:* labels cover parts of the repository that are
not a skill family. They exist only as issue / PR labels and never
appear in a family: frontmatter key — the validator would reject them:
| Label | Covers |
|---|---|
family:tools |
Substrate tools and capability adapters under tools/* (CLI bridges, agent-runtime adapters, mail-source backends) |
family:ci |
.github/ workflows, prek hooks, validators |
family:docs |
docs/, MISSION.md, READMEs |
family:dev |
Repository development that ships nothing: .asf.yaml, the spec-loop specs and their sync marker, the root package.json / package-lock.json, the repository’s own .claude/settings.json |
family:cross-family |
A cross-cutting sweep that touches so much it would gain more labels than the labeler’s limit (licence headers, renames, dependency bumps across every tool); applied instead of those labels |
A change that spans both dimensions carries both labels — a new
mentoring skill and its guide is family:mentoring + family:docs.
The two tables above are the reference for the repository’s label set:
if the label you need is not on the repository yet, a committer creates
it from here rather than reaching for an approximate existing one.
2. capability — two axes (skills vs tools)
Per RFC-AI-0005, “capability” is two orthogonal
vocabularies, one per entity. A skill carries one or more skill
capabilities (capability:*); a tool carries one or more tool
capabilities (contract:* or substrate:*). List all that apply;
do not pick a single “primary”.
Axis 1 — skill capability (capability:*) — the workflow-lifecycle
phase a skill performs:
| Label | Definition |
|---|---|
capability:triage |
Sweep a queue, classify candidates, propose dispositions for human confirmation. |
capability:review |
Deep per-item code review of a PR or local diff; also contributor mentoring (single-item teaching intervention). |
capability:fix |
Implement a code change against an upstream repo to resolve a triaged issue. |
capability:intake |
Import external signal (mailing list, scan report, public PR) into a tracker entry, or keep an existing entry reconciled with one of those sources. |
capability:reconciliation |
Compare tracker state against an external inventory (e.g. ASF security dashboard, organization-wide issue registry); surface drift; propose corrections. Does not write to either source. |
capability:resolve |
Close-out actions: invalidate, dedupe, CVE-allocate, post-announcement housekeeping. |
capability:reassess |
Re-run resolved or end-of-life issues against current code to verify still-fixed / still-broken. |
capability:stats |
Read-only dashboards, metrics, governance evidence, contributor nomination briefs. |
capability:platform |
Framework / agent substrate skills: install, verify, update, doctor, override-upstream, status, shared-config-sync, the setup bootstrap. |
capability:authoring |
Skills that author or maintain a durable framework artefact rather than acting on a queue item: other skills (write-skill, optimize-skill) and the project’s own security model (security-model-prepare, security-model-update). |
Axis 2 — tool capability (contract:* / substrate:*) — the
interface a tool/adapter provides. contract:<name> implements a
capability contract under tools/<contract>/; substrate:<name> is
framework substrate:
| Label | Kind | Definition |
|---|---|---|
contract:tracker |
contract | Issue / board / label backend. |
contract:source-control |
contract | Branch / commit / diff / push (VCS). |
contract:change-request |
contract | Proposed-change review + merge gate (pull request / merge request / Gerrit change). |
contract:mail-archive |
contract | Mailing-list / forum archive reads. |
contract:chat |
contract | Project chat reads — public channels only (Slack, Discord). Read-only; never posts. |
contract:mail-source |
contract | Inbound-mail ingestion (mbox / IMAP / …). |
contract:mail-create |
contract | Outbound mail composition. Always produces an editable draft; sending is a separate human-approved step on that draft (draft mode = default and the only mode implemented today; send mode declared but unimplemented — no autonomous send). |
contract:cve-authority |
contract | CVE allocation / record management / publication. |
contract:report-relay |
contract | Inbound security-report relay detection. |
contract:scan-format |
contract | Security-scanner report parsing. |
contract:project-metadata |
contract | Governance rosters / people / releases. |
contract:release-staging |
contract | Release-staging repository reads (ASF Nexus at repository.apache.org). Read-only — never closes, drops, or promotes. |
contract:security-cross-ref |
contract | Vulnerability database / cross-reference alias lookup (OSV.dev / NVD). |
contract:typed-decision |
contract | Provider-agnostic typed decision backend (Choice / Score / Noul). |
contract:people |
contract | Forge / tracker accounts: profile lookup, repository collaborators, team membership (one confirmed write). Distinct from contract:project-metadata, which reads an organization’s governance rosters. |
contract:security-tracker |
contract | Where the security skills keep embargoed reports: body fields, status rollup, attachments, a confidentiality guard, and a publish step for working-copy backends (GitHub, local files, private Jira). |
contract:body-field |
contract | How the ### <Name> fields of a tracker issue body are found, read and rewritten: field boundaries, closed code blocks, the refusals, and a language-neutral conformance suite every implementation passes. |
contract:hook-manager |
contract | Git-hook managers (prek, pre-commit, lefthook, husky, …) under the secure agent setup: where a manager’s install puts its hook, and how its home is split between sandboxed and host runs. |
contract:sbom-pipeline |
contract | SBOM generation in a project’s build: one CycloneDX 1.7 SBOM per distributable artifact, with the same meaning whatever ecosystem produced it, and content from other ecosystems embedded as assemblies. |
substrate:analytics |
substrate | Read-only metrics / dashboards / renderers. |
substrate:sandbox |
substrate | Agent isolation, egress control, settings audit. |
substrate:action-guard |
substrate | Deterministic pre-tool-use command guards. |
substrate:privacy |
substrate | PII redaction / approved-LLM gating. |
substrate:framework-dev |
substrate | Build / validate / eval the framework itself. |
substrate:release |
substrate | Release-artefact helpers an adopter’s release process runs: reproducible-archive build, lint and comparison; maven-artifact-verify for staged JVM artefacts; release-config loading and pre-flight checks; release-verify checks of a staged release candidate; release-management rendering of the paste-ready release blocks; secret-prompt for the release manager’s upload credentials. |
substrate:setup |
substrate | Adopter-side setup state an agent resolves at runtime rather than at development time: lock parsing, floor comparison, reconciliation fingerprints. |
substrate:review |
substrate | A second model’s read of a change before it is published: other models’ CLIs run read-only, findings merged. |
Coverage qualifiers
Some tool READMEs may declare a Coverage: qualifier next to a capability
when the tool intentionally implements only part of a contract.
partial-read-only means the tool implements a read-only subset of named
contract operations, but does not satisfy the complete contract and must not
be advertised as a complete/selectable backend.
partial means the same without the read-only restriction: some named
operations, including writes, are implemented, but not the complete contract.
The README form is a line **Coverage:** partial (or partial-read-only).
tools/vendor-neutrality-score reads it
and never counts a partial tool as a backend vendor, so a partial foundation
cannot turn a contract green in
docs/vendor-neutrality.md.
Both capability axes are orthogonal to family:*. A single
query can answer “how is our triage stack doing across PR + issue +
security?” by filtering on capability:triage alone, without
enumerating per-area queries.
Agent-harness support (substrate tools only). A substrate tool that
integrates with the agent harness (a hook, a settings file, a launcher)
declares a **Harness:** field naming the harness(es) it supports, or
agnostic when it depends on none. This is the agent-harness axis of
LLM-integration neutrality and is scored by
tools/vendor-neutrality-score —
distinct from a tool’s **Runtime:** field, which is its execution
environment (e.g. “Python stdlib”). The recognised harnesses are: Claude
Code, Codex, Cursor, Antigravity, Copilot, OpenCode, Kiro, Pi, Goose. A tool is
harness-neutral when it is agnostic or supports two or more harnesses.
3. kind:* — change type (pre-existing)
| Label | Covers |
|---|---|
kind:dx |
Maintainer dev-loop / CLI UX |
kind:policy |
Rule changes (eligibility, thresholds, behaviour switches) |
kind:perf |
Token / latency / API-call budget |
kind:adopter-config |
Per-adopter knob |
4. mode:* — handling mode (pre-existing)
| Label | Covers |
|---|---|
mode:Triage |
Agentic Triage — spot, classify, route, surface duplicates |
mode:Mentoring |
Agentic Mentoring — teaching-register issue/PR interventions + good-first-issue authoring |
mode:Drafting |
Agentic Drafting — agent-authored fix, human-reviewed PR |
mode:Pairing |
Agentic Pairing — developer-side dev-cycle skills with mentorship intrinsic |
mode:Autonomous |
Agentic Autonomous — narrowly-scoped auto-merge (off until Triage/Mentoring/Drafting run 2 quarters) |
mode:cross-cutting |
Spans multiple modes |
mode:platform |
Substrate / infra — not a mode (sandbox, CI, validators) |
Standalone labels
marketing (branding artefacts), dependencies (dependency-update
PRs), python:uv (Python uv-managed code), plus the default GitHub
labels (bug, enhancement, documentation, good first issue,
etc.).
Capability to skill map
Capabilities for every skill currently in
.claude/skills/. Skills with two values
(separated by +) carry both labels.
| Skill | Capability / capabilities |
|---|---|
pr-management-triage |
capability:triage |
issue-triage |
capability:triage |
issue-stale-sweep |
capability:triage |
pr-stale-sweep |
capability:triage |
security-issue-triage |
capability:triage |
ci-runner-audit |
capability:triage |
dependency-vulnerability-audit |
capability:triage |
dependency-license-audit |
capability:triage |
workflow-security-audit |
capability:triage |
workflow-optimization |
capability:triage |
license-compliance-audit |
capability:triage |
flaky-test-triage |
capability:triage |
reviewer-routing |
capability:triage (scores the configured reviewer roster on area match, git-history familiarity, and open-review load; proposes a primary reviewer plus optional backup — read-only, propose-then-confirm) |
pr-management-merge-candidates |
capability:triage + capability:review (screens the ready-for-review queue for trivial, all-gates-green PRs — triage; submits the maintainer’s approve on per-PR confirmation — review) |
pr-management-code-review |
capability:review |
pr-management-stack-review |
capability:review (stack-level review of a GitHub stacked pull request; posts one COMMENT, never a review event) |
pr-management-shepherd |
capability:fix + capability:review (fixes the maintainer’s own open PRs and a red default branch — fix; routes everyone else’s PRs to pr-management-code-review — review) |
pairing-self-review |
capability:review |
pairing-multi-agent-review |
capability:review |
pre-first-pr-check |
capability:review (newcomer-facing pre-flight checklist: SPDX headers, commit shape, Generated-by trailer, placeholder convention — read-only) |
pr-management-thread-mentor |
capability:review |
good-first-issue-author |
capability:review (authors a newcomer-ready good first issue — contributor mentoring on the supply side) |
good-first-issue-sweep |
capability:review + capability:triage (sweeps the open issue backlog for GFI candidates; scores each against the G1–G7 rubric and proposes the label on maintainer confirmation — a triage sweep in the mentoring family) |
mentoring-welcome |
capability:review (drafts a first-contact orientation comment for first-time contributors on issues and PRs) |
onboarding-concierge |
capability:review (answers newcomer “how do I contribute here” questions from the project’s contributing guide; hands off design, security, and out-of-scope queries to a human) |
newcomer-issue-explainer |
capability:review (explains a good-first-issue in beginner terms and sketches an approach; read-only, never posts without confirmation) |
security-model-verify |
capability:review (pre-flight on a published security model: discoverability chain plus completeness against the minimum-bar rubric; remediates with a repo PR or a private-list mail, never a public issue) |
issue-fix-workflow |
capability:fix |
audit-finding-fix |
capability:fix |
security-issue-fix |
capability:fix + capability:resolve (opens the PR that closes the tracker — both phases) |
security-issue-import |
capability:intake |
security-issue-import-from-md |
capability:intake |
security-issue-import-from-pr |
capability:intake |
security-issue-import-via-forwarder |
capability:intake |
security-issue-import-from-scan |
capability:intake |
security-issue-sync |
capability:intake (+ capability:reconciliation once #337 lands the ASF-dashboard step) |
setup-shared-config-sync |
capability:intake + capability:platform (reconciles user-scope config to a sync repo; the act is intake, the subject is setup) |
release-vote-tally |
capability:triage + capability:resolve (reads the vote thread / approval signal, classifies each reply as binding or non-binding, tallies the result — triage over the vote-thread queue — and drafts the [RESULT] [VOTE] close-out email for RM review — resolve) |
release-prepare |
capability:resolve (drafts the planning issue, prep PR, and post-release bump PR that open the release lifecycle) |
release-announce-draft |
capability:resolve (drafts the [ANNOUNCE] email and opens the site-bump PR that complete the release lifecycle) |
release-verify-rc |
capability:triage (read-only RC pre-flight: verifies GPG signatures, checksums, RAT licence headers, NOTICE/LICENSE presence, prohibited binaries, and version-string consistency; emits a PASS/PASS-WITH-WARNINGS/FAIL report) |
release-promote |
capability:resolve (emits the backend-shaped promotion command set that moves a passed-vote RC to the release distribution area; never runs the command itself) |
release-keys-sync |
capability:resolve (drafts the KEYS file diff and paste-ready svn command sequence to add the RM’s public key; validates key strength against the ASF floor) |
release-rc-cut |
capability:resolve (emits the paste-ready tag, build, sign, checksum, and staging command sequences for an RC) |
release-vote-draft |
capability:resolve (drafts the [VOTE] email and planning-issue comment that advance the release to the vote stage) |
release-archive-sweep |
capability:resolve + capability:triage (scans the dist area, classifies each release against the retention rule — triage — and proposes the command set to move past-retention releases to the archive — resolve) |
security-cve-allocate |
capability:resolve |
security-issue-invalidate |
capability:resolve |
security-issue-deduplicate |
capability:resolve |
issue-deduplicate |
capability:resolve (closes a duplicate general-issue and posts cross-reference comments; maintainer confirms before any action is applied) |
security-model-update |
capability:reassess + capability:authoring (re-reads closed trackers, reporter threads, and canned responses against the published model — reassess — and proposes the known-non-finding and gap diff — authoring) |
security-submit-to-oss-scan |
capability:authoring (prepares the scanner enrolment and derives its threat-model summary from the project’s security model) |
issue-reassess |
capability:reassess |
issue-reproducer |
capability:reassess |
pr-management-stats |
capability:stats |
issue-reassess-stats |
capability:stats |
issue-backlog-stats |
capability:stats |
security-tracker-stats-dashboard |
capability:stats |
contributor-nomination |
capability:stats |
contributor-to-committer |
capability:stats |
contributor-calibrate |
capability:stats |
contributor-candidate-screen |
capability:stats |
contributor-activity-sweep |
capability:stats |
contributor-identity-map |
capability:intake (brings a contributor’s identities on external channels into the project’s identity file, keeping existing entries reconciled) |
contributor-sentiment |
capability:stats (measures contributor-sentiment signals — thread tone, time-to-first-reply, first-PR retention, reviewer load — and produces the gate report for experimental→stable advancement) |
committer-onboarding |
capability:resolve + capability:triage (post-vote onboarding close-out — resolve — after validating the vote result in pre-flight — triage) |
list-skills |
capability:stats |
release-audit-report |
capability:stats (assembles the per-release audit record from the planning issue, vote thread, artefact list, and announce archive URL) |
setup-privacy-llm |
capability:platform (configures which LLMs may see the project’s private foundation content, and verifies the gate and the PII redactor — framework plumbing, not an act on any issue or PR) |
setup-status |
capability:stats + capability:platform (reports the adoption configuration — stats — and delegates reconfiguration to the setup skill) |
setup |
capability:platform |
setup-isolated-setup-install |
capability:platform |
setup-isolated-setup-verify |
capability:platform |
setup-isolated-setup-update |
capability:platform |
setup-upgrade |
capability:platform |
setup-isolated-setup-doctor |
capability:platform + capability:reassess (re-checks an installed sandbox against current spec — the phase is reassess on subject setup) |
setup-override-upstream |
capability:platform |
setup-welcome-guide |
capability:platform (shows the framework’s own welcome guides and turns a dismissed one back on) |
setup-upstream-fix |
capability:platform |
report-framework-issue |
capability:platform (files a redacted bug / change-proposal issue against the framework repo when a skill or tool misbehaves; the mandatory public-disclosure scrub keeps private tracker / CVE / cross-project content out of the public issue; never files without confirmation) |
security-model-prepare |
capability:authoring (produces the project’s first security model in draft-first mode and lands it, plus its discoverability chain, as one reviewable PR per repository) |
write-skill |
capability:authoring |
optimize-skill |
capability:authoring |
pre-release-sweep |
capability:reconciliation + capability:triage (checks specs, docs, principles, tool shipping and evals against the code — reconciliation; finds open issues already resolved on main — triage) |
skill-reconciler |
capability:reconciliation (compares two near-duplicate skill copies and classifies every difference as ALLOWED, DRIFT, or SAFETY-BASELINE; proposes convergence; never writes either copy) |
Capability to tool map
Tools under tools/. A tool’s capability is the interface
it provides; a tool may carry more than one value (separated by +) when
it provides more than one interface — either several contracts (e.g.
tools/gmail provides mail-source, mail-archive, and mail-create)
or a contract-free mix of substrates (e.g. tools/spec-inventory is
substrate:framework-dev + substrate:analytics).
| Tool | Capability / capabilities | Role |
|---|---|---|
tools/agent-guard |
substrate:action-guard |
Deterministic pre-execution guard dispatcher (harness-neutral core behind Claude Code and Codex native PreToolUse hooks, an OpenCode tool.execute.before plugin, a Kiro preToolUse hook, an Antigravity PreToolUse hook, a Pi tool_call extension, and a Goose PreToolUse plugin hook): blocks gh/git commands that would ping maintainers, carry a Co-Authored-By trailer, mark-ready prematurely, leak security language publicly, or empty a PR via force-push. Extensible — skills contribute guards via guards.d |
tools/agent-isolation |
substrate:sandbox |
Secure-agent sandbox helpers |
tools/apache-projects |
contract:project-metadata |
ASF project-metadata substrate (apache/comdev apache-projects-mcp); read-only projects.apache.org/json rosters / people / releases. Backs contributor-nomination and the security roster-resolution paths; tracked at main, not pinned |
tools/asf-nexus |
contract:release-staging |
ASF Nexus staging-repository adapter (read-only, repository.apache.org): anonymous content-tree reads plus authenticated staging-API reads for the authoritative open/closed state and the profile-wide repository listing. Implements check 4 of issue #1173; consumed by release-verify-rc Step 6c. Never closes, drops, or promotes |
tools/asf-svn |
contract:source-control |
ASF SVN tool adapter: source-control binding for svn.apache.org working copies (centralized model), svn CLI operation catalogue, dist.apache.org release-distribution helpers (stage/promote/prune), ASF committer/PMC authorization, and optional svnpubsub site publishing. The SVN counterpart to tools/github/ for ASF projects. Also the land delegate for the jira-patch and mail-patch change-request backends (svn patch + svn commit) |
tools/change-request |
contract:change-request |
Adapter contract for the proposed-change review + merge gate (pull request / merge request / patch). Pure interface spec; no executable code — backends under tools/github/ (PR), tools/jira-patch/, and tools/mail-patch/ implement it. The seam that lets pr-management-* skills run on non-GitHub backends |
tools/cve-org |
contract:cve-authority |
CVE.org services adapter: publishes records to CVE.org and reads back the resulting CVE state. Implements the tools/cve-tool/ contract for the CVE.org-direct backend |
tools/cve-tool |
contract:cve-authority |
Adapter contract for CNA backends (Vulnogram, MITRE form, CVE.org direct, GHSA), and the cve-tool command the skills run: it reads cve_authority.tool and dispatches to that backend’s adapter, over the sibling tools/cve-tool-*/ directories. |
tools/cve-tool-vulnogram |
contract:cve-authority |
ASF Vulnogram CVE-allocation adapter. Implements the tools/cve-tool/ contract. Previously named tools/vulnogram/. |
tools/dashboard-generator |
substrate:analytics |
Self-contained HTML dashboard generator |
tools/dev |
substrate:framework-dev |
Framework dev-loop helpers |
tools/discourse |
contract:mail-archive |
Coverage: partial. Discourse forum bridge: reads a forum topic and its posts as mail-archive thread_data, lists category activity using thread_summary fields with separate activity timestamps, and searches topics with matching post excerpts (#307). Not a complete/selectable backend; the contract verbs remain unimplemented. |
tools/egress-gateway |
substrate:sandbox |
Egress-allowlist forward proxy (proxy.py plugin); host-level egress chokepoint — defence-in-depth for RFC-AI-0003 §4.4 |
tools/container-gateway |
substrate:sandbox |
Per-project policy proxy for the podman / docker API; label-scoped, mount- and privilege-checked container access from inside the sandbox |
tools/forwarder-relay |
contract:report-relay |
Adapter contract for inbound-relay backends (ASF Security relay, huntr.com, HackerOne triagers). Pure interface spec; adapters declare detection + credit-extraction + reporter-addressing rules. |
tools/bitbucket |
contract:change-request + contract:tracker |
Coverage: partial. Bitbucket Cloud and Bitbucket Data Center bridge foundation for repository metadata context, branch restriction context for PR-management decisions, pull-request discovery/fetching, read-only commit fetching, read-only diff fetching, comments-only discussion fetching, read-only review-state fetching, Cloud-only pull-request task listing/fetching, read-only merge-check context fetching, and read-only status fetching, plus narrowly scoped pull-request comment creation, approve/unapprove, and request-changes/remove-request-changes actions on Cloud and Data Center, and Cloud-only write actions: pr review (with a comment, approve, or request-changes verdict), decline, reject, and pr merge (with pr merge-task-status to follow an asynchronous merge). Native Bitbucket issue operations are not implemented: Atlassian removed the native Bitbucket Cloud Issue Tracker API on 2026-08-20 and Data Center native issues were never supported, so the historical issue CLI surface fails closed before any request. Data Center pr jira-issues <id> provides read-only discovery of Jira keys associated with pull-request commits and hands them to the Jira bridge (tools/jira) for tracker operations. The partial qualifier means this tool implements named contract operations but does not satisfy the complete contract and must not be counted as a complete/selectable backend. Broader linked Jira coverage and the remaining pull-request coverage are incomplete. |
tools/forgejo |
contract:tracker + contract:source-control + contract:change-request |
Coverage: partial. Forgejo / Gitea REST API and tea CLI forge bridge foundation for issue listing/fetching, confirmed issue creation, body edits, comments, labels, and milestones under contract:tracker, git-backed branch/commit/push operations under contract:source-control, and pull-request creation via REST API / compare URL and label edits under contract:change-request. Project boards are unsupported (no-op) due to absence of REST card/column endpoints. The partial qualifier means this tool implements named contract operations but does not satisfy the complete contract and must not be counted as a complete/selectable backend. |
tools/fossil |
contract:tracker + contract:source-control |
Fossil SCM forge bridge: integrates local SQLite-backed ticket tracking, wiki, and forum reads with the version-control shim |
tools/github |
contract:tracker + contract:source-control + contract:change-request + contract:people |
GitHub REST / GraphQL tracker substrate (called by every lifecycle phase) plus the Git source-control binding documented in source-control.md (runnable backend in tools/vcs), the pull-request review/merge gate (change-request; the ASF default backend, alongside tools/jira-patch/ and tools/mail-patch/ for SVN-first projects), and account profiles / collaborators / team membership (people) |
tools/gitlab |
contract:tracker + contract:source-control + contract:change-request |
Coverage: partial. GitLab REST API v4 forge bridge foundation for repository metadata context under contract:source-control, issue listing/fetching under contract:tracker, and merge request discovery, diffs, commits, and CI pipeline status under contract:change-request. The partial qualifier means this tool implements named contract operations but does not satisfy the complete contract and must not be counted as a complete/selectable backend. Write operations, issue mutation, and merge request mutations remain out of scope for this foundation. |
tools/github-body-field |
contract:tracker + contract:body-field |
Reference implementation of the body-field contract. Read or rewrite one ### Field section of a GitHub issue body without bringing the body into agent context — substrate helper for the security-sync skills |
tools/github-rollup |
contract:tracker |
Append to (or create) the status-rollup comment on a GitHub issue without bringing the rollup body into agent context — substrate helper for every status-update-emitting skill |
tools/gmail |
contract:mail-source + contract:mail-create + contract:mail-archive |
Gmail API substrate — inbound report intake (mail-source), thread / archive reads (mail-archive), plus outbound courtesy-reply drafting (mail-create); read + draft only, never sends |
tools/jira |
contract:tracker + contract:people + contract:security-tracker + contract:body-field |
JIRA REST substrate (general-tracker writes in the Groovy bridge, tracked in #301); the tracker’s contributor-activity reads run in the jira backend of tools/contributor-metrics, and people provides profile lookup only (display name, existence). magpie-jira-tracker is the private-Jira security-tracker backend: create always sets the configured issue-security level, every write on an issue without one is refused, and all requests go through the shared host-bound-token REST client |
tools/jira-patch |
contract:change-request |
JIRA-patch change-request backend: patches attached to JIRA issues as the proposal, reviewed via JIRA comments, landed via contract:source-control (svn patch + svn commit). Composes tools/jira/ (REST) + tools/asf-svn/ (land). Implements the tools/change-request/ contract |
tools/chat |
contract:chat |
Adapter contract for project chat (Slack, Discord): public-channel reads for community signals. Pure interface spec. |
tools/chat-slack |
contract:chat |
Slack adapter for the tools/chat/ contract, over the Slack MCP; public channels only, never posts. |
tools/chat-discord |
contract:chat |
Discord adapter for the tools/chat/ contract, over the Discord MCP; public channels only, never posts. |
tools/mail-archive |
contract:mail-archive |
Adapter contract for public mail-archive backends (PonyMail, Hyperkitty, Discourse, Google Groups, GitHub Discussions). Pure interface spec. |
tools/mail-patch |
contract:change-request |
[PATCH]-mail change-request backend: a [PATCH] thread on dev@ as the proposal, reviewed via drafted replies (contract:mail-create), read via contract:mail-archive, landed via contract:source-control (svn patch + svn commit). Implements the tools/change-request/ contract |
tools/mail-source |
contract:mail-source |
Mail-source backend abstraction (mbox / IMAP / Mailman 3) feeding a uniform inbound thread/message view to the intake pipeline |
tools/maildir |
contract:mail-source + contract:mail-create |
Local Maildir backend (Vendor: Maildir) — the offline, credential-free counterpart of tools/gmail. Implements mail-create by filing editable outbound drafts into a local Maildir for any mail client to send (never sends itself); its mail-source side is the local mbox/Maildir archive reader (tools/mail-source/mbox). The second, non-Google mail-create backend — closes the outbound-mail vendor-neutrality gap |
tools/osv |
contract:security-cross-ref |
OSV.dev vulnerability cross-reference client (Vendor: OSV.dev): queries vulnerability records, alias cross-references (CVE ↔ GHSA ↔ OSV IDs), affected package versions, and vulnerabilities associated with a public upstream commit via OSV.dev REST API v1 |
tools/people |
contract:people |
Adapter contract for accounts on a forge or tracker: profile lookup, repository collaborators, team membership (one confirmed write). Pure interface spec; GitHub implements every verb, Jira profile lookup only |
tools/ponymail |
contract:mail-archive + contract:mail-source |
PonyMail public mail-archive substrate (ASF lists.apache.org); implements the tools/mail-archive/ contract for archive reads and the tools/mail-source/ contract for inbound list-traffic ingestion |
tools/scan-format |
contract:scan-format |
Adapter contract for security-scanner report formats (ASVS reference; anthropic-oss-scanner for scans delivered as one email); reads a scan’s finding index + per-finding evidence for the security-issue-import-from-scan pipeline. |
tools/permission-audit |
substrate:sandbox |
Audit + atomically edit Claude Code permissions.allow[] entries; backs /magpie-setup:setup verify --apply-permission-audit (check 8d) |
tools/adversarial-review |
substrate:review |
Runs other models’ CLIs (Codex, Copilot, Antigravity, Pi, Grok, Goose, Claude) read-only over a change before its PR is created, and merges their findings into one advisory JSON report |
tools/vetted-ops |
substrate:sandbox |
Fixed, policy-scoped forge operations — a closed catalogue whose parameters can never become commands or flags, so one allow entry replaces the wildcard Layer 3 ask rules |
tools/contributor-metrics |
substrate:analytics |
Deterministic contributor activity counts, per-area shares and automated-work weighting for the contributor-growth skills |
tools/pr-management |
substrate:analytics |
Deterministic core of the pr-management skills: classifies a saved PR sweep (pre-filters, decision table, stale sweeps), guards each mutation on fresh reads, renders every contributor-facing body, and builds the whole PR-backlog dashboard |
tools/skill-lock |
substrate:action-guard |
Per-skill write lock for the batch skills: one write phase per skill per repository, taken before the first post / label / close and released after the recap; a second run stops with already_running and the holder, so overlapping sweeps never double-comment. Lease-based, lives in the personal config layer |
tools/security-management |
substrate:analytics |
Deterministic core of the security-* skills: the Step 1 pre-filter, batched threadId dedup, forwarder pre-screen, the sanitised tracker body, rollup entry, rejections-ledger record and fix-already-public reply, the receipt-draft matrix, the confirmation-reply grammar and the recap; runs nothing. Used by security-issue-import Steps 0–8 security-issue-import-from-pr Steps 0–8 (PR reference, scope detection, milestone check, duplicate query, body, labels, rollup, recap), security-issue-import-from-md Steps 0–6 (findings parser, keyword, body, rollup, proposal, recap), security-issue-import-via-forwarder Steps 0–3 (preflight, adapter detection, credit kind, routing) and security-issue-import-from-scan Steps C–F (bucket rule, report, decision, scrub) |
tools/preflight-audit |
substrate:analytics |
Dry-run the bulk-mode pre-flight classifier; measure skip-rate before / after any rule edit in the security-issue-sync skill |
tools/privacy-llm |
substrate:privacy |
Privacy-LLM PII-scrubbing gate |
tools/probe-templates |
substrate:sandbox |
Sandbox-doctor probe templates |
tools/sandbox-lint |
substrate:sandbox |
Sandbox settings linter |
tools/security-tracker-stats-dashboard |
substrate:analytics |
Security-tracker analytics engine |
tools/setup-preflight |
substrate:setup |
Deterministic setup pre-flight: resolves a project’s lock, floor and reconciliation state plus one skill’s fingerprint into a JSON verdict, so every skill’s shared pre-flight block runs a command instead of re-deriving the rules from prose |
tools/spec-loop |
substrate:framework-dev |
Spec-driven build loop runner (Ralph-style) for framework development |
tools/skill-evals |
substrate:framework-dev |
Eval harness for skills; framework-dev infrastructure whose run output is governance evidence |
tools/skill-and-tool-validator |
substrate:framework-dev |
Skill-frontmatter and convention validator |
tools/skill-token-count |
substrate:framework-dev + substrate:analytics |
Reproducible full-file skill token measurements and documentation drift check |
tools/spec-inventory |
substrate:framework-dev + substrate:analytics |
Compact routing inventory for spec-loop prompts — summarizes specs, skills, and tool metadata so agents can choose relevant files before direct verification |
tools/spec-status-index |
substrate:framework-dev + substrate:analytics |
Index of spec / RFC implementation status — framework-dev substrate that also doubles as a governance/stats view (analytics) |
tools/vendor-neutrality-score |
substrate:framework-dev + substrate:analytics |
Deterministic vendor-neutrality score — reads each contract tool’s **Kind:** / **Vendor:** metadata and scores per-contract + per-skill neutrality (analytics); backs the score block in docs/vendor-neutrality.md |
tools/spec-validator |
substrate:framework-dev |
Spec-frontmatter and body-section validator — counterpart to skill-and-tool-validator for tools/spec-loop/specs/ |
tools/release-config |
substrate:release |
release-config — loads the release-management config (<project-config> layered lookup, defaults, derived values) and runs each release-* skill’s deterministic Step 0 pre-flight checks as JSON; used by every release-* skill’s Step 0 and the Step 1 metadata of rc-cut, vote-draft, announce-draft, promote and verify-rc |
tools/release-management |
substrate:release |
release-management — renders what the release-* skills hand the release manager (paste-ready command blocks, drafts, planning-issue comments) from release-config load, refusing a dist/release/ staging target or an MD5 / SHA-1 digest in code; runs nothing. Used by rc-cut Steps 0 and 2–4, verify-rc Steps 1–10, vote-draft Steps 0, 2 and 3 (verify-rc gate, [VOTE] body, planning-issue comment), vote-tally Steps 0–3 (pre-classification, the tally, the [RESULT] [VOTE] body), promote Steps 0 and 2, announce-draft Steps 0, 2 and 3, archive-sweep Steps 0–2 (the listing command, trains.json, the retention rule, the backend-shaped archive commands), audit-report Steps 0–3 (the planning-issue URL, the mail-archive search plan, voter handles, the record, the PR proposal) keys-sync Steps 0–2 (the KEYS lookup and UID comparison over release-verify list-keys output, the strength floor, the KEYS block and the svn / git commands), and prepare Steps 0, 1, 2, 14 and A (train coverage, the planning issue, the changelog and its coverage, the 2e archive review, the prep and post-release PRs, the automated-signing gate and workflow) |
tools/reproducible-archive |
substrate:release |
repro-archive — build, lint and compare reproducible source archives from a git ref (git archive + .gitattributes export-ignore, every reproducible-builds.org archive rule applied); used by release-rc-cut Step 2/2b and release-verify-rc Step 9 |
tools/maven-artifact-verify |
substrate:release |
maven-artifact-verify — verify locally staged JVM RC artefacts: POM ALv2 licence / developers / scm (with parent-POM inheritance resolution), podling incubation disclaimer in <description>, companion -sources.jar / -javadoc.jar presence with their own signatures and checksums; used by release-verify-rc Step 6b |
tools/release-verify |
substrate:release |
release-verify — deterministic, read-only checks of a staged RC (inventory, signatures against the project KEYS only, checksums, NOTICE/LICENSE, prohibited binaries, dangling symlinks, version strings) and the verdict roll-up, each as JSON; used by release-verify-rc Steps 1–3, 5–8 and 10; and list-keys, the fingerprints and UIDs of a KEYS file or fetched key, for release-keys-sync Steps 0–1 |
tools/secret-prompt |
substrate:release |
secret-prompt — asks the release manager for a secret (terminal, macOS dialog, zenity/kdialog, pinentry) and runs one command with it in one environment variable, so an upload token never reaches the shell history, a file or an agent’s transcript |
tools/symlink-lint |
substrate:framework-dev |
Self-adoption symlink hygiene — rejects cyclic symlinks, misdirected skill relays (canonical/relay target-correctness), and incomplete self-adoption symlink sets |
tools/pilot-report-validator |
substrate:framework-dev |
Adopter pilot-report validator — required frontmatter keys, no unfilled placeholders, valid profile, and required body sections; counterpart to spec-validator for docs/pilot-report-template.md |
tools/skill-reconciler-diff |
substrate:framework-dev |
Deterministic structural diff between two skill trees — parses frontmatter, section headings, step inventory, placeholders, support files, and safety-baseline clauses into a JSON diff object for the skill-reconciler skill |
tools/vcs |
contract:source-control |
Backend-dispatching implementation of the source-control (VCS) capability (tools/github/source-control.md); complete Git, Mercurial (Hg), Fossil, and Subversion (SVN) backends |
tools/sourcehut |
contract:tracker + contract:source-control + contract:mail-archive |
SourceHut (sr.ht) forge bridge: todo.sr.ht, lists.sr.ht, builds.sr.ht, and git/hg repository reads |
tools/hook-manager |
contract:hook-manager |
Contract for git-hook managers under the secure agent setup: the install-target and home rules, and the registry of adapters (prek, overcommit, lefthook and captainhook today) that the hook-manager shim, the whole-user dispatcher and sandbox-lint are generated from |
tools/sbom-pipeline |
contract:sbom-pipeline |
Contract for SBOM generation in a project’s build: the format, subject, component, assembly, reproducibility and distribution rules, the pipeline operations and conformance checks, and the per-ecosystem adapters (Maven, Gradle, JS, Python, Go, Rust; all planned) |
tools/tracker |
contract:tracker |
Interface spec for the tracker contract’s read-only contributor-activity queries (issues filed, triaged and commented on; issues created; first maintainer reply). Pure interface spec; GitHub and Jira implement it, and the rest of the contract is described by tools/github/tool.md |
tools/body-field-contract |
contract:body-field |
The body-field contract: how every reader and writer finds a tracker body’s ### <Name> fields, with a language-neutral conformance suite run against every implementation. Pure interface spec; implementations: tools/github-body-field/ (reference), tools/vetted-ops/, tools/local-tracker/, tools/jira/ |
tools/security-tracker |
contract:security-tracker |
Adapter contract for the security tracker the security-* skills read and write, selected by tracker.platform. Pure interface spec; backends: tools/github/ (default), tools/local-tracker/, tools/jira/ |
tools/asf-security-dash |
contract:security-tracker |
Coverage: partial. Read-only bridge to the ASF Security dashboard (dash.security.apache.org): lists a PMC’s open cases and reconciles them with the project’s own tracker. Not a selectable tracker.platform: the dashboard holds no issue bodies, comments or fields, and only the ASF Security team edits its records |
tools/local-tracker |
contract:security-tracker + contract:body-field |
Security tracker as Markdown files in a private Git or SVN working copy; learns an existing report layout, refuses writes until access is human-confirmed, and commits and pushes on confirmation |
tools/typed-decision |
contract:typed-decision |
Provider-agnostic typed decision tool contract (Choice / Score / Noul) with TypeSafe Jev API as initial backend |
A tool’s capability is the interface it provides, not which skills
happen to consume it (RFC-AI-0005). tools/github provides the
contract:tracker interface; tools/cve-tool-vulnogram provides
contract:cve-authority; tools/privacy-llm is substrate:privacy.
Use a contract:<name> value when the tool implements a capability
contract under tools/<contract>/, and a substrate:<name> value for
framework substrate. A tool may carry more than one value whenever it
genuinely exposes several interfaces — the multi-value rows in the table
above are the authoritative list, and they are a normal case rather than
an exception (forge bridges such as tools/github, tools/fossil, and
tools/sourcehut; the mail backends tools/gmail, tools/maildir, and
tools/ponymail; and the framework-dev tools that double as analytics).
MCP servers, classified by capability
Several tools wrap a Model Context Protocol (MCP) server as their concrete backend. An MCP server is not a separate axis — it is classified by the capability its wrapping tool provides; the MCP is just the transport, interchangeable with a CLI or REST backend behind the same contract. A skill never names an MCP server — it targets the capability, and the tool routes to whichever backend the adopter wired in. The framework consumes six:
| MCP server | Tool prefix | Wrapped by | Capability provided | Organization |
|---|---|---|---|---|
| GitHub MCP | mcp__github__* |
tools/github |
contract:tracker + contract:source-control + contract:change-request + contract:people |
— |
| Gmail MCP (claude.ai) | mcp__claude_ai_Gmail__* |
tools/gmail |
contract:mail-source + contract:mail-create + contract:mail-archive |
— |
PonyMail MCP (apache/comdev) |
mcp__ponymail__* |
tools/ponymail |
contract:mail-archive + contract:mail-source |
ASF |
| Slack MCP (claude.ai) | mcp__claude_ai_Slack__* |
tools/chat-slack |
contract:chat |
— |
Discord MCP (PaSympa/discord-mcp) |
mcp__discord__* |
tools/chat-discord |
contract:chat |
— |
apache-projects MCP (apache/comdev) |
mcp__apache-projects__* |
tools/apache-projects |
contract:project-metadata |
ASF |
Each wrapping tool declares this relationship in its own README with an
**MCP:** <server> (mcp__<prefix>__*) marker (see
tools/AGENTS.md) — that per-tool marker is the
source of truth; this table mirrors it for a one-glance overview.
Non-MCP backends fulfil the same contracts: JIRA is reached over REST
and gh is the CLI fallback, both contract:tracker. See
docs/prerequisites.md for connection setup.
MCP servers are installed for the user, not the project. They are
registered at user scope (claude mcp add … -s user), so a single
registration serves every repository on the machine. Consequently they
are usable by any agent session — not only Magpie-adopting projects
or Magpie-related work. Magpie surfaces the registration command and
verifies it during setup, but the server itself is a plain,
project-agnostic MCP: once registered it is available to any agentic
session the same way a globally-installed CLI would be. Nothing about
using one ties a session to Magpie.
The rule
When you create any of the following on this repository, declare the capability:
A GitHub issue
Apply at least one family:* AND one capability label — a skill
capability (capability:*) for skill work, a tool capability
(contract:* / substrate:*) for tool work. If the issue genuinely
spans capabilities, apply all that apply.
A pull request
Same: family:* AND the matching capability. Match the capability the
change is implementing, not the file paths it happens to touch. A PR
that adjusts the validator config to support a new triage rule is
capability:triage (the change’s purpose), not substrate:framework-dev
(the file it edited).
Labels are pre-applied the moment a PR is opened or pushed to:
.github/workflows/labeler.yml
runs on the completion of the unprivileged
labeler-signal.yml, from the default branch,
and applies the rules in .github/labeler.yml, which
tools/dev/generate-labeler-config.py
generates from the repository’s own declarations:
the family: and capability: frontmatter of every skill (covering its directory and its eval suite),
the **Capability:** line of every tool README,
and the paths of the non-skill families (family:tools, family:ci, family:docs, family:dev).
A PR that would gain more than the limit of 20 path labels gets none from the labeler;
tools/dev/labeler-cliff.py then marks it family:cross-family.
The same labels are passed on to the issues the PR closes,
and, for a project member’s PR, to issues its description introduces with a reference phrase
(“Part of #N”, “Refs #N”, “Related to #N”, “Relates to #N”, “Follow-up to #N”); a passing #N is not a reference.
An outside contributor’s PR labels only the issues its merge closed.
A daily run labels any open PR still without a family:* label.
That is a starting point, not the answer: remove a label the change does not
implement, and add the capability it does implement when the paths do not show it.
Bot PRs are left unlabelled.
A new tool under tools/
Declare the tool’s capability in the first paragraph of its README using the line:
**Capability:** contract:NAME
…or substrate:NAME for framework substrate. If the tool serves more
than one, list them (contract:a + substrate:b). Pick the
contract:<name> that matches the capability contract the tool
implements, or the substrate:<name> kind that fits.
A new skill under .claude/skills/
Declare the capability in the skill’s frontmatter:
---
name: my-new-skill
description: |
...
capability: capability:NAME
---
The write-skill skill
prompts for this on every new-skill scaffold.
A new doc under docs/
Capability-specific docs (e.g. a guide for a single skill family)
should link to this page and name the capability in their first
paragraph. Cross-cutting docs (MISSION.md, top-level READMEs) need
no capability marker.
Why this exists
The original family:* labels split issues by subject — useful for
“what part of the codebase is this?” but unable to answer “what kind
of thing is this?”. The capability:* dimension fills that gap and
is orthogonal: a triage-rule change in PR management
(family:pr-management + capability:triage) and a triage-rule change
in security (family:security + capability:triage) become trivially
findable as a cohort even though they live in different families.
Capability is also a forcing function for skill design: if a new skill doesn’t fit any of the ten skill-capability buckets cleanly, that’s a signal worth inspecting before the skill ships.