Initial commit

2025-11-29 17:57:06 +08:00
commit a81cf788f6
14 changed files with 5537 additions and 0 deletions
--- a/skills/rc-manager/SKILL.md
+++ b/skills/rc-manager/SKILL.md
@@ -0,0 +1,660 @@
+---
+name: rc-manager
+description: Manages Release Candidate (RC) workflows including pre-release tagging, RC lifecycle (alpha/beta/rc), testing validation, RC promotion to production, rollback procedures, and channel-based releases. Handles RC versioning (v1.0.0-rc.1, v1.0.0-beta.1), tracks RC testing status, coordinates RC across multiple repositories, manages canary/blue-green deployments. Activates for release candidate, RC, pre-release, beta release, alpha release, canary release, rc workflow, promote rc, rc testing, staging release, pre-production.
+---
+
+# Release Candidate Manager
+
+**Expertise**: Release Candidate (RC) lifecycle management, pre-release workflows, testing validation, and production promotion.
+
+## Core Capabilities
+
+### 1. RC Version Tagging
+
+**Pre-Release Version Format**:
+
+```yaml
+# Semantic Versioning Pre-Release
+MAJOR.MINOR.PATCH-PRERELEASE.ITERATION
+
+Examples:
+  1.0.0-alpha.1       # Alpha release (very early, unstable)
+  1.0.0-alpha.2       # Alpha iteration 2
+  1.0.0-beta.1        # Beta release (feature complete, testing)
+  1.0.0-beta.2        # Beta iteration 2
+  1.0.0-rc.1          # Release candidate (near production)
+  1.0.0-rc.2          # RC iteration 2
+  1.0.0               # Final production release
+
+Version Ordering:
+  1.0.0-alpha.1 < 1.0.0-alpha.2 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0
+```
+
+**RC Iteration Rules**:
+```yaml
+# First RC
+v1.0.0-rc.1
+
+# Bug found, fixed → New RC
+v1.0.0-rc.2
+
+# More bugs fixed → New RC
+v1.0.0-rc.3
+
+# All tests pass → Promote to production
+v1.0.0 (final)
+
+# Key Rule: Never modify existing RC tags (immutable)
+```
+
+### 2. RC Lifecycle
+
+**Three-Stage Pre-Release**:
+
+```mermaid
+graph LR
+    A[Development] -->|Feature Complete| B[Alpha]
+    B -->|Stable API| C[Beta]
+    C -->|Production Ready| D[RC]
+    D -->|Validated| E[Production]
+
+    B -->|Bug Fix| B
+    C -->|Bug Fix| C
+    D -->|Bug Fix| D
+```
+
+**Alpha Release** (Early Development):
+```yaml
+Purpose: Early feedback, API exploration
+Tag: v1.0.0-alpha.1, v1.0.0-alpha.2, ...
+Audience: Internal developers, early adopters
+Stability: Unstable (breaking changes expected)
+Duration: Weeks to months
+Testing: Unit + integration tests
+Deployment: Dev environment only
+
+What Can Change:
+  - API contracts (breaking changes OK)
+  - Features (add/remove freely)
+  - Architecture (refactor allowed)
+  - Performance (optimize later)
+
+Exit Criteria:
+  - API stabilized (no more breaking changes)
+  - Core features implemented
+  - Integration tests passing
+```
+
+**Beta Release** (Feature Complete):
+```yaml
+Purpose: Broader testing, performance validation
+Tag: v1.0.0-beta.1, v1.0.0-beta.2, ...
+Audience: Beta testers, QA team, select customers
+Stability: Mostly stable (minor breaking changes only)
+Duration: 2-6 weeks
+Testing: E2E tests, performance tests, security scans
+Deployment: Staging environment
+
+What Can Change:
+  - Bug fixes (no new features)
+  - Minor API tweaks (avoid breaking changes)
+  - Performance improvements
+  - Documentation
+
+Exit Criteria:
+  - All planned features complete
+  - No critical bugs
+  - Performance benchmarks met
+  - Security scan clean
+```
+
+**Release Candidate (RC)** (Production Ready):
+```yaml
+Purpose: Final validation before production
+Tag: v1.0.0-rc.1, v1.0.0-rc.2, ...
+Audience: Production-like environment, select production users
+Stability: Production-ready (no changes except critical fixes)
+Duration: 1-2 weeks
+Testing: Smoke tests, load tests, chaos engineering
+Deployment: Pre-production / Canary (1-5% traffic)
+
+What Can Change:
+  - Critical bug fixes ONLY
+  - Hotfixes for showstoppers
+  - Configuration tweaks
+
+Exit Criteria:
+  - All tests passing (100%)
+  - No blocker bugs
+  - Performance stable under load
+  - Stakeholder sign-off
+  - Chaos engineering passed
+```
+
+**Production Release**:
+```yaml
+Purpose: Stable release for all users
+Tag: v1.0.0 (final)
+Audience: All production users
+Stability: Stable (no changes, only hotfix branches)
+Testing: Continuous monitoring
+Deployment: Production (100% traffic)
+
+Post-Release:
+  - Monitor for 24-48 hours
+  - Track error rates, latency, throughput
+  - Rollback plan ready
+  - Hotfix branch created from tag
+```
+
+### 3. RC Testing & Validation
+
+**Multi-Level Testing Matrix**:
+
+```yaml
+Alpha Testing:
+  - Unit tests: 80%+ coverage
+  - Integration tests: Core flows
+  - Manual testing: Basic functionality
+  - Performance: Not critical yet
+  - Security: Basic scans
+
+Beta Testing:
+  - Unit tests: 90%+ coverage
+  - Integration tests: All flows
+  - E2E tests: Critical paths
+  - Performance: Load testing (50% expected load)
+  - Security: OWASP Top 10 scan
+  - Manual testing: Edge cases
+
+RC Testing:
+  - Unit tests: 90%+ coverage
+  - Integration tests: All flows
+  - E2E tests: All paths
+  - Performance: Load testing (150% expected load)
+  - Security: Full penetration testing
+  - Chaos engineering: Kill random services
+  - Manual testing: Exploratory testing
+  - Smoke tests: After deployment
+
+Production:
+  - Continuous monitoring
+  - Real user monitoring (RUM)
+  - Error tracking (Sentry, Datadog)
+  - APM (Application Performance Monitoring)
+  - Synthetic monitoring (Pingdom, UptimeRobot)
+```
+
+**Validation Checklist** (RC → Production):
+```markdown
+## RC Promotion Checklist: v1.0.0-rc.3 → v1.0.0
+
+### Automated Tests
+- [x] All unit tests passing (2,345 tests)
+- [x] All integration tests passing (456 tests)
+- [x] All E2E tests passing (123 tests)
+- [x] Performance tests: <200ms p95 latency ✓
+- [x] Load tests: 10K req/s sustained ✓
+- [x] Security scan: No critical/high vulnerabilities ✓
+
+### Manual Tests
+- [x] Smoke tests: All critical paths working
+- [x] Exploratory testing: No major issues found
+- [x] Cross-browser testing: Chrome, Firefox, Safari ✓
+- [x] Mobile testing: iOS, Android ✓
+
+### Infrastructure
+- [x] Database migrations tested (forward + rollback)
+- [x] Canary deployment: 5% traffic for 24 hours ✓
+- [x] No increase in error rate
+- [x] No performance degradation
+- [x] Rollback plan validated
+
+### Documentation
+- [x] CHANGELOG.md updated
+- [x] API documentation updated
+- [x] Migration guide written (breaking changes)
+- [x] Release notes drafted
+
+### Stakeholder Approval
+- [x] Product Manager sign-off
+- [x] Engineering Lead sign-off
+- [x] Security Team sign-off
+- [x] Customer Success briefed
+
+### Monitoring
+- [x] Alerts configured (error rate, latency)
+- [x] Dashboards updated (Grafana)
+- [x] On-call schedule confirmed
+
+**Decision**: APPROVED for production release ✅
+```
+
+### 4. RC Promotion Workflow
+
+**Step-by-Step RC → Production**:
+
+```bash
+# 1. Create initial RC
+git tag v1.0.0-rc.1
+git push origin v1.0.0-rc.1
+
+# 2. Deploy to staging
+kubectl apply -f k8s/staging/
+# Wait for pods ready
+
+# 3. Run automated tests
+npm run test:e2e
+npm run test:performance
+npm run test:security
+
+# 4. Deploy canary (5% traffic)
+kubectl apply -f k8s/canary/
+# Monitor for 24 hours
+
+# 5. Found bug → Fix and iterate
+git tag v1.0.0-rc.2
+git push origin v1.0.0-rc.2
+# Repeat steps 2-4
+
+# 6. All tests pass → Promote to production
+git tag v1.0.0
+git push origin v1.0.0
+
+# 7. Deploy to production (gradual rollout)
+# - 10% traffic (1 hour)
+# - 25% traffic (2 hours)
+# - 50% traffic (4 hours)
+# - 100% traffic (8 hours)
+
+# 8. Monitor post-release
+# - Error rates
+# - Latency (p50, p95, p99)
+# - Throughput
+# - User feedback
+
+# 9. Mark RC as promoted
+# Update metadata:
+# .specweave/increments/0045-v1-release/metadata.json
+# {
+#   "rc": {
+#     "promoted": true,
+#     "promotedAt": "2025-01-15T10:00:00Z",
+#     "finalVersion": "1.0.0",
+#     "rcVersion": "1.0.0-rc.3"
+#   }
+# }
+```
+
+### 5. Multi-Repo RC Coordination
+
+**Coordinated RC Across Repos**:
+
+```yaml
+# Scenario: Product v3.0.0-rc.1 spans 4 repos
+
+Product: v3.0.0-rc.1
+RC Versions:
+  - frontend: v5.0.0-rc.1
+  - backend: v3.0.0-rc.1
+  - api-gateway: v4.0.0-rc.1
+  - shared-lib: v2.0.0-rc.1
+
+RC Release Process:
+  1. Tag all repos with rc.1
+  2. Deploy to staging (all services)
+  3. Run cross-service E2E tests
+  4. Found bugs in frontend + gateway
+  5. Fix bugs, tag rc.2:
+     - frontend: v5.0.0-rc.2
+     - api-gateway: v4.0.0-rc.2
+     - backend: v3.0.0-rc.1 (unchanged)
+     - shared-lib: v2.0.0-rc.1 (unchanged)
+  6. Re-test all services
+  7. All pass → Promote to production:
+     - frontend: v5.0.0
+     - backend: v3.0.0
+     - api-gateway: v4.0.0
+     - shared-lib: v2.0.0
+  8. Update product version matrix:
+     Product v3.0.0 = {frontend: v5.0.0, backend: v3.0.0, ...}
+```
+
+**RC Dependency Validation**:
+```yaml
+# Ensure RC versions are compatible
+
+Check 1: Shared library versions match
+  frontend depends on: shared-lib ^2.0.0
+  backend depends on: shared-lib ^2.0.0
+  shared-lib RC: v2.0.0-rc.1 ✓
+
+Check 2: API contracts aligned
+  frontend API client: v4.0.0-rc.1
+  api-gateway version: v4.0.0-rc.1 ✓
+
+Check 3: Database schema compatible
+  Backend requires: schema v12
+  Current staging schema: v12 ✓
+
+Result: All dependencies aligned ✓
+```
+
+### 6. Channel-Based Releases
+
+**Release Channels**:
+
+```yaml
+# NPM-style channels
+Stable: v1.0.0, v1.1.0, v1.2.0
+  - Production users (default)
+  - Fully tested and validated
+  - npm install myapp (installs latest stable)
+
+Beta: v1.1.0-beta.1, v1.2.0-beta.1
+  - Beta testers opt-in
+  - Feature complete, testing phase
+  - npm install myapp@beta
+
+Alpha: v1.1.0-alpha.1, v1.2.0-alpha.1
+  - Early adopters, internal testing
+  - Bleeding edge, unstable
+  - npm install myapp@alpha
+
+Canary: v1.1.0-canary.abc123 (commit-based)
+  - Continuous deployment from main branch
+  - Every commit = new canary
+  - npm install myapp@canary
+```
+
+**Channel Deployment Strategy**:
+```yaml
+# Kubernetes deployment channels
+
+Stable Deployment (Production):
+  replicas: 10
+  traffic: 100%
+  image: myapp:1.0.0
+  rollout: gradual (10% → 25% → 50% → 100%)
+
+Beta Deployment (Pre-Production):
+  replicas: 2
+  traffic: 0% (manual testing only)
+  image: myapp:1.1.0-beta.1
+  namespace: beta
+
+Canary Deployment (Production + Experimental):
+  replicas: 1
+  traffic: 5% (random users)
+  image: myapp:1.1.0-canary.abc123
+  rollback: automatic if error rate > 1%
+  namespace: production
+```
+
+### 7. RC Rollback Procedures
+
+**When to Rollback RC**:
+```yaml
+Immediate Rollback Triggers:
+  - Error rate > 5% (critical)
+  - Latency p95 > 2x baseline (severe degradation)
+  - Data corruption detected (critical)
+  - Security vulnerability discovered (critical)
+  - Showstopper bug (app unusable)
+
+Evaluation Period:
+  - Monitor for 1 hour after deployment
+  - Check dashboards: Grafana, Datadog, Sentry
+  - Review user feedback: Support tickets, social media
+  - Consult on-call engineer
+
+Decision Matrix:
+  - Critical issue + production = Immediate rollback
+  - Severe issue + staging = Fix and iterate RC
+  - Minor issue + canary = Monitor and evaluate
+```
+
+**Rollback Execution**:
+```bash
+# Rollback from v1.0.0-rc.2 to v1.0.0-rc.1
+
+# 1. Stop new deployments
+kubectl rollout pause deployment/myapp
+
+# 2. Rollback to previous RC
+kubectl rollout undo deployment/myapp
+
+# 3. Verify rollback
+kubectl get pods
+kubectl logs <pod-name>
+
+# 4. Validate health
+curl https://api.example.com/health
+# Expected: 200 OK
+
+# 5. Monitor metrics
+# - Error rate back to normal? ✓
+# - Latency back to baseline? ✓
+# - User reports resolved? ✓
+
+# 6. Communicate
+# - Notify team: "Rolled back to rc.1"
+# - Update incident report
+# - Schedule postmortem
+
+# 7. Fix issues, create rc.3
+git tag v1.0.0-rc.3
+git push origin v1.0.0-rc.3
+```
+
+### 8. RC Documentation
+
+**RC Status Tracking**:
+```markdown
+# RC Status: v1.0.0-rc.3
+
+## Timeline
+- 2025-01-10: Created v1.0.0-rc.1
+- 2025-01-12: Found bug in auth flow → v1.0.0-rc.2
+- 2025-01-14: Found performance issue → v1.0.0-rc.3
+- 2025-01-15: All tests passing ✓
+
+## Testing Status
+- [x] Unit tests (2,345 tests)
+- [x] Integration tests (456 tests)
+- [x] E2E tests (123 tests)
+- [x] Performance tests (p95 < 200ms)
+- [x] Security scan (no critical issues)
+- [x] Load test (10K req/s sustained)
+- [x] Chaos engineering (service failures handled)
+
+## Deployment History
+- rc.1: Staging (2025-01-10) → Bug found ❌
+- rc.2: Staging (2025-01-12) → Performance issue ❌
+- rc.3: Staging (2025-01-14) → All tests pass ✓
+- rc.3: Canary 5% (2025-01-15) → Monitoring...
+
+## Issues Found
+1. Bug in rc.1: Authentication fails for SSO users
+   - Fixed: Add SSO provider check
+   - Commit: abc123
+
+2. Performance issue in rc.2: API latency p95 = 800ms
+   - Fixed: Optimize database query
+   - Commit: def456
+
+## Promotion Decision
+- **Status**: APPROVED for production ✅
+- **Approvers**: PM (Jane), Eng Lead (John), Security (Alice)
+- **Scheduled**: 2025-01-16 10:00 AM UTC
+- **Rollout Plan**: Gradual (10% → 25% → 50% → 100%)
+```
+
+## When to Use This Skill
+
+**Ask me to**:
+
+1. **Create RC**:
+   - "Create release candidate for v1.0.0"
+   - "Tag v2.0.0-rc.1"
+   - "Start RC workflow for multi-repo release"
+
+2. **Manage RC lifecycle**:
+   - "What's the status of RC v1.0.0-rc.3?"
+   - "List all RCs for product v3.0.0"
+   - "Show RC testing checklist"
+
+3. **Validate RC**:
+   - "Is RC ready for production?"
+   - "Run RC validation checks"
+   - "Check RC promotion criteria"
+
+4. **Promote RC**:
+   - "Promote v1.0.0-rc.3 to production"
+   - "Deploy RC to canary"
+   - "Gradual rollout of RC"
+
+5. **Rollback RC**:
+   - "Rollback from rc.2 to rc.1"
+   - "RC deployment failed, rollback"
+   - "Undo canary deployment"
+
+## Best Practices
+
+**RC Creation**:
+- Always start with rc.1 (never skip)
+- Tag immutable (never modify existing RC)
+- Document what changed since last release
+
+**RC Testing**:
+- Run ALL tests for each RC iteration
+- Never skip validation steps
+- Use production-like data in staging
+
+**RC Promotion**:
+- Gradual rollout (10% → 25% → 50% → 100%)
+- Monitor for 1+ hour at each stage
+- Have rollback plan ready
+
+**RC Documentation**:
+- Track all RC iterations
+- Document bugs found and fixes
+- Record promotion decision rationale
+
+## Integration Points
+
+**Release Coordinator**:
+- Creates RCs for coordinated releases
+- Validates RC dependencies
+- Promotes RCs in correct order
+
+**Version Aligner**:
+- Manages RC version tags
+- Ensures RC compatibility
+- Updates version matrix with RC info
+
+**Living Docs**:
+- Documents RC status
+- Tracks RC history
+- Links to GitHub releases
+
+**CI/CD**:
+- Automates RC deployment
+- Runs validation tests
+- Monitors RC health
+
+## Example Workflows
+
+### Single-Repo RC
+
+```bash
+# 1. Create RC
+/specweave-release:rc create 1.0.0
+
+# 2. Deploy to staging
+# (Automated via CI/CD)
+
+# 3. Run tests
+/specweave-release:rc test 1.0.0-rc.1
+
+# 4. Bug found → iterate
+/specweave-release:rc create 1.0.0 --iteration 2
+
+# 5. All tests pass → promote
+/specweave-release:rc promote 1.0.0-rc.3
+```
+
+### Multi-Repo RC
+
+```bash
+# 1. Create coordinated RC
+/specweave-release:rc create-multi product-v3.0.0
+
+# 2. Tags all repos with rc.1
+# - frontend: v5.0.0-rc.1
+# - backend: v3.0.0-rc.1
+# - api-gateway: v4.0.0-rc.1
+
+# 3. Deploy all to staging
+# (Coordinated deployment)
+
+# 4. Cross-service E2E tests
+/specweave-release:rc test-multi product-v3.0.0-rc.1
+
+# 5. Issues found → iterate
+# - frontend: rc.2
+# - api-gateway: rc.2
+# - backend: unchanged (rc.1)
+
+# 6. All pass → promote
+/specweave-release:rc promote-multi product-v3.0.0-rc.2
+```
+
+## Commands Integration
+
+Works with release commands:
+
+- `/specweave-release:rc create <version>` - Create new RC
+- `/specweave-release:rc test <rc-version>` - Validate RC
+- `/specweave-release:rc promote <rc-version>` - Promote to production
+- `/specweave-release:rc rollback <rc-version>` - Rollback RC
+- `/specweave-release:rc status <rc-version>` - Show RC status
+
+## Dependencies
+
+**Required**:
+- Git (version tags)
+- SpecWeave core (increment lifecycle)
+
+**Optional**:
+- Kubernetes (`kubectl`) - Deployment management
+- Docker (`docker`) - Container testing
+- GitHub CLI (`gh`) - Release notes
+- CI/CD (GitHub Actions, GitLab CI)
+
+## Output
+
+**Creates/Updates**:
+- Git tags (v1.0.0-rc.1, v1.0.0-rc.2, ...)
+- RC status document (increment reports/)
+- Deployment manifests (K8s, Docker)
+- Test reports
+- Promotion checklist
+
+**Provides**:
+- RC version history
+- Testing validation status
+- Deployment timeline
+- Rollback procedures
+- Production readiness assessment
+
+---
+
+**Remember**: Release Candidates are the final gate before production. Never rush RC validation. Always:
+- Test thoroughly (unit + integration + E2E + performance + security)
+- Deploy gradually (canary → 10% → 25% → 50% → 100%)
+- Monitor continuously (error rates, latency, user feedback)
+- Have rollback plan ready (test rollback procedure)
+- Document everything (bugs found, fixes applied, decisions made)
+
+**Goal**: Catch issues before production, deploy confidently, rollback quickly if needed.
--- a/skills/release-coordinator/SKILL.md
+++ b/skills/release-coordinator/SKILL.md
@@ -0,0 +1,535 @@
+---
+name: release-coordinator
+description: Coordinates multi-repository releases with dependency management, release order orchestration, and cross-repo validation. Handles coordinated releases (lockstep versioning), independent releases, and umbrella versioning. Creates release increments spanning multiple repositories, manages release dependencies (repo A must release before B), generates comprehensive release plans, validates pre-release checks across all repos. Activates for coordinate releases, multi-repo release, release dependencies, release order, cross-repo release, synchronized release, orchestrate release, release planning, multi-service release, coordinated deployment.
+---
+
+# Release Coordinator
+
+**Expertise**: Multi-repository release orchestration, dependency management, release order planning, and cross-repo validation.
+
+## Core Capabilities
+
+### 1. Release Dependency Management
+
+**Understands and manages release order**:
+
+**Dependency Types**:
+```yaml
+# Build-time dependencies
+shared-lib: v2.0.0
+  └─ service-a: v3.1.0 (depends on shared-lib)
+  └─ service-b: v2.5.0 (depends on shared-lib)
+
+# Runtime dependencies
+auth-service: v1.8.0
+  └─ api-gateway: v2.0.0 (calls auth-service)
+     └─ frontend: v3.2.0 (calls api-gateway)
+
+# Data schema dependencies
+database-migrations: v10
+  └─ backend-services: v2.x (requires schema v10)
+```
+
+**Release Order Calculation**:
+1. Build dependency graph
+2. Topological sort for correct order
+3. Identify circular dependencies (error)
+4. Generate release waves:
+   - Wave 1: No dependencies (shared-lib, database-migrations)
+   - Wave 2: Depends on Wave 1 (service-a, service-b)
+   - Wave 3: Depends on Wave 2 (api-gateway)
+   - Wave 4: Depends on Wave 3 (frontend)
+
+**Example Release Plan**:
+```markdown
+## Release Order for Product v3.0.0
+
+### Wave 1 (Foundations)
+- [ ] shared-lib: v2.0.0 → v3.0.0
+- [ ] database-migrations: v9 → v10
+
+### Wave 2 (Backend Services)
+- [ ] auth-service: v1.8.0 → v2.0.0 (depends: shared-lib v3.0.0)
+- [ ] user-service: v1.5.0 → v2.0.0 (depends: shared-lib v3.0.0, schema v10)
+- [ ] order-service: v2.1.0 → v3.0.0 (depends: shared-lib v3.0.0, schema v10)
+
+### Wave 3 (API Layer)
+- [ ] api-gateway: v2.0.0 → v3.0.0 (depends: auth-service v2.0.0, user-service v2.0.0)
+
+### Wave 4 (Frontend)
+- [ ] web-app: v3.2.0 → v4.0.0 (depends: api-gateway v3.0.0)
+- [ ] mobile-app: v2.5.0 → v3.0.0 (depends: api-gateway v3.0.0)
+
+**Total Duration**: ~4 hours (waves run sequentially, repos in wave release in parallel)
+```
+
+### 2. Coordinated Release Strategies
+
+**Lockstep Versioning** (all repos share version):
+```yaml
+Product: v3.0.0
+Repositories:
+  - frontend: v3.0.0
+  - backend: v3.0.0
+  - api: v3.0.0
+  - shared: v3.0.0
+
+Benefits:
+  - Simple to understand (one version = one product state)
+  - Clear API compatibility
+  - Easier rollback (revert entire product)
+
+Challenges:
+  - Forces releases even if no changes
+  - High coordination overhead
+  - All teams must sync
+
+Use When:
+  - Tight coupling between repos
+  - Small team (all work together)
+  - Breaking changes affect all repos
+```
+
+**Independent Versioning** (each repo has own version):
+```yaml
+Product: N/A
+Repositories:
+  - frontend: v4.2.0
+  - backend: v2.8.0
+  - api: v3.1.0
+  - shared: v1.5.0
+
+Benefits:
+  - Autonomous teams
+  - Release when ready
+  - No forced releases
+
+Challenges:
+  - Complex compatibility matrix
+  - Hard to understand product state
+  - Testing combinations expensive
+
+Use When:
+  - Loose coupling between repos
+  - Large team (independent squads)
+  - Frequent releases (daily/weekly)
+```
+
+**Umbrella Versioning** (product version + service versions):
+```yaml
+Product: v5.0.0 (umbrella)
+├─ frontend: v4.2.0
+├─ backend: v2.8.0
+├─ api: v3.1.0
+└─ shared: v1.5.0
+
+Benefits:
+  - Clear product milestones (v5.0.0 = major release)
+  - Internal flexibility (services version independently)
+  - Best of both worlds
+
+Challenges:
+  - Version matrix tracking
+  - Compatibility validation
+
+Use When:
+  - Medium/large team
+  - Product-level milestones important
+  - Services evolve at different rates
+```
+
+### 3. Release Increment Creation
+
+**Creates release increments spanning repos**:
+
+**Single-Repo Release Increment**:
+```
+.specweave/increments/0020-backend-v2-release/
+├── spec.md           # What's being released
+├── plan.md           # Release execution plan
+├── tasks.md          # Release checklist
+└── metadata.json     # Repository: backend, target: v2.0.0
+```
+
+**Multi-Repo Release Increment**:
+```
+.specweave/increments/0025-product-v3-release/
+├── spec.md           # Product release overview
+├── plan.md           # Cross-repo orchestration
+├── tasks.md          # Multi-repo checklist
+└── metadata.json     # Repositories: [frontend, backend, api], umbrella: v3.0.0
+```
+
+**spec.md Example**:
+```markdown
+# Product v3.0.0 Release
+
+## Release Type
+Umbrella (coordinated major version)
+
+## Repositories
+- frontend: v3.2.0 → v4.0.0
+- backend: v2.5.0 → v3.0.0
+- api-gateway: v2.8.0 → v3.0.0
+- shared-lib: v1.8.0 → v2.0.0
+
+## Key Changes
+- **Breaking**: API v2 → v3 (remove legacy endpoints)
+- **Feature**: Real-time notifications (WebSocket)
+- **Performance**: 50% faster API response time
+
+## Release Waves
+See plan.md for detailed orchestration
+
+## Success Criteria
+- [ ] All repos tagged (v3.0.0 umbrella)
+- [ ] GitHub releases published
+- [ ] Changelogs updated
+- [ ] Packages published (NPM/Docker)
+- [ ] Deployed to production
+- [ ] Smoke tests passing
+- [ ] DORA metrics: Lead time <1 day
+```
+
+### 4. Pre-Release Validation
+
+**Cross-Repo Validation Checks**:
+
+**Before Release**:
+```bash
+# 1. Version Compatibility
+✓ shared-lib v2.0.0 compatible with service-a v3.0.0
+✓ API contracts match between gateway and services
+✗ Database schema v10 required by backend, but only v9 deployed
+
+# 2. CI/CD Status
+✓ All tests passing in all repos
+✓ No pending code review comments
+✗ Staging deployment failed for frontend
+
+# 3. Dependency Versions
+✓ All repos use shared-lib v2.0.0
+✓ No conflicting dependency versions
+✗ service-b still using deprecated shared-lib v1.5.0
+
+# 4. Documentation
+✓ CHANGELOG.md updated in all repos
+✓ API docs regenerated
+✗ Migration guide missing for breaking changes
+
+# 5. Release Notes
+✓ All commits since last release analyzed
+✓ Breaking changes documented
+✗ Missing highlights section
+```
+
+**Blocking Issues Report**:
+```markdown
+## Pre-Release Validation: BLOCKED ❌
+
+### Blockers (MUST FIX)
+1. **Database schema mismatch**:
+   - Backend requires schema v10
+   - Current production: schema v9
+   - Action: Deploy migration v9→v10 first
+
+2. **Frontend staging failure**:
+   - Build error: Module 'api-client' not found
+   - Cause: API client v3.0.0 not published yet
+   - Action: Publish api-client first (Wave 1)
+
+3. **Outdated dependency**:
+   - service-b using shared-lib v1.5.0 (deprecated)
+   - Required: shared-lib v2.0.0
+   - Action: Update service-b, test, then release
+
+### Warnings (Should Fix)
+1. Missing migration guide for API v2→v3
+2. Incomplete release notes (missing highlights)
+
+### Ready to Release
+- auth-service v2.0.0 ✓
+- user-service v2.0.0 ✓
+- shared-lib v2.0.0 ✓
+```
+
+### 5. Release Execution Orchestration
+
+**Automated Release Workflow**:
+
+```bash
+# Command
+/specweave-release:execute 0025-product-v3-release
+
+# Executes:
+1. Pre-flight checks (validation)
+2. Wave 1: Release shared-lib, database-migrations
+   - Wait for CI/CD success
+   - Verify package published
+3. Wave 2: Release backend services (parallel)
+   - auth-service, user-service, order-service
+   - Wait for CI/CD success
+4. Wave 3: Release api-gateway
+   - Wait for CI/CD success
+5. Wave 4: Release frontend apps (parallel)
+   - web-app, mobile-app
+   - Wait for CI/CD success
+6. Post-release validation
+   - Smoke tests
+   - Health checks
+   - Monitor for 1 hour
+7. Update living docs
+   - Sync release-strategy.md
+   - Update version matrix
+8. Notify stakeholders
+   - Slack/email: "Product v3.0.0 released"
+   - DORA metrics: Deployment frequency +1
+```
+
+### 6. Rollback Coordination
+
+**Multi-Repo Rollback**:
+
+```markdown
+## Rollback Plan: Product v3.0.0 → v2.5.0
+
+### Trigger
+- Critical bug in api-gateway v3.0.0
+- Affected: 20% of API calls failing
+
+### Strategy
+Reverse wave order (rollback dependencies first)
+
+### Wave 1 (Rollback Frontend First)
+- [ ] web-app: v4.0.0 → v3.2.0
+- [ ] mobile-app: v3.0.0 → v2.5.0
+
+### Wave 2 (Rollback API Layer)
+- [ ] api-gateway: v3.0.0 → v2.8.0
+
+### Wave 3 (Rollback Backend - Optional)
+- [ ] Keep backend services at v3.0.0 (backward compatible)
+- [ ] If needed: auth-service v2.0.0 → v1.8.0
+
+### Wave 4 (Rollback Shared - Optional)
+- [ ] Keep shared-lib at v2.0.0 (no bugs reported)
+
+**Duration**: ~30 minutes (frontend + gateway only)
+**Impact**: Minimal (API compatible with older clients)
+```
+
+### 7. Integration with SpecWeave Workflows
+
+**Release Increment Lifecycle**:
+
+```bash
+# 1. Plan release
+/specweave:increment "0025-product-v3-release"
+# → Creates increment with multi-repo spec
+
+# 2. Coordinate release (this skill activates)
+# → Analyzes dependencies
+# → Generates release waves
+# → Creates validation checklist
+
+# 3. Execute release
+/specweave:do
+# → Runs pre-flight checks
+# → Executes wave-by-wave
+# → Monitors progress
+
+# 4. Complete release
+/specweave:done 0025
+# → Validates all repos released
+# → Updates living docs
+# → Syncs to GitHub/Jira/ADO
+```
+
+## When to Use This Skill
+
+**Ask me to**:
+
+1. **Coordinate multi-repo releases**:
+   - "Plan release for 5 microservices"
+   - "Coordinate backend and frontend release"
+   - "Create release plan spanning repos"
+
+2. **Manage release dependencies**:
+   - "What order should we release repos?"
+   - "Which services depend on shared-lib?"
+   - "Calculate release waves"
+
+3. **Validate pre-release**:
+   - "Check if we're ready to release"
+   - "Validate cross-repo compatibility"
+   - "Run pre-flight checks"
+
+4. **Execute coordinated releases**:
+   - "Release product v3.0.0"
+   - "Execute umbrella release"
+   - "Orchestrate wave-by-wave deployment"
+
+5. **Plan rollbacks**:
+   - "Create rollback plan for v3.0.0"
+   - "How to rollback if frontend fails?"
+   - "Reverse release order"
+
+## Best Practices
+
+**Dependency Management**:
+- Document dependencies in release-strategy.md
+- Automate dependency detection (package.json, imports)
+- Version lock shared libraries (avoid floating versions)
+
+**Release Windows**:
+- Schedule releases during low-traffic periods
+- Reserve rollback window (2x release duration)
+- Communicate blackout periods (holidays, weekends)
+
+**Validation Gates**:
+- Never skip pre-flight checks (catch issues early)
+- Automate validation (CI/CD pipelines)
+- Manual approval gates for production
+
+**Communication**:
+- Notify all teams before release (1 day notice)
+- Real-time status updates during release
+- Post-release summary (DORA metrics, issues)
+
+## Integration Points
+
+**Release Strategy Advisor**:
+- Reads release-strategy.md for approach
+- Adapts coordination to strategy type
+- Suggests improvements based on issues
+
+**Version Aligner**:
+- Uses version alignment rules
+- Ensures compatibility across repos
+- Validates semver constraints
+
+**RC Manager**:
+- Coordinates RC releases (pre-production)
+- Validates RC before production
+- Promotes RC to final release
+
+**Living Docs**:
+- Documents release history
+- Updates version matrix
+- Links to GitHub releases
+
+## Example Workflows
+
+### Microservices Coordinated Release
+
+```bash
+# 1. User initiates release
+/specweave:increment "0030-product-v4-release"
+
+# 2. Coordinator analyzes
+# - 8 microservices detected
+# - Dependency graph: shared-lib → services → gateway → frontend
+# - Release strategy: Umbrella versioning
+
+# 3. Generates plan
+# - Wave 1: shared-lib v3.0.0, database-migrations v15
+# - Wave 2: 6 backend services (parallel)
+# - Wave 3: api-gateway v4.0.0
+# - Wave 4: web + mobile apps (parallel)
+
+# 4. Pre-flight validation
+# - All tests passing ✓
+# - No blocking dependencies ✓
+# - Changelogs updated ✓
+# - Ready to release ✓
+
+# 5. Execute release
+/specweave:do
+# - Wave 1 released (15 min)
+# - Wave 2 released (20 min, parallel)
+# - Wave 3 released (10 min)
+# - Wave 4 released (25 min, parallel)
+# Total: 70 minutes
+
+# 6. Post-release
+# - All smoke tests passing ✓
+# - DORA metrics updated ✓
+# - Stakeholders notified ✓
+# - Living docs synced ✓
+```
+
+### Monorepo Release (Lerna)
+
+```bash
+# 1. User initiates release
+/specweave:increment "0035-monorepo-v2-release"
+
+# 2. Coordinator analyzes
+# - Lerna monorepo (12 packages)
+# - Independent versioning
+# - Changes detected in 4 packages
+
+# 3. Generates plan
+# - @myapp/shared: v1.5.0 → v1.6.0 (patch)
+# - @myapp/api-client: v2.0.0 → v2.1.0 (minor)
+# - @myapp/web: v3.2.0 → v3.3.0 (minor)
+# - @myapp/mobile: v2.8.0 → v2.8.1 (patch)
+
+# 4. Dependency order
+# - shared → api-client → (web, mobile)
+
+# 5. Execute release
+npx lerna publish --conventional-commits
+# - Shared released first
+# - API client released second
+# - Web and mobile released in parallel
+```
+
+## Commands Integration
+
+Works with release commands:
+
+- `/specweave-release:coordinate <increment>` - Plan multi-repo release
+- `/specweave-release:validate <increment>` - Run pre-flight checks
+- `/specweave-release:execute <increment>` - Execute coordinated release
+- `/specweave-release:rollback <increment>` - Rollback coordinated release
+
+## Dependencies
+
+**Required**:
+- Git (version tags)
+- SpecWeave core (increment lifecycle)
+- Release strategy documentation
+
+**Optional**:
+- GitHub CLI (`gh`) - GitHub releases
+- NPM (`npm`) - NPM package detection
+- Docker (`docker`) - Container image detection
+- Kubernetes (`kubectl`) - Deployment verification
+
+## Output
+
+**Creates/Updates**:
+- Release increment (spec.md, plan.md, tasks.md)
+- Release waves documentation
+- Pre-flight validation report
+- Rollback plan
+- Release history in living docs
+
+**Provides**:
+- Dependency graph visualization
+- Release order (topological sort)
+- Pre-flight validation status
+- Real-time release progress
+- Post-release metrics
+
+---
+
+**Remember**: Release coordination is critical for multi-repo architectures. Always:
+- Understand dependencies before releasing
+- Validate cross-repo compatibility
+- Execute wave-by-wave (never "big bang" all at once)
+- Have rollback plan ready
+- Monitor for 1+ hour post-release
+
+**Goal**: Safe, predictable, repeatable coordinated releases across multiple repositories.
--- a/skills/release-strategy-advisor/SKILL.md
+++ b/skills/release-strategy-advisor/SKILL.md
@@ -0,0 +1,473 @@
+---
+name: release-strategy-advisor
+description: Expert in analyzing and recommending release strategies for software projects. Detects existing release patterns in brownfield projects (git tags, CI/CD workflows, changelogs, version files). Suggests optimal strategies based on architecture (single-repo, multi-repo, monorepo, microservices), team size, deployment frequency, and dependencies. Creates comprehensive release-strategy.md in living docs (.specweave/docs/internal/delivery/ or projects/{id}/delivery/). Activates for release strategy, versioning strategy, multi-repo releases, monorepo versioning, semantic versioning, coordinated releases, independent releases, release planning, version alignment, brownfield release analysis, deployment strategy, CI/CD release, how to version, release best practices.
+---
+
+# Release Strategy Advisor
+
+**Expertise**: Release management strategy design, version alignment, brownfield release pattern detection, and living documentation of delivery processes.
+
+## Core Capabilities
+
+### 1. Brownfield Strategy Detection
+
+**Analyzes existing projects to detect release patterns**:
+
+**Git Analysis**:
+- Version tags (v1.0.0, v2.1.0-rc.1, etc.)
+- Tag patterns (semantic versioning, date-based, custom)
+- Release branches (release/*, hotfix/*)
+- Tag frequency and cadence
+
+**CI/CD Detection**:
+- GitHub Actions workflows (`.github/workflows/release.yml`)
+- GitLab CI (`.gitlab-ci.yml`)
+- Jenkins pipelines (`Jenkinsfile`)
+- CircleCI config (`.circleci/config.yml`)
+- Azure Pipelines (`azure-pipelines.yml`)
+
+**Package Managers**:
+- NPM: `package.json` (version, scripts: version/publish)
+- Python: `setup.py`, `pyproject.toml`
+- Java: `pom.xml`, `build.gradle`
+- Go: `go.mod`
+- Ruby: `*.gemspec`
+- Rust: `Cargo.toml`
+
+**Monorepo Tools**:
+- Lerna (`lerna.json`)
+- Nx (`nx.json`, `workspace.json`)
+- Turborepo (`turbo.json`)
+- Yarn Workspaces (`package.json` workspaces)
+- Changesets (`.changeset/config.json`)
+
+**Release Automation**:
+- Semantic Release (`.releaserc`, `release.config.js`)
+- Standard Version (`.versionrc`)
+- Conventional Changelog
+- Custom release scripts
+
+### 2. Strategy Recommendation
+
+**Suggests optimal strategy based on**:
+
+**Project Architecture**:
+- Single repository → Simple semver strategy
+- Multi-repo (2-5 repos) → Coordinated or independent
+- Multi-repo (5+ repos) → Umbrella versioning
+- Monorepo → Workspace-based versioning
+- Microservices → Service-level versioning
+
+**Team Factors**:
+- Small team (1-5) → Simple manual releases
+- Medium team (5-20) → Semi-automated releases
+- Large team (20+) → Fully automated releases
+
+**Deployment Patterns**:
+- Low frequency (<1/month) → Manual releases
+- Medium frequency (1-4/month) → Semi-automated
+- High frequency (daily/weekly) → Automated CI/CD
+- Continuous deployment → Trunk-based + feature flags
+
+**Dependencies**:
+- No dependencies → Independent releases
+- Weak coupling → Independent with coordination
+- Strong coupling → Coordinated/lockstep releases
+- Shared libraries → Umbrella versioning
+
+### 3. Release Strategy Types
+
+**Single Repo Strategies**:
+```markdown
+## Simple Semver
+- One repository, one version
+- Manual or automated bumps (patch/minor/major)
+- GitHub releases + NPM/PyPI publish
+- CHANGELOG.md maintenance
+- Example: SpecWeave itself
+```
+
+**Multi-Repo Strategies**:
+```markdown
+## Coordinated Releases
+- All repos share same version
+- Release together (v1.0.0 across all)
+- Synchronized CI/CD
+- Example: Microservices with tight coupling
+
+## Independent Releases
+- Each repo has own version
+- Release independently
+- Example: service-a v2.1.0, service-b v1.5.0
+
+## Umbrella Versioning
+- Product version (v3.0.0) spans multiple repos
+- Internal service versions tracked separately
+- Example: "Product v3.0.0" contains:
+  - frontend v2.5.0
+  - backend v1.8.0
+  - api v2.1.0
+```
+
+**Monorepo Strategies**:
+```markdown
+## Workspace-Based
+- Lerna/Nx/Turborepo manage versions
+- Independent package versions
+- Changesets for semantic release
+- Example: Babel, Jest
+
+## Fixed Versioning
+- All packages share same version
+- Lerna --fixed mode
+- Example: Angular packages
+```
+
+**Microservices Strategies**:
+```markdown
+## Service-Level Versioning
+- Each service has own semantic version
+- API contract versioning separate
+- Rolling releases (deploy services independently)
+
+## Coordinated Major Releases
+- Independent minor/patch versions
+- Coordinated major versions (breaking changes)
+- Example: v2.x (service-a v2.3.0, service-b v2.1.0)
+```
+
+### 4. Release Candidate (RC) Management
+
+**RC Patterns**:
+
+**Pre-Release Tags**:
+- `v1.0.0-rc.1`, `v1.0.0-rc.2` → `v1.0.0` (final)
+- `v2.0.0-beta.1` → `v2.0.0-rc.1` → `v2.0.0`
+- `v3.0.0-alpha.1` → `v3.0.0-beta.1` → `v3.0.0-rc.1` → `v3.0.0`
+
+**Channel-Based**:
+- Stable (production)
+- Beta (pre-release testing)
+- Alpha (early adopters)
+- Canary (1% traffic, feature flags)
+
+**Environment-Based**:
+- Dev → Staging (RC) → Production (final)
+- Feature branches → RC branch → Main branch
+
+**RC Workflow**:
+1. Create RC: `v1.0.0-rc.1`
+2. Deploy to staging/beta channel
+3. Testing & bug fixes (creates rc.2, rc.3, ...)
+4. Validation complete → Promote RC to v1.0.0
+5. Deploy to production
+
+### 5. Living Documentation
+
+**Creates release-strategy.md in**:
+
+**Cross-Project** (applies to entire system):
+```
+.specweave/docs/internal/delivery/release-strategy.md
+```
+
+**Project-Specific** (multi-project mode):
+```
+.specweave/docs/internal/projects/{project-id}/delivery/release-strategy.md
+```
+
+**Document Structure**:
+```markdown
+# Release Strategy: {Product/Project Name}
+
+## Current Strategy
+- Type: Single-repo / Multi-repo / Monorepo / Microservices
+- Versioning: Semantic / Date-based / Custom
+- Alignment: Lockstep / Independent / Umbrella
+- RC Process: Pre-release tags / Channels / Feature flags
+
+## Repositories
+- Repo A: {purpose, current version, release frequency}
+- Repo B: {purpose, current version, release frequency}
+
+## Version Alignment
+- Major: Coordinated (breaking changes)
+- Minor: Independent (new features)
+- Patch: Independent (bug fixes)
+
+## Release Candidate Workflow
+1. Create RC tag: v1.0.0-rc.1
+2. Deploy to staging
+3. Testing phase (1 week)
+4. Promote to production: v1.0.0
+
+## CI/CD Integration
+- GitHub Actions: .github/workflows/release.yml
+- Automated: npm publish, Docker push, Deploy to K8s
+- Manual gates: QA approval, stakeholder sign-off
+
+## Changelog Management
+- Tool: Conventional Changelog / Keep a Changelog
+- Format: CHANGELOG.md (root or per-package)
+- Automation: semantic-release / standard-version
+
+## Hotfix Strategy
+- Branch: hotfix/* from production tag
+- Version: Patch bump (v1.0.1)
+- Process: Fast-track testing, immediate deploy
+
+## Release Checklist
+- [ ] All tests passing
+- [ ] Changelog updated
+- [ ] Version bumped
+- [ ] Git tag created
+- [ ] GitHub release published
+- [ ] Package published (NPM/PyPI/Docker)
+- [ ] Deployment successful
+- [ ] Documentation updated
+
+## Metrics & Monitoring
+- DORA Metrics: Deployment frequency, lead time, MTTR, change failure rate
+- Release cadence: {weekly / bi-weekly / monthly}
+- Hotfix frequency: {target <5% of releases}
+
+## Decision History
+- 2025-01-15: Adopted umbrella versioning (ADR-023)
+- 2025-02-01: Introduced RC workflow (ADR-025)
+- 2025-03-10: Migrated to semantic-release (ADR-028)
+```
+
+### 6. Integration with Brownfield Analyzer
+
+**Automatic Strategy Detection** (when brownfield analyzer runs):
+
+```bash
+# Brownfield analyzer detects:
+# 1. Repository structure (single/multi/monorepo)
+# 2. Existing version tags
+# 3. CI/CD configurations
+# 4. Package manager configs
+# 5. Release automation tools
+
+# Then invokes release-strategy-advisor:
+# - Analyze detected patterns
+# - Classify release strategy
+# - Document findings in release-strategy.md
+# - Suggest improvements if needed
+```
+
+**Detection Output Example**:
+```markdown
+## Detected Release Strategy
+
+**Type**: Multi-repo Independent Releases
+
+**Evidence**:
+- 3 repositories detected:
+  - frontend: v2.5.0 (last release: 2025-01-10)
+  - backend: v1.8.0 (last release: 2025-01-08)
+  - shared: v1.2.0 (last release: 2024-12-15)
+
+- Version alignment: None (independent)
+- Release frequency: Weekly (frontend), Bi-weekly (backend), Monthly (shared)
+- CI/CD: GitHub Actions with semantic-release
+- Changelog: Conventional Changelog (auto-generated)
+
+**Recommendations**:
+1. Consider umbrella versioning for product releases
+2. Add RC workflow for major versions
+3. Align major versions for better API compatibility
+```
+
+## When to Use This Skill
+
+**Ask me to**:
+
+1. **Analyze existing release strategy**:
+   - "What's our current release strategy?"
+   - "Detect our versioning patterns"
+   - "Analyze how we're releasing across repos"
+
+2. **Recommend optimal strategy**:
+   - "What release strategy should we use?"
+   - "How should we version our microservices?"
+   - "Should we use coordinated or independent releases?"
+
+3. **Create release documentation**:
+   - "Document our release process"
+   - "Create release-strategy.md"
+   - "Write down our versioning approach"
+
+4. **Plan multi-repo releases**:
+   - "How to coordinate releases across 5 repos?"
+   - "Should we align versions?"
+   - "What's the best RC workflow for us?"
+
+5. **Brownfield integration**:
+   - "Understand our existing release process"
+   - "What release tools are we using?"
+   - "Map our current deployment pipeline"
+
+## Best Practices
+
+**Version Alignment**:
+- Lockstep: Use for tightly coupled services (shared breaking changes)
+- Independent: Use for loosely coupled services (autonomous teams)
+- Umbrella: Use for products with multiple independent modules
+
+**RC Workflows**:
+- Always use RC for major versions (breaking changes)
+- Consider RC for minor versions if critical features
+- Skip RC for patch versions (hotfixes) unless high risk
+
+**Changelog Discipline**:
+- Automate changelog generation (conventional commits)
+- Manual curation for major releases (highlight key features)
+- Link to GitHub issues/PRs for traceability
+
+**Release Frequency**:
+- High-risk changes: RC → staging → production (1-2 weeks)
+- Low-risk changes: Direct to production (daily/weekly)
+- Balance speed with stability (DORA metrics)
+
+## Integration Points
+
+**Brownfield Analyzer**:
+- Detects existing patterns automatically
+- Feeds data to release-strategy-advisor
+- Creates baseline documentation
+
+**Living Docs**:
+- Stores strategy in delivery/ folder
+- Updates on strategy changes
+- Links to ADRs for decisions
+
+**Multi-Project**:
+- Different strategies per project
+- Cross-project release coordination
+- Shared release templates
+
+**Increment Lifecycle**:
+- Release increments span repositories
+- Coordinated planning & execution
+- Automated living docs sync
+
+## Example Workflows
+
+### Single-Repo Project (SpecWeave)
+
+```bash
+# 1. User asks for release strategy
+"What release strategy should SpecWeave use?"
+
+# 2. Advisor analyzes:
+# - Single repo (GitHub: anton-abyzov/specweave)
+# - NPM package
+# - GitHub Actions for releases
+# - Existing semver tags
+
+# 3. Recommends:
+# - Simple semver strategy
+# - Automated releases via GitHub Actions
+# - CHANGELOG.md maintenance
+# - RC for major versions only
+
+# 4. Creates:
+# .specweave/docs/internal/delivery/release-strategy.md
+```
+
+### Multi-Repo Microservices
+
+```bash
+# 1. User asks for strategy
+"How should we release our 5 microservices?"
+
+# 2. Advisor analyzes:
+# - 5 repos detected (user-service, order-service, ...)
+# - Tight coupling (shared API contracts)
+# - High deployment frequency (daily)
+
+# 3. Recommends:
+# - Umbrella versioning (product v1.0.0)
+# - Independent service versions (service-a v2.3.0)
+# - RC workflow for product major versions
+# - Rolling releases for services
+
+# 4. Creates:
+# .specweave/docs/internal/delivery/release-strategy.md
+# - Umbrella version matrix
+# - Service version independence
+# - RC workflow for product releases
+```
+
+### Monorepo (Lerna/Nx)
+
+```bash
+# 1. User asks for strategy
+"How to version our Lerna monorepo?"
+
+# 2. Advisor analyzes:
+# - Monorepo with 12 packages
+# - Lerna detected (lerna.json)
+# - Changesets for versioning
+# - Independent package releases
+
+# 3. Recommends:
+# - Independent versioning (Lerna independent mode)
+# - Changesets for semantic release
+# - Automated changelogs per package
+# - Fixed versioning for core packages
+
+# 4. Creates:
+# .specweave/docs/internal/delivery/release-strategy.md
+# - Lerna configuration explanation
+# - Changesets workflow
+# - Package grouping strategy
+```
+
+## Commands Integration
+
+Works with release management commands:
+
+- `/specweave-release:init` - Analyze & recommend strategy
+- `/specweave-release:align` - Align versions across repos
+- `/specweave-release:rc` - Create release candidate
+- `/specweave-release:publish` - Execute release
+
+## Dependencies
+
+**Required**:
+- Git (version tag analysis)
+- SpecWeave core (living docs integration)
+
+**Optional** (for detection):
+- GitHub CLI (`gh`) - GitHub release detection
+- NPM (`npm`) - NPM package detection
+- Python (`python`) - Python package detection
+- Lerna (`lerna`) - Monorepo detection
+- Nx (`nx`) - Nx workspace detection
+
+## Output
+
+**Creates/Updates**:
+- `.specweave/docs/internal/delivery/release-strategy.md` (cross-project)
+- `.specweave/docs/internal/projects/{id}/delivery/release-strategy.md` (project-specific)
+
+**Provides**:
+- Current strategy analysis
+- Recommended improvements
+- RC workflow templates
+- CI/CD integration guides
+- Version alignment matrix
+- Release checklist
+
+---
+
+**Remember**: Release strategy is a living document. Update it when:
+- Architecture changes (new repos, services)
+- Team size changes
+- Deployment frequency changes
+- Tooling changes (new CI/CD, monorepo tools)
+- Lessons learned from releases
+
+**Goal**: Clear, documented, repeatable release process that scales with your team and product.
--- a/skills/version-aligner/SKILL.md
+++ b/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.