| name | check-versions |
| description | Verify version consistency across plugin.json and marketplace.json for all plugins. Use when (1) before creating a pull request or release to ensure metadata consistency, (2) after manually editing version numbers in either plugin.json or marketplace.json, (3) repository health verification or preflight checks are requested, (4) after using bump-version to confirm both files were updated correctly, (5) during debugging if plugins aren't appearing correctly in the marketplace, (6) as part of comprehensive validation alongside check-skill-counts and check-changelogs. |
Check Versions
Maintain version consistency across metadata files to preserve trust with users about what they're installing.
Instructions
1. Recognize that version metadata creates a promise. Each plugin declares its version in plugin.json while the marketplace announces that same version in marketplace.json—when these numbers diverge, one file was updated without syncing the other, breaking the chain of truth that connects source code to marketplace listing to user installation.
2. Execute validation across the plugin ecosystem. Run .claude/scripts/check-versions.sh to scan all plugins and surface discrepancies, producing either confirmation that metadata files agree or detailed comparison showing where each plugin's two version declarations differ.
3. Read validation output as a map of metadata integrity. Success means version numbers form a consistent story from plugin source to marketplace entry; failures identify specific plugins where the story breaks, displaying both the plugin.json version and marketplace.json version so the gap becomes immediately visible.
4. Trace discrepancies to their source and guide resolution. When mismatches surface, examine recent commits and CHANGELOG.md entries to determine which version reflects reality—the higher number might represent legitimate progress not yet synced to marketplace, or accidental inflation without corresponding changes—then guide toward correcting whichever file drifted from truth.
5. Prevent future drift by recommending atomic updates. Point to the bump-version skill for version increments since it updates both metadata files in a single operation, eliminating the window where manual editing of one file can orphan the other.
Script Usage
.claude/scripts/check-versions.sh
The script takes no arguments and checks all plugins in the repository. It returns exit code 0 if all versions match, or exit code 1 if mismatches are found.
Examples
Example 1: All versions match
$ .claude/scripts/check-versions.sh
Checking version consistency across metadata files...
thinkies:
plugin.json: 1.3.0
marketplace.json: 1.3.0
✅ Versions match
software:
plugin.json: 1.1.2
marketplace.json: 1.1.2
✅ Versions match
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ PASS: All plugin versions are consistent
Report success and confirm that metadata files maintain their promise to users.
Example 2: Version mismatch detected
$ .claude/scripts/check-versions.sh
Checking version consistency across metadata files...
thinkies:
plugin.json: 1.4.0
marketplace.json: 1.3.0
❌ Version mismatch
software:
plugin.json: 1.1.2
marketplace.json: 1.1.2
✅ Versions match
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ FAIL: Found version mismatches in 1 plugin(s)
Identify that thinkies breaks the version contract, showing 1.4.0 in its source declaration while the marketplace still advertises 1.3.0 to users. Examine recent commits and CHANGELOG.md to determine whether 1.4.0 represents genuine progress warranting marketplace sync, or premature inflation requiring rollback to 1.3.0. Guide toward updating whichever file drifted from truth, then suggest running check-changelogs to verify the CHANGELOG documents the corrected version.
