claude-code - 💡(How to fix) Fix [DOCS] Plugin dependency docs missing git-tag version constraint update behavior [1 comments, 2 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/plugins-reference

Section/Topic

plugin.json manifest schema, plugin dependency/version resolution behavior, and plugin auto-update behavior for git-tagged dependencies

Current Documentation

The plugin reference currently says it documents the manifest fields comprehensively, but it does not describe plugin-to-plugin dependency declarations or version-constraint behavior:

The .claude-plugin/plugin.json file defines your plugin's metadata and configuration. This section documents all supported fields and options.

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  ...
  "monitors": "./monitors.json"
}

The marketplace guide documents only fixed git pins for plugin sources:

You can pin to a specific branch, tag, or commit:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

ref: Optional. Git branch or tag (defaults to repository default branch)

sha: Optional. Full 40-character git commit SHA to pin to an exact version

The install/update docs only describe generic latest-version updates:

Claude Code can automatically update marketplaces and their installed plugins at startup. When auto-update is enabled for a marketplace, Claude Code refreshes the marketplace data and updates installed plugins to their latest versions.

Update a plugin to the latest version.

What's Wrong or Missing?

Changelog v2.1.119 added a user-visible behavior change: plugins pinned by another plugin's version constraint now auto-update to the highest satisfying git tag.

The current docs do not explain:

A. How plugin dependency version constraints are declared

plugins-reference says it documents all supported plugin.json fields, but there is no documented field or schema explanation for one plugin depending on another plugin with a version constraint.

B. How constraint resolution works for git-based plugins

plugin-marketplaces explains fixed ref and sha pins, but not semver-like dependency constraints that resolve against git tags.

C. How auto-update behaves when a dependency is constraint-pinned

discover-plugins and plugins-reference say plugins update to the “latest version,” but they do not explain that dependency-constrained git plugins advance to the highest satisfying tag rather than staying on the originally installed tag.

Without this, plugin authors and admins cannot reliably predict how dependent plugins are selected or updated.

Suggested Improvement

Add a dedicated subsection to plugins-reference for plugin dependencies/version constraints that covers:

1. The manifest field(s) used to declare that one plugin depends on another
2. Accepted version-constraint syntax
3. How git-based dependencies resolve against tags
4. The v2.1.119 behavior that auto-update selects the highest satisfying git tag for dependency-constrained plugins
5. How this differs from fixed ref and sha pinning

Then add short cross-references:

• In plugin-marketplaces, note that direct plugin source ref/sha pinning is different from dependency-based version resolution
• In discover-plugins, link the auto-update section to the detailed dependency/version-resolution reference

An example would help clarify expected behavior for a dependency constrained to a range such as ^2.0.0 and what tag Claude Code selects during auto-update.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Source: Changelog v2.1.119

Exact changelog entry: Plugins pinned by another plugin's version constraint now auto-update to the highest satisfying git tag