Enforce plugin version sync between plugin.json and marketplace.json

.github/instructions/plugin-editing.instructions.md

@@ -0,0 +1,29 @@
+---
+applyTo: "plugins/**"
+---
+
+# Plugin Editing — Version Bump Reminder
+
+Whenever you edit any file inside a `plugins/<name>/` directory, remind the user to bump the plugin version before committing:
+
+1. Increment the `version` field in `plugins/<name>/plugin.json` using the semver rules below.
+2. Update the matching entry's `version` in `.github/plugin/marketplace.json` to the same value.
+
+## Semver guidance for plugins
+
+**Patch** (`1.0.x`) — backward-compatible fixes and clarifications with no change in scope:
+- Fixing typos, grammar, or unclear wording in instructions
+- Rewording guidance to improve clarity without changing intent
+- Adding or improving examples that illustrate existing rules
+
+**Minor** (`1.x.0`) — backward-compatible additions that expand what the plugin covers:
+- Adding new instruction files or new sections to existing ones
+- Adding a new agent, prompt, or capability to the plugin
+- Extending keywords or categories in `plugin.json`
+
+**Major** (`x.0.0`) — changes that alter existing behavior in a way users may need to adapt to:
+- Removing or renaming instruction files referenced by the plugin
+- Fundamentally changing the guidance or recommendations in a way that conflicts with prior versions
+- Changing the plugin `name` field (affects install commands and `@` references)
+
+The CI workflow enforces that these two versions match, so both files must be updated together.

.github/instructions/plugin-version-sync.instructions.md

@@ -0,0 +1,13 @@
+---
+applyTo: "plugins/**/plugin.json,.github/plugin/marketplace.json"
+---
+
+# Plugin Version Sync
+
+The `version` field in every `plugins/<name>/plugin.json` **must always match** the corresponding entry's `version` in `.github/plugin/marketplace.json`.
+
+When editing either file:
+- If you change the `version` in a `plugin.json`, update the matching entry in `.github/plugin/marketplace.json` to the same value.
+- If you change a plugin's `version` in `marketplace.json`, update the corresponding `plugin.json` to the same value.
+
+Both files must be committed together so the CI version-sync check passes.

.github/workflows/validate-plugins.yml

@@ -73,3 +73,46 @@ jobs:
 
           print("✓ All plugin names are unique")
           EOF
+
+      - name: Validate plugin versions match marketplace.json
+        run: |
+          python3 << 'EOF'
+          import json
+          import glob
+          import sys
+
+          with open(".github/plugin/marketplace.json", "r") as f:
+              marketplace = json.load(f)
+
+          marketplace_versions = {
+              p["name"]: p["version"] for p in marketplace.get("plugins", [])
+          }
+
+          errors = []
+          for plugin_file in glob.glob("plugins/**/plugin.json", recursive=True):
+              with open(plugin_file, "r") as f:
+                  plugin = json.load(f)
+
+              name = plugin.get("name")
+              plugin_version = plugin.get("version")
+              marketplace_version = marketplace_versions.get(name)
+
+              if marketplace_version is None:
+                  errors.append(
+                      f"❌ {plugin_file}: plugin '{name}' not found in marketplace.json"
+                  )
+              elif plugin_version != marketplace_version:
+                  errors.append(
+                      f"❌ {plugin_file}: version '{plugin_version}' does not match "
+                      f"marketplace.json version '{marketplace_version}' for plugin '{name}'"
+                  )
+              else:
+                  print(f"✓ {plugin_file}: version '{plugin_version}' matches marketplace.json")
+
+          if errors:
+              for error in errors:
+                  print(error)
+              sys.exit(1)
+
+          print("\n✓ All plugin versions match marketplace.json")
+          EOF