SemVer

A Semantic Versioning management skill for Letta Code agents. Handles version bumps, component→root aggregation, deploy gating, and optional GitHub integration. Follows Semantic Versioning 2.0.0.

What it does

• First-run setup — Configures your project's version tracking mode, component structure, and GitHub connection. See First run: Project setup below for what happens.
• Version bumps — Automatically determines bump type from conventional commits (feat→minor, fix→patch, breaking→major)
• Two-level SemVer — Components have their own versions that feed into a root version, tracking project completeness toward 1.0.0
• Deploy gating — Requires a version bump before every deploy (on-deploy mode)
• GitHub integration — Optional. Creates tags, releases, and changelogs via gh CLI. Works fully local too.
• /bump — Manual version increment command
• /status — Current version state, unreleased changes, last deploy date

Why SemVer matters

Semantic Versioning provides a clear, machine-readable contract about what changes between releases:

• PATCH (0.0.x): Bug fixes — safe to upgrade, zero breaking changes
• MINOR (0.x.0): New features — backward-compatible, safe to upgrade
• MAJOR (x.0.0): Breaking changes — may require migration

This contract lets automated tools, dependency managers, and humans make informed decisions about upgrades. Read the full specification at semver.org.

First run: Project setup

When the skill runs for the first time, it asks four questions:

1. Version tracking mode — When should versions increment?

   • On deploy — Version bumps happen when code is deployed to production (recommended for production projects)
   • On completion — Version bumps happen when a feature/fix is complete (useful for libraries, skills, and pre-launch projects)

2. Component structure — Does the project have sub-components?

   • Single version — One version for the whole project
   • Component + root — Each component has its own version, and a root version aggregates them (two-level SemVer)

3. GitHub integration — Connect to a GitHub repo?

   • Yes — Uses gh CLI for tags, releases, and changelogs
   • No — Keeps version tracking local only (git commits + tags, zero GitHub releases)

4. Component registry (if component + root mode) — List each component with name, current version, and path

After setup, the config is saved for all future version operations.

Two-level SemVer

For projects with multiple components (e.g. a web app, a bot, and a shared library), two-level SemVer tracks both individual component versions and an aggregate root version:

• Root version = project completeness toward 1.0.0
• Component bumps feed into root, weighted by significance:
  • Component patch → root patch
  • Component minor → root patch (typically), or root minor if it's a major milestone
  • Component major → root minor
• Root → 1.0.0 only when ALL components are production-ready

This gives you a single number that reflects the overall project state, while each component maintains its own release history.

Installation

Copy the SKILL.md file to your Letta Code skills directory:

mkdir -p ~/.letta/skills/sem-ver
cp SKILL.md ~/.letta/skills/sem-ver/

Usage

In your Letta Code conversation:

Use the sem-ver skill.

Or: apply it as a default behavior — the agent follows the version bump workflow automatically when code is deployed or a feature is complete.

Commands

• /bump — Manually trigger a version increment
• /status — Show current version state, unreleased changes, and last deploy date

Configuration

After first run, the project config is saved in this format:

# sem-ver config
version_mode: deploy|completion
structure: single|component_root
github: true|false
repo: owner/repo
tag_format: "component@${version}"
components:
  - name: component-name
    version: 0.1.0
    path: ./path/to/component
root:
  version: 0.1.0
  bump_rules:
    component_patch: root_patch
    component_minor: root_patch
    component_major: root_minor

License

MIT