name: version-aligner description: 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.

Version Aligner

Expertise: Multi-repository version alignment, semantic versioning, version conflict detection, and compatibility validation.

Core Capabilities

1. Semantic Versioning (Semver)

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

2. Version Alignment Strategies

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

3. Conventional Commits Analysis

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

4. Version Conflict Detection

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)

5. Compatibility Validation

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 ✓

6. Version Matrix Management

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

7. Automated Version Bumping

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

When to Use This Skill

Ask me to:

Align versions across repos:
- "Align versions for all microservices"
- "Sync versions before release"
- "What versions should we bump to?"
Detect version conflicts:
- "Check for version conflicts"
- "Validate cross-repo compatibility"
- "Are our dependencies aligned?"
Suggest version bumps:
- "What version should we bump to?"
- "Analyze commits for version bump"
- "Calculate semver from commits"
Manage version matrices:
- "Update version matrix"
- "Show compatibility matrix"
- "Track umbrella version history"
Validate compatibility:
- "Can frontend v5.0.0 work with backend v2.8.0?"
- "Check API contract compatibility"
- "Validate dependency ranges"

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

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

Integration Points

Release Strategy Advisor:

Reads alignment strategy from release-strategy.md
Adapts to lockstep/independent/umbrella

Release Coordinator:

Provides version bump suggestions
Validates compatibility before release
Updates version matrix post-release

RC Manager:

Handles pre-release version tags
Promotes RC to final version
Tracks RC version history

Brownfield Analyzer:

Detects existing version patterns
Extracts current version matrix
Suggests alignment improvements

Example Workflows

Independent Versioning

# 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

Umbrella Versioning

# 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 ✓

Commands Integration

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 matrix

Dependencies

Required:

Git (version tags)
Semver library (version parsing)
SpecWeave core (living docs)

Optional:

NPM (npm version) - Automated bumping
Conventional Commits (commit analysis)
GitHub CLI (gh release) - Release notes

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
Compatibility validation report
Version conflict detection
Dependency graph
Version history

Remember: Version alignment is critical for multi-repo architectures. Always:

Follow semantic versioning strictly
Validate compatibility before releasing
Document breaking changes clearly
Update version matrices regularly
Automate where possible (conventional commits + semantic-release)

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

version-aligner