Skip to content

docs: explain how vendor neutrality is achieved - #613

Merged
potiuk merged 1 commit into
mainfrom
docs/vendor-neutrality-how
Jun 29, 2026
Merged

potiuk merged 1 commit into
mainfrom
docs/vendor-neutrality-how

Conversation

@potiuk

@potiuk potiuk commented Jun 29, 2026

Copy link
Copy Markdown
Member

What

Adds docs/vendor-neutrality.md — the authoritative explanation of how
Magpie achieves vendor neutrality — and wires it into docs/index.md and
PRINCIPLES.md §9.

Why

The framework already asserts vendor neutrality (PRINCIPLES.md §9/§3,
MISSION.md § Affordability, RFC-AI-0004 §3), but the mechanism was
scattered across labels-and-capabilities.md, setup/privacy-llm.md,
tools/vcs/, and README.md. No single doc answered the recurring question
"is Magpie really vendor neutral, and how?" — raised most recently on the
website tracker (apache/magpie-site#17).

What the new doc says

  • Separates the two questions that get conflated — is the architecture
    vendor-neutral (yes, by construction) vs. is every vendor already
    implemented and hardened (impossible for anyone, and not what neutrality
    means).
  • Five axes — LLM, agentic runtime, forge/tracker, VCS, project
    governance — each independent.
  • Reads the skills / tools / capabilities model as the mechanism: skills
    target the abstraction, tools are the only vendor-specific layer,
    capabilities are the contract — backed by the real adapter-contract tools
    (cve-tool, mail-archive, mail-source, forwarder-relay,
    scan-format, vcs).
  • Honest per-axis status (e.g. VCS = Git complete, Hg/SVN detected
    extension points, the rest tracked), a status-at-a-glance table, and an
    explicit does / does-not claim section so website wording stays accurate.
  • What keeps it neutral over time (blockable on principle, capability-floor
    minimisation, eval discipline) and the contribution model.

Notes

  • All hooks pass (markdownlint, lychee link check, doctoc, typos).
  • Docs-only; no skill/tool/spec changes.

🤖 Generated with Claude Code

The framework asserts vendor neutrality in PRINCIPLES.md §9/§3, MISSION.md,
and RFC-AI-0004 §3, but the *mechanism* was scattered across
labels-and-capabilities.md, setup/privacy-llm.md, tools/vcs/, and README.md.
No single doc answered "how is vendor neutrality actually achieved?" — the
recurring question raised on the website tracker (apache/magpie-site#17).

Add docs/vendor-neutrality.md as the authoritative explanation:

- Separates the two questions that get conflated — is the *architecture*
  vendor-neutral (yes, by construction) vs is *every* vendor already
  implemented (impossible for anyone, and not what neutrality means).
- Names the five axes (LLM, agentic runtime, forge/tracker, VCS, project
  governance) and shows each is independent.
- Reads the skills / tools / capabilities model as the neutrality mechanism:
  skills target the abstraction, tools are the only vendor-specific layer,
  capabilities are the contract; backed by the real adapter-contract tools
  (cve-tool, mail-archive, mail-source, forwarder-relay, scan-format, vcs).
- Documents the per-axis status honestly (e.g. VCS = Git complete, Hg/SVN
  detected extension points, the rest tracked) with a status-at-a-glance
  table and an explicit does/does-not-claim section.
- Covers what keeps it neutral over time (principle block, capability-floor
  minimisation, eval discipline) and the contribution model.

Wire it in: a "Where to go next" row in docs/index.md and a pointer from
PRINCIPLES.md §9 to the new how-to doc.

Generated-by: Claude Code (Opus 4.8)
@potiuk
potiuk merged commit 22b9ca6 into main Jun 29, 2026
28 checks passed
@potiuk
potiuk deleted the docs/vendor-neutrality-how branch June 29, 2026 02:02
@potiuk potiuk added the family:docs Docs, MISSION.md, READMEs label Nov 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

family:docs Docs, MISSION.md, READMEs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant