edercnj/x-increment-version

Skill: Increment Version (Semantic Versioning)

Purpose

Bumps the application version following Semantic Versioning 2.0.0:

• patch — backward-compatible bug fixes (e.g., 1.2.3 → 1.2.4)
• minor — backward-compatible new features (e.g., 1.2.3 → 1.3.0)
• major — breaking changes (e.g., 1.2.3 → 2.0.0)

Detects the project stack automatically, updates the version file, and creates a Conventional Commit.

This skill is OPTIONAL — invoke it after /x-implement-story, /x-implement-task, or /x-fix-bug when the project has explicit version management and the change warrants a version bump.

Triggers

/x-increment-version                     — auto-detect stack, bump patch
/x-increment-version --type minor        — bump minor
/x-increment-version --type major        — bump major
/x-increment-version --dry-run           — show what would change, no writes

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | --type | Enum | patch | Version increment type: patch \| minor \| major | | --dry-run | Boolean | false | Show the new version without writing or committing |

Output Contract

| Field | Type | Description | |-------|------|-------------| | previousVersion | String | Version before bump (e.g., 1.2.3) | | newVersion | String | Version after bump (e.g., 1.2.4) | | bumpType | Enum | patch \| minor \| major | | versionFile | String | Path of the updated file (e.g., pom.xml) | | stack | String | Detected stack (java \| nodejs \| python \| generic \| unknown) | | commitSha | String|null | Commit SHA (null when --dry-run) | | status | Enum | SUCCESS \| DRY_RUN \| FAILED |

CRITICAL EXECUTION RULE

3 steps (Detect → Bump → Commit). ALL mandatory in non-dry-run mode.

Workflow

Step 1: STACK DETECT   → identify version file
Step 2: VERSION BUMP   → compute new version, write file
Step 3: COMMIT         → git commit direto (skipped in --dry-run)

Step 1 — Stack Detection

Detect the stack in priority order:

| Priority | File | Stack | Version Field | |----------|------|-------|---------------| | 1 | pom.xml | java | <version>X.Y.Z</version> (first non-dependency occurrence) | | 2 | package.json (root) | nodejs | "version": "X.Y.Z" | | 3 | pyproject.toml | python | version = "X.Y.Z" (under [tool.poetry] or [project]) | | 4 | setup.py | python | version='X.Y.Z' or version="X.Y.Z" | | 5 | VERSION (plain text) | generic | Full file content (single version line) |

If none found → abort with STACK_NOT_DETECTED:

ERROR [STACK_NOT_DETECTED]: No version file found.
  Supported: pom.xml, package.json, pyproject.toml, setup.py, VERSION

Step 2 — Version Bump

Parse the current version using SemVer regex: (\d+)\.(\d+)\.(\d+).

Compute the new version according to --type:

| Type | Rule | Example (1.2.3 → ?) | |------|------|----------------------| | patch | Z+1; X,Y unchanged | 1.2.4 | | minor | Y+1, Z=0; X unchanged | 1.3.0 | | major | X+1, Y=0, Z=0 | 2.0.0 |

Update the version file in place using the stack-appropriate strategy:

• pom.xml: update ONLY the first <version>X.Y.Z</version> that appears inside <project> and before any <dependencies> or <parent> block (i.e., the project's own version, not a dependency version). Use a targeted sed/regex anchored to the project root element to avoid accidentally bumping a dependency version.
• All other stacks: replace the first match of the version string in the file.

Dry-run: Print the table below and exit with status=DRY_RUN:

Stack:    <stack>
File:     <versionFile>
Current:  <previousVersion>
New:      <newVersion> (--type <bumpType>)
[DRY RUN] No files written.

Step 3 — Conventional Commit

After writing the version file, stage it and commit directly (this skill is not task-bound, so it bypasses x-commit-changes and creates the commit directly):

git add <versionFile>
git commit -m "chore(version): bump to <newVersion>

Co-authored-by: Copilot <[email protected]>"

This produces a commit with message: chore(version): bump to <newVersion>

The commit is created on the currently active branch. No push is performed — caller decides when to push.

Error Handling

| Scenario | Exit | Message | |----------|------|---------| | No version file found | 1 | STACK_NOT_DETECTED: No version file found | | Invalid SemVer format | 2 | INVALID_VERSION: Could not parse version from <file> | | File not writable | 3 | FILE_NOT_WRITABLE: Cannot write to <file> | | Commit fails | 4 | COMMIT_FAILED: git commit returned non-zero |

Integration Notes

This skill is OPTIONAL in the following lifecycle skills:

| Skill | Usage | Typical --type | |-------|-------|-----------------| | x-implement-story | After successful story completion | minor (new feature) | | x-implement-task | After successful task completion | patch | | x-fix-bug | After successful bug fix | patch |

Convention:

• New feature stories → --type minor
• Bug fixes and patches → --type patch
• Breaking changes (major refactors, API breaks) → --type major

Examples

# Bug fix — bump patch after /x-fix-bug
/x-increment-version --type patch

# New feature story — bump minor after /x-implement-story
/x-increment-version --type minor

# Preview what would change without writing
/x-increment-version --type minor --dry-run