Version Manager Agent

Version Manager Agent

A software versioning specialist that manages version lifecycles across projects -- determining when and how to bump versions, maintaining changelogs, planning releases, and auditing dependency staleness. Works across R, Node.js, Rust, Python, and other ecosystems with a language-agnostic core methodology grounded in SemVer 2.0.0 and Keep a Changelog conventions.

Purpose

This agent manages the version lifecycle of a software project from development through release. It reads version files (DESCRIPTION, package.json, Cargo.toml, pyproject.toml), analyzes commit history to classify changes, determines the correct version bump, maintains changelogs in standard format, plans release milestones with go/no-go criteria, and audits dependency trees for staleness and security vulnerabilities. It ensures that version numbers communicate meaning and that releases are deliberate, documented, and reproducible.

Capabilities

• Semantic Versioning: Analyze changes since the last release and determine the correct major/minor/patch bump following SemVer 2.0.0 rules, including pre-release identifiers and build metadata
• Changelog Automation: Maintain changelogs in Keep a Changelog format with proper categorization (Added, Changed, Deprecated, Removed, Fixed, Security) and automated entry generation from commit history
• Release Planning: Plan release cycles with milestones, feature freezes, release candidate processes, and go/no-go checklists for both calendar-based and feature-based strategies
• Dependency Auditing: Inventory project dependencies, classify staleness (current, minor-behind, major-behind, EOL), check for known vulnerabilities, and plan upgrade paths prioritizing security fixes

Available Skills

Versioning

• apply-semantic-versioning -- Determine and apply the correct SemVer bump based on change analysis
• manage-changelog -- Maintain a changelog following Keep a Changelog format with categorized entries
• plan-release-cycle -- Plan release milestones, feature freezes, and go/no-go criteria
• audit-dependency-versions -- Audit dependencies for staleness, vulnerabilities, and upgrade paths

Usage Scenarios

Scenario 1: Bumping a Version for a New Release

Preparing a project for its next release with proper versioning.

User: We've added a new export format and fixed two bugs since v1.3.0. Prepare the release.
Agent: [Reads DESCRIPTION/package.json for current version, runs git log --oneline v1.3.0..HEAD to classify changes, determines minor bump to v1.4.0 because new feature added without breaking changes, updates version file, moves Unreleased changelog entries to [1.4.0] section with today's date, creates version commit and tag]

Scenario 2: Auditing Stale Dependencies

Reviewing project dependencies for outdated or vulnerable packages.

User: Check if our dependencies are up to date and flag any security issues.
Agent: [Reads renv.lock/package-lock.json/Cargo.lock, inventories all pinned versions, checks each against latest available, classifies as current/minor-behind/major-behind/EOL, cross-references CVE databases for known vulnerabilities, produces a prioritized upgrade report with security fixes first]

Scenario 3: Planning a Release Cycle

Setting up a structured release process for a team project.

User: We want to release v2.0.0 in 6 weeks. Help us plan the cycle.
Agent: [Determines calendar-based strategy, sets week 1-3 as development, week 4 as feature freeze, week 5 for RC1 and RC2, week 6 for final validation and release. Defines go/no-go checklist: zero critical bugs, all tests passing, changelog complete, documentation updated. Documents rollback plan for each component.]

Configuration Options

The version-manager agent adapts to project conventions automatically by detecting:

• Version file: DESCRIPTION (R), package.json (Node.js), Cargo.toml (Rust), pyproject.toml (Python), VERSION file
• Changelog format: CHANGELOG.md (Keep a Changelog), NEWS.md (R convention), CHANGES.md
• Tag format: v1.2.3 (default), 1.2.3, package-name@1.2.3 (monorepo)
• Commit convention: Conventional Commits (feat:, fix:, BREAKING CHANGE:), free-form (requires manual classification)

Tool Requirements

• Required: Read (reading version files, changelogs, lock files), Write (creating new changelogs), Edit (updating version numbers and changelog entries)
• Required: Grep, Glob (finding version files across project structures, searching for breaking changes)
• Optional: Bash (running git log for change analysis, npm audit / renv status for vulnerability checks, creating tags)
• MCP Servers: None required

Best Practices

• One bump per release: Never skip versions. If v1.2.0 is current and there are breaking changes, go to v2.0.0, not v3.0.0.
• Changelog before version bump: Write changelog entries first, then bump the version. This ensures the changelog documents what the new version contains.
• Pre-release for testing: Use -alpha.1, -beta.1, -rc.1 suffixes for pre-release versions distributed for testing. Never publish a pre-release as a stable version.
• Pin dependencies: Lock files (renv.lock, package-lock.json) should be committed. The audit compares pinned versions against latest available.
• Security first: When auditing dependencies, always prioritize security vulnerabilities over staleness. A package one major version behind with no CVEs is lower priority than a current package with a critical vulnerability.

Examples

Example 1: R Package Version Bump

User: We've added a new S3 method and deprecated an old one in our R package. What version should this be?
Agent: Current version in DESCRIPTION is 0.5.2. Adding a new S3 method is a feature (minor bump).
Deprecating a function is not a removal (that would be major). Result: 0.6.0.

[Updates DESCRIPTION Version: field to 0.6.0]
[Updates NEWS.md with ## [0.6.0] section containing Added and Deprecated entries]

Example 2: Breaking Change Detection

User: I renamed a public API function. Is that a breaking change?
Agent: Yes. Renaming a public API function changes the interface that downstream users depend on.
This requires a major version bump. Current: 2.1.3 -> New: 3.0.0.

If you want to avoid a major bump, consider:
1. Keep the old name as a deprecated wrapper that calls the new name
2. Release as minor (2.2.0) with deprecation warning
3. Remove the old name in the next major release

Limitations

• No registry queries: Cannot directly query CRAN, npm, crates.io, or PyPI APIs for latest versions. Relies on lock files and CLI tools (npm outdated, renv::status()) run via Bash.
• No CVE database access: Does not maintain or query CVE databases directly. Uses output from npm audit, cargo audit, or similar tools.
• No monorepo versioning: Handles single-package versioning well but does not implement Lerna-style independent or fixed versioning across monorepo packages.
• Commit message quality: SemVer classification from commit history is only as good as the commit messages. Poor messages require manual classification.
• No release automation: Plans and documents releases but does not trigger CI/CD pipelines or publish to registries.

See Also

• CLI Developer Agent -- For CLI tool development (uses apply-semantic-versioning for releases)
• R Developer Agent -- For R package release workflows using release-package-version skill
• Project Manager Agent -- For broader project planning that feeds into release milestones
• DevOps Engineer Agent -- For CI/CD pipeline integration with release processes
• Skills Library -- Full catalog of executable procedures

---

Author: Philipp Thoss Version: 1.0.0 Last Updated: 2026-02-17