Table of Contents generated with DocToc
Vendor neutrality is one of Magpie's non-negotiable design principles (PRINCIPLES.md §9, §3) and a top-to-bottom mission commitment (MISSION.md § Affordability and vendor neutrality). Those documents state that the framework is vendor-neutral and why. This page explains how — the architecture that delivers it, what is neutral by construction today, and where the extension points are for backends that do not yet have a reference implementation.
It is the answer to the recurring question “is Magpie really vendor neutral?” The honest answer starts with a distinction.
“Is X vendor neutral?” almost always collapses two very different questions into one:
These have different answers, and only the first is a meaningful test of neutrality:
So Magpie's claim is precise: the architecture is vendor-neutral, a range of backends already work end-to-end, nothing in the design prevents adding more, and adding one is a contribution against a documented contract — not a fork of the workflows. That is what “vendor neutral” means here, and it is the only definition that is both achievable and useful.
“Vendor” is not one thing. Magpie is neutral across six independent axes, and a backend choice on one axis never constrains the others:
| Axis | The “vendor” | Neutral by… |
|---|---|---|
| LLM backend | Anthropic, OpenAI, Google, Bedrock, local Ollama/vLLM, a future ASF endpoint | Skills written against a model contract (capability floor), not a client; a privacy gate that keys on endpoint identity, not on who hosts it |
| Agentic runtime | Claude Code, Codex, Cursor, Gemini CLI, Copilot, OpenCode, Kiro, … | Skills are AGENTS.md-standard markdown under a shared .agents/skills/ home that every runtime reads |
| Forge / tracker | GitHub, GitLab, Gitea, Forgejo, Pagure, Bitbucket, Jira, Bugzilla | Per-interface tools behind capability contracts; many tools are pure adapter specs with pluggable backends |
| Communication channels | Mailing lists, GitHub Discussions, Discourse, Zulip, Matrix, IRC | Mail-archive / mail-source adapter contracts; chat and forum bridges as sibling tools |
| Source control (VCS) | Git, Mercurial, Subversion, Jujutsu, Fossil, Perforce, … | A single VCSBackend contract; skills call the abstract operation, the backend is detected from the working copy |
| Project governance | ASF PMC, foundation-hosted, single-vendor, informal maintainer group | Modes and thresholds are adopter config; non-ASF adopters are first-class (PRINCIPLES.md §3) |
The rest of this page walks the mechanism that makes all six true, then states exactly where each axis stands today.
Magpie's neutrality is not a promise bolted onto the side — it falls out of a three-layer architecture. The same three layers explain the label taxonomy; here they are read as the neutrality mechanism.
SKILLS ── generic workflows, written in English, zero vendor names │ declare the capabilities they need ▼ CAPABILITIES ── the contract: "source-control", "CVE allocation", │ "mail archive read", "tracker write", … ▼ TOOLS ── the only layer that knows a vendor exists; one tool (or one adapter) per concrete backend, fulfilling a capability
A skill is a step-by-step workflow in markdown. By PRINCIPLES.md §9, a skill hard-coded to one vendor or model family is broken, not specialized. Skills name capabilities they need (“read the mail archive”, “open a change for review”, “allocate a CVE”), never a vendor's API. A concrete name (apache/airflow, a real CVE ID, a mailing-list address, git push) inside a skill is a refactor bug, not a shortcut (PRINCIPLES.md §12).
This is also why the workflows are portable across runtimes: a skill is plain English with a tool contract, which is exactly what the AGENTS.md standard describes. It is not a Claude artefact — it is a markdown file any capable agent can follow.
The framework is still finishing the migration of a few early skills that inlined vendor calls; that cleanup is tracked openly (search the repo's PRs for agnostic) and is a maintenance task, not an architectural gap.
Everything that knows a specific vendor exists is a tool under tools/. Two shapes:
apache-projects project-metadata MCP, a PonyMail MCP).Crucially, a large fraction of the tool layer is deliberately split into a contract plus interchangeable adapters, so adding a vendor is “write one adapter,” not “patch the framework.” Pure interface specs with pluggable backends already include:
| Contract tool | What plugs in behind it |
|---|---|
tools/cve-tool | CNA backends — Vulnogram, MITRE form, CVE.org direct, GHSA |
tools/mail-archive | PonyMail, Hyperkitty, Discourse, Google Groups, GitHub Discussions |
tools/mail-source | mbox, IMAP, Gmail API (tools/gmail), Mailman 3 |
tools/forwarder-relay | ASF Security relay, huntr.com, HackerOne triagers |
tools/scan-format | security-scanner report formats (ASVS reference) |
tools/vcs | Git (complete), Mercurial (complete), Subversion, … (extension points) |
The security-team surface follows the same pattern: CNA backends live behind tools/cve-tool (the ASF Vulnogram adapter tools/cve-tool-vulnogram is the landed reference), inbound report relays behind tools/forwarder-relay, scanner formats behind tools/scan-format, and an OSV.dev vulnerability cross-reference bridge is the open extension point (#311).
The distinction Magpie enforces: vendor-specific integrations are expected and welcome; vendor-specific workflows are forbidden. A GitHub tool is fine. A skill that only works because it assumes GitHub is a bug.
A capability is what a tool exposes to a skill — the stable verb a workflow depends on, independent of which vendor fulfils it. Every skill declares the capabilities it needs in its frontmatter; every tool declares the capabilities it provides in its README. The capability taxonomy is the canonical map of which skill needs what and which tool provides it.
Because the skill ↔ tool coupling is the capability and nothing else, swapping a backend is a config change, never a code change to the workflow. An adopter picks, under Tools enabled, which tool fulfils a capability; the same skill code runs on top.
The contract-plus-backend split above has a name. A tool adapter is the unit that fulfils a capability for one concrete backend. A capability contract — tools/<contract>/, a pure interface spec — defines the verbs a workflow needs; a tool adapter implements that contract for one vendor:
| Capability contract | Reference adapter(s) | Other backends (extension points) |
|---|---|---|
tools/cve-tool | tools/cve-tool-vulnogram (ASF) | MITRE form, CVE.org direct, GHSA |
tools/mail-archive | tools/ponymail (ASF) | Hyperkitty, Discourse, Google Groups, GitHub Discussions |
tools/mail-source | mbox, IMAP, Gmail API (tools/gmail) | Mailman 3 |
tools/forwarder-relay | ASF-security (tools/gmail/asf-relay.md) | huntr.com, HackerOne |
tools/scan-format | ASVS | other scanner formats |
tools/vcs | Git | Mercurial, Subversion, … |
A project selects an adapter per capability in its config (cve_authority.tool: vulnogram, archive_system.kind: ponymail, forwarders.enabled: [asf-security]); skill bodies never branch on the choice. Tool adapters are exactly where vendor specificity is allowed to live — and the reason adding a vendor is “write one adapter,” not a fork of the workflows.
Most adapter selections are identical for every project under one governing organization: every ASF project allocates CVEs through the same Vulnogram, reads the same lists.apache.org archive, and gates on PMC membership. An organization (organizations/<org>/) groups those shared defaults — the governance vocabulary (what the governing body is called, how contributors are admitted, the lifecycle stages) plus the capability→adapter bundle and infrastructure values — so they live once instead of in every project.
A project names its organization (organization: ASF) and inherits the rest; resolution is project.md → organizations/<org>/ → framework default, first hit wins. The reference organization is organizations/ASF/; organizations/independent/ is the no-formal-organization baseline. This is what lets the same skill run unchanged for an ASF project and a non-ASF one — the organization, not the skill, carries the difference. See organizations/README.md.
Neutrality is only real if adopters can extend it. When Magpie ships no adapter for your backend — a forge, a CNA, a chat system, or a whole organization profile — you author one, and you have two supported paths:
organizations/_template/ for an organization) and open a PR. Accepted adapters ship under Apache-2.0 like the rest of the framework (PRINCIPLES.md §17), so every other adopter on that backend reuses your work. The write-skill flow and CONTRIBUTING.md walk you through the conventions (a **Capability:** line, a ## Prerequisites section, an eval); the step-by-step how-to is docs/adapters/authoring.md.PRINCIPLES.md §13, the adapter index is for discovery, never for installation: nothing is auto-fetched, and you wire an external adapter in deliberately, exactly as you would a built-in one. (Trusted external skill sources are the one installable exception §13 carves out — pinned, verified, and adopter-vouched; see docs/skill-sources/.)Either way the skills stay agnostic: they target the capability, and your adapter — wherever it lives — supplies the backend. The same three homes (in-tree, your adopter repo, an external repo) apply to skills and whole organizations too — see docs/extending.md for the full extension model (by project, organization, or individual).
Skills are written against a declared capability floor (context window, tool use, vision, sustained reasoning) — never against a provider's SDK. Any backend that meets the floor is a valid backend, and the floor itself must be justified and minimised so it cannot become a vendor lock-in by proxy (PRINCIPLES.md §9).
The privacy-aware routing layer is the concrete proof: it ships end-to-end recipes for six LLM-stack variants and keys approval on the endpoint's identity, not on who hosts it (docs/setup/privacy-llm.md, RFC-AI-0003):
*.apache.org, default-approved)Affordability is part of neutrality, not separate from it: every release ships at least one configuration that runs end-to-end on a single developer machine (variants 2 and 3), even if individual skills run at reduced quality there. A maintainer for whom a frontier subscription is out of reach still gets the full skill catalogue.
Magpie skills are not a Claude Code feature. They are AGENTS.md-standard markdown, installed under a single canonical home — .agents/skills/ — which is the path shared by Codex, Cursor, Gemini CLI, Copilot and others, with thin relay symlinks giving every other agent directory (.claude/skills/, .github/skills/, …) a pointer to the same entry (README.md § snapshot + override). Users already run Magpie under several different agentic CLIs. Adding first-class features for another runtime is an family:tools contribution, not a re-architecture — and the extension points are already open, labelled good first issue: Codex, Gemini CLI, local LLM (Ollama / llama.cpp / vLLM), Cursor, Aider, GitHub Copilot, Goose, Amazon Q, JetBrains Junie, OpenHands. The step-by-step wiring recipe for any new runtime is docs/adapters/add-a-harness.md.
Forge and tracker access is mediated entirely by the tool layer: tools/github and tools/jira are substrate today, and the contract-plus-adapter tools above (mail-archive, mail-source, forwarder-relay, cve-tool, scan-format) already abstract the surfaces where more than one vendor exists. Skills speak to the capability, so a forge/tracker backend plugs in at the tool layer without the workflows knowing which forge answered — the recipe is documented in tools/github/tool.md § When to replace this tool (create a sibling tools/<name>/ with the same capability files; declare it under Tools enabled; no skill changes).
The forge/tracker extension points are open, labelled good first issue, not hypothetical: GitLab, Codeberg / Gitea / Forgejo, Pagure (Fedora / pagure.io), Bitbucket (initial tools/bitbucket partial-read-only bridge; deeper Jira pairing, complete change-request coverage, and write coverage tracked there), and SourceHut (email-patch review). Tracker-only surfaces are tracked the same way — e.g. Bugzilla — alongside the existing tools/jira bridge. The tracker capability and the source-control capability are separable: a project can pair, say, GitHub issues with a Subversion working copy, or a Bitbucket forge over Git, because each is a distinct contract.
Project conversation does not all live on the forge. The intake and mentoring skills read mailing-list archives, and a project may run its discussion on a forum or chat system instead of (or alongside) a list. Both surfaces sit behind adapter contracts:
tools/mail-archive — public archive reads across PonyMail, Hyperkitty, Discourse, Google Groups, GitHub Discussions.tools/mail-source — raw mail ingestion across mbox, IMAP, Mailman 3.The open extension points are labelled good first issue: mail-source backends — mbox, IMAP, Mailman 3 / Hyperkitty; and chat / forum bridges — Discourse, Zulip, Matrix / Element. A project on IRC, Slack, or any other channel plugs in the same way — a sibling tool fulfilling the read capability the mentoring / intake skills declare, with no skill change.
The newest axis to be abstracted, and a good worked example of the mechanism. Earlier, dev-loop skills inlined git … calls. Two changes fixed that:
tools/github/source-control.md defines the abstract operations skills are allowed to assume (branch, stage, commit, diff, log, fetch, push, working-tree reset), and every git-using skill was pointed at it.tools/vcs (magpie-vcs) runs the abstract operation and detects the active backend from the working copy.Today: Git and Mercurial are complete (the Git and Mercurial bindings); Subversion (#602) is a real, detected extension point that raises an actionable error naming its tracking issue until the full binding lands. Adding a backend means replacing one _UnimplementedBackend with a concrete VCSBackend subclass — detection, dispatch, the CLI, and every skill that calls magpie-vcs pick it up automatically. Nothing else changes.
The ASF SVN surface goes beyond the generic VCS binding: the tools/asf-svn/ adapter packages the SVN source-control binding together with ASF-specific capabilities that no other tool covers — dist.apache.org release staging/promotion/pruning and ASF committer/PMC authorization resolution. This means even a GitHub-hosted ASF project that uses Git for source control needs tools/asf-svn to steward its release flow through dist.apache.org.
Tracking issues exist, labelled good first issue, for the remaining non-Git/non-Hg systems: Subversion (generic VCS binding; tools/asf-svn covers the full ASF SVN surface including dist.apache.org and authorization), Jujutsu, Fossil, and Perforce — so the extension points are public and labelled, not hypothetical. (The Bitbucket and SourceHut forges, which carry their own VCS surfaces, are tracked under the forge axis above.)
Vendor neutrality extends to how a project is run, not just to its tooling. Each adopting project picks which modes run and how much automation fits its culture, whatever its governance — ASF PMC, foundation-hosted, single-vendor, or an informal maintainer group. The framework offers a range, never mandates a level, and non-ASF adopters are first-class adopters, not a compatibility afterthought (PRINCIPLES.md §3).
Neutrality is enforced, not just intended:
PRINCIPLES.md §9) — any committer may block it and the block holds until it complies.PRINCIPLES.md §8). Skill behaviour is graded against eval cases, including the abstraction layer it targets, so a regression toward a vendor-coupled shortcut is caught before release.The final piece is structural, and it is deliberately the ASF model: the framework's job is not to implement every backend — it is to provide a vendor-neutral architecture plus working reference implementations, and to make filling a gap an easy contribution.
write-skill meta-skill and the contributor guidelines walk a newcomer through authoring a new tool or skill against the contracts.Where the core team spends its own effort is a Pareto call, surfaced on the dev list and backed by usage data: jump-start the high-usage backends, leave the long tail to contributors who need them. That is not a neutrality gap — it is how an open-source framework scales coverage without pretending one team can implement an open-ended set.
| Axis | Architecture neutral? | Reference backends working today | Extension points |
|---|---|---|---|
| LLM backend | ✅ by construction | Claude Code, Ollama, vLLM, Apache-hosted, Bedrock, direct Anthropic | Any endpoint meeting the capability floor + privacy gate |
| Agentic runtime | ✅ by construction (AGENTS.md standard) | Claude Code; community use under Codex, Cursor, Gemini CLI, Copilot, OpenCode, Kiro | Runtime adapters #313–#322 |
| Forge / tracker | ✅ by construction | GitHub, Jira, SourceHut; Bitbucket partial-read-only foundation excluded from complete-backend counts; CVE/scan/relay via adapter contracts | GitLab #305, Forgejo/Gitea #310, Pagure #312, full Bitbucket tracker/change-request/Jira coverage #606, Bugzilla #302 |
| Communication channels | ✅ by construction | PonyMail / mail-archive reads | mbox #304, IMAP #303, Mailman 3 #306; Discourse #307, Zulip #308, Matrix #309 |
| Source control (VCS) | ✅ by construction | Git (complete), Mercurial (complete); ASF SVN surface (tools/asf-svn: source control + dist.apache.org + authorization) | Subversion generic VCS binding #602 (detected); Jujutsu #603, Fossil #604, Perforce #605 (tracked) |
| Project governance | ✅ by construction | ASF + non-ASF adopter profiles | Adopter config (modes, thresholds) |
✅ “by construction” means the workflows carry no vendor assumption; adding a backend is an adapter against a documented contract, not a change to any skill.
The six axes above are the narrative. This section is the measurement — a deterministic score computed straight from repository metadata by tools/vendor-neutrality-score, so the number is reproducible from the source tree and cannot quietly drift from the code.
Neutrality is measured per capability contract — the contract:* verbs a skill depends on. Substrate tools (Magpie's own machinery: sandboxing, analytics, framework-dev) are excluded, because they are not a vendor choice.
Every contract tool declares three fields in its README: **Capability:** (the contract it fulfils), **Kind:** (interface for a pure spec, implementation for a concrete backend), and **Vendor:** (the backend identity). The scorer reads them and applies one rule per contract class:
The overall score is green contracts / total contracts — a hard, falsifiable number. It moves only on shipping backends: add a second vendor for a contract and it flips to green on the next run; remove a backend and its contract flips back. The same rule then classifies every skill: capability-pure if it names no backend, portable if every backend it invokes has an alternative, and vendor-coupled only if it reaches for the sole implementation of a capability.
The same tool also measures the LLM-integration axis on two fronts. The agent harness (which runtime drives the skills): each substrate tool — Magpie's own machinery — declares **Harness:**, the harness it integrates with or agnostic, and a tool is harness-neutral when it is agnostic or supports two or more harnesses. The model endpoint (which LLM may receive data): the default-approved classes come straight from the privacy-llm registry, which keys approval on endpoint identity rather than vendor. Both appear in the generated block below.
Overall vendor-neutrality score: 10/10 capability contracts (100%). Generated by tools/vendor-neutrality-score; re-run it to refresh this section.
| Capability contract | Neutral? | Class | Backends today | Basis |
|---|---|---|---|---|
contract:tracker | ✅ | vendor-backed | Atlassian, Fossil, GitHub, SourceHut | 4 backend vendors: Atlassian, Fossil, GitHub, SourceHut |
contract:source-control | ✅ | vendor-backed | Fossil, Git, GitHub, SourceHut, Subversion | 5 backend vendors: Fossil, Git, GitHub, SourceHut, Subversion |
contract:change-request | ✅ | vendor-backed | Atlassian, GitHub, email | 3 backend vendors: Atlassian, GitHub, email |
contract:mail-archive | ✅ | vendor-backed | ASF, Google, SourceHut | 3 backend vendors: ASF, Google, SourceHut |
contract:mail-source | ✅ | vendor-backed | ASF, Google, Maildir | 3 backend vendors: ASF, Google, Maildir |
contract:mail-create | ✅ | vendor-backed | Google, Maildir | 2 backend vendors: Google, Maildir |
contract:cve-authority | ✅ | vendor-backed | CVE.org, Vulnogram | 2 backend vendors: CVE.org, Vulnogram |
contract:report-relay | ✅ | agnostic | — | vendor-neutral by construction — one spec serves every backend |
contract:scan-format | ✅ | agnostic | — | vendor-neutral by construction — one spec serves every backend |
contract:project-metadata | ✅ | single-org | ASF | single-organisation capability (ASF); no vendor choice to make |
Per-skill assessment: 70/70 skills carry no vendor lock-in. A skill is capability-pure when it names no backend at all, portable when every backend it names has an alternative (its contract is green), and vendor-coupled only when it reaches for a backend that is the sole implementation of a capability.
| Skill neutrality | Count |
|---|---|
| capability-pure (names no backend) | 11 |
| portable (named backends are swappable) | 59 |
| vendor-coupled (sole-backend dependency) | 0 |
Organization scope (declared, orthogonal to vendor): ASF = 14, agnostic = 56.
LLM / agent-integration neutrality
Agent harness: 22/22 substrate tools run under any harness unchanged (100%). Substrate tools are Magpie's own machinery; each declares the agent harness it integrates with (**Harness:**), or agnostic. A tool is neutral when it is harness-agnostic or supports two or more harnesses; coupled when it targets a single harness.
| Substrate tool | Substrate | Harness support | Verdict |
|---|---|---|---|
agent-guard | action-guard | Claude Code, Kiro, OpenCode | ✅ portable |
agent-isolation | sandbox | any | ✅ agnostic |
dashboard-generator | analytics | any | ✅ agnostic |
dev | framework-dev | any | ✅ agnostic |
egress-gateway | sandbox | any | ✅ agnostic |
permission-audit | sandbox | Claude Code, Kiro, OpenCode | ✅ portable |
pilot-report-validator | framework-dev | any | ✅ agnostic |
pr-management-stats | analytics | any | ✅ agnostic |
preflight-audit | analytics | any | ✅ agnostic |
privacy-llm | privacy | any | ✅ agnostic |
probe-templates | sandbox | any | ✅ agnostic |
sandbox-lint | sandbox | Claude Code, Kiro, OpenCode | ✅ portable |
security-tracker-stats-dashboard | analytics | any | ✅ agnostic |
skill-and-tool-validator | framework-dev | any | ✅ agnostic |
skill-evals | framework-dev | any | ✅ agnostic |
skill-reconciler-diff | framework-dev | any | ✅ agnostic |
spec-inventory | framework-dev, analytics | any | ✅ agnostic |
spec-loop | framework-dev | Claude Code, Codex, Cursor, Gemini CLI, Kiro, OpenCode | ✅ portable |
spec-status-index | framework-dev, analytics | any | ✅ agnostic |
spec-validator | framework-dev | any | ✅ agnostic |
symlink-lint | framework-dev | any | ✅ agnostic |
vendor-neutrality-score | framework-dev, analytics | any | ✅ agnostic |
Harness → substrate tools it supports:
agent-guard, permission-audit, sandbox-lint, spec-loopspec-loopspec-loopspec-loopagent-guard, permission-audit, sandbox-lint, spec-loopagent-guard, permission-audit, sandbox-lint, spec-loopagent-isolation, dashboard-generator, dev, egress-gateway, pilot-report-validator, pr-management-stats, preflight-audit, privacy-llm, probe-templates, security-tracker-stats-dashboard, skill-and-tool-validator, skill-evals, skill-reconciler-diff, spec-inventory, spec-status-index, spec-validator, symlink-lint, vendor-neutrality-scoreModel endpoint: neutral by construction — 4 default-approved endpoint classes across independent trust domains, plus adopter opt-in. From the privacy-llm registry: the framework 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 URL, data-residency contract, approver), so the choice is local and audited.
100% reads as: every one of the ten capabilities already works across more than one vendor — no axis of the architecture privileges a single vendor, and none is a design that assumes one. The last red cell, outbound mail composition (mail-create), closed when the local Maildir backend (tools/maildir/) landed as the second, non-Google implementation: an offline, credential-free writer that files editable drafts into a local Maildir for any mail client to send. A project that cannot or will not depend on Gmail can now drive every draft-producing skill. The number is not a finish line — new vendors keep arriving, and each must clear the same two-backend bar — but it does mean there is no vendor-locked capability left in the framework today.
The change-request gate — the pull-request review/merge contract that every skill driving gh pr resolves through — went green in #669. contract:tracker is green because Jira also handles issues, but Jira has no pull-request model; so change-request is a separate contract, and it now ships three backends across three vendors: GitHub pull requests (tools/github/), patches on JIRA issues landed via SVN (tools/jira-patch/), and [PATCH] threads on dev@ landed via SVN (tools/mail-patch/). The two SVN-first backends delegate their terminal land to contract:source-control and own only the proposal lifecycle. Every skill that drives gh pr is now portable without a line of skill code changing — the seam is the contract (tools/change-request/), not the workflow.
To keep the marketing honest and the engineering claim precise:
Where a single axis has exactly one reference backend working today (e.g. VCS = Git), the precise status is documented above rather than papered over — the neutrality is in the architecture and the open extension point, and the roadmap to more backends is public and labelled.
PRINCIPLES.md §9 — Vendor neutrality is non-negotiablePRINCIPLES.md §3 — Project autonomy is the structural starting pointMISSION.md § Affordability and vendor neutralitydocs/labels-and-capabilities.md — the skill / tool / capability taxonomy this page reads as the neutrality mechanismdocs/setup/privacy-llm.md — the six LLM-stack variantsdocs/rfcs/RFC-AI-0004.md § Principle 3 — vendor neutrality as a baseline ethics principletools/vcs/ and tools/github/source-control.md — the VCS abstraction worked exampledocs/mode-economics.md — what each mode costs to run, per model class