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 @@ + + +**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) + + + + + +# 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//` 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/-/` (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:** ` line if the adapter belongs + to a specific organization. +4. **Wire it in.** Point your `/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//`, fill in `organization.md` (identity incl. `logo`, +governance vocabulary, and the backend bundle), and point projects at it +with `organization: `. 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 @@ + + +**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) + + + + + +# 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.md` (or `organizations//`) 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//` 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: `. 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)).