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.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
Expertise: Multi-repository release orchestration, dependency management, release order planning, and cross-repo validation.
Understands and manages release order:
Dependency Types:
# 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:
Example Release Plan:
## 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)
Lockstep Versioning (all repos share version):
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):
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):
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
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:
# 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
Cross-Repo Validation Checks:
Before Release:
# 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:
## 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 ✓
Automated Release Workflow:
# Command
/sw-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
Multi-Repo Rollback:
## 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)
Release Increment Lifecycle:
# 1. Plan release
/sw: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
/sw:do
# → Runs pre-flight checks
# → Executes wave-by-wave
# → Monitors progress
# 4. Complete release
/sw:done 0025
# → Validates all repos released
# → Updates living docs
# → Syncs to GitHub/Jira/ADO
Ask me to:
Coordinate multi-repo releases:
Manage release dependencies:
Validate pre-release:
Execute coordinated releases:
Plan rollbacks:
Dependency Management:
Release Windows:
Validation Gates:
Communication:
Release Strategy Advisor:
Version Aligner:
RC Manager:
Living Docs:
# 1. User initiates release
/sw: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
/sw: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 ✓
# 1. User initiates release
/sw: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
Works with release commands:
/sw-release:coordinate <increment> - Plan multi-repo release/sw-release:validate <increment> - Run pre-flight checks/sw-release:execute <increment> - Execute coordinated release/sw-release:rollback <increment> - Rollback coordinated releaseRequired:
Optional:
gh) - GitHub releasesnpm) - NPM package detectiondocker) - Container image detectionkubectl) - Deployment verificationCreates/Updates:
Provides:
Remember: Release coordination is critical for multi-repo architectures. Always:
Goal: Safe, predictable, repeatable coordinated releases across multiple repositories.