You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/06/29 06:07:37 UTC
(magpie) branch docs/adapter-registry created (now 6138de96)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a change to branch docs/adapter-registry
in repository https://gitbox.apache.org/repos/asf/magpie.git
at 6138de96 docs(adapters): add external-adapter discovery index + authoring guide
This branch includes the following new commits:
new 6138de96 docs(adapters): add external-adapter discovery index + authoring guide
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(magpie) 01/01: docs(adapters): add external-adapter discovery index + authoring guide
Posted by po...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch docs/adapter-registry
in repository https://gitbox.apache.org/repos/asf/magpie.git
commit 6138de96a1bbbe3b96821ec4b8306028ee1ff0c8
Author: Tester <t...@example.com>
AuthorDate: Mon Jun 29 08:07:23 2026 +0200
docs(adapters): add external-adapter discovery index + authoring guide
Completes the "link to adapters defined elsewhere" path with concrete
artifacts.
- docs/adapters/registry.md — a discovery-only index of in-tree tool
adapters (per capability contract, with shipping adapters + tracked
extension points), in-tree organizations, and a table for
community/external adapters maintained outside the repo. States the
discovery-not-installation rule (PRINCIPLES §13): nothing is
auto-fetched; an external link is a pointer to evaluate, and adopters
wire an adapter in deliberately.
- docs/adapters/authoring.md — the step-by-step how-to for authoring a
tool adapter (find the contract → implement → declare capability +
prerequisites + optional organization → wire in → add an eval) or an
organization, with the contribute-upstream vs keep-external trade-off.
Wire-in: vendor-neutrality "Authoring your own adapter" now links both;
docs/index.md gains a "Find or author a backend adapter" row;
organizations/README points its authoring section at the new guide.
Generated-by: Claude Code (Opus 4.8)
---
docs/adapters/authoring.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++
docs/adapters/registry.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++
docs/index.md | 1 +
docs/vendor-neutrality.md | 8 +++--
organizations/README.md | 3 +-
5 files changed, 176 insertions(+), 4 deletions(-)
diff --git a/docs/adapters/authoring.md b/docs/adapters/authoring.md
new file mode 100644
index 00000000..2693160b
--- /dev/null
+++ b/docs/adapters/authoring.md
@@ -0,0 +1,84 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Authoring an adapter](#authoring-an-adapter)
+ - [Two homes for an adapter](#two-homes-for-an-adapter)
+ - [Authoring a tool adapter](#authoring-a-tool-adapter)
+ - [Authoring an organization](#authoring-an-organization)
+ - [After authoring](#after-authoring)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Authoring an adapter
+
+When Magpie ships no [adapter](../vendor-neutrality.md#tool-adapters) for
+your backend — a forge, a CNA tool, a chat system, a mail archive, a VCS,
+or a whole [organization](../../organizations/README.md) profile — you
+author one. The skills stay agnostic: they target a *capability*, and
+your adapter supplies the concrete backend. This guide is the how-to; the
+[registry](registry.md) is the index of what already exists.
+
+## Two homes for an adapter
+
+| | Contribute to Magpie | Keep it external |
+|---|---|---|
+| **Where it lives** | a PR into `apache/magpie` | your own repository |
+| **License** | Apache-2.0 ([§17](../../PRINCIPLES.md#17-contributions-land-under-apache-license-20)) | yours |
+| **Who reuses it** | every adopter on that backend | you (and anyone you share it with) |
+| **Discovery** | shipped in-tree | optionally listed in the [registry](registry.md) |
+| **Install** | part of the snapshot | you wire it in deliberately — never auto-fetched ([§13](../../PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies)) |
+
+Both are first-class. Contributing upstream is preferred when the backend
+is one other projects share; an external adapter is right when it is
+specific to you or you are not ready to upstream.
+
+## Authoring a tool adapter
+
+A tool adapter fulfils a capability *contract* for one backend.
+
+1. **Find the contract.** Pick the `tools/<contract>/` whose capability
+ you are implementing (e.g. [`tools/cve-tool/`](../../tools/cve-tool/)
+ for a CNA tool, [`tools/mail-archive/`](../../tools/mail-archive/) for
+ an archive). Its README enumerates the methods/verbs your adapter must
+ provide. If no contract exists for the capability, propose one first.
+2. **Create the adapter directory** — `tools/<contract>-<backend>/` (in
+ tree) or a directory in your own repo (external). Implement the
+ contract's operations.
+3. **Declare the metadata** the validator requires (see
+ [`tools/AGENTS.md`](../../tools/AGENTS.md)):
+ - a `**Capability:** capability:NAME` line in the README;
+ - a `## Prerequisites` section (runtime, CLIs, credentials, network);
+ - optionally an `**Organization:** <org>` line if the adapter belongs
+ to a specific organization.
+4. **Wire it in.** Point your `<project-config>/project.md` *Tools
+ enabled* manifest (or the relevant capability key, e.g.
+ `cve_authority.tool`) at the adapter. Skill bodies never change.
+5. **Add an eval** ([§8](../../PRINCIPLES.md#8-eval-is-a-release-blocking-discipline))
+ under `tools/skill-evals/evals/` so the adapter's behaviour is graded,
+ not just demoed.
+
+The [`write-skill`](../../skills/write-skill/SKILL.md) flow and
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md) walk the conventions in detail;
+`skill-and-tool-validate` enforces the capability + prerequisites lines.
+
+## Authoring an organization
+
+An organization groups governance vocabulary + capability→adapter
+selections + identity for every project under one governing body. To add
+one, copy [`organizations/_template/`](../../organizations/_template/) to
+`organizations/<org>/`, fill in `organization.md` (identity incl. `logo`,
+governance vocabulary, and the backend bundle), and point projects at it
+with `organization: <org>`. See
+[`organizations/README.md`](../../organizations/README.md).
+
+## After authoring
+
+- **Contributing upstream?** Open the PR; once it merges and adopters run
+ `/magpie-setup upgrade`, the adapter is available to everyone.
+- **Keeping it external?** Optionally add a row to the
+ [registry](registry.md#community--external-adapters) so others can
+ discover it — discovery only, no install.
diff --git a/docs/adapters/registry.md b/docs/adapters/registry.md
new file mode 100644
index 00000000..4eb5cf4b
--- /dev/null
+++ b/docs/adapters/registry.md
@@ -0,0 +1,84 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Adapter registry](#adapter-registry)
+ - [In-tree tool adapters](#in-tree-tool-adapters)
+ - [In-tree organizations](#in-tree-organizations)
+ - [Community / external adapters](#community--external-adapters)
+ - [Adding an external adapter to this index](#adding-an-external-adapter-to-this-index)
+ - [See also](#see-also)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Adapter registry
+
+A **discovery** index of the [tool adapters](../vendor-neutrality.md#tool-adapters)
+and [organizations](../../organizations/README.md) Magpie knows about —
+the ones that ship in-tree, the open extension points, and links to
+**community-maintained adapters defined elsewhere**.
+
+> **Discovery, never installation.** Per
+> [`PRINCIPLES.md` §13](../../PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies),
+> this page is an index, not a package manager. Nothing here is
+> auto-fetched. To use an adapter you wire it in deliberately — point
+> your `<project-config>/project.md` (or `organizations/<org>/`) at it,
+> exactly as you would a built-in one. An external link is a pointer for
+> humans to evaluate, not a supply-chain hook.
+
+To author a new adapter, see [`authoring.md`](authoring.md).
+
+## In-tree tool adapters
+
+Each capability contract under `tools/<contract>/` enumerates the
+adapters that fulfil it. Shipping = a working adapter in the tree;
+extension point = a documented, labelled slot with a tracking issue.
+
+| Capability contract | Shipping adapter(s) | Extension points (tracked) |
+|---|---|---|
+| [`tools/cve-tool`](../../tools/cve-tool/) | [`cve-tool-vulnogram`](../../tools/cve-tool-vulnogram/) (ASF) | MITRE form, CVE.org direct, GHSA |
+| [`tools/mail-archive`](../../tools/mail-archive/) | [`ponymail`](../../tools/ponymail/) (ASF) | Hyperkitty, Discourse, Google Groups, GitHub Discussions |
+| [`tools/mail-source`](../../tools/mail-source/) | mbox, IMAP | Mailman 3 ([#306](https://github.com/apache/magpie/issues/306)) |
+| [`tools/forwarder-relay`](../../tools/forwarder-relay/) | ASF-security ([`tools/gmail/asf-relay.md`](../../tools/gmail/asf-relay.md)) | huntr.com, HackerOne, GHSA relay |
+| [`tools/scan-format`](../../tools/scan-format/) | ASVS | other scanner formats |
+| [`tools/vcs`](../../tools/vcs/) | Git | Mercurial [#601](https://github.com/apache/magpie/issues/601), Subversion [#602](https://github.com/apache/magpie/issues/602), Jujutsu [#603](https://github.com/apache/magpie/issues/603), Fossil [#604](https://github.com/apache/magpie/issues/604), Perforce [#605](https://github.com/apache/magpie/issues/605) |
+| Forge / tracker | [`github`](../../tools/github/), [`jira`](../../tools/jira/) | GitLab [#305](https://github.com/apache/magpie/issues/305), Forgejo/Gitea [#310](https://github.com/apache/magpie/issues/310), Pagure [#312](https://github.com/apache/magpie/issues/312), Bitbucket [#606](https://github.com/apache/magpie/issues/606), SourceHut [#607](https://github.com/apache/magpie/issues/607), Bugzilla [#302](https://github.com/apache/magpie/issues/302) |
+| Agentic runtime | Claude Code | Codex [#313](https://github.com/apache/magpie/issues/313)–OpenHands [#322](https://github.com/apache/magpie/issues/322) |
+| Security cross-ref | — | OSV.dev [#311](https://github.com/apache/magpie/issues/311) |
+
+## In-tree organizations
+
+| Organization | Directory |
+|---|---|
+| Apache Software Foundation | [`organizations/ASF/`](../../organizations/ASF/) |
+| Independent (no formal governing body) | [`organizations/independent/`](../../organizations/independent/) |
+
+## Community / external adapters
+
+Adapters maintained **outside** this repository — kept in their authors'
+own repos and linked here for discovery. An adopter wires one in by
+pointing their config at it (see the discovery-not-installation note
+above); the framework never fetches them.
+
+| Adapter | Capability / org | Maintainer | Link | Notes |
+|---|---|---|---|---|
+| *(none listed yet)* | | | | Open a PR to add a row — see below. |
+
+### Adding an external adapter to this index
+
+Open a PR against `apache/magpie` that adds one row to the table above
+with: the adapter name, the capability contract (or organization) it
+implements, the maintainer, a link to its repository, and a one-line
+note. Listing here is **editorial discovery only** — it makes no
+guarantee about the adapter and triggers no install. Adapters you would
+rather contribute into the tree itself follow [`authoring.md`](authoring.md)
+instead.
+
+## See also
+
+- [`docs/vendor-neutrality.md`](../vendor-neutrality.md) — how tool adapters and organizations deliver neutrality.
+- [`authoring.md`](authoring.md) — authoring your own adapter.
+- [`organizations/README.md`](../../organizations/README.md) — the organization entity.
diff --git a/docs/index.md b/docs/index.md
index 399bd302..31f58532 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -120,6 +120,7 @@ from mailing lists, slack etc.
|---|---|
| Understand the full vision | [MISSION.md](../MISSION.md) |
| Understand how it stays vendor-neutral | [vendor-neutrality.md](vendor-neutrality.md) |
+| Find or author a backend adapter | [adapters/registry.md](adapters/registry.md) |
| See what skills exist today | [modes.md](modes.md) |
| Adopt in my project | [README → Adopting](../README.md#adopting-the-framework) |
| Set up the secure agent sandbox | [setup/](setup/README.md) |
diff --git a/docs/vendor-neutrality.md b/docs/vendor-neutrality.md
index a4a6347f..6ef6978e 100644
--- a/docs/vendor-neutrality.md
+++ b/docs/vendor-neutrality.md
@@ -248,11 +248,13 @@ organization profile — you author one, and you have two supported paths:
so every other adopter on that backend reuses your work. The
[`write-skill`](../skills/write-skill/SKILL.md) flow and
[`CONTRIBUTING.md`](../CONTRIBUTING.md) walk you through the conventions
- (a `**Capability:**` line, a `## Prerequisites` section, an eval).
+ (a `**Capability:**` line, a `## Prerequisites` section, an eval); the
+ step-by-step how-to is [`docs/adapters/authoring.md`](adapters/authoring.md).
- **Link to an adapter defined elsewhere.** You do not have to upstream
it. Keep the adapter in your own repository and point your project or
- organization config at it. The framework curates a discovery index of
- in-tree and community-maintained adapters — but, per
+ organization config at it. The framework curates a
+ [discovery index](adapters/registry.md) of in-tree and
+ community-maintained adapters — but, per
[`PRINCIPLES.md` §13](../PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies),
an index is **for discovery, never for installation**: nothing is
auto-fetched, and you wire an external adapter in deliberately, exactly
diff --git a/organizations/README.md b/organizations/README.md
index 04fec51c..6b0f0fa8 100644
--- a/organizations/README.md
+++ b/organizations/README.md
@@ -97,4 +97,5 @@ governance vocabulary and the capability→adapter bundle, and point your
project at it with `organization: <org>`. You can then either
**contribute it back** to `apache/magpie` under Apache-2.0 (so other
projects in your organization reuse it) or keep it local. See
-[`docs/vendor-neutrality.md` § Authoring your own adapter](../docs/vendor-neutrality.md#authoring-your-own-adapter).
+[`docs/adapters/authoring.md`](../docs/adapters/authoring.md) (and
+[`docs/vendor-neutrality.md` § Authoring your own adapter](../docs/vendor-neutrality.md#authoring-your-own-adapter)).