Aligns versions across multiple repositories according to release strategy (lockstep, independent, umbrella). Handles semantic versioning constraints, detects version conflicts, suggests version bumps based on conventional commits, validates cross-repo compatibility, manages version matrices for umbrella releases. Activates for version alignment, align versions, version sync, semver, version conflicts, version bump, version compatibility, cross-repo versions, umbrella version matrix, lockstep versioning.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
Expertise: Multi-repository version alignment, semantic versioning, version conflict detection, and compatibility validation.
Enforces semver rules:
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: Early development (unstable)
1.0.0-alpha.1, 1.0.0-alpha.2, ...
# Beta: Feature complete (testing)
1.0.0-beta.1, 1.0.0-beta.2, ...
# RC: Release candidate (near production)
1.0.0-rc.1, 1.0.0-rc.2, ...
# Final: Production release
1.0.0
Lockstep Versioning (all repos share version):
Strategy: Lockstep
Current State:
- frontend: v2.5.0
- backend: v2.5.0
- api: v2.5.0
- shared: v2.5.0
Proposed Bump: MAJOR (breaking change in API)
New State:
- frontend: v3.0.0
- backend: v3.0.0
- api: v3.0.0
- shared: v3.0.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
Current State:
- frontend: v4.2.0
- backend: v2.8.0
- api: v3.1.0
- shared: v1.5.0
Changes:
- frontend: Bug fix → PATCH bump
- backend: New feature → MINOR bump
- api: No changes → No bump
- shared: Breaking change → MAJOR bump
New State:
- frontend: v4.2.1 (patch)
- backend: v2.9.0 (minor)
- api: v3.1.0 (unchanged)
- shared: v2.0.0 (major)
Rules:
- Each repo versions independently
- Only bump repos with changes
- Validate compatibility constraints
Umbrella Versioning (product version + service versions):
Strategy: Umbrella
Product: v5.0.0 (umbrella)
Version Matrix:
- frontend: v4.2.0
- backend: v2.8.0
- api: v3.1.0
- shared: v1.5.0
Changes for Product v6.0.0:
- frontend: v4.2.0 → v5.0.0 (major redesign)
- backend: v2.8.0 → v2.9.0 (new endpoints)
- api: v3.1.0 → v4.0.0 (breaking changes)
- shared: v1.5.0 → v1.5.0 (no changes)
New Product: v6.0.0 (umbrella)
- frontend: v5.0.0
- backend: v2.9.0
- api: v4.0.0
- shared: v1.5.0
Rules:
- Product version bumps for milestones
- Services version independently
- Track matrix in release-strategy.md
Analyzes commits to suggest version bumps:
Commit Patterns:
# 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
chore: upgrade React to v18 # NO BUMP
# Analysis
Breaking changes: 1 → MAJOR bump (v2.5.0 → v3.0.0)
Features: 1 → Overridden by MAJOR
Bug fixes: 1 → Overridden by MAJOR
# Suggested: v2.5.0 → v3.0.0
Detects incompatible versions:
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 (new endpoint)
backend:
Current version: v2.8.0
Provides: POST /api/v2/users (old endpoint)
Conflict:
- Frontend expects v3 API
- Backend hasn't released v3 yet
- Deployment will fail
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)
Validates cross-repo compatibility:
Semver Range Checking:
// Example: Validate service-a can work with shared-lib versions
// 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)
API Contract Validation:
# OpenAPI spec comparison
api-gateway v2.8.0 (current):
POST /api/v2/users:
parameters:
- name: email (required)
- name: password (required)
api-gateway v3.0.0 (proposed):
POST /api/v3/users:
parameters:
- name: email (required)
- name: password (required)
- name: phoneNumber (optional) # NEW (backward compatible)
Compatibility:
- New optional field → Minor version bump (v2.8.0 → v2.9.0) ✗
- But route changed (/v2 → /v3) → Major version bump (v3.0.0) ✓
- Verdict: v3.0.0 is correct ✓
Tracks versions for umbrella releases:
Version Matrix Document:
# Product Version Matrix
## v6.0.0 (Latest - 2025-01-15)
- frontend: v5.0.0
- backend: v2.9.0
- api-gateway: v4.0.0
- auth-service: v2.1.0
- user-service: v2.0.0
- order-service: v3.2.0
- shared-lib: v2.0.0
- database-schema: v12
## v5.0.0 (Previous - 2024-12-10)
- frontend: v4.2.0
- backend: v2.8.0
- api-gateway: v3.1.0
- auth-service: v2.0.0
- user-service: v1.8.0
- order-service: v3.1.0
- shared-lib: v1.5.0
- database-schema: v11
## 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 |
| v4.0.0 | v3.5.0 | v2.5.0 | v2.8.0 | v1.2.0 | v10 |
## 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
### v5.0.0
- Frontend v4 → v5: React 16 → 18 (requires Node.js 18+)
- User Service v1 → v2: Changed user creation API
Suggests and executes version bumps:
Interactive Version Bump:
# Command
/sw-release:align
# Interactive prompts
? Which repositories to align?
◉ frontend (v4.2.0)
◉ backend (v2.8.0)
◉ api-gateway (v3.1.0)
◯ shared-lib (v2.0.0) - no changes
? Alignment strategy?
◯ Lockstep (all repos same version)
◉ Independent (bump changed repos only)
◯ Umbrella (product milestone)
# Analysis
Analyzing conventional commits since last release...
frontend (v4.2.0):
- 12 commits since v4.2.0
- Breaking changes: 1
- Features: 3
- Bug fixes: 5
Suggested: v5.0.0 (MAJOR)
backend (v2.8.0):
- 8 commits since v2.8.0
- Features: 2
- Bug fixes: 3
Suggested: v2.9.0 (MINOR)
api-gateway (v3.1.0):
- 15 commits since v3.1.0
- Breaking changes: 2
- Features: 4
Suggested: v4.0.0 (MAJOR)
? Confirm version bumps?
◉ frontend: v4.2.0 → v5.0.0
◉ backend: v2.8.0 → v2.9.0
◉ api-gateway: v3.1.0 → v4.0.0
[Yes / No / Edit]
Automated Execution:
# Updates package.json
npm version major # frontend
npm version minor # backend
npm version major # api-gateway
# Creates git tags
git tag v5.0.0 (frontend)
git tag v2.9.0 (backend)
git tag v4.0.0 (api-gateway)
# Updates CHANGELOG.md
# - Extracts commits since last tag
# - Groups by type (breaking, features, fixes)
# - Generates markdown
# Updates version matrix
# - Adds new product version row
# - Links to service versions
# - Documents breaking changes
Ask me to:
Align versions across repos:
Detect version conflicts:
Suggest version bumps:
Manage version matrices:
Validate compatibility:
Semver Discipline:
Dependency Management:
Version Matrix:
Automation:
Release Strategy Advisor:
Release Coordinator:
RC Manager:
Brownfield Analyzer:
# 1. Analyze changes
/sw-release:align
# 2. Review suggested bumps
Frontend v4.2.0 → v5.0.0 (breaking changes)
Backend v2.8.0 → v2.9.0 (new features)
API v3.1.0 → v3.1.1 (bug fixes only)
# 3. Validate compatibility
✓ Frontend v5.0.0 compatible with Backend v2.8.0+
✓ Backend v2.9.0 compatible with API v3.1.0+
✗ Shared-lib v1.5.0 outdated (requires v2.0.0)
# 4. Fix blocking issues
Update Backend to use shared-lib v2.0.0
# 5. Execute version bumps
✓ All versions aligned
✓ Tags created
✓ Changelogs updated
# 1. Create product release
/sw:increment "0040-product-v6-release"
# 2. Analyze component versions
Current umbrella: v5.0.0
Proposed: v6.0.0 (major milestone)
# 3. Review version matrix
Frontend: v4.2.0 → v5.0.0 (redesign)
Backend: v2.8.0 → v2.9.0 (new API)
API: v3.1.0 → v4.0.0 (breaking changes)
Shared: v1.5.0 → v2.0.0 (breaking changes)
# 4. Validate umbrella bump
Breaking changes detected → MAJOR bump correct ✓
Product v5.0.0 → v6.0.0 ✓
# 5. Update version matrix
.specweave/docs/internal/delivery/version-matrix.md updated ✓
Works with release commands:
/sw-release:align - Interactive version alignment/sw-release:validate-versions - Check compatibility/sw-release:bump <repo> <type> - Bump specific repo/sw-release:matrix - Show version matrixRequired:
Optional:
npm version) - Automated bumpinggh release) - Release notesCreates/Updates:
package.json (version field)CHANGELOG.md (release notes).specweave/docs/internal/delivery/version-matrix.mdProvides:
Remember: Version alignment is critical for multi-repo architectures. Always:
Goal: Consistent, predictable versioning across all repositories with clear compatibility guarantees.