decision: plugin distribution contradicts the official docs (plugin.json version is authoritative; a separate marketplace repo is not needed for one plugin)

hexajon commented

2026-08-17 21:23:07 +00:00

Owner

Scope note

This forks ADR 0010 (release is a tag; plugin.json version treated as cosmetic) and touches ADR 0033 (distribution home). I checked the official Claude Code docs, not our own rationale. I have changed nothing; this records the finding and the decision.

Finding 1 - plugin.json `version` is authoritative, not cosmetic

The docs say Claude Code reads the plugin's OWN version for update detection:

"Claude Code always uses the plugin.json value without warning, so a stale manifest version can mask a version you set in marketplace.json."

"If you declare a version in plugin.json and push new commits without changing that string, existing users keep the cached copy... Bump the field on every release, or omit it to fall back to the resolved version [the commit SHA]."

ADR 0010 assumes the opposite: the marketplace entry is authoritative and the source plugin.json version is cosmetic and "never hand-maintained." That is backwards. Today it does not bite only because scripts/assemble-plugin-artifact.sh stamps the tag version into the VENDORED artifact's plugin.json. The SOURCE .claude-plugin/plugin.json still says 0.14.6 while main is at v0.18.3. An install straight from the madtea repo would read 0.14.6 and never detect an update.

Correct handling per the docs: bump plugin.json version on every release, OR omit the field so Claude Code uses the commit SHA. Either one reopens the ADR 0010 "zero-commit release, never touch plugin.json" goal.

Finding 2 - a separate marketplace repo is not required for one plugin

The docs support one repo being BOTH the plugin AND its own marketplace: add .claude-plugin/marketplace.json beside .claude-plugin/plugin.json, with the plugin entry "source": "./". Users run /plugin marketplace add sixfold-space/madtea then /plugin install madtea@<name>. A separate marketplace repo is warranted only to catalog many plugins from different repos. For one plugin it is extra machinery (the vendor + stamp + PR-into-claude-plugins flow).

Sources:

https://code.claude.com/docs/en/plugins-reference (plugin manifest schema; version management)
https://code.claude.com/docs/en/plugin-marketplaces (marketplace schema; plugin sources)

Options

Self-host. madtea becomes its own marketplace (add marketplace.json, source ./), retire the separate claude-plugins vendor/stamp flow, and either bump plugin.json version per release or omit it for SHA-based updates. Simplest; removes a repo and the assemble step; but a per-release version bump is a commit, so this reopens the zero-commit-release rule unless the field is omitted.
Keep the separate marketplace, but fix the source version so it cannot mask updates: omit version from the source plugin.json, or make "not authoritative" explicit by setting the source to the 0.0.0 sentinel and treating the stamped vendored artifact as the only supported install path.
Status quo. Works only through the stamped vendored artifact. The stale source version stays a trap for any direct-repo install, and two repos ship one plugin.

I need to settle this before the public launch, because it reopens ADR 0010's premise.

Secondary (minor)

The plugin description claims madtea "works with Claude Code, OpenAI Codex CLI, and Antigravity CLI." The plugin format itself is Claude-Code-only; the cross-client surface is the MCP server, a separate install. Worth splitting that claim so the plugin manifest does not assert cross-client support it cannot have.

ADR 0010, ADR 0033.
#436 (commit provenance) - separate, part of the same pre-launch pass.

## Scope note This forks **ADR 0010** (release is a tag; plugin.json version treated as cosmetic) and touches **ADR 0033** (distribution home). I checked the official Claude Code docs, not our own rationale. I have changed nothing; this records the finding and the decision. ## Finding 1 - plugin.json `version` is authoritative, not cosmetic The docs say Claude Code reads the plugin's OWN `version` for update detection: > "Claude Code always uses the plugin.json value without warning, so a stale manifest version can mask a version you set in marketplace.json." > "If you declare a version in plugin.json and push new commits without changing that string, existing users keep the cached copy... Bump the field on every release, or omit it to fall back to the resolved version [the commit SHA]." ADR 0010 assumes the opposite: the marketplace entry is authoritative and the source `plugin.json` version is cosmetic and "never hand-maintained." That is backwards. Today it does not bite only because `scripts/assemble-plugin-artifact.sh` stamps the tag version into the VENDORED artifact's plugin.json. The SOURCE `.claude-plugin/plugin.json` still says `0.14.6` while main is at v0.18.3. An install straight from the madtea repo would read `0.14.6` and never detect an update. Correct handling per the docs: bump `plugin.json` `version` on every release, OR omit the field so Claude Code uses the commit SHA. Either one reopens the ADR 0010 "zero-commit release, never touch plugin.json" goal. ## Finding 2 - a separate marketplace repo is not required for one plugin The docs support one repo being BOTH the plugin AND its own marketplace: add `.claude-plugin/marketplace.json` beside `.claude-plugin/plugin.json`, with the plugin entry `"source": "./"`. Users run `/plugin marketplace add sixfold-space/madtea` then `/plugin install madtea@<name>`. A separate marketplace repo is warranted only to catalog many plugins from different repos. For one plugin it is extra machinery (the vendor + stamp + PR-into-claude-plugins flow). Sources: - https://code.claude.com/docs/en/plugins-reference (plugin manifest schema; version management) - https://code.claude.com/docs/en/plugin-marketplaces (marketplace schema; plugin sources) ## Options 1. **Self-host.** madtea becomes its own marketplace (add `marketplace.json`, source `./`), retire the separate `claude-plugins` vendor/stamp flow, and either bump plugin.json `version` per release or omit it for SHA-based updates. Simplest; removes a repo and the assemble step; but a per-release version bump is a commit, so this reopens the zero-commit-release rule unless the field is omitted. 2. **Keep the separate marketplace**, but fix the source version so it cannot mask updates: omit `version` from the source plugin.json, or make "not authoritative" explicit by setting the source to the `0.0.0` sentinel and treating the stamped vendored artifact as the only supported install path. 3. **Status quo.** Works only through the stamped vendored artifact. The stale source version stays a trap for any direct-repo install, and two repos ship one plugin. I need to settle this before the public launch, because it reopens ADR 0010's premise. ## Secondary (minor) The plugin `description` claims madtea "works with Claude Code, OpenAI Codex CLI, and Antigravity CLI." The plugin format itself is Claude-Code-only; the cross-client surface is the MCP server, a separate install. Worth splitting that claim so the plugin manifest does not assert cross-client support it cannot have. ## Related - ADR 0010, ADR 0033. - #436 (commit provenance) - separate, part of the same pre-launch pass.

