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)

4. 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

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.