semver-plugin
Apply Semantic Versioning 2.0.0 rules to release decisions and reviews.
Open source Open in the app JSON README (API)
About
Apply Semantic Versioning 2.0.0 rules to release decisions and reviews.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- lenoseibert
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.2.6
- Stars
- 1
- Forks
- 1
- Last push
- 2026-07-25T00:35:14Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
lenoseibert/semver-plugin
README
# SemVer Rules [](LICENSE) [](https://semver.org/) [](LICENSES/CC-BY-3.0.txt)  > Portable plugin for coding agents that applies the official > [Semantic Versioning 2.0.0](https://semver.org/) specification when planning > and reviewing releases. --- ## 📋 Table of Contents - [Use case and problem solved](#-use-case-and-problem-solved) - [Languages](#-languages) - [Features](#-features) - [Supported harnesses](#-supported-harnesses) - [Installation](#-installation) - [Uninstalling](#-uninstalling) - [Updating](#-updating) - [Usage](#-usage) - [Project automation](#-project-automation) - [License and attribution](#-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](README.md) · [🇨🇳 中文（简体）](docs/README.zh-CN.md) · [🇪🇸 Español](docs/README.es.md) · [🇮🇳 हिन्दी](docs/README.hi.md) · [🇧🇷 Português (Brasil)](docs/README.pt-BR.md) --- ## ✨ 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 ```sh 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 ```sh 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`: ```sh 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 ```sh 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: ```sh 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: ```sh 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: ```sh ./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: ```sh make remove-local ``` To remove the plugin and marketplace installed from GitHub: ```sh # 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 ```sh 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 ```sh claude plugin marketplace update semver-plugin claude plugin update semver-plugin@semver-plugin ``` Run `/reload-plugins` or start a new session. ### Gemini CLI ```sh gemini extensions update semver-plugin ``` Use `gemini extensions update --all` to update every installed extension. Restart the Gemini session afterward. ### GitHub Copilot CLI ```sh 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: ```sh 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`](VERSION). The same version must appear in the Codex, Claude Code, Gemini CLI, and GitHub Copilot manifests. CI runs `node scripts/check-version.js` on pull requests and pushes to `main` or `dev`, which also verifies that both hook files still expose their plugin-root variable. This project is still in `0.x`, so it documents its own pre-1.0 policy: a breaking change to a published contract — hook event or command shape, skill name or frontmatter, manifest keys, or dropping a harness — increments `MINOR`, and every other change increments `PATCH`. Every merge into `main` carries a version bump, documentation-only changes included. Run `make validate` for the full check, `make test` for the installer smoke test, and `make lint` for Markdown and shell linting. CI runs the same checks. 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](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](LICENSES/CC-BY-3.0.txt). See [NOTICE](NOTICE) for the required attribution and source link.