specweave 0.17.0 → 0.17.2

package/plugins/specweave-release/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.