Initial commit
This commit is contained in:
Zhongwei Li
535
skills/release-coordinator/SKILL.md
Normal file
535
skills/release-coordinator/SKILL.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user