{
  "markdown": "# SemVer Rules\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![SemVer](https://img.shields.io/badge/SemVer-2.0.0-blue.svg)](https://semver.org/) [![CC BY 3.0](https://img.shields.io/badge/Rules-CC%20BY%203.0-lightgrey.svg)](LICENSES/CC-BY-3.0.txt)\n\n![Abstract illustration of three connected version milestones](assets/semver-rules-hero.png)\n\n> Portable plugin for coding agents that applies the official\n> [Semantic Versioning 2.0.0](https://semver.org/) specification when planning\n> and reviewing releases.\n\n---\n\n## 📋 Table of Contents\n\n- [Use case and problem solved](#-use-case-and-problem-solved)\n- [Languages](#-languages)\n- [Features](#-features)\n- [Supported harnesses](#-supported-harnesses)\n- [Installation](#-installation)\n- [Uninstalling](#-uninstalling)\n- [Updating](#-updating)\n- [Usage](#-usage)\n- [Project automation](#-project-automation)\n- [License and attribution](#-license-and-attribution)\n\n---\n\n## 🎯 Use case and problem solved\n\nUse this plugin when an agent needs to decide whether a set of changes should\nproduce a `major`, `minor`, `patch`, or no release, especially during release\nplanning, pull request review, changelog preparation, or version audits.\n\nIt solves a common release problem: version bumps are often chosen from commit\nlabels, gut feeling, or the size of a diff. SemVer instead depends on the\ndeclared public API and compatibility impact. The plugin keeps that rule in\nfront of the agent, helps inspect the actual changes, and makes the release\nrecommendation easier to justify.\n\n---\n\n## 🌐 Languages\n\nEnglish is the canonical README. Translations are provided in five of the\nworld's most widely spoken first languages:\n\n[🇺🇸 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)\n\n---\n\n## ✨ Features\n\n| Skill | Description |\n| --- | --- |\n| `semver` | Chooses the next version and validates version syntax and precedence |\n| `semver-review` | Reviews changes and recommends `major`, `minor`, `patch`, or no release |\n| Hooks | Session- and subagent-start hooks load a concise rules reminder without external dependencies beyond the host's Node.js runtime |\n\n---\n\n## 🔌 Supported harnesses\n\n| Harness | Integration |\n| --- | --- |\n| **Codex** | native manifest, marketplace, skills, and hooks |\n| **Claude Code** | manifest, skills, and hooks |\n| **Gemini CLI** | extension, context, skills, and session hook |\n| **GitHub Copilot CLI** | plugin, skills, and hooks |\n| **OpenCode / Cursor** | portable instructions through `AGENTS.md` |\n\n---\n\n## 📦 Installation\n\n### Codex\n\n```sh\ncodex plugin marketplace add LenoSeibert/semver-plugin\ncodex plugin add semver-plugin@semver-plugin\n```\n\nOpen `/hooks`, review and authorize the hooks, then start a new Codex task.\n\n### Claude Code\n\n```sh\nclaude plugin marketplace add LenoSeibert/semver-plugin\nclaude plugin install semver-plugin@semver-plugin\n```\n\nBy default the plugin is installed at the user level. To choose where it\napplies, pass `--scope`:\n\n```sh\nclaude plugin install semver-plugin@semver-plugin --scope user     # all your projects (default)\nclaude plugin install semver-plugin@semver-plugin --scope project  # shared via .claude/settings.json\nclaude plugin install semver-plugin@semver-plugin --scope local    # this machine only (.claude/settings.local.json)\n```\n\nThe interactive `/plugin` menu also lets you pick the scope at install time.\n\nRun `/reload-plugins` or start a new session.\n\n### Gemini CLI\n\n```sh\ngemini extensions install https://github.com/LenoSeibert/semver-plugin\n```\n\nRestart the Gemini session. To develop from a local clone, run\n`gemini extensions link .`.\n\n### GitHub Copilot CLI\n\nMarketplace installs are the forward-compatible path. Direct repository installs\nstill work today, but Copilot warns that they are deprecated:\n\n```sh\ncopilot plugin install LenoSeibert/semver-plugin\n```\n\n### OpenCode and Cursor\n\nThese harnesses discover `AGENTS.md` in the project. Clone the repository and\ncopy or link the file without overwriting existing instructions:\n\n```sh\ngit clone https://github.com/LenoSeibert/semver-plugin.git\ncp semver-plugin/AGENTS.md /path/to/project/AGENTS.md\n```\n\n> **💡 Tip:** If the project already has an `AGENTS.md`, incorporate the SemVer\n> section manually.\n\n### Local source development\n\nInstall or refresh the current working tree without pushing it to GitHub:\n\n```sh\n./scripts/install-local.sh all\n# or\nmake install-local\n```\n\nPass `codex`, `claude`, `gemini`, or `copilot` instead of `all` to update one\nharness. Use `--dry-run` to inspect the commands first. The script includes\ntracked, modified, and untracked files; start a new harness session afterward.\nRun `make help` to see the corresponding per-harness and validation targets.\n\n---\n\n## 🗑️ Uninstalling\n\nTo remove local source installations created by this repository:\n\n```sh\nmake remove-local\n```\n\nTo remove the plugin and marketplace installed from GitHub:\n\n```sh\n# Codex\ncodex plugin remove semver-plugin@semver-plugin\ncodex plugin marketplace remove semver-plugin\n\n# Claude Code\nclaude plugin uninstall semver-plugin@semver-plugin --scope user\nclaude plugin marketplace remove semver-plugin --scope user\n\n# Gemini CLI\ngemini extensions uninstall semver-plugin\n\n# GitHub Copilot CLI\ncopilot plugin uninstall semver-plugin\n```\n\nFor OpenCode or Cursor, remove the SemVer section previously copied into the\nproject's `AGENTS.md`; do not delete unrelated project instructions.\n\n---\n\n## 🔄 Updating\n\n### Codex\n\n```sh\ncodex plugin marketplace add LenoSeibert/semver-plugin\ncodex plugin add semver-plugin@semver-plugin\n```\n\nRe-running the install commands refreshes the marketplace and pulls the latest\nversion. Re-authorize the hooks in `/hooks` if prompted, then start a new task.\n\n### Claude Code\n\n```sh\nclaude plugin marketplace update semver-plugin\nclaude plugin update semver-plugin@semver-plugin\n```\n\nRun `/reload-plugins` or start a new session.\n\n### Gemini CLI\n\n```sh\ngemini extensions update semver-plugin\n```\n\nUse `gemini extensions update --all` to update every installed extension.\nRestart the Gemini session afterward.\n\n### GitHub Copilot CLI\n\n```sh\ncopilot plugin install LenoSeibert/semver-plugin\n```\n\nRe-running the install command fetches the latest version.\n\n### OpenCode and Cursor\n\nPull the latest repository and re-copy the file, preserving any local edits:\n\n```sh\ngit -C semver-plugin pull\ncp semver-plugin/AGENTS.md /path/to/project/AGENTS.md\n```\n\n> **💡 Tip:** If you merged the SemVer section into an existing `AGENTS.md`,\n> reconcile the changes manually instead of overwriting.\n\n---\n\n## 🚀 Usage\n\nAfter installation, try:\n\n- *\"What should the next version be after these changes?\"*\n- *\"Review this diff according to SemVer.\"*\n- *\"Order these versions with pre-releases.\"*\n\n> **ℹ️ Note:** The plugin follows SemVer 2.0.0. npm, Cargo, PEP 440, or other\n> ecosystem conventions apply only when explicitly requested.\n\n---\n\n## 🤖 Project automation\n\nThis repository keeps the release version in [`VERSION`](VERSION). The same\nversion must appear in the Codex, Claude Code, Gemini CLI, and GitHub Copilot\nmanifests. CI runs `node scripts/check-version.js` on pull requests and pushes\nto `main` or `dev`, which also verifies that both hook files still expose their\nplugin-root variable.\n\nThis project is still in `0.x`, so it documents its own pre-1.0 policy: a\nbreaking change to a published contract — hook event or command shape, skill\nname or frontmatter, manifest keys, or dropping a harness — increments `MINOR`,\nand every other change increments `PATCH`. Every merge into `main` carries a\nversion bump, documentation-only changes included.\n\nRun `make validate` for the full check, `make test` for the installer smoke\ntest, and `make lint` for Markdown and shell linting. CI runs the same checks.\n\nWhen `dev` changes, the promotion workflow validates the version and prints a\ncompare link for opening a `dev` to `main` pull request. It does not create or\nmerge pull requests automatically.\n\nWhen `main` changes, the release workflow validates the version, creates the\nGitHub tag `vX.Y.Z`, builds `semver-plugin-X.Y.Z.zip`, and publishes a GitHub\nRelease. `VERSION` remains strict SemVer without the leading `v`.\n\n---\n\n## 📄 License and attribution\n\nThe plugin's original code and documentation are licensed under the\n[MIT License](LICENSE). The Semantic Versioning 2.0.0 rules incorporated or\nadapted here are attributed to Tom Preston-Werner and are available under\n[CC BY 3.0](LICENSES/CC-BY-3.0.txt). See [NOTICE](NOTICE) for the required\nattribution and source link.\n",
  "bytes": 8661,
  "sha": "5f01ca29305b320c28ebb14a1965026e3778fdb65236d1eecaf1e6e58982a62f",
  "repo_slug": "lenoseibert/semver-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_lenoseibert_semver_plugin_1f875043/readme"
}