SemVer Rules

Portable plugin for coding agents that applies the official Semantic Versioning 2.0.0 specification when planning and reviewing releases.

---

📋 Table of Contents

• Use case and problem solved
• Languages
• Features
• Supported harnesses
• Installation
• Uninstalling
• Updating
• Usage
• Project automation
• License and attribution

---

🎯 Use case and problem solved

Use this plugin when an agent needs to decide whether a set of changes should produce a major, minor, patch, or no release, especially during release planning, pull request review, changelog preparation, or version audits.

It solves a common release problem: version bumps are often chosen from commit labels, gut feeling, or the size of a diff. SemVer instead depends on the declared public API and compatibility impact. The plugin keeps that rule in front of the agent, helps inspect the actual changes, and makes the release recommendation easier to justify.

---

🌐 Languages

English is the canonical README. Translations are provided in five of the world's most widely spoken first languages:

🇺🇸 English · 🇨🇳 中文（简体） · 🇪🇸 Español · 🇮🇳 हिन्दी · 🇧🇷 Português (Brasil)

---

✨ Features

Skill	Description
semver	Chooses the next version and validates version syntax and precedence
semver-review	Reviews changes and recommends major, minor, patch, or no release
Hooks	Session- and subagent-start hooks load a concise rules reminder without external dependencies beyond the host's Node.js runtime

---

🔌 Supported harnesses

Harness	Integration
Codex	native manifest, marketplace, skills, and hooks
Claude Code	manifest, skills, and hooks
Gemini CLI	extension, context, skills, and session hook
GitHub Copilot CLI	plugin, skills, and hooks
OpenCode / Cursor	portable instructions through AGENTS.md

---

📦 Installation

Codex

codex plugin marketplace add LenoSeibert/semver-plugin
codex plugin add semver-plugin@semver-plugin

Open /hooks, review and authorize the hooks, then start a new Codex task.

Claude Code

claude plugin marketplace add LenoSeibert/semver-plugin
claude plugin install semver-plugin@semver-plugin

By default the plugin is installed at the user level. To choose where it applies, pass --scope:

claude plugin install semver-plugin@semver-plugin --scope user     # all your projects (default)
claude plugin install semver-plugin@semver-plugin --scope project  # shared via .claude/settings.json
claude plugin install semver-plugin@semver-plugin --scope local    # this machine only (.claude/settings.local.json)

The interactive /plugin menu also lets you pick the scope at install time.

Run /reload-plugins or start a new session.

Gemini CLI

gemini extensions install https://github.com/LenoSeibert/semver-plugin

Restart the Gemini session. To develop from a local clone, run gemini extensions link ..

GitHub Copilot CLI

Marketplace installs are the forward-compatible path. Direct repository installs still work today, but Copilot warns that they are deprecated:

copilot plugin install LenoSeibert/semver-plugin

OpenCode and Cursor

These harnesses discover AGENTS.md in the project. Clone the repository and copy or link the file without overwriting existing instructions:

git clone https://github.com/LenoSeibert/semver-plugin.git
cp semver-plugin/AGENTS.md /path/to/project/AGENTS.md

💡 Tip: If the project already has an AGENTS.md, incorporate the SemVer section manually.

Local source development

Install or refresh the current working tree without pushing it to GitHub:

./scripts/install-local.sh all
# or
make install-local

Pass codex, claude, gemini, or copilot instead of all to update one harness. Use --dry-run to inspect the commands first. The script includes tracked, modified, and untracked files; start a new harness session afterward. Run make help to see the corresponding per-harness and validation targets.

---

🗑️ Uninstalling

To remove local source installations created by this repository:

make remove-local

To remove the plugin and marketplace installed from GitHub:

# Codex
codex plugin remove semver-plugin@semver-plugin
codex plugin marketplace remove semver-plugin

# Claude Code
claude plugin uninstall semver-plugin@semver-plugin --scope user
claude plugin marketplace remove semver-plugin --scope user

# Gemini CLI
gemini extensions uninstall semver-plugin

# GitHub Copilot CLI
copilot plugin uninstall semver-plugin

For OpenCode or Cursor, remove the SemVer section previously copied into the project's AGENTS.md; do not delete unrelated project instructions.

---

🔄 Updating

Codex

codex plugin marketplace add LenoSeibert/semver-plugin
codex plugin add semver-plugin@semver-plugin

Re-running the install commands refreshes the marketplace and pulls the latest version. Re-authorize the hooks in /hooks if prompted, then start a new task.

Claude Code

claude plugin marketplace update semver-plugin
claude plugin update semver-plugin@semver-plugin

Run /reload-plugins or start a new session.

Gemini CLI

gemini extensions update semver-plugin

Use gemini extensions update --all to update every installed extension. Restart the Gemini session afterward.

GitHub Copilot CLI

copilot plugin install LenoSeibert/semver-plugin

Re-running the install command fetches the latest version.

OpenCode and Cursor

Pull the latest repository and re-copy the file, preserving any local edits:

git -C semver-plugin pull
cp semver-plugin/AGENTS.md /path/to/project/AGENTS.md

💡 Tip: If you merged the SemVer section into an existing AGENTS.md, reconcile the changes manually instead of overwriting.

---

🚀 Usage

After installation, try:

• "What should the next version be after these changes?"
• "Review this diff according to SemVer."
• "Order these versions with pre-releases."

ℹ️ Note: The plugin follows SemVer 2.0.0. npm, Cargo, PEP 440, or other ecosystem conventions apply only when explicitly requested.

---

🤖 Project automation

This repository keeps the release version in VERSION. The same version must appear in the Codex, Claude Code, and GitHub Copilot plugin manifests. CI runs node scripts/check-version.js on pull requests and pushes to main or dev.

When dev changes, the promotion workflow validates the version and prints a compare link for opening a dev to main pull request. It does not create or merge pull requests automatically.

When main changes, the release workflow validates the version, creates the GitHub tag vX.Y.Z, builds semver-plugin-X.Y.Z.zip, and publishes a GitHub Release. VERSION remains strict SemVer without the leading v.

---

📄 License and attribution

The plugin's original code and documentation are licensed under the MIT License. The Semantic Versioning 2.0.0 rules incorporated or adapted here are attributed to Tom Preston-Werner and are available under CC BY 3.0. See NOTICE for the required attribution and source link.