hexajon added the

bug

status/needs-decision

labels

2026-08-17 21:23:07 +00:00

hexajon referenced this issue

2026-08-17 22:42:28 +00:00

plugin distribution: make the marketplace repo authoritative, drop the manifest version (git-hash updates), remove madtea's .claude-plugin, rework assemble #443

hexajon removed the

status/needs-decision

label

2026-08-17 22:42:48 +00:00

hexajon commented

2026-08-17 22:42:48 +00:00

Author

Owner

Decision: sixfold-space/claude-plugins is authoritative for the plugin. The manifest drops its version field, so update detection keys off the marketplace repo's git commit hash rather than a stamped version. madtea's source .claude-plugin/ is removed and the assemble step is reworked to match. Full task list and implementation: #443.

Decision: `sixfold-space/claude-plugins` is authoritative for the plugin. The manifest drops its `version` field, so update detection keys off the marketplace repo's git commit hash rather than a stamped version. madtea's source `.claude-plugin/` is removed and the assemble step is reworked to match. Full task list and implementation: #443.

hexajon referenced this issue

2026-08-21 22:19:08 +00:00

decision: should madtea ship a Claude Code plugin at all, or is the MCP server the whole product? #450

hexajon referenced this issue

2026-08-25 19:51:57 +00:00

decision: should madtea ship a Claude Code plugin at all, or is the MCP server the whole product? #450

hexajon referenced this issue

2026-08-25 19:52:06 +00:00

plugin distribution: make the marketplace repo authoritative, drop the manifest version (git-hash updates), remove madtea's .claude-plugin, rework assemble #443

hexajon referenced this issue from sixfold-space/claude-plugins

2026-08-25 20:00:07 +00:00

narrow the madtea plugin to hooks + skills: drop the bundled MCP server, the manifest version, and the cross-client claim #15

hexajon referenced this issue

2026-08-25 21:39:30 +00:00

feat(release): narrow plugin vendor to hooks+skills, idempotent, marketplace-owned manifest #453

hexajon commented

2026-08-25 21:39:58 +00:00

Author

Owner

Resolved. The plugin-distribution contradiction (a plugin.json version competing with the marketplace's update model) is gone:

The plugin carries no version anywhere. Claude Code keys update detection off the marketplace repo's commit hash (verified against code.claude.com/docs plugin-marketplaces).
The marketplace repo (sixfold-space/claude-plugins) is the sole owner of plugin.json, marketplace.json, and the README.

Landed in: the claude-plugins narrowing (its PR #16, merged) and madtea PR #453 (merged, full gate green). The product-shape decision behind it is #450 (option 3, plugin = hooks + skills). Closing.

Resolved. The plugin-distribution contradiction (a `plugin.json` version competing with the marketplace's update model) is gone: - The plugin carries no `version` anywhere. Claude Code keys update detection off the marketplace repo's commit hash (verified against code.claude.com/docs plugin-marketplaces). - The marketplace repo (`sixfold-space/claude-plugins`) is the sole owner of `plugin.json`, `marketplace.json`, and the README. Landed in: the claude-plugins narrowing (its PR #16, merged) and madtea PR #453 (merged, full gate green). The product-shape decision behind it is #450 (option 3, plugin = hooks + skills). Closing.

hexajon closed this issue

2026-08-25 21:40:02 +00:00

Rows
Columns

decision: plugin distribution contradicts the official docs (plugin.json version is authoritative; a separate marketplace repo is not needed for one plugin) #437

Scope note

Finding 1 - plugin.json version is authoritative, not cosmetic

Finding 2 - a separate marketplace repo is not required for one plugin

Options

Secondary (minor)

Related

Finding 1 - plugin.json `version` is authoritative, not cosmetic