version-aligner

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