Skill

Release Expert

From sw

Orchestrates multi-repo releases with semantic versioning enforcement, alignment strategies (lockstep/independent/umbrella), RC lifecycles (alpha/beta/rc), dependency waves, brownfield detection, and rollback planning. Use for synchronized releases or version alignment.

devops

git-workflow

Popularity

Parent stars

149

Parent forks

Invocation

How this skill is triggered — by the user, by Claude, or both

Slash command

/sw:release-expert

User invocable

Model invocable

Forked subagent

Default effort

Configuration

Modelopus

Tool Access

This skill is limited to the following tools:

ReadWriteEditBashGlobGrep

Context Preview

The summary Claude sees in its skill listing — used to decide when to auto-load this skill

Multi-repo release orchestration, version alignment, RC lifecycle management, and release strategy.

SKILL.md

503 lines · ~2.8k tokens

Stats

LanguageTypeScript

Parent stars149

Parent forks18

MaintenanceExcellent

Last CommitJul 15, 2026

Actions

View Source View Plugin View on GitHub View README

Release Expert

Multi-repo release orchestration, version alignment, RC lifecycle management, and release strategy.

Core Capabilities

Semantic versioning enforcement and version bump suggestions
Multi-repo version alignment (lockstep/independent/umbrella strategies)
Version conflict detection and compatibility validation
Release dependency management and wave-based coordination
RC lifecycle management (alpha/beta/rc/final)
Brownfield strategy detection from existing projects
Rollback planning with reverse wave ordering
Version matrix management for umbrella releases

Semantic Versioning (Semver)

Format: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Version Bump Rules:

MAJOR (1.0.0 -> 2.0.0):
  - Breaking changes (incompatible API)
  - Remove features
  - Change behavior of existing features
  Examples:
    - Remove deprecated endpoints
    - Change function signatures
    - Modify data formats

