specweave 0.17.0 → 0.17.1

package/plugins/specweave-release/skills/version-aligner/SKILL.md

@@ -0,0 +1,579 @@
+---
+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.