Add plugin-version skill and bump plugin versions to 0.2.1

.claude-plugin/marketplace.json

@@ -6,15 +6,15 @@
   },
   "metadata": {
     "description": "Official OpenSaaS Stack plugin marketplace for development and migration tools",
-    "version": "1.1.0",
+    "version": "1.1.1",
     "homepage": "https://stack.opensaas.au/"
   },
   "plugins": [
     {
       "name": "opensaas-stack",
       "source": "./claude-plugins/opensaas-stack",
       "description": "Feature-driven development assistant for OpenSaaS Stack. Build complete applications by describing what you want to build instead of configuring infrastructure.",
-      "version": "0.2.0",
+      "version": "0.2.2",
       "author": {
         "name": "OpenSaaS",
         "url": "https://opensaas.au"
@@ -29,7 +29,7 @@
       "name": "opensaas-migration",
       "source": "./claude-plugins/opensaas-migration",
       "description": "OpenSaaS Stack migration assistant with AI-guided configuration, schema analysis, and code generation support",
-      "version": "0.2.0",
+      "version": "0.2.2",
       "author": {
         "name": "OpenSaaS Team",
         "url": "https://github.com/OpenSaasAU/stack"

.claude/skills/plugin-version/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: plugin-version
+description: Bump plugin versions in the OpenSaaS Stack monorepo. Invoke whenever any file under claude-plugins/* or .claude-plugin/ is modified — skills, commands, agents, or marketplace config. Plugin versions must be bumped before committing so users who install the plugin get the updated version. Note: this is separate from pr-changeset, which handles npm packages — plugin versions are managed directly in plugin.json and marketplace.json.
+allowed-tools: Read, Edit, Bash, Grep, Glob
+---
+
+# Plugin Version Skill
+
+This skill bumps version numbers for Claude plugins and the marketplace manifest. Plugin versions live directly in JSON files (not changesets) — bumping them is what signals to the marketplace that something changed and triggers users to get the update.
+
+## Files This Skill Manages
+
+| Changed directory                    | Files to update                                                                                                                                             |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `claude-plugins/opensaas-stack/`     | `claude-plugins/opensaas-stack/.claude-plugin/plugin.json` (version) AND `.claude-plugin/marketplace.json` (plugins[name="opensaas-stack"].version)         |
+| `claude-plugins/opensaas-migration/` | `claude-plugins/opensaas-migration/.claude-plugin/plugin.json` (version) AND `.claude-plugin/marketplace.json` (plugins[name="opensaas-migration"].version) |
+| `.claude-plugin/` root files only    | `.claude-plugin/marketplace.json` (metadata.version only)                                                                                                   |
+
+## Versioning Rules
+
+### Patch (bug fixes only)
+
+- **Use for**: Bug fixes, typo corrections, documentation fixes, minor wording improvements in skill descriptions
+- **Bump**: `x.y.Z` → `x.y.Z+1`
+- **Description**: Maximum 2 lines
+
+### Minor (features or enhancements)
+
+- **Use for**: New skills, new commands, new agents, new MCP tools, enhancements to existing capabilities
+- **Bump**: `x.Y.z` → `x.Y+1.0` (reset patch to 0)
+- **Description**: Describe the new capability
+
+### Major (breaking changes)
+
+- **Use for**: Removed skills/commands/tools, changed invocation patterns, incompatible changes
+- **ONLY when explicitly requested by the user**
+- **Bump**: `X.y.z` → `X+1.0.0` (reset minor and patch to 0)
+
+## Instructions
+
+### Step 1: Identify Changed Plugin Directories
+
+Run git commands to detect which plugin areas changed:
+
+```bash
+git diff --name-only HEAD
+# or for staged changes:
+git diff --name-only --cached
+# or for all changes relative to main:
+git diff --name-only origin/main...HEAD
+```
+
+Look for paths starting with:
+
+- `claude-plugins/opensaas-stack/` → opensaas-stack plugin changed
+- `claude-plugins/opensaas-migration/` → opensaas-migration plugin changed
+- `.claude-plugin/` → marketplace root changed (check if any file other than version fields changed)
+
+### Step 2: Determine Version Bump Type
+
+For each changed plugin:
+
+- **Is this a bug fix or correction?** → Use `patch`
+- **Is this a new skill, command, agent, or capability?** → Use `minor`
+- **Does this remove or rename something users depend on?** → Use `major` only if user explicitly requested it; otherwise ask
+
+### Step 3: Read Current Versions
+
+For each affected plugin, read the current version:
+
+```
+Read: claude-plugins/<plugin-name>/.claude-plugin/plugin.json
+```
+
+The version is in the top-level `"version"` field.
+
+For the marketplace:
+
+```
+Read: .claude-plugin/marketplace.json
+```
+
+The marketplace metadata version is at `metadata.version`. Each plugin's marketplace entry version is at `plugins[i].version` where `plugins[i].name` matches the plugin name.
+
+### Step 4: Calculate New Version
+
+Given the current version string `"x.y.z"`:
+
+- **patch**: increment z → `"x.y.(z+1)"`
+  - `"0.2.0"` → `"0.2.1"`
+  - `"1.3.4"` → `"1.3.5"`
+- **minor**: increment y, reset z to 0 → `"x.(y+1).0"`
+  - `"0.2.0"` → `"0.3.0"`
+  - `"1.3.4"` → `"1.4.0"`
+- **major**: increment x, reset y and z to 0 → `"(x+1).0.0"`
+  - `"0.2.0"` → `"1.0.0"`
+  - `"1.3.4"` → `"2.0.0"`
+
+### Step 5: Edit the JSON Files
+
+For each changed plugin, make two targeted edits using the Edit tool.
+
+**Edit 1 — The plugin's own plugin.json:**
+
+Find the `"version"` field near the top of the file and replace just that value.
+
+Example in `claude-plugins/opensaas-stack/.claude-plugin/plugin.json`:
+
+```
+"version": "0.2.0",
+```
+
+→
+
+```
+"version": "0.2.1",
+```
+
+**Edit 2 — The matching entry in marketplace.json:**
+
+The `plugins` array in `.claude-plugin/marketplace.json` has one object per plugin. Find the object where `"name"` matches the plugin name and edit its `"version"` field.
+
+Example: find the block for `"name": "opensaas-stack"` and edit:
+
+```
+      "version": "0.2.0",
+```
+
+→
+
+```
+      "version": "0.2.1",
+```
+
+**Edit 3 (conditional) — Marketplace metadata.version:**
+
+Only bump `metadata.version` if files in the `.claude-plugin/` root directory were directly changed (e.g., `MARKETPLACE.md`, new fields added to `marketplace.json` structure, owner/metadata fields edited). Do NOT bump it just because plugin versions changed.
+
+### Step 6: Verify the Edits
+
+After editing, read back the affected files to confirm:
+
+- The version field shows the new version
+- No other fields were accidentally changed
+- Both plugin.json and the matching marketplace.json entry show the same new version number
+
+## Examples
+
+### Example 1: Patch — Fix a typo in a skill description
+
+Changed files: `claude-plugins/opensaas-stack/skills/some-skill/SKILL.md`
+
+Current version: `"0.2.0"` → New version: `"0.2.1"`
+
+Edit `claude-plugins/opensaas-stack/.claude-plugin/plugin.json`:
+
+- `"version": "0.2.0"` → `"version": "0.2.1"`
+
+Edit `.claude-plugin/marketplace.json` (in the `opensaas-stack` plugins entry):
+
+- `"version": "0.2.0"` → `"version": "0.2.1"`
+
+Do NOT change `metadata.version` — the marketplace structure itself did not change.
+
+### Example 2: Minor — Add a new skill to opensaas-migration
+
+Changed files: `claude-plugins/opensaas-migration/skills/new-skill/SKILL.md` (new file)
+
+Current version: `"0.2.0"` → New version: `"0.3.0"`
+
+Edit `claude-plugins/opensaas-migration/.claude-plugin/plugin.json`:
+
+- `"version": "0.2.0"` → `"version": "0.3.0"`
+
+Edit `.claude-plugin/marketplace.json` (in the `opensaas-migration` plugins entry):
+
+- `"version": "0.2.0"` → `"version": "0.3.0"`
+
+### Example 3: Changes to both plugins
+
+Changed files include both `claude-plugins/opensaas-stack/...` and `claude-plugins/opensaas-migration/...`
+
+Determine bump type independently for each plugin based on the nature of its changes. They can be bumped to different versions.
+
+Edit `claude-plugins/opensaas-stack/.claude-plugin/plugin.json` with its new version.
+Edit `claude-plugins/opensaas-migration/.claude-plugin/plugin.json` with its new version.
+Edit `.claude-plugin/marketplace.json` twice — once for each plugin's entry.
+
+### Example 4: Marketplace-only change
+
+Changed files: `.claude-plugin/marketplace.json` (added a new top-level field) or `.claude-plugin/MARKETPLACE.md`
+
+The marketplace structure itself changed, so bump `metadata.version`.
+
+Current: `"version": "1.1.0"` → New: `"version": "1.1.1"` (patch)
+
+Edit `.claude-plugin/marketplace.json` `metadata.version` field only.
+Do NOT change any plugin.json files — no plugin logic changed.
+
+## Common Mistakes to Avoid
+
+1. **Don't bump metadata.version just because plugin versions changed**
+   - Plugin version entries in marketplace.json are synced from plugin.json
+   - Only bump metadata.version when the marketplace file's own structure changed
+
+2. **Don't forget the marketplace.json plugin entry**
+   - When you bump a plugin.json, always also update the matching entry in marketplace.json
+   - The two must stay in sync
+
+3. **Don't use major unless explicitly requested**
+   - New skills and commands are minor, not major
+   - Ask the user if you think a major bump is warranted
+
+4. **Don't reset patch to 0 on a patch bump**
+   - patch: `0.2.3` → `0.2.4` (not `0.2.0`)
+   - minor: `0.2.3` → `0.3.0` (reset patch)
+   - major: `0.2.3` → `1.0.0` (reset both)
+
+5. **Don't edit unrelated fields**
+   - Use Edit tool with precise old_string/new_string targeting just the version line
+   - Verify after editing that only the version changed
+
+6. **Don't create changeset files**
+   - This skill edits JSON files directly
+   - Plugin versions are NOT managed by the npm changeset system
+
+## Workflow
+
+When working on plugin changes:
+
+1. Make your plugin code changes
+2. Before committing, invoke this skill to bump versions
+3. Verify the JSON files show the correct new versions
+4. Commit all changed files together (plugin code + plugin.json + marketplace.json)
+
+## Troubleshooting
+
+**Q: Both plugins changed but for very different reasons — do I use the same bump type?**
+A: No. Evaluate each plugin independently. One might be a patch and the other a minor bump.
+
+**Q: I added a new skill AND fixed a bug in the same plugin. Which bump type?**
+A: Use minor (the higher of the two).
+
+**Q: How do I know if marketplace metadata.version should be bumped?**
+A: Ask: "Did I change marketplace.json itself beyond just updating plugin version entries?" If you edited owner, metadata.description, added new top-level fields, or changed MARKETPLACE.md — yes. If you only updated plugin version numbers — no.
+
+**Q: What if I only changed README.md inside a plugin directory?**
+A: Still bump the plugin version (patch). Documentation is part of the plugin release.
+
+**Q: Should this skill be used alongside pr-changeset?**
+A: These are independent. `pr-changeset` handles npm packages in `packages/*`. This skill handles Claude plugins in `claude-plugins/*`. If a PR changes both, use both skills.
+
+## Important Notes
+
+- Plugin versions are semver strings stored directly in JSON — there is no automated tooling managing them
+- The marketplace.json `plugins[].version` fields must always match the corresponding plugin.json `version` fields
+- marketplace.json `metadata.version` is independent and tracks the marketplace manifest itself
+- Both plugin.json files and marketplace.json must be committed together in the same commit as the plugin changes

.claude/skills/pr-changeset/SKILL.md

@@ -1,19 +1,12 @@
 ---
 name: pr-changeset
-description: Create changesets for package changes in pull requests. Use whenever you modify code in any package (packages/*). Required before committing changes to packages. Handles versioning with patch for bug fixes, minor for features, and major only when explicitly requested.
+description: Create changesets for package changes in pull requests. Invoke whenever any file under packages/* is modified — including bug fixes, new features, and even documentation or typo changes. Changesets are required before committing; without one, the release pipeline won't know what changed or how to version it. Also trigger when the user asks about versioning, what changeset to create, or whether a change needs a changeset.
 allowed-tools: Write, Read, Bash, Grep, Glob
 ---
 
 # PR Changeset Skill
 
-This skill helps you create proper changeset files when making changes to packages in the monorepo. **You MUST use this skill whenever you modify code in any package.**
-
-## When to Use
-
-- **ALWAYS** when modifying files in `packages/*`
-- Before committing changes to any package
-- When creating or updating a pull request that affects packages
-- Even for small changes (typo fixes, documentation updates in packages)
+This skill creates the changeset file that tells the release pipeline what changed and how to version it. Every change to a package needs one — even small fixes — because changesets are how versions get bumped and changelogs get generated automatically.
 
 ## Versioning Rules
 

CLAUDE.md

@@ -9,6 +9,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **README files:** Each package and example has its own README for specific usage instructions
 - **Claude Skills:** Specialized skills for common tasks are in `.claude/skills/`
   - `pr-changeset`: **REQUIRED** - Use when modifying any package code to create proper changeset files
+  - `plugin-version`: **REQUIRED** - Use when modifying any Claude plugin code to bump plugin and marketplace versions
 
 ## Project Overview
 
@@ -1311,6 +1312,20 @@ Then follow the prompts to select packages and version bumps.
 2. Commit changes including the changeset file.
    Version bumping and publishing is handled automatically by changesets during release in a GitHub Action.
 
+## Publishing Plugins
+
+Claude plugins in `claude-plugins/*` use direct semver versioning in JSON files. Whenever you modify plugin code, skills, commands, agents, or marketplace root files, you must bump the version using the `plugin-version` skill.
+
+**IMPORTANT:** When working with Claude Code, you MUST use the `plugin-version` skill to bump plugin versions. It handles both the plugin's own `plugin.json` and the matching entry in `.claude-plugin/marketplace.json`.
+
+The `plugin-version` skill:
+
+- Detects which plugin directories changed (`claude-plugins/opensaas-stack/`, `claude-plugins/opensaas-migration/`, `.claude-plugin/`)
+- Determines patch vs minor bump (patch for fixes, minor for new capabilities, major only when explicitly requested)
+- Directly edits version fields in JSON — no changeset files
+- Keeps `plugin.json` and `marketplace.json` plugin entries in sync
+- Only bumps `marketplace.metadata.version` when the marketplace structure itself changed (not just plugin version numbers)
+
 - Data passed in as props to a component that is marked with `"use client"` must be serialised and must only contain the minimum data required to make that component work
 - Avoid the use of the `any` type, and do not use type casting. All types must be strongly typed to ensure type satefy - the `unkown` and `any` types must never exposed as an exteral type and are only to be used internally (within a package) where absolutely necessary
 

claude-plugins/opensaas-migration/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "opensaas-migration",
   "description": "OpenSaaS Stack migration assistant with AI-guided configuration, schema analysis, and code generation support",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "author": {
     "name": "OpenSaaS Team",
     "url": "https://github.com/OpenSaasAU/stack"

claude-plugins/opensaas-migration/skills/migrate-document-fields/SKILL.md

@@ -102,7 +102,7 @@ Write a comment in the code for any document fields that had existing content so
 ```typescript
 // NOTE: This field was migrated from Keystone document format.
 // Existing content may not render correctly until re-saved in the Tiptap editor.
-// See specs/keystone-image-migration.md for data migration guidance.
+// See specs/keystone-document-migration.md for data migration guidance.
 content: richText()
 ```
 

claude-plugins/opensaas-migration/skills/opensaas-migration/SKILL.md

@@ -1,22 +1,12 @@
 ---
 name: opensaas-migration
-description: Expert knowledge for migrating projects to OpenSaaS Stack. Use when discussing migration strategies, access control patterns, or OpenSaaS Stack configuration best practices.
+description: Expert knowledge for migrating projects to OpenSaaS Stack. Invoke whenever the user mentions migrating from KeystoneJS, Prisma, or an existing Next.js project; asks about access control patterns or opensaas.config.ts; or is troubleshooting any aspect of an OpenSaaS Stack migration. Don't wait for the user to say "migration" — trigger whenever the conversation touches these areas.
 ---
 
 # OpenSaaS Stack Migration
 
 Expert guidance for migrating existing projects to OpenSaaS Stack.
 
-## When to Use This Skill
-
-Use this skill when:
-
-- Planning a migration from Prisma, KeystoneJS, or Next.js
-- Designing access control patterns
-- Configuring `opensaas.config.ts`
-- Troubleshooting migration issues
-- Explaining OpenSaaS Stack concepts
-
 ## Migration Process
 
 ### 1. Install Required Packages

claude-plugins/opensaas-stack/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "opensaas-stack",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Feature-driven development assistant for OpenSaaS Stack. Build complete applications by describing what you want to build instead of configuring infrastructure.",
   "author": {
     "name": "OpenSaaS",

claude-plugins/opensaas-stack/skills/opensaas-builder/SKILL.md

@@ -1,6 +1,9 @@
-# OpenSaaS App Builder Skill
+---
+name: opensaas-builder
+description: Build applications and features on the OpenSaaS Stack. Use this whenever a user describes building an app, adding functionality, implementing a feature, or asks "how do I implement X" in an OpenSaaS Stack project. Also trigger when the user describes business requirements, data models, or use cases — even if they don't say "OpenSaaS" explicitly.
+---
 
-**When to invoke**: User describes wanting to build an application or add functionality to their OpenSaaS Stack app
+# OpenSaaS App Builder Skill
 
 ## Pattern Recognition