semver-guard

Catch breaking changes before you call it a patch.

🇺🇸 English · 🇮🇩 Bahasa Indonesia · 🇨🇳 简体中文

A skill for your coding agent (Claude Code — also Codex, Cursor, Gemini CLI, opencode). Before you bump a version or call a change "a patch", it diffs your public surface — exports, signatures, types, return shapes — classifies each change as breaking / additive / internal, and won't let a breaking change ship under a patch or minor label.

A breaking change released as a patch is how you wake up to a hundred red builds that updated overnight. The bump is a promise; semver-guard keeps it honest.

Before / After

Without semver-guard — the agent renames things and ships a "patch":

- export const parseConfig = ...
+ export const withRetry = ...
- export function fetchUser(id) { ... }
+ export function fetchUser(id, opts) { ... }   // opts now required

$ npm version patch   ✅ "small change, just a patch"

(…every caller of parseConfig and fetchUser(id) breaks on update.)

With semver-guard — it diffs the public surface first:

semver-guard — 3 changes to the public surface
  ✗ breaking  removed export `parseConfig`            → major
  ✗ breaking  `fetchUser` now requires `opts`          → major  (make opts optional to avoid)
  ✓ additive  new export `withRetry`                  → minor
This is a MAJOR bump. You called it a patch.

Same diff. The version stops lying about what changed.

Real runs

Not a mockup. Actual semver-guard runs in Claude Code — see CASES.md.

Install

# macOS / Linux / WSL
curl -fsSL https://raw.githubusercontent.com/ryanda9910/semver-guard/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/ryanda9910/semver-guard/main/install.ps1 | iex

Finds every coding agent you have and installs the skill into each. ~10 seconds, safe to re-run. --project also installs into the current repo's .claude/. No key, no account, no dependency.

Manual: copy skill/SKILL.md into your agent's skills/rules dir (Claude Code: ~/.claude/skills/semver-guard/SKILL.md).

Documentation

Full docs in docs/ — usage · reference · install · customizing · FAQ · real runs · contributing.

Works in

Claude Code (native skill), plus any agent that loads a rules/skill file — Codex, Cursor, Gemini CLI, opencode, Aider, GitHub Copilot CLI.

License

MIT.