msd-core/docs/registries/README.md

MSD Registries: Community Capability Registry, EoS Registry & Reviewer Lane Registry

Specification, entry schema, and submission process for MSD's three third-party discoverability catalogs — the MSD Community Capability Registry, the MSD EoS Registry, and the MSD Reviewer Lane Registry.

---

Non-endorsement stance

Inclusion in this registry means only that a maintainer merged a PR that linked to the author's repository. It is not an endorsement. MSD has not reviewed, tested, audited, or verified the correctness, quality, safety, or security of any listed solution, nor its claimed MSD interactions. Use at your own risk; evaluate the linked source yourself. Entries are removed only for illegal content, malware, spam, or a link that is dead/completely non-functional — never curated for quality.

This stance applies identically to every entry in all three registries. It is reproduced verbatim at the top of each generated catalog (capability-registry.md, eos-registry.md, reviewer-registry.md).

Narrow removal policy

A merged entry is removed only for one of these reasons:

• The linked content is illegal.
• The linked repository distributes malware.
• The entry is spam (not a genuine, working solution).
• The linked repository or its default branch is dead or completely non-functional (404, archived-and-empty, permanently inaccessible).

A registry entry is never removed for quality, staleness of a working project, disagreement with its design, or because a maintainer would have built it differently. The registry is a directory, not a curated marketplace — see Non-endorsement stance above.

---

What gets listed

Three independent catalogs, sharing one schema shape, one non-endorsement stance, and one submission process:

• Community Capability Registry (docs/registries/capability-registry.md, generated from docs/registries/capabilities.json) — third-party Feature Capabilities: plug-ins that attach at MSD's Loop Extension Points (ADR-857, ADR-894, ADR-1244) and are installed with msd capability install <spec>.
• EoS Registry (docs/registries/eos-registry.md, generated from docs/registries/eos.json) — third-party Embeddable Orchestration System (EoS) host integrations: projects that embed MSD as an orchestration engine inside a host through the ADR-1239 Host-Integration Interface.
• Reviewer Lane Registry (docs/registries/reviewer-registry.md, generated from docs/registries/reviewers.json) — third-party reviewer lanes: role: "reviewer" capabilities (ADR-2782) that add an external review lane to /msd-review, installed with msd capability install <spec>. A lane registers on zero Loop Extension Points and owns no artifacts, which is why it cannot be listed as a Feature Capability.

All three registries are non-endorsing discoverability catalogs (issue #2182, plus #2904 for the Reviewer Lane Registry). None is the runtime Capability Registry (the generated manifest consumed at load time, ADR-894 §5) or the Capability Registry Overlay (the runtime loader that merges an installed third-party manifest into that generated registry, ADR-1244 D2) — see CONTEXT.md → "Community Capability Registry", "EoS Registry", and "Reviewer Lane Registry" for the full disambiguation.

---

Entry schema

Every entry is one JSON object in docs/registries/capabilities.json, docs/registries/eos.json, or docs/registries/reviewers.json, validated by scripts/registry-schema.cjs. Field names below are exact and case-sensitive; unknown top-level keys are rejected.

Capability entries (capabilities.json, type: "capability")

Field	Required	Meaning
id	yes	Unique slug across the registry (^[a-z0-9]+(-[a-z0-9]+)*$).
name	yes	Human-readable name.
type	yes	Must equal "capability".
repo	yes	owner/repo on github.com — the author's own repository.
description	yes	One-paragraph plain-language description of the solution and the problem it solves.
author	yes	Author name (and, optionally, contact).
license	yes	SPDX identifier (or UNLICENSED / Proprietary).
enginesMsd	yes	Declared engines.msd semver range (ADR-1244 D1), e.g. >=1.6.0.
install	yes	Exact, copy-pasteable install command — the ADR-1244 URL-import flow, e.g. msd capability install https://github.com/OWNER/REPO.git#v1.0.0.
uninstall	yes	Exact, copy-pasteable removal command, e.g. msd capability remove <id>.
interactions	yes	Object — see below.
discussion	yes	URL of this entry's GitHub Discussion (https://github.com/<owner>/<repo>/discussions/<n>).

interactions (Capability):

Field	Required	Meaning
loopExtensionPoints	yes, non-empty	Subset of the 12 Loop Extension Points the capability registers on: discuss:pre, discuss:post, plan:pre, plan:post, execute:pre, execute:wave:pre, execute:wave:post, execute:post, verify:pre, verify:post, ship:pre, ship:post.
hookKinds	yes	Subset of step, contribution, gate — the hook kind registered at each point above.
configKeys	yes	Array of federated config keys the capability owns (may be empty).
requires	yes	Array of other Capability ids this capability depends on (may be empty).
runtimeCompat	yes	Array of compatible runtimes; ["all"] is allowed.
produces	yes	Array describing artifacts/data the capability produces (may be empty).
consumes	yes	Array describing artifacts/data the capability consumes (may be empty).

Example:

{
  "id": "linear-issue-sync",
  "name": "Linear Issue Sync",
  "type": "capability",
  "repo": "some-org/msd-cap-linear-sync",
  "description": "Mirrors ROADMAP.md items to Linear issues as a ship:post contribution.",
  "author": "Some Org <hello@some-org.example>",
  "license": "MIT",
  "enginesMsd": ">=1.6.0",
  "install": "msd capability install https://github.com/some-org/msd-cap-linear-sync.git#v1.0.0",
  "uninstall": "msd capability remove linear-issue-sync",
  "interactions": {
    "loopExtensionPoints": ["ship:post"],
    "hookKinds": ["contribution"],
    "configKeys": ["linear-issue-sync.enabled"],
    "requires": [],
    "runtimeCompat": ["all"],
    "produces": ["linear-issue-links"],
    "consumes": ["ROADMAP.md"]
  },
  "discussion": "https://github.com/open-gsd/gsd-core/discussions/1234"
}

EoS entries (eos.json, type: "eos")

Field	Required	Meaning
id	yes	Unique slug across the registry.
name	yes	Human-readable name.
type	yes	Must equal "eos".
repo	yes	owner/repo on github.com — the author's own repository.
description	yes	One-paragraph plain-language description of the host integration.
author	yes	Author name (and, optionally, contact).
license	yes	SPDX identifier (or UNLICENSED / Proprietary).
enginesMsd	yes	Declared engines.msd semver range this integration targets.
protocolVersion	yes	Integer ≥ 1 — the ADR-1239 PROTOCOL_VERSION this integration implements.
install	yes	The host-plugin's own install steps (free string).
uninstall	yes	The host-plugin's own teardown steps (free string).
interactions	yes	Object — see below.
discussion	yes	URL of this entry's GitHub Discussion.

interactions (EoS):

Field	Required	Meaning
interfacePoints	yes, non-empty	Subset of the six ADR-1239 interface points it binds: command, dispatch, model, hooks, state, artifact.
profile	yes	One of the three host-capability profiles: programmatic-cli, declarative-cli, ide.
axes	yes	Object carrying all eight required ADR-1239 negotiated axes keys — embeddingMode, commandSurface, dispatch, modelMode, hookBus, stateIO, transport, runtime — and optionally a ninth, effortSurface (argv | none). No other key is accepted. effortSurface is optional because ADR-1239 amendment #2481 added it after entries already existed; requiring it would retroactively invalidate every entry published before the amendment.

axes value vocabulary:

Axis	Allowed values
embeddingMode	imperative, declarative
commandSurface	slash-file, slash-programmatic, slash-toml, palette, prose-only
dispatch	Free descriptive string (ADR-1239 dispatch is a structured object; the registry accepts a human summary).
modelMode	active, passive
hookBus	host, engine, none
stateIO	filesystem, sandboxed-storage, session-log-append
transport	mcp, native-extension
runtime	node, bun, sandboxed-web, python, go, rust, electron, other

Example:

{
  "id": "acme-editor-embed",
  "name": "Acme Editor MSD Embed",
  "type": "eos",
  "repo": "some-org/acme-msd-embed",
  "description": "Embeds MSD as an orchestration engine inside the Acme editor's command palette.",
  "author": "Some Org <hello@some-org.example>",
  "license": "Apache-2.0",
  "enginesMsd": ">=1.6.0",
  "protocolVersion": 1,
  "install": "Install the Acme MSD Embed extension from the Acme marketplace — see https://github.com/some-org/acme-msd-embed#install",
  "uninstall": "Remove the extension from Acme's extension manager.",
  "interactions": {
    "interfacePoints": ["command", "dispatch", "model", "hooks", "state", "artifact"],
    "profile": "ide",
    "axes": {
      "embeddingMode": "declarative",
      "commandSurface": "palette",
      "dispatch": "Routes palette invocations through Acme's own task-runner to msd_run",
      "modelMode": "active",
      "hookBus": "host",
      "stateIO": "filesystem",
      "transport": "native-extension",
      "runtime": "electron"
    }
  },
  "discussion": "https://github.com/open-gsd/gsd-core/discussions/1235"
}

Reviewer entries (reviewers.json, type: "reviewer")

Field	Required	Meaning
id	yes	Unique slug across the registry (^[a-z0-9]+(-[a-z0-9]+)*$).
name	yes	Human-readable name.
type	yes	Must equal "reviewer".
repo	yes	owner/repo on github.com — the author's own repository.
description	yes	One-paragraph plain-language description of the reviewer lane and what it reviews.
author	yes	Author name (and, optionally, contact).
license	yes	SPDX identifier (or UNLICENSED / Proprietary).
enginesMsd	yes	Declared engines.msd semver range (ADR-1244 D1), e.g. >=1.8.0.
install	yes	Exact, copy-pasteable install command — the ADR-1244 URL-import flow, e.g. msd capability install https://github.com/OWNER/REPO.git#v1.0.0.
uninstall	yes	Exact, copy-pasteable removal command, e.g. msd capability remove <id>.
interactions	yes	Object — see below.
discussion	yes	URL of this entry's GitHub Discussion (https://github.com/<owner>/<repo>/discussions/<n>).

interactions (Reviewer):

Field	Required	Meaning
slug	yes	Lane identity, matching the manifest's reviewer.slug. Must match the runtime lane grammar ^[a-z0-9][a-z0-9_-]*$ — underscores and a leading digit are permitted (lm_studio, 4o-mini), unlike the kebab-only id field.
flags	yes, non-empty	The CLI flags that select the lane, e.g. ["--gemini"]. Each must match ^--[a-z0-9][a-z0-9-]*$ — flags are kebab even when the slug is snake (lm_studio → --lm-studio).
transport	yes	spawn or openai-http.
evidenceClass	yes	source-grounded or diff-only.
reviewsSection	yes	The REVIEWS.md heading the lane renders under (max 200 characters).
requiresBinaries	yes	External binaries the lane needs (may be empty).
configKeys	yes	Federated config keys it owns (may be empty).
runtimeCompat	yes	Array of compatible runtimes; ["all"] is allowed.

Credential-bearing configKeys carry an exposure the example below does not show. Config values are written in plaintext to .planning/config.json — masking is display-only, and that file is the security boundary — while planning.commit_docs defaults to true. A key holding a live credential therefore lands in the installing user's repository unless they have gitignored .planning/. No first-party reviewer lane stores a credential this way. If yours must, document the exposure in your own README.

Example:

{
  "id": "acme-review-lane",
  "name": "Acme Review Lane",
  "type": "reviewer",
  "repo": "some-org/msd-lane-acme",
  "description": "Adds an Acme-hosted model as an external reviewer lane for /msd-review, evaluating diffs against Acme's static-analysis findings.",
  "author": "Some Org <hello@some-org.example>",
  "license": "MIT",
  "enginesMsd": ">=1.8.0",
  "install": "msd capability install https://github.com/some-org/msd-lane-acme.git#v1.0.0",
  "uninstall": "msd capability remove acme-review-lane",
  "interactions": {
    "slug": "acme",
    "flags": ["--acme"],
    "transport": "openai-http",
    "evidenceClass": "diff-only",
    "reviewsSection": "## Acme Review",
    "requiresBinaries": [],
    "configKeys": ["acme.api_key"],
    "runtimeCompat": ["all"]
  },
  "discussion": "https://github.com/open-gsd/gsd-core/discussions/1236"
}

A role: "runtime" capability that also carries a reviewer body (a host that is also a reviewer keeps one manifest, ADR-2782 D1) lists under whichever catalog matches its primary install shape — the Reviewer Lane Registry is for lanes that are not install targets in their own right.

---

Submission process

Registration is a documentation PR, per CONTRIBUTING.md → Documentation Updates:

1. Fork the repository.
2. Edit docs/registries/capabilities.json (Capability Registry), docs/registries/eos.json (EoS Registry), or docs/registries/reviewers.json (Reviewer Lane Registry) and append exactly one entry matching the schema above.
3. Run npm run gen:registry to regenerate the corresponding docs/registries/capability-registry.md, docs/registries/eos-registry.md, or docs/registries/reviewer-registry.md. Commit both the JSON source and the regenerated markdown.
4. Open a PR from a docs/<issue#>-<slug> branch (see CONTRIBUTING.md branch-naming conventions) using the registry-entry PR template.
5. A maintainer reviews and merges. The only gate is whether the entry is a real, linkable solution with all required fields present — not a quality judgment (see Non-endorsement stance).

One entry = one PR. Do not bundle multiple registry additions, updates, or removals into a single PR.

The generated .md files are GENERATED — never hand-edit them. docs/registries/capability-registry.md, docs/registries/eos-registry.md, and docs/registries/reviewer-registry.md are produced by scripts/gen-registry.cjs from capabilities.json / eos.json / reviewers.json. A PR that edits the generated markdown without a matching JSON source change will fail the gen:registry --check drift gate. Always edit the JSON and regenerate.

---

Latest-release tracking

Each entry embeds a live shields.io badge and a permalink to the linked repository's latest GitHub Release:

![release](https://img.shields.io/github/v/release/OWNER/REPO?sort=semver&include_prereleases)

https://github.com/OWNER/REPO/releases/latest

There is no re-registration on new releases: register once, and your GitHub Releases are the update channel forever. The badge and permalink are rendered live by GitHub's markdown viewer directly from the linked repository — the registry itself never needs a follow-up PR when you cut a new version.

---

Ranking + comments

Ranking and community feedback live in GitHub Discussions, not in the registry markdown. Each merged entry — from any of the three registries — gets exactly one Discussion in the dedicated EoS Registry Discussions category:

• Upvotes on the Discussion post and on individual comments, with GitHub's built-in Top sort surfacing the most-upvoted community feedback first.
• Threaded comments for experience reports, questions, and follow-up from other users.

Operational setup (one-time, per repo): a repo admin creates the EoS Registry category under this repository's Discussions settings, using the open-ended discussion format. From then on, every merged entry gets its own Discussion thread created in that category, and the thread's URL is recorded in the entry's discussion field (see Entry schema above) so the generated catalog links directly to it. Despite its name, the category carries threads for all three catalogs — discussion is required on Capability and Reviewer entries exactly as it is on EoS entries.

The open-ended format is required, and the choice is not cosmetic. Because discussion is a required field, the thread must exist before the entry's PR is opened — and the person opening it is the entry's author, an outside contributor holding neither maintain nor admin permission on this repository. GitHub's Announcement format restricts starting new discussions to those two permission levels, so choosing it blocks every external submission at the first step, while still looking correctly configured to the admin who set it up. Question/Answer adds answer-marking, which pins one reply above the rest of a thread — a directory entry has no answer, and the pinning cuts across the upvote Top ordering described above. Open-ended is the format this process requires.