From d25fc53e9b61dee4f73691f2db288e14a67e33a2 Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Tue, 14 Oct 2025 13:30:16 -0700
Subject: [PATCH] feat: Add version compatibility checking to plugin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds version management to help users keep bd CLI and plugin in sync.

Changes:
- Add engines field to plugin.json requiring bd >=0.9.0
- Add /bd-version command to check component versions
- Add comprehensive "Updating" section to PLUGIN.md
- Document recommended update workflow

Users can now run /bd-version to check:
- bd CLI version
- Plugin version
- MCP server status
- Compatibility warnings

Addresses version sync concerns raised in plugin development.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .claude-plugin/commands/bd-version.md | 22 +++++++++++
 .claude-plugin/plugin.json            |  3 ++
 PLUGIN.md                             | 56 +++++++++++++++++++++++++++
 3 files changed, 81 insertions(+)
 create mode 100644 .claude-plugin/commands/bd-version.md

diff --git a/.claude-plugin/commands/bd-version.md b/.claude-plugin/commands/bd-version.md
new file mode 100644
index 00000000..aeedaf3e
--- /dev/null
+++ b/.claude-plugin/commands/bd-version.md
@@ -0,0 +1,22 @@
+---
+description: Check beads and plugin versions
+---
+
+Check the installed versions of beads components and verify compatibility.
+
+Use the beads MCP tools to:
+1. Run `bd --version` via bash to get the CLI version
+2. Check the plugin version from the environment
+3. Compare versions and report any mismatches
+
+Display:
+- bd CLI version (from `bd --version`)
+- Plugin version (0.9.0)
+- MCP server status (from `stats` tool or connection test)
+- Compatibility status (✓ compatible or ⚠️ update needed)
+
+If versions are mismatched, provide instructions:
+- Update bd CLI: `curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash`
+- Update plugin: `/plugin update beads`
+
+Suggest checking for updates if the user is on an older version.
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 99197caa..6cb8487d 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -19,6 +19,9 @@
     "agent-memory",
     "mcp-server"
   ],
+  "engines": {
+    "beads": ">=0.9.0"
+  },
   "mcpServers": {
     "beads": {
       "command": "uv",
diff --git a/PLUGIN.md b/PLUGIN.md
index 0ceb17d7..783c6b66 100644
--- a/PLUGIN.md
+++ b/PLUGIN.md
@@ -73,6 +73,10 @@ After installation, restart Claude Code to activate the MCP server.
 
 ## Available Commands
 
+### Version Management
+
+- **`/bd-version`** - Check bd CLI, plugin, and MCP server versions
+
 ### Core Workflow Commands
 
 - **`/bd-ready`** - Find tasks with no blockers, ready to work on
@@ -225,6 +229,58 @@ git pull
 bd ready  # Fresh data from git!
 ```
 
+## Updating
+
+The beads plugin has three components that may need updating:
+
+### 1. Plugin Updates
+
+Check for plugin updates:
+```bash
+/plugin update beads
+```
+
+Claude Code will pull the latest version from GitHub. After updating, **restart Claude Code** to apply MCP server changes.
+
+### 2. bd CLI Updates
+
+The plugin requires the `bd` CLI to be installed. Update it separately:
+
+```bash
+# Quick update
+curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash
+
+# Or with go
+go install github.com/steveyegge/beads/cmd/bd@latest
+```
+
+### 3. Version Compatibility
+
+Check version compatibility:
+```bash
+/bd-version
+```
+
+This will show:
+- bd CLI version
+- Plugin version
+- MCP server status
+- Compatibility warnings if versions mismatch
+
+**Recommended update workflow:**
+1. Check versions: `/bd-version`
+2. Update bd CLI if needed (see above)
+3. Update plugin: `/plugin update beads`
+4. Restart Claude Code
+5. Verify: `/bd-version`
+
+### Version Numbering
+
+Beads follows semantic versioning. The plugin version tracks the bd CLI version:
+- Plugin 0.9.x requires bd CLI 0.9.0+
+- Major version bumps may introduce breaking changes
+- Check CHANGELOG.md for release notes
+
 ## Troubleshooting
 
 ### Plugin not appearing