536 lines
14 KiB
Markdown
536 lines
14 KiB
Markdown
---
|
|
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.
|