How Magpie is built
Four layers, one rule: workflows never name a vendor. Skills declare the capabilities they need; tools provide contract and substrate interfaces; adapters implement a contract for one backend; and organizations bundle the defaults a whole foundation or company shares. Everything on this page is generated directly from apache/magpie, so it never drifts from the framework.
The model
The four layers and how they connect. The seam between a workflow and a vendor is always a capability — so swapping a backend is a config change, never a rewrite.
SKILL ──declares──▶ capability:triage ┐
│ the capability is the only coupling
TOOL ──provides──▶ contract:tracker ─┘ (skills never branch on the backend)
│
├─ contract:* one per capability seam → an ADAPTER implements it for a vendor
└─ substrate:* framework plumbing (sandbox, privacy, analytics, …)
ORGANIZATION (ASF, independent, …) ──bundles──▶ which adapter fulfils each capability
+ governance vocabulary + identity/logoSkill capabilities
The workflow-lifecycle phase a skill performs (capability:*). A skill may carry more than one.
Tool capabilities
What a tool provides. A contract is a capability seam with pluggable backends (where vendor neutrality is delivered); a substrate is framework plumbing shared by everything.
Contracts (10)
Substrates (5)
Vendor neutrality
Not a slogan — a deterministic score, computed straight from repository metadata by tools/vendor-neutrality-score and regenerated with this page, so the number cannot drift from the code. Neutrality is measured per capability contract: a contract is green once two or more backend vendors implement it, by construction when one spec serves every backend, or by exemption when it is bound to a single organization's data model.
A skill is capability-pure when it names no backend, portable when every backend it invokes has an alternative, and vendor-coupled only when it reaches for the sole implementation of a capability. Swap in a second backend for that capability and every coupled skill becomes portable — without a line of skill code changing.
Per-contract score
AtlassianFossil
GitHubGitHubGitHubSourceHut
GitGitHubSourceHut
SubversionAtlassianAtlassianemailGitHub
ASF
GoogleSourceHutASFGoogleMaildirGoogleMaildirASFSkills by neutrality
Every skill placed in its bucket. Hover a portable skill to see which capability contracts it invokes — each already has more than one backend, so the skill runs unchanged whichever vendor a project picks.
LLM & agent-integration neutrality
A different axis from the backend contracts above: which LLM and agent Magpie's own machinery is tied to. Two fronts — the agent harness that drives the skills, and the model endpoint that may receive data.
Every substrate tool is either harness-agnostic or already runs under more than one harness — the integration layer names no single agent.
The privacy-llm registry keys approval on endpoint identity, not on who hosts the model — so no single LLM vendor is privileged.
| Default-approved endpoint class | Examples |
|---|---|
| Claude Code itself | The agent invoking the skill |
| *.apache.org-hosted endpoints | A future ASF-hosted inference endpoint at e.g. `inference.apache.org`; an in-tracker endpoint at `<project>.apache.org/llm/` |
| Local-only inference | Ollama serving a local model, vLLM on the user's workstation, llama.cpp embedded in a CLI helper |
| Air-gapped on-prem | A PMC-hosted inference appliance on a private VLAN |
Every other endpoint is opt-in — the adopting project's security team declares it in <project-config>/privacy-llm.md (endpoint, data-residency contract, approver).
Browse the 45 tools
Filter by the contract or substrate a tool provides, by backend vendor, by organization, or by whether it wraps an MCP server — the dimensions combine. Within a dimension, pick more than one to widen the view.
A deterministic pre-execution guard dispatcher. It inspects every shell command rule — protections that must not depend on the model remembering a SKILL.md instruction.
This directory ships the moving pieces the framework's docs/setup/secure-agent-setup.md document references. It is not a Python project (unlike the sibling tools under tools/cve-tool-vulnogram/ and tools/gmail/oauth-draft/) — these are…
ASF MCPAdapter / specexperimentalASF project-metadata substrate. Read-only, unauthenticated client for the official apache/comdev apache-projects-mcp server, which wraps the public projects.apache.org/json feeds (committee / committer rosters, people + Apache IDs,…
Wraps the apache-projects MCP (apache/comdev) via mcp__apache-projects__* — the MCP is just the transport behind the contract; a CLI or REST backend can fulfil the same capability.
SubversionAdapter / specexperimentalASF SVN tool adapter — the Subversion counterpart to tools/github/. Where the GitHub tool covers forge issues, project boards, and Git-backed source control, this adapter covers the SVN surfaces that every ASF project uses regardless of…
AtlassianImplementedexperimentalBitbucket Cloud and Bitbucket Data Center bridge for Magpie adopters that use Bitbucket as a forge, pull-request review surface, or Jira-paired Atlassian backend.
The framework's change-proposal adapter contract: the seam that lets a project drive PR-shaped review-and-merge work over a backend that is *not* a GitHub pull request. Today every pr-management-* skill is hardwired to gh pr — gh pr…
CVE.org publication client. Submits CVE records via the CVE.org REST API; consumed by security-cve-allocate once a CVE has been allocated via the ASF Vulnogram path. See tool.md for the protocol detail and cve.org field mapping.
The framework's CVE-tooling adapter contract. Today every CVE-aware skill in this repository — security-cve-allocate, security-issue-sync, security-issue-invalidate, security-issue-deduplicate — speaks Vulnogram. They embed Vulnogram's…
Adapter / specstableASF Vulnogram CVE-allocation client. OAuth-authenticated API that allocates a CVE ID through the ASF's Vulnogram instance and publishes the CVE record. Consumed by security-cve-allocate. See allocation.md, record.md, and…
Deterministic reference implementations of the dashboard that issue-reassess-stats produces. Adopters who want CI-rendered dashboards (refreshed on schedule, published as a build artefact) use one of these reference scripts instead of…
Framework dev-loop helpers (placeholder check, agent pre-commit hook). Invoked by prek and CI; not consumed by any skill directly. See the individual scripts in this directory for usage.
A local host-allowlisting HTTP(S) forward proxy for the Magpie framework. It is the egress-control chokepoint: framework tools point HTTPS_PROXY/HTTP_PROXY at it, and the gateway rejects any connection to a host that is not on its…
A forwarder-relay adapter is a pluggable seam that teaches the security skills how to recognise an inbound report that arrived reporter's message to the project), how to extract the original-reporter credit from the relayed body, and…
Fossil SCM forge and tracker bridge implementation for the Apache Magpie framework. It integrates version-control checks, ticket tracking, wiki reads, and forum thread reads.
GitHub MCPAdapter / specexperimentalGitHub REST + GraphQL substrate. Pure read/write wrapper used by every lifecycle phase (triage / intake / fix / resolve / stats). See tool.md for the operation catalogue and the per-area files (issue-template.md, labels.md,…
Wraps the GitHub MCP via mcp__github__* — the MCP is just the transport behind the contract; a CLI or REST backend can fulfil the same capability.
GitHubImplementedexperimentalRead or rewrite a single ### Field section of a GitHub issue body without bringing the body into agent context.
GitHubImplementedexperimentalAppend to (or create) the status-rollup comment on a GitHub issue without bringing the rollup body into agent context.
Google MCPAdapter / specstableGmail API substrate. Read + draft-only — never sends. Provides two contracts: mail-source for inbound report intake (search / read a uniform thread/message view) and mail-create for outbound courtesy-reply composition. It implements…
Wraps the Gmail MCP (claude.ai) via mcp__claude_ai_Gmail__* — the MCP is just the transport behind the contract; a CLI or REST backend can fulfil the same capability.
AtlassianImplementedexperimentalJIRA REST helpers for the issue-* skill family. Adopters with JIRA-based issue trackers wire this in as their tracker bridge; adopters using GitHub Issues or other trackers contribute a parallel tools/<tracker>/ directory.
AtlassianAdapter / specexperimentalJIRA-patch change-request adapter — the backend that lets a JIRA-tracker, SVN-hosted project drive the pr-management-* skills over patches attached to JIRA issues instead of GitHub pull requests. It implements the tools/change-request/…
This file defines the adapter contract for public mail-archive backends — the seam that lets adopting projects plug a non-ASF archive system (Hyperkitty, Discourse, Google Groups, GitHub Discussions, or none at all) into the same skills…
Adapter / specexperimental[PATCH]-mail change-request adapter — the backend that lets a project driving code review over its developer mailing list use the pr-management-* skills. It implements the tools/change-request/ contract for the oldest review mechanism…
Mail-source backend abstraction. Pluggable backends (mbox, IMAP, the Gmail API via tools/gmail, future Mailman 3 / Hyperkitty) that feed the security-issue-import intake pipeline a uniform thread/message view. See contract.md for the…
The local-files mail backend: one vendor-neutral substrate that serves both mail directions the framework needs, using nothing but the on-disk Maildir / mbox formats and the Python standard library. No cloud provider, no account, no…
Audit + atomically edit Claude Code's permissions.allow[] entries in <repo>/.claude/settings.json and <repo>/.claude/settings.local.json.
Validates adopter pilot-report files against the required schema defined in docs/pilot-report-template.md. Pilot reports are the feedback artefact that documents an adopter's end-to-end run of an experimental skill family, and are the…
ASF MCPAdapter / specstablePonyMail archive substrate. Read-only ASF mailing-list archive client; complements gmail for threads not present in the inbox. Used by security-issue-import + sync to cross-reference public mailing-list discussions. See tool.md for the…
Wraps the PonyMail MCP (apache/comdev) via mcp__ponymail__* — the MCP is just the transport behind the contract; a CLI or REST backend can fulfil the same capability.
Deterministic reference implementation of the data-fetch + classification contract that backs the pr-management-stats skill.
Dry-run the bulk-mode pre-flight classifier against a real or replayed tracker. Use to measure skip-rate before / after any rule change — closes the tune-then-verify loop so rule edits are made against evidence, not guesswork.
Privacy-LLM PII-scrubbing gate. Standalone redactor / checker pair that screens content for PII before it reaches an external LLM. See tool.md and wiring.md for integration details, models.md for the model catalogue, and pii.md for the…
Runnable cross-family probe scripts that the issue-reproducer skill copies from when its Step 9 (optional cross-family probe) runs against an issue.
Lints .claude/settings.json against the shipped baseline at tools/sandbox-lint/expected.json, and against the security invariants documented in docs/security/threat-model.md (mitigation M.29). The threat-model document lands in a…
A scan-format adapter teaches security-issue-import-from-scan how to read one security scanner's report layout. The skill is scanner-agnostic; everything format-specific — how to recognise a scan folder, how to enumerate findings, how…
Generate a self-contained HTML dashboard of <tracker> repository statistics — issue-lifecycle bands (untriaged / triaged / PR-merged / fixed-released / closed-other), opened-vs-untriaged backlog, cumulative opened/closed, and…
Validate framework skill definitions — YAML frontmatter, internal link integrity, and placeholder conventions.
Behavioral eval harness for Apache Magpie skills. Each eval suite tests a skill pipeline step by step, verifying that the model produces the correct structured JSON output for a fixed set of fixture cases.
A deterministic uv tool that parses two SKILL.md skill trees into normalised structural representations and emits a JSON diff. The output grounds the skill-reconciler skill's ALLOWED / DRIFT / SAFETY-BASELINE classification decisions in…
SourceHut (sr.ht) forge bridge implementation for the Apache Magpie framework. It integrates ticket tracking (todo.sr.ht), mailing list patchset review (lists.sr.ht), CI builds (builds.sr.ht), and repository reads (git.sr.ht & hg.sr.ht)…
A deterministic uv tool that emits a compact routing inventory for the spec-loop prompts. It summarizes spec frontmatter, where-it-lives hints, validation commands, known gaps, skill frontmatter, and tool/test presence so agents can…
A spec-driven build loop for this framework, in the general Ralph style (run a fresh agent context against a fixed prompt, repeat), adapted to the framework's human-in-the-loop posture. The full write-up is in…
A deterministic uv tool that reads spec-loop specs from tools/spec-loop/specs/ and prints them grouped by status, so build iterations can choose the next work item mechanically.
Validates spec files in tools/spec-loop/specs/ — the counterpart to tools/skill-and-tool-validator/ for the spec side of the framework.
Lints the framework's self-adoption skill symlinks — the canonical .agents/skills/ links and their relays — against two invariants. This is the single place the rationale lives; the module, the prek hook, and the error output all point…
GitImplementedexperimentalRunnable implementation of the source-control (VCS) capability documented in tools/github/source-control.md. It extracts the abstraction the dev-loop skills assume — branch, stage, commit, diff, log, fetch, push, working-tree reset —…
A deterministic uv tool that scores Magpie's vendor neutrality from repository metadata alone — no network, no judgement at runtime. It answers the question raised in apache/magpie-site#17: *for each capability contract, does Magpie…
No tools match the selected filters.
Organizations
An organization bundles the defaults every project under it shares — which adapter fulfils each capability, the governance vocabulary, and the identity (incl. logo) the site renders. A project says organization: <id> once and inherits the rest. This is what lets the same skill run for an ASF project and a non-ASF one.
Running Magpie under a different foundation or company? Propose an organization bundle so every project under it inherits your defaults — start the conversation on the developer mailing list.
Email the dev list →Go deeper
This page is the at-a-glance map. The detailed write-ups — the six axes of neutrality, the contract-plus-adapter split, organizations, and the three "homes" an extension can live in — are in the framework docs.