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:22:16 UTC
(magpie) branch docs/extension-model created (now cb907a53)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a change to branch docs/extension-model
in repository https://gitbox.apache.org/repos/asf/magpie.git
at cb907a53 docs: document the extension model + allow external/own-repo organizations
This branch includes the following new commits:
new cb907a53 docs: document the extension model + allow external/own-repo organizations
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: document the extension model + allow external/own-repo organizations
Posted by po...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch docs/extension-model
in repository https://gitbox.apache.org/repos/asf/magpie.git
commit cb907a53dd3bc7e026bf7028a69c4d89b419ee3a
Author: Tester <t...@example.com>
AuthorDate: Mon Jun 29 08:22:05 2026 +0200
docs: document the extension model + allow external/own-repo organizations
Make "external / own-repo" a first-class home for organizations (as it
already is for adapters), and add one guide explaining every way Magpie
can be extended.
- docs/extending.md (new): what you can extend (skill, tool/adapter,
capability contract, organization, project config, user config), the
three homes each can live in (in-tree / your adopter repo / external
repo) with a trade-off table, and who typically owns each (project /
organization / individual). Reiterates discovery-not-installation (§13).
- AGENTS.md: the organization resolution order now includes an
adopter-local / external org home —
`.apache-magpie-overrides/organizations/<org>/` — so `organization:`
need not name an in-tree org.
- organizations/README.md: new "three homes" note for an organization
(in-tree / adopter repo / org's own repo) + the resolution order.
- docs/adapters/authoring.md: "two homes" → "three homes" (adds the
adopter-repo override home) for consistency.
- Wire-in: docs/index.md "Extend Magpie" row; vendor-neutrality +
adapter registry link the new guide.
Generated-by: Claude Code (Opus 4.8)
---
AGENTS.md | 12 ++++-
docs/adapters/authoring.md | 31 +++++++-----
docs/adapters/registry.md | 1 +
docs/extending.md | 124 +++++++++++++++++++++++++++++++++++++++++++++
docs/index.md | 1 +
docs/vendor-neutrality.md | 5 +-
organizations/README.md | 28 +++++++---
7 files changed, 179 insertions(+), 23 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index d59f6e49..cd2bc1d1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -308,10 +308,20 @@ Every placeholder and dotted config key then resolves in this order,
```text
<project-config>/project.md
- → organizations/<org>/organization.md (org named by project.md → organization:)
+ → organizations/<org>/organization.md (in-tree org)
+ → <project-config>/.apache-magpie-overrides/organizations/<org>/organization.md (adopter-local / external org)
→ framework default
```
+The organization an `organization:` value names need **not** be in-tree.
+The framework ships `organizations/ASF/` and `organizations/independent/`,
+but an organization Magpie does not ship is resolved from an
+adopter-local copy under `.apache-magpie-overrides/organizations/<org>/`
+— maintained in the adopter's repo or vendored from the organization's
+own repo (discovery, never auto-fetch, per
+[`PRINCIPLES.md` §13](PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies)).
+See [`docs/extending.md`](docs/extending.md) for the full extension model.
+
A project declares only what differs from its organization; an
organization declares only what differs from the framework baseline
(`organizations/independent/` is that baseline). This is the only
diff --git a/docs/adapters/authoring.md b/docs/adapters/authoring.md
index 2693160b..b9881ea9 100644
--- a/docs/adapters/authoring.md
+++ b/docs/adapters/authoring.md
@@ -3,7 +3,7 @@
**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)
+ - [Three homes for an adapter](#three-homes-for-an-adapter)
- [Authoring a tool adapter](#authoring-a-tool-adapter)
- [Authoring an organization](#authoring-an-organization)
- [After authoring](#after-authoring)
@@ -22,19 +22,22 @@ 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.
+## Three homes for an adapter
+
+| | In-tree (upstream) | In your adopter repo | External (another repo) |
+|---|---|---|---|
+| **Where it lives** | a PR into `apache/magpie` | `<project-config>/.apache-magpie-overrides/` | a repo you/the community maintain |
+| **License** | Apache-2.0 ([§17](../../PRINCIPLES.md#17-contributions-land-under-apache-license-20)) | yours | the author's |
+| **Who reuses it** | every adopter on that backend | your project | anyone who wires it in |
+| **Discovery** | shipped in-tree | committed in your repo | optionally listed in the [registry](registry.md) |
+| **Install** | part of the snapshot | committed override | you wire it in deliberately — never auto-fetched ([§13](../../PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies)) |
+
+All three are first-class. Contribute upstream when the backend is one
+other projects share; keep it in your adopter repo when it is specific to
+your project; keep it external when a third party maintains it or it is
+shared across your repos but not in Magpie. See
+[`docs/extending.md`](../extending.md) for the same model applied to every
+extension type.
## Authoring a tool adapter
diff --git a/docs/adapters/registry.md b/docs/adapters/registry.md
index 4eb5cf4b..09885a74 100644
--- a/docs/adapters/registry.md
+++ b/docs/adapters/registry.md
@@ -79,6 +79,7 @@ instead.
## See also
+- [`docs/extending.md`](../extending.md) — the full extension model (what / where / who).
- [`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/extending.md b/docs/extending.md
new file mode 100644
index 00000000..22322b77
--- /dev/null
+++ b/docs/extending.md
@@ -0,0 +1,124 @@
+<!-- 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)*
+
+- [Extending Magpie](#extending-magpie)
+ - [What you can extend](#what-you-can-extend)
+ - [Where an extension can live (the three homes)](#where-an-extension-can-live-the-three-homes)
+ - [How each entity resolves across homes](#how-each-entity-resolves-across-homes)
+ - [Who extends what](#who-extends-what)
+ - [A project (adopter)](#a-project-adopter)
+ - [An organization (foundation / company / collective)](#an-organization-foundation--company--collective)
+ - [An individual](#an-individual)
+ - [Contributing an extension back](#contributing-an-extension-back)
+ - [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 -->
+
+# Extending Magpie
+
+Magpie is built to be extended without forking it. This page is the map:
+**what** you can extend, **where** an extension can live, and **who**
+typically owns each kind.
+
+If you only remember one rule: extensions are **discovered and wired in
+deliberately, never auto-installed** — per
+[`PRINCIPLES.md` §13](../PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies),
+indexes and catalogs exist for discovery, not installation.
+
+## What you can extend
+
+| Entity | What it is | Reference |
+|---|---|---|
+| **Skill** | a workflow the agent follows | [`PRINCIPLES.md` §14](../PRINCIPLES.md#14-skills-are-the-unit-of-authorship), [`write-skill`](../skills/write-skill/SKILL.md) |
+| **Tool / tool adapter** | the only layer that knows a vendor — a backend behind a capability contract | [vendor-neutrality § Tool adapters](vendor-neutrality.md#tool-adapters), [`adapters/authoring.md`](adapters/authoring.md) |
+| **Capability contract** | the stable verb set a skill depends on; the seam adapters plug into | [`tools/cve-tool/`](../tools/cve-tool/) and siblings |
+| **Organization** | governance vocabulary + backend bundle + identity, shared by an org's projects | [`organizations/README.md`](../organizations/README.md) |
+| **Project config** | one adopter's concrete values | [`projects/_template/`](../projects/_template/) |
+| **User config** | one person's preferences (handle, governance membership, local clone paths) | [`AGENTS.md` § user.md](../AGENTS.md#usermd-resolution-order) |
+
+## Where an extension can live (the three homes)
+
+Every extension — a skill, an adapter, or a whole organization — has the
+same three possible homes. They are not mutually exclusive: start local,
+upstream later.
+
+| Home | Where | Travels with | Licence | Best when |
+|---|---|---|---|---|
+| **In-tree** (upstream) | a PR into `apache/magpie` | the framework, to every adopter | Apache-2.0 ([§17](../PRINCIPLES.md#17-contributions-land-under-apache-license-20)) | the extension is broadly useful — other projects share the backend/org |
+| **In your adopter repo** | `<project-config>/` + `<project-config>/.apache-magpie-overrides/` (committed) | your repo | yours | it is specific to your project, or not ready to upstream |
+| **External** (another repo) | a repo you (or a community) maintain, **referenced** from config | nothing automatically — you vendor/clone it in deliberately | the author's | a third party maintains it, or it is shared across your repos but not in Magpie |
+
+The middle home is the framework's **snapshot + override** model
+([§13](../PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies)):
+the framework is a gitignored snapshot; your additions and tweaks are
+committed agent-readable markdown alongside it. The external home is the
+same act of wiring-in as the middle one — you just keep the source in
+another repo and the [registry](adapters/registry.md) lists it for
+discovery.
+
+### How each entity resolves across homes
+
+- **Skills** — framework skills come from the snapshot; project tweaks
+ live in `.apache-magpie-overrides/<skill>.md` (consulted at run time);
+ a wholly new skill you keep can live in your repo's agent-skill dir.
+- **Tools / adapters** — selected per capability in
+ `<project-config>/project.md` *Tools enabled*. The selected adapter may
+ be an in-tree `tools/<name>/`, a directory you keep in your adopter
+ repo, or one you vendored from an external repo. Skills never branch on
+ the choice. See [`adapters/authoring.md`](adapters/authoring.md).
+- **Organizations** — `organization: <org>` in `project.md` resolves to
+ an in-tree [`organizations/<org>/`](../organizations/README.md) first;
+ if your organization is not in-tree, it resolves to an adopter-local
+ org adapter you keep under `<project-config>/.apache-magpie-overrides/organizations/<org>/`
+ (copied from your own or another repo). Either way the resolution chain
+ is `project.md → organization → framework default`.
+
+## Who extends what
+
+### A project (adopter)
+
+Owns its `<project-config>/`: identity, per-skill config, and
+`.apache-magpie-overrides/` for behaviour tweaks. A project may also
+keep a **local organization or adapter** in its override layer when no
+in-tree one fits — and upstream it later with
+[`setup-override-upstream`](../skills/setup-override-upstream/SKILL.md).
+
+### An organization (foundation / company / collective)
+
+Owns an **organization adapter** — the defaults every project under it
+inherits (CVE authority, mail/forwarder/archive backends, governance
+vocabulary, identity + logo). It can ship that adapter **in-tree**
+(contributed to `apache/magpie`, so all its projects and others reuse it)
+or maintain it **in the organization's own repo** and have member
+projects point at it. See [`organizations/README.md`](../organizations/README.md).
+
+### An individual
+
+Owns their `user.md` (per-user preferences, resolved first-match across
+`$APACHE_MAGPIE_USER_CONFIG` → `~/.config/apache-magpie/user.md` →
+`<project-config>/user.md`). An individual can also **author** any skill,
+adapter, or organization above and choose a home for it — contribute it
+upstream, keep it in their project's override layer, or maintain it in a
+personal repo and link it.
+
+## Contributing an extension back
+
+Whatever the home you start with, upstreaming is one PR away and benefits
+every adopter:
+
+- a **skill** — [`write-skill`](../skills/write-skill/SKILL.md) +
+ [`CONTRIBUTING.md`](../CONTRIBUTING.md);
+- a **tool/adapter or organization** —
+ [`adapters/authoring.md`](adapters/authoring.md);
+- an **override you have been running** —
+ [`setup-override-upstream`](../skills/setup-override-upstream/SKILL.md).
+
+## See also
+
+- [`docs/vendor-neutrality.md`](vendor-neutrality.md) — the skills / tools / capabilities / organizations architecture.
+- [`docs/adapters/registry.md`](adapters/registry.md) — discovery index of in-tree and external adapters.
+- [`organizations/README.md`](../organizations/README.md) — the organization entity and its resolution order.
diff --git a/docs/index.md b/docs/index.md
index 31f58532..5c51d26f 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -121,6 +121,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) |
+| Extend Magpie (project / org / individual) | [extending.md](extending.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 6ef6978e..2310ae26 100644
--- a/docs/vendor-neutrality.md
+++ b/docs/vendor-neutrality.md
@@ -261,7 +261,10 @@ organization profile — you author one, and you have two supported paths:
as you would a built-in one.
Either way the skills stay agnostic: they target the capability, and your
-adapter — wherever it lives — supplies the backend.
+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`](extending.md) for the full
+extension model (by project, organization, or individual).
## How each axis is delivered
diff --git a/organizations/README.md b/organizations/README.md
index 6b0f0fa8..66677ae7 100644
--- a/organizations/README.md
+++ b/organizations/README.md
@@ -92,10 +92,24 @@ not branch on the organization.
## Authoring a new organization
-Copy [`_template/`](_template/) to `organizations/<org>/`, fill in the
-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/adapters/authoring.md`](../docs/adapters/authoring.md) (and
-[`docs/vendor-neutrality.md` § Authoring your own adapter](../docs/vendor-neutrality.md#authoring-your-own-adapter)).
+Copy [`_template/`](_template/) to fill in the governance vocabulary, the
+capability→adapter bundle, and the identity (incl. `logo`), then point a
+project at it with `organization: <org>`.
+
+An organization can live in any of three homes (see
+[`docs/extending.md`](../docs/extending.md) for the full model):
+
+- **In-tree** — `organizations/<org>/` here, contributed to
+ `apache/magpie` under Apache-2.0 so every project under the
+ organization (and others) reuses it.
+- **In your adopter repo** — `<project-config>/.apache-magpie-overrides/organizations/<org>/`,
+ committed in the adopter repo when the organization is not (yet)
+ in-tree.
+- **In the organization's own repo** — maintained externally and vendored
+ into the adopter's override location; discovery, never auto-fetch
+ ([`PRINCIPLES.md` §13](../PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies)).
+
+`organization: <org>` resolves in-tree first, then the adopter-local
+copy. See
+[`docs/adapters/authoring.md`](../docs/adapters/authoring.md) for the
+authoring how-to.