MINOR (1.0.0 -> 1.1.0):
  - New features (backward compatible)
  - Add endpoints/functions
  - Deprecate (but don't remove) features
  Examples:
    - Add new API endpoints
    - Add optional parameters
    - New module exports

PATCH (1.0.0 -> 1.0.1):
  - Bug fixes (no API changes)
  - Performance improvements
  - Documentation updates
  Examples:
    - Fix null pointer error
    - Optimize database query
    - Update README

Pre-Release Tags:

Alpha: 1.0.0-alpha.1  # Early development (unstable)
Beta:  1.0.0-beta.1   # Feature complete (testing)
RC:    1.0.0-rc.1     # Release candidate (near production)
Final: 1.0.0          # Production release

Version Alignment Strategies

Lockstep Versioning (all repos share version)

Strategy: Lockstep
When to Use: Tight coupling, small team, shared breaking changes

Current State:
  - frontend: v2.5.0
  - backend: v2.5.0
  - api: v2.5.0

Rules:
  - ALL repos MUST bump together
  - Use highest bump type (if any repo needs MAJOR, all bump MAJOR)
  - Version always stays in sync

Independent Versioning (each repo has own version)

Strategy: Independent
When to Use: Loose coupling, autonomous teams, frequent releases

Current State:
  - frontend: v4.2.0
  - backend: v2.8.0
  - api: v3.1.0

Rules:
  - Each repo versions independently
  - Only bump repos with changes
  - Validate compatibility constraints

Umbrella Versioning (product version + service versions)

Strategy: Umbrella
When to Use: Product milestones, services evolve at different rates

Product: v5.0.0 (umbrella)
  - frontend: v4.2.0
  - backend: v2.8.0
  - api: v3.1.0

Rules:
  - Product version bumps for milestones
  - Services version independently
  - Track matrix in release-strategy.md

Conventional Commits Analysis

Analyzes commits to suggest version bumps:

# MAJOR (breaking change)
feat!: remove legacy authentication
BREAKING CHANGE: Old auth endpoints removed

# MINOR (new feature)
feat: add real-time notifications
feat(api): add WebSocket support

# PATCH (bug fix)
fix: prevent null pointer in user service
fix(ui): correct button alignment
perf: optimize database queries

# No version bump
docs: update README
chore: upgrade dependencies
style: format code
refactor: extract helper function
test: add unit tests

Version Bump Calculation:

# Example commit history
git log v2.5.0..HEAD --oneline

feat!: remove deprecated endpoints       # BREAKING
feat: add dark mode toggle               # FEATURE
fix: prevent crash on logout             # BUGFIX
docs: update API documentation           # NO BUMP

# Analysis: Breaking changes detected -> MAJOR bump
# Suggested: v2.5.0 -> v3.0.0

Version Conflict Detection

Dependency Version Conflicts

# Scenario: Two services depend on different versions of shared-lib

service-a:
  package.json: "shared-lib": "^2.0.0"
  Currently using: v2.0.0

service-b:
  package.json: "shared-lib": "^1.5.0"
  Currently using: v1.8.0

Conflict:
  - service-a requires shared-lib v2.x (breaking changes)
  - service-b still on shared-lib v1.x (outdated)
  - Cannot release until service-b upgrades

Resolution:
  1. Update service-b to "shared-lib": "^2.0.0"
  2. Test service-b with shared-lib v2.0.0
  3. Release service-b
  4. Then proceed with coordinated release

API Contract Version Conflicts

# Scenario: Frontend expects API v3, but backend provides v2

frontend:
  api-client: v3.0.0
  Expects: POST /api/v3/users

backend:
  Current version: v2.8.0
  Provides: POST /api/v2/users

Conflict:
  - Frontend expects v3 API
  - Backend hasn't released v3 yet

Resolution:
  1. Release backend v3.0.0 first (Wave 1)
  2. Verify API v3 endpoints work
  3. Then release frontend v5.0.0 (Wave 2)

Release Dependency Management

# Build-time dependencies
shared-lib: v2.0.0
  - service-a: v3.1.0 (depends on shared-lib)
  - service-b: v2.5.0 (depends on shared-lib)

# Runtime dependencies
auth-service: v1.8.0
  - api-gateway: v2.0.0 (calls auth-service)
    - frontend: v3.2.0 (calls api-gateway)

Release Order Calculation:

Build dependency graph
Topological sort for correct order
Identify circular dependencies (error)
Generate release waves

Release Waves

### Wave 1 (Foundations)
- [ ] shared-lib: v2.0.0 -> v3.0.0
- [ ] database-migrations: v9 -> v10

### Wave 2 (Backend Services)
- [ ] auth-service: v1.8.0 -> v2.0.0 (depends: shared-lib v3.0.0)
- [ ] user-service: v1.5.0 -> v2.0.0 (depends: schema v10)

### Wave 3 (API Layer)
- [ ] api-gateway: v2.0.0 -> v3.0.0 (depends: auth-service v2.0.0)

### Wave 4 (Frontend)
- [ ] web-app: v3.2.0 -> v4.0.0 (depends: api-gateway v3.0.0)

Release Candidate (RC) Lifecycle

RC Workflow

# 1. Create RC
git tag -a v2.0.0-rc.1 -m "Release candidate 1"
npm version 2.0.0-rc.1

# 2. Deploy to staging
gh release create v2.0.0-rc.1 --prerelease

# 3. Testing phase (1-2 weeks)
# Bug found -> create v2.0.0-rc.2

# 4. Promote to final
git tag -a v2.0.0 -m "Production release"
npm version 2.0.0
gh release create v2.0.0  # NOT prerelease

RC State Machine

DRAFT -> TESTING -> VALIDATED -> PROMOTED
           |            |
        FAILED       HOTFIX -> back to TESTING

Tag Cleanup

# List RC tags
git tag -l "*-rc.*" | sort -V

# Delete old RC after promotion
git tag -d v2.0.0-rc.1 v2.0.0-rc.2
git push origin --delete v2.0.0-rc.1 v2.0.0-rc.2

Pre-Release Validation

# 1. Version Compatibility
shared-lib v2.0.0 compatible with service-a v3.0.0
Database schema v10 required but only v9 deployed

# 2. CI/CD Status
All tests passing
Staging deployment status

# 3. Documentation
CHANGELOG.md updated
Migration guide present

Rollback Coordination

## Rollback: v3.0.0 -> v2.5.0 (Reverse wave order)

### Wave 1 (Rollback Frontend First)
- [ ] web-app: v4.0.0 -> v3.2.0
- [ ] mobile-app: v3.0.0 -> v2.5.0

### Wave 2 (Rollback API Layer)
- [ ] api-gateway: v3.0.0 -> v2.8.0

### Wave 3 (Backend - Optional)
- [ ] Keep backend if backward compatible

Compatibility Validation

Semver Range Checking

// service-a/package.json
{
  "dependencies": {
    "shared-lib": "^2.0.0"  // Allows 2.0.0 to <3.0.0
  }
}

// Validation
shared-lib v2.0.0 -> Compatible
shared-lib v2.5.0 -> Compatible
shared-lib v2.9.9 -> Compatible
shared-lib v3.0.0 -> Incompatible (MAJOR change)

Version Matrix Management

Tracks versions for umbrella releases:

# Product Version Matrix

## v6.0.0 (Latest)
- frontend: v5.0.0
- backend: v2.9.0
- api-gateway: v4.0.0
- auth-service: v2.1.0
- shared-lib: v2.0.0
- database-schema: v12

## Compatibility Matrix

| Product | Frontend | Backend | API Gateway | Shared Lib | Schema |
|---------|----------|---------|-------------|------------|--------|
| v6.0.0  | v5.0.0   | v2.9.0  | v4.0.0      | v2.0.0     | v12    |
| v5.0.0  | v4.2.0   | v2.8.0  | v3.1.0      | v1.5.0     | v11    |

## Breaking Changes

### v6.0.0
- API Gateway v3 -> v4: Removed legacy /v2 endpoints
- Shared Lib v1 -> v2: Changed authentication interface
- Schema v11 -> v12: Added user_metadata table

Brownfield Strategy Detection

Analyzes existing projects to detect release patterns:

Git: Version tags, release branches
CI/CD: GitHub Actions, GitLab CI, Jenkins
Package Managers: NPM, Python, Go
Monorepo Tools: Lerna, Nx, Turborepo
Release Automation: semantic-release, standard-version

Living Documentation

Creates release-strategy.md:

# Release Strategy: {Product Name}

## Current Strategy
- Type: Multi-repo / Monorepo / Microservices
- Versioning: Semantic / Date-based
- Alignment: Lockstep / Independent / Umbrella
- RC Process: Pre-release tags / Channels

## Release Checklist
- [ ] All tests passing
- [ ] Changelog updated
- [ ] Version bumped
- [ ] Git tag created
- [ ] GitHub release published
- [ ] Package published
- [ ] Documentation updated

Integration with SpecWeave

# 1. Plan release increment
sw:increment "0025-product-v3-release"

# 2. Execute wave-by-wave
sw:do

# 3. Complete release
sw:done 0025

Commands

sw-release:release-expert - Full release orchestration and version alignment
sw-release:validate-versions - Check compatibility
sw-release:bump <repo> <type> - Bump specific repo
sw-release:matrix - Show version matrix

Best Practices

Semver Discipline:

Never skip versions (v1.0.0 -> v1.1.0, not v1.0.0 -> v1.2.0)
Use pre-release tags for testing (v1.0.0-rc.1)
Document breaking changes clearly

Dependency Management:

Pin major versions ("^2.0.0" not "*")
Update dependencies regularly (avoid drift)
Test compatibility before bumping

Release Coordination:

Understand dependencies before releasing
Execute wave-by-wave (never "big bang")
Always use RC for major versions
Have rollback plan ready
Monitor 1+ hour post-release
Clean up RC tags after promotion

Version Matrix:

Update after every product release
Link to ADRs for breaking changes
Track deprecation timelines

Automation:

Use conventional commits (enables automated analysis)
Automate changelog generation
Validate versions in CI/CD

Output

Creates/Updates:

package.json (version field)
Git tags (v1.0.0, v2.0.0, etc.)
CHANGELOG.md (release notes)
.specweave/docs/internal/delivery/version-matrix.md
Release strategy documentation

Provides:

Version bump suggestions from commit analysis
Compatibility validation reports
Version conflict detection
Release wave plans with dependency ordering
Rollback coordination plans
Version history and matrices

Goal: Consistent, predictable versioning and coordinated releases across all repositories with clear compatibility guarantees.

Release Expert

Popularity

Invocation

Configuration

Tool Access

Context Preview

SKILL.md

Release Expert

Popularity

Invocation

Configuration

Tool Access

Context Preview

SKILL.md

Release Expert

Core Capabilities

Semantic Versioning (Semver)

Version Alignment Strategies

Lockstep Versioning (all repos share version)

Independent Versioning (each repo has own version)

Umbrella Versioning (product version + service versions)

Conventional Commits Analysis

Version Conflict Detection

Dependency Version Conflicts

API Contract Version Conflicts

Release Dependency Management

Release Waves

Release Candidate (RC) Lifecycle

RC Workflow

RC State Machine

Tag Cleanup

Pre-Release Validation

Rollback Coordination

Compatibility Validation

Semver Range Checking

Version Matrix Management

Brownfield Strategy Detection

Living Documentation

Integration with SpecWeave

Commands

Best Practices

Output

Similar Skills

Release Expert

Core Capabilities

Semantic Versioning (Semver)

Version Alignment Strategies

Lockstep Versioning (all repos share version)

Independent Versioning (each repo has own version)

Umbrella Versioning (product version + service versions)

Conventional Commits Analysis

Version Conflict Detection

Dependency Version Conflicts

API Contract Version Conflicts

Release Dependency Management

Release Waves

Release Candidate (RC) Lifecycle

RC Workflow

RC State Machine

Tag Cleanup

Pre-Release Validation

Rollback Coordination

Compatibility Validation

Semver Range Checking

Version Matrix Management

Brownfield Strategy Detection

Living Documentation

Integration with SpecWeave

Commands

Best Practices

Output

Similar Skills