golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(#1245): add capability ecosystem ADR, PRD, and developer documentation (#1248)

Browse Source 
Phase 0 of the Capability Ecosystem epic (#1244): the design record and the
third-party-author documentation set, with no runtime or code changes.

- docs/adr/1244-capability-ecosystem.md — architecture decision record
  (amends/extends ADR-857 Decisions 7 & 8)
- docs/prd/1244-capability-ecosystem.md — product requirements
- Diataxis docs: tutorial, how-to (publish/import/version/remove),
  reference (manifest schema, /gsd:capability command, capability matrix),
  explanation (trust model); cross-links added to develop-a-capability.md

Refs #1244

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-14 17:51:43 -04:00
committed by GitHub
parent 10ae85cbbf
commit f52a7a5f77
12 changed files with 2072 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/how-to/develop-a-capability.md
View File

@@ -234,3 +234,17 @@ Run the Phase 6 capstone test whenever a Capability adds a `when` key or moves a
## Keep the docs with the slice
Every Phase 6 slice that changes capability behaviour must update the relevant docs in the same PR. Use this manual for developer-facing Capability authoring facts, use how-to guides for task flows, and use ADRs only for decisions and trade-offs.
## The capability ecosystem (1.6.0)
From GSD 1.6.0, capabilities are versioned (the `version` field is required in `capability.json`) and can be installed directly from a URL, a git ref, an npm package, or a local path — without modifying the core repo.
- **Tutorial** — [Build your first capability](../tutorials/build-your-first-capability.md): scaffold and install a declarative capability end-to-end in under ten minutes.
- **How-to** — [Publish a capability](../how-to/publish-a-capability.md): package and distribute a capability via a URL or registry.
- **How-to** — [Import a capability from a URL](../how-to/import-a-capability-from-a-url.md): install a third-party capability from a git URL, tarball, or npm package.
- **How-to** — [Version and update a capability](../how-to/version-a-capability.md): manage `version`, `engines.gsd`, and `compatVersions`; use `gsd capability update`.
- **How-to** — [Remove a capability](../how-to/remove-a-capability.md): uninstall cleanly with `gsd capability remove`, including the `--purge-data` option.
- **Reference** — [Capability manifest](../reference/capability-manifest.md): all fields and validation rules for `capability.json`.
- **Reference** — [Capability matrix](../reference/capability-matrix.md): which first-party capabilities exist, their extension points, and their compatibility matrix.
- **Explanation** — [Capability trust model](../explanation/capability-trust-model.md): how declarative and executable capabilities are treated differently at install time.
- **ADR-1244** — `docs/adr/1244-capability-ecosystem.md`: the architectural decision that introduced the installable capability ecosystem.

177
docs/how-to/import-a-capability-from-a-url.md Normal file
View File

@@ -0,0 +1,177 @@
# How to import a capability from a URL
This guide is for GSD users who want to install a published capability — from a git repository, an npm package, a tarball, or a local path. It covers running the install command, understanding the pre-install summary, consenting to executable surfaces, verifying integrity, and choosing a scope.
Before installing a third-party capability, read [Capability trust model](../explanation/capability-trust-model.md) to understand how GSD treats external code.
---
## Run the install command
The `install` subcommand accepts several source spec forms. Use whichever matches how the capability was published.
**Git repository at a tag:**
```bash
gsd capability install https://github.com/some-org/gsd-cap-example.git#v1.0.0
```
**Git repository pinned to a commit SHA (fully reproducible):**
```bash
gsd capability install https://github.com/some-org/gsd-cap-example.git#sha:abc123def456...
```
**npm package:**
```bash
gsd capability install npm:@some-org/gsd-cap-example@1.0.0
```
**Tarball at an HTTPS URL:**
```bash
gsd capability install https://example.com/releases/gsd-cap-example-1.0.0.tgz
```
**Local path (for testing a capability you are developing):**
```bash
gsd capability install ./path/to/capability
```
You can also use the slash command form inside a supported runtime (surfaced as `gsd:capability install <spec>` — without the leading `/` in the command palette).
---
## Read the pre-install summary
Before asking for confirmation, GSD fetches the manifest and displays a summary:
```
Capability: Example Planning Step
Version: 1.0.0
Author: Some Org <hello@some-org.example>
Homepage: https://github.com/some-org/gsd-cap-example
License: MIT
engines.gsd: >=1.6.0
Artefacts: 3 files (skills: 1, agents: 1, fragments: 1)
Executable surfaces:
hooks: plan:pre (step), ship:pre (gate, blocking)
MCP servers: none
command modules: none
```
If the capability declares hooks, MCP servers, or command modules, these are listed under **Executable surfaces**. These surfaces run as part of the GSD loop on your machine. Review them carefully.
---
## Consent to executable surfaces
If the capability declares any executable surface — hooks, MCP servers, or command modules — GSD displays a consent prompt:
```
This capability registers executable hooks that will run during your GSD sessions.
Do you consent to installing it? [y/N]
```
If you do not trust the source, type `N` or press Enter to cancel. The capability will not be installed and nothing will be written to disk.
If the capability declares no executable surfaces (skills, agents, and prompt fragments only), GSD installs without a consent prompt.
After initial consent, if you later run `gsd capability update` and the updated version adds new executable surfaces that were not present when you first consented, GSD will prompt for consent again before applying the update.
---
## Verify integrity (recommended for tarballs)
If the capability author has published an `sha512` integrity hash, pass it with `--integrity` to verify the download before extraction:
```bash
gsd capability install https://example.com/releases/gsd-cap-example-1.0.0.tgz \
--integrity sha512-AbCdEf...
```
If the computed hash does not match the value you provide, GSD aborts the install. Nothing is written to disk. This protects against a tampered or corrupted download.
For Git and npm installs, the hosting platform provides its own transport-layer assurance. The `--integrity` flag is most important for tarball URLs hosted outside a verified registry.
---
## Choose a scope
Use `--scope project` to install the capability for the current project only. The files land in `.gsd/capabilities/<id>/` relative to the project root, and the ledger entry goes into the project's local config.
```bash
gsd capability install <spec> --scope project
```
Use `--scope global` (the default) to install for all your projects on this machine. The files land in `~/.gsd/capabilities/<id>/` and the ledger is written per runtime (for example, `~/.claude/.gsd-capabilities.json`).
```bash
gsd capability install <spec> --scope global
```
Project-scoped capabilities take precedence over global ones when both are present. Use project scope when the capability is specific to one codebase, or when you want to pin a version independently of your global install.
---
## Handle a version mismatch
If the capability's `engines.gsd` requirement is not satisfied by your installed GSD version, the install will be blocked:
```
Error: Capability requires gsd >=1.7.0 but you have 1.6.2.
```
In this case, either upgrade GSD with `gsd update` and retry, or ask the capability author whether an older compatible version is available. If the capability publishes `compatVersions`, GSD may offer to install the newest version compatible with your current GSD:
```
A compatible older version (0.9.0, requires gsd >=1.6.0) is available.
Install that instead? [y/N]
```
---
## Handle a blocked install (strictKnownRegistries)
If your organisation has set `strictKnownRegistries` to a non-empty allowlist in your GSD config, installs from sources outside that allowlist will be refused:
```
Error: Source is not in the known-registries allowlist. Contact your GSD administrator.
```
To install the capability, either ask your administrator to add the source to the allowlist, or install from an approved source.
---
## Skip the confirmation prompt
If you are running in a script or CI context and have already inspected the manifest, pass `--yes` to proceed without interactive prompts. Use this only when you are certain about what you are installing.
```bash
gsd capability install <spec> --yes
```
---
## Confirm the installation
After a successful install, verify the capability is active:
```bash
gsd capability list
```
The output shows each installed capability, its version, scope, and enabled status. If the capability did not activate as expected, check that your GSD version satisfies `engines.gsd` and that the capability is not disabled.
---
## Next steps
- [Version and update a capability](./version-a-capability.md) — check for updates with `gsd capability outdated` and apply them with `gsd capability update`.
- [Remove a capability](./remove-a-capability.md) — uninstall with `gsd capability remove`, including the `--purge-data` option.
- [Capability trust model](../explanation/capability-trust-model.md) — the full explanation of how GSD handles trust for first-party and third-party capabilities.
- [Capability manifest](../reference/capability-manifest.md) — field reference for `capability.json`.

190
docs/how-to/publish-a-capability.md Normal file
View File

@@ -0,0 +1,190 @@
# How to publish a capability so others can install it
This guide is for capability authors who want to distribute their work so other GSD users can install it with `gsd capability install`. It covers preparing the manifest, validating locally, and releasing through each supported distribution channel.
Before publishing, make sure your capability works locally by following [Develop a Capability](./develop-a-capability.md).
---
## Add the required publishing fields
Open your `capabilities/<id>/capability.json` and add these fields if they are not already present.
### `version` (required)
```json
"version": "1.0.0"
```
Use [Semantic Versioning](https://semver.org/). Every published capability must carry a version; GSD will reject installation of a manifest that omits it.
### `engines.gsd` (required)
```json
"engines": {
"gsd": ">=1.6.0"
}
```
Declare the minimum GSD version your capability requires. GSD checks this constraint at both install time and load time and refuses to activate the capability on an incompatible installation. Be as permissive as correctness allows — a tighter range blocks more users.
If you need to offer a graceful downgrade path for users on older GSD versions, you can also declare `compatVersions`:
```json
"compatVersions": {
"1.0.0": ">=1.6.0",
"0.9.0": ">=1.5.0"
}
```
`compatVersions` is only meaningful when your distribution channel enumerates available versions (a registry or a package feed). For Git and tarball releases, the installer downloads the version you point to directly.
### Author and provenance fields (recommended)
These fields are displayed in the pre-install summary that users see before they consent to installation. Filling them in builds trust.
```json
"author": {
"name": "Your Name",
"email": "you@example.com",
"url": "https://example.com"
},
"homepage": "https://github.com/your-org/gsd-cap-example",
"repository": "https://github.com/your-org/gsd-cap-example",
"license": "MIT"
```
`license` must be a valid [SPDX expression](https://spdx.org/licenses/). `keywords` is optional but helps discoverability on registries.
For the full list of manifest fields and their validation rules, see [Capability manifest](../reference/capability-manifest.md).
---
## Namespace reservation
The prefixes `gsd-`, `gsd-core-`, and `anthropic-` are reserved for first-party capabilities. Do not use them as the `id` or package name of a third-party capability.
---
## Validate locally before publishing
Run the registry check to confirm the manifest is well-formed:
```bash
node scripts/gen-capability-registry.cjs --check
```
If you are developing outside the core repo, use the standalone validator when it is available, or install your capability locally and check that `gsd capability list` shows it without errors:
```bash
gsd capability install ./path/to/your-capability --scope project
gsd capability list
```
Fix any validation errors before proceeding.
---
## Choose a distribution channel
### Git repository (recommended for open-source capabilities)
Push your capability to a public Git host. Tag each release:
```bash
git tag v1.0.0
git push origin v1.0.0
```
Consumers install by pointing at the tag:
```bash
gsd capability install https://github.com/your-org/gsd-cap-example.git#v1.0.0
```
For a reproducible pin that cannot be moved, consumers can use a commit SHA instead:
```bash
gsd capability install https://github.com/your-org/gsd-cap-example.git#sha:abc123def456...
```
Publish release notes on your Git host so users know what changed between versions.
### npm package
Publish your capability as an npm package. The package name becomes the npm spec consumers use. Use a scoped package name to make the origin clear:
```bash
npm publish
```
Consumers install using the `npm:` prefix:
```bash
gsd capability install npm:@your-org/gsd-cap-example@1.0.0
```
A version range is also accepted:
```bash
gsd capability install npm:@your-org/gsd-cap-example@^1.0.0
```
### Tarball release
Build a tarball of the capability directory and attach it to a GitHub release or host it on any HTTPS URL:
```bash
tar -czf gsd-cap-example-1.0.0.tgz capabilities/example/
```
Consumers install using the tarball URL:
```bash
gsd capability install https://github.com/your-org/gsd-cap-example/releases/download/v1.0.0/gsd-cap-example-1.0.0.tgz
```
For tarball releases, publishing an integrity hash is strongly recommended (see below).
---
## Compute and publish an integrity hash (recommended for tarballs)
An `sha512` integrity hash lets consumers verify the download has not been tampered with. Compute it with:
```bash
openssl dgst -sha512 -binary gsd-cap-example-1.0.0.tgz | openssl base64 -A | sed 's/^/sha512-/'
```
Publish the resulting string in your release notes. Consumers pass it at install time:
```bash
gsd capability install https://example.com/gsd-cap-example-1.0.0.tgz \
--integrity sha512-<hash>
```
GSD verifies the hash before extracting the archive and aborts if it does not match.
---
## Add provenance (optional)
If your release process produces a provenance record — for example, a GitHub Actions attestation — you can embed it in the manifest so that audit tools can surface it:
```json
"provenance": {
"sourceRepo": "https://github.com/your-org/gsd-cap-example",
"commit": "abc123def456..."
}
```
This is optional metadata. It does not change the install-time trust model.
---
## Next steps
- [Import a capability from a URL](./import-a-capability-from-a-url.md) — walk through installation from the consumer's perspective.
- [Version and update a capability](./version-a-capability.md) — manage `version`, `engines.gsd`, and `compatVersions` across releases.
- [Capability manifest](../reference/capability-manifest.md) — full field reference.
- [Capability trust model](../explanation/capability-trust-model.md) — how GSD treats third-party capabilities at install time.

111
docs/how-to/remove-a-capability.md Normal file
View File

@@ -0,0 +1,111 @@
# How to remove or disable a capability
This guide covers two distinct operations: **removing** a capability (deletes its files and cleans up all shared configuration it wrote) and **disabling** a capability (toggles it off without touching any files). Choose the one that fits your intent.
---
## Disable a capability (reversible, files kept)
If you want to stop a capability from participating in the loop but may want it back later, disable it:
```bash
gsd capability disable <id>
```
Disabling is a toggle: no files are deleted, no shared configuration is modified. The capability's hooks stop firing, its skills leave the active surface, and its command modules stop responding. To re-activate it:
```bash
gsd capability enable <id>
```
Everything you had before is restored — hook registrations, config keys, contributed agents — without reinstalling.
If you want to toggle a capability off within a single runtime session rather than system-wide, see [Turn a capability off (and keep it off)](turn-a-capability-off.md).
---
## Remove a capability
Removal is permanent within the current install. Use it when you no longer need the capability and want to reclaim its disk footprint and clean its entries from your runtime configuration.
```bash
gsd capability remove <id>
```
### What is removed
GSD uses the **ledger** — a per-runtime record written at install time (for example, `~/.claude/.gsd-capabilities.json`) — as the authoritative list of what the install owns. Removal acts precisely on that record:
- **Owned files** — every file the capability wrote at install (skills, agents, referenced assets) is deleted.
- **Shared configuration fragments** — entries the capability injected into shared files such as `settings.json` (hooks) and `hooks.json` (MCP server registrations) are stripped. Only the capability's own entries are removed; no other capability's hooks or MCP server entries are touched.
- **Federated config keys** — configuration keys that belong to the capability's declared config slice are dropped from the merged config.
### What is NOT removed
- **Shared files themselves.** Files such as `settings.json` and `hooks.json` are edited in place, not deleted. Only the capability's specific entries are excised.
- **Persistent capability data.** Any data the capability wrote during use (databases, caches, runtime artefacts stored outside the install root) is **not** auto-deleted. You must pass `--purge-data` to remove it, and GSD will prompt for confirmation before doing so:
```bash
gsd capability remove <id> --purge-data
```
If you want to keep your data, omit `--purge-data`. The capability's runtime data will remain on disk even after the capability itself is removed.
### Prompts and confirmation
`gsd capability remove` will ask you to confirm before proceeding. Pass `--yes` to skip the prompt in scripts or non-interactive contexts:
```bash
gsd capability remove <id> --yes
```
If the capability also ships persistent data and you pass `--purge-data`, GSD prompts once more specifically for the data deletion, regardless of `--yes`, because that action is irreversible.
---
## Troubleshooting
**If a previous remove was interrupted** (for example, the process was killed mid-run), GSD's reconciliation sweep repairs the orphaned state automatically on the next command invocation. You do not need to intervene manually; running any `gsd capability` command is sufficient to trigger the sweep.
**If the capability ships hooks**, removal strips its hook entries from `settings.json` without affecting any other hook entry. If after removal you still see the capability's hooks listed under `settings.json`, run:
```bash
gsd capability list --json
```
and confirm the capability is no longer present. If it still appears, re-run the remove command — the reconciliation sweep will complete any partial work.
**If you see "capability not found" during remove**, the capability may have been installed under a different scope (global vs. project). Check which scope it was installed under:
```bash
gsd capability list
```
The `--scope` column indicates whether an entry is `global` or `project`. Pass the matching scope explicitly if needed:
```bash
gsd capability remove <id> --scope global
gsd capability remove <id> --scope project
```
---
## Disable vs. remove: a quick comparison
| | `disable` | `remove` |
|---|---|---|
| Files deleted | No | Yes (ledger-recorded files only) |
| Shared config entries removed | No | Yes (capability's entries only) |
| Federated config keys dropped | No | Yes |
| Persistent data deleted | No | Only with `--purge-data` + prompt |
| Reversible without reinstall | Yes (`enable`) | No |
| Use when | You want it back later | You no longer need it |
---
## Related guides
- [How to version and upgrade a capability](version-a-capability.md)
- [Develop a Capability for GSD 1.5+](develop-a-capability.md)
- [Turn a capability off (and keep it off)](turn-a-capability-off.md)
- [Trust model explanation](../adr/1244-capability-ecosystem.md#d5----trust-model-artifact-parity-is-full-trust-posture-is-tiered)

141
docs/how-to/version-a-capability.md Normal file
View File

@@ -0,0 +1,141 @@
# How to version and upgrade a capability
This guide covers two separate journeys: how a **capability author** keeps their manifest correctly versioned as GSD evolves, and how a **capability consumer** safely applies updates. Read only the section that matches your role; each stands alone.
---
## If you author a capability
### Choose a version number
Every `capability.json` must carry a `version` field expressed as a [semver](https://semver.org) string. GSD rejects a capability manifest that omits it.
Use the standard semver conventions:
| Kind of change | Version bump | Examples |
|---|---|---|
| Backwards-compatible bug fixes or minor prompt improvements | **patch** (0.0.x) | Fix a typo in an agent instruction; tighten a hook condition. |
| New loop-extension hook, new skill, or new config key — existing consumers unaffected | **minor** (0.x.0) | Add a `verify:post` gate; add a new optional config key. |
| Breaking change to the hook contract, removal of a skill or config key, change of `id` | **major** (x.0.0) | Rename a hook extension point; remove a skill consumers depend on. |
Set the version in your manifest before every release:
```jsonc
{
"id": "my-deploy-gate",
"version": "1.2.0",
"engines": { "gsd": ">=1.6.0 <3.0.0" }
}
```
### Decide when to raise `engines.gsd`
The `engines.gsd` range expresses which GSD host versions your capability is compatible with. GSD enforces this as a hard gate at install time and again at load time.
Raise the lower bound when you start using a GSD feature introduced in a specific release — for example, a loop extension point added in 1.7.0, a new manifest field, or a config federation key that does not exist in older GSD builds. Do not raise it pre-emptively; only raise it when the capability genuinely requires the newer behaviour.
When you do raise the lower bound:
1. Bump `version` (at minimum a minor bump, or a major bump if the change is otherwise breaking).
2. Update `engines.gsd` to reflect the new minimum.
3. Add a `compatVersions` entry (see below).
### Maintain `compatVersions`
`compatVersions` is a capability-version → minimum-GSD-version table that lets GSD offer older consumers a downgrade instead of a hard block:
```jsonc
{
"version": "2.0.0",
"engines": { "gsd": ">=1.7.0 <3.0.0" },
"compatVersions": {
"1.2.0": "1.6.0"
}
}
```
This entry tells GSD: "version 1.2.0 of this capability requires at least GSD 1.6.0." When a consumer's GSD is older than 1.7.0, GSD uses `compatVersions` to offer them version 1.2.0 instead of failing outright.
Add a new entry **only when you change `engines.gsd`** — that is the only moment an older GSD version and a specific capability version become correlated. A `compatVersions` entry is not meaningful for a capability distributed as a bare tarball URL (a tarball exposes a single version and cannot be auto-selected from a table); it is only actionable for sources that enumerate versions: git tags, a registry, or npm.
### Publish a new version
How consumers receive the update depends on your distribution channel.
**Git tag.** Commit the updated `capability.json` (with the new `version` field), then push a tag whose name matches the version:
```bash
git tag v1.2.0
git push origin v1.2.0
```
GSD's git adapter fetches tags to determine what is available. Without a matching tag, the new version is invisible to `gsd capability outdated`.
**npm.** Publish normally. GSD uses `dist-tags` to check for updates, so the standard `npm publish` flow is sufficient:
```bash
npm version 1.2.0
npm publish
```
**New tarball.** Upload the new archive at a URL and communicate the URL to consumers. GSD cannot auto-detect updates for tarball sources — consumers must run `gsd capability update <id> <new-url>` manually after you announce the new URL. If you anticipate frequent updates, consider switching to a git or npm source.
---
## If you consume a capability
### Check for available updates
Run:
```bash
gsd capability outdated
```
GSD contacts the source of each installed capability and reports which ones have a newer version available. Whether an update is detectable depends on the source:
| Source | Auto-detectable? |
|---|---|
| Git (tags / manifest) | Yes — GSD fetches available tags. |
| Registry | Yes — GSD queries the catalogue. |
| npm | Yes — GSD checks `dist-tags`. |
| Tarball URL | **No** — a tarball exposes one version; updates must be applied manually when the author announces a new URL. |
If a capability is installed from a tarball and the author publishes a new version at a different URL, you will need to run `gsd capability update <id> <new-url>` yourself once the author communicates the new address.
### Apply an update
To update a specific capability:
```bash
gsd capability update <id>
```
To update all installed capabilities at once:
```bash
gsd capability update --all
```
Updates are **atomic**: GSD fully fetches and validates the new version before swapping it in. The ledger write is the commit point. If GSD stops mid-update (for example, due to a network failure), the next command run will detect the orphaned state via a reconciliation sweep and restore a consistent install — you will never be left with a half-updated capability.
### Consent when the executable surface changes
If the new version adds or removes hooks, MCP server entries, or command modules compared to the version you have installed, GSD will pause and present a summary of the changes before proceeding. You must confirm explicitly; declining leaves the current version in place.
This re-prompt applies even if you previously consented to auto-update. The consent mechanism is scoped to the declared executable surface of a specific version, so a changed surface is always a fresh decision.
Auto-update is **off by default** for third-party capabilities. If you enable it, the re-prompt on executable-surface change still applies.
### When `engines.gsd` no longer matches
If the new version of a capability requires a GSD version newer than what you have installed, GSD will tell you clearly and — where the source enumerates versions — offer the newest `compatVersions`-compatible version instead. If no compatible version is available, or the source is a bare tarball, you will need to either upgrade GSD or stay on your current capability version.
---
## Related guides
- [How to remove or disable a capability](remove-a-capability.md)
- [Develop a Capability for GSD 1.5+](develop-a-capability.md)
- [Capability manifest reference](../reference/capability-matrix.md)
- [Turn a capability off (and keep it off)](turn-a-capability-off.md)