Version Bump

Core Question

What version change is justified by observed evidence and project policy, and which local files must be updated consistently without tagging or publishing?

When To Use

Use this skill when the user asks to:

• recommend the next version,
• validate version consistency,
• apply a local patch, minor, major, or prerelease bump,
• update version files and lockfiles,
• reason about monorepo fixed or independent versioning.

When Not To Use

Do not use this skill to create tags, publish packages, publish hosted releases, draft release notes, or edit changelog sections unless explicitly routed for evidence only.

Route to:

• tag-release for Git tag creation.
• a future publish-release skill or manual workflow for package publication or hosted release publication.
• release-notes for release-note text.
• changelog-maintenance for changelog sections.
• conventional-commits for commit classification only.

Required Evidence

Inspect or establish:

• current version files such as package.json, pyproject.toml, Cargo.toml, .csproj, VERSION, or ecosystem equivalents,
• lockfiles that must stay consistent,
• release/versioning policy docs,
• changelog unreleased section,
• commits since last tag when recommending a bump,
• conventional commit evidence when available,
• breaking-change and migration evidence,
• monorepo tooling and fixed/independent versioning policy,
• prerelease naming and existing prerelease pattern.

Do not assume SemVer, default version files, package manager behavior, or monorepo policy without evidence.

Operating Contract

You MAY:

• inspect version files, changelog, commits, tags, and release policy,
• recommend a version bump,
• edit local version files when user intent explicitly requires implementation,
• update lockfiles with the project tool when behavior is known and safe,
• verify local version consistency.

You MUST:

• distinguish recommendation from mutation,
• keep changes limited to local version-related files,
• inspect whether package-manager version commands create commits or tags,
• use no-tag/no-commit flags where available when only editing version files,
• route Git tags and publication out of this skill,
• report missing policy or evidence gaps.

You MUST NOT:

• create Git tags,
• create commits unless routed through the appropriate commit workflow,
• publish packages or hosted releases,
• assume SemVer or monorepo strategy,
• silently change unrelated package versions,
• rewrite changelog/release notes unless routed and explicitly requested.

State / Risk Table

Workflow

1. Identify whether the user wants recommendation, validation, or local file mutation.
2. Inspect version files, lockfiles, policy, changelog, commits, and tags as needed.
3. Classify project versioning model and risk.
4. Recommend or apply the minimal version change.
5. If mutating, update all authoritative local version files consistently.
6. Verify file consistency and command side effects.
7. Report evidence, version decision, files changed, verification, and limitations.

Decision Rules

• If SemVer applies, breaking change means major, user-visible feature means minor, and bug fix means patch.
• For 0.x, inspect project policy before applying major/minor semantics.
• If SemVer does not clearly apply, state the policy gap and present options.
• For monorepos, identify fixed versus independent versioning before mutation.
• Keep dependency lockfile changes with package metadata when the ecosystem requires it.
• Do not infer security, performance, or compatibility claims from version number alone.
• Do not create tags or publish.

Tool Rules

Allowed:

• read version files, lockfiles, changelog, commit history, and tags,
• edit local version files when explicitly requested,
• run package manager commands only after command behavior is known.

Package manager version commands may create commits or tags depending on ecosystem and flags. Before running them, inspect project policy and command behavior. Use no-tag/no-commit flags where available unless commit/tag creation is explicitly requested and routed to the owning skill.

For npm, prefer npm version --no-git-tag-version when only editing version files.

Forbidden:

• tag creation,
• package publication,
• hosted release publication,
• remote/shared mutation,
• unrelated version file changes.

Verification

Minimum verification:

• R1: recommendation self-check against evidence.
• R2: diff inspection of version files and lockfiles.
• R3: consistency check across packages plus residual-risk note.

Verify:

• all authoritative version files agree,
• lockfiles are consistent when present,
• package-manager command did not create unintended commits or tags,
• changelog/release notes are not silently edited.

Output Contract

Final response should include:

## Recommendation / Change

- Version decision or files updated.

## Evidence

- Policy, commits, changelog, version files used.

## Verification

- Consistency checks and command results.

## Risks / Limitations

- Missing policy, monorepo ambiguity, unrun tests, or publication out of scope.

Stop / Confirmation Rules

Stop when repository or version state is ambiguous in a way that could update the wrong package, create unintended tags/commits, invalidate release policy, or require a gated action.

Requires confirmation for:

• local version-file mutation when user did not explicitly request implementation,
• monorepo-wide version changes,
• commands with unclear side effects,
• generated lockfile updates that are not clearly tied to the version change.

Route tag creation and publication out of this skill.

Lazy-load References

Load:

• references/semver-rules.md when version impact is unclear.
• references/ecosystem-files.md for ecosystem-specific version files.
• references/monorepo.md for multi-package versioning.
• references/prerelease.md for prerelease rules.
• references/commands.md before package-manager mutation.
• references/verification.md for consistency checks.