---
name: avizmarlon/version-bump-rules
source: https://app.decimal.ai/s/avizmarlon-version-bump-rules@1/SKILL.md
source_sha256: 80aadafdaaff
---

## Version Control — Mandatory Practice

Every software project must maintain a version number. Every change that reaches production or main branch must bump the version in the same commit — no exceptions, no deferral.

### Where version lives (by project type)

| Project Type | Version File Location |
|---|---|
| Node.js / npm package | `package.json` → `"version"` field |
| **WXT (browser extension)** | **`wxt.config.ts` → `manifest: { version: "x.y.z" }` — NOT `package.json`** |
| Monorepo (multiple packages) | each affected `package.json` + `manifest.json` if extension |
| Python | `pyproject.toml` → `[project] version` OR `__version__` in `__init__.py` |
| Rust / Cargo | `Cargo.toml` → `version` field |
| Mobile (Expo) | `app.json` / `app.config.ts` → `version` + `buildNumber` / `versionCode` |
| Bash / Python script (standalone) | comment at top: `# v1.2.3` |
| Custom setup (no standard file) | `VERSION` file in root, one line |

#### Critical: WXT extension gotcha

Browser extensions built with WXT read the version from **`wxt.config.ts`** in the `manifest` block, **not** from `package.json`. Bumping only `package.json` leaves the manifest at the old version, so users see stale version info in the browser extension UI.

**Always verify `wxt.config.ts` when working with WXT projects.**

### Semantic versioning rules

```
MAJOR.MINOR.PATCH
  │      │     └── bug fix, cosmetic adjustment, refactor with no external impact
  │      └──────── new feature, backwards-compatible (new behavior, new UI, new integration)
  └─────────────── breaking change (removed behavior, changed public interface, mandatory migration)
```

**When in doubt between MINOR and PATCH?** If the end user will notice → MINOR. If only internal code changed → PATCH.

### Anti-patterns (mandatory to avoid)

- Committing a new feature without bumping the version → forbidden
- "I'll bump it later" → deferral is not allowed. Bump in the same commit or merge commit
- Version frozen at 0.0.1 while product evolves → traceability failure
- Multiple packages in a monorepo with different versions without justification → align them if they release together

### Required workflow

1. Session delivers production-bound change (feature, bugfix, release)
2. Identify the project's version file(s) from the table above
3. Decide the bump level (MAJOR / MINOR / PATCH) using the semver rule
4. Bump the version before committing the code (or include in the commit)
5. Add entry to `CHANGELOG.md` with the new version at the top

### Implementation notes for AI agents

- **Gate before commit:** if code is shipping, version must bump. If version hasn't bumped, the commit is incomplete.
- **Monorepo edge case:** if multiple packages are affected but release independently, bump each. If they always release together, keep versions in sync.
- **Validation:** after bumping, run a quick check (grep, parse JSON/TOML, read source) to confirm the new version is in place and matches the old version + bump you applied.
- **CHANGELOG discipline:** version number in CHANGELOG must match the version file after the bump. If they diverge, the next AI session or developer has incomplete information about what version contains which features.

### Applies to

All software projects, all AI agents (Claude, Codex, Cursor, Gemini), all sessions.