---
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**:
```yaml
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**:
```yaml
# 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):

```yaml
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):

```yaml
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):

```yaml
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**:
```bash
# 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**:
```bash
# 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**:
```yaml
# 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**:
```yaml
# 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**:
```typescript
// 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**:
```yaml
# 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**:
```markdown
# 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**:
```bash
# Command
/specweave-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**:
```bash
# 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**:

1. **Align versions across repos**:
   - "Align versions for all microservices"
   - "Sync versions before release"
   - "What versions should we bump to?"

2. **Detect version conflicts**:
   - "Check for version conflicts"
   - "Validate cross-repo compatibility"
   - "Are our dependencies aligned?"

3. **Suggest version bumps**:
   - "What version should we bump to?"
   - "Analyze commits for version bump"
   - "Calculate semver from commits"

4. **Manage version matrices**:
   - "Update version matrix"
   - "Show compatibility matrix"
   - "Track umbrella version history"

5. **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

```bash
# 1. Analyze changes
/specweave-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

```bash
# 1. Create product release
/specweave: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:

- `/specweave-release:align` - Interactive version alignment
- `/specweave-release:validate-versions` - Check compatibility
- `/specweave-release:bump <repo> <type>` - Bump specific repo
- `/specweave-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.