diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index c7b71a3f..2b55a315 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ }, "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": [ @@ -14,7 +14,7 @@ "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" diff --git a/.claude/skills/plugin-version/SKILL.md b/.claude/skills/plugin-version/SKILL.md new file mode 100644 index 00000000..c7f3cb62 --- /dev/null +++ b/.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//.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 diff --git a/.claude/skills/pr-changeset/SKILL.md b/.claude/skills/pr-changeset/SKILL.md index 74462fab..0f9a7bb8 100644 --- a/.claude/skills/pr-changeset/SKILL.md +++ b/.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 diff --git a/CLAUDE.md b/CLAUDE.md index 395f2be6..2f2f4bbf 100644 --- a/CLAUDE.md +++ b/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 diff --git a/claude-plugins/opensaas-migration/.claude-plugin/plugin.json b/claude-plugins/opensaas-migration/.claude-plugin/plugin.json index 647e6477..5a2adb02 100644 --- a/claude-plugins/opensaas-migration/.claude-plugin/plugin.json +++ b/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" diff --git a/claude-plugins/opensaas-migration/skills/migrate-document-fields/SKILL.md b/claude-plugins/opensaas-migration/skills/migrate-document-fields/SKILL.md index ebb64e6b..13f342ad 100644 --- a/claude-plugins/opensaas-migration/skills/migrate-document-fields/SKILL.md +++ b/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() ``` diff --git a/claude-plugins/opensaas-migration/skills/opensaas-migration/SKILL.md b/claude-plugins/opensaas-migration/skills/opensaas-migration/SKILL.md index 1dd4cc65..25acf84d 100644 --- a/claude-plugins/opensaas-migration/skills/opensaas-migration/SKILL.md +++ b/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 diff --git a/claude-plugins/opensaas-stack/.claude-plugin/plugin.json b/claude-plugins/opensaas-stack/.claude-plugin/plugin.json index 6daf25c7..114cab67 100644 --- a/claude-plugins/opensaas-stack/.claude-plugin/plugin.json +++ b/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", diff --git a/claude-plugins/opensaas-stack/skills/opensaas-builder/SKILL.md b/claude-plugins/opensaas-stack/skills/opensaas-builder/SKILL.md index 2fb1577f..77a9196c 100644 --- a/claude-plugins/opensaas-stack/skills/opensaas-builder/SKILL.md +++ b/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