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:

## 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:

## 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:

## 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:

## 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:

Create RC: v1.0.0-rc.1
Deploy to staging/beta channel
Testing & bug fixes (creates rc.2, rc.3, ...)
Validation complete → Promote RC to v1.0.0
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:

# 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):

# 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:

## 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:

Analyze existing release strategy:
- "What's our current release strategy?"
- "Detect our versioning patterns"
- "Analyze how we're releasing across repos"
Recommend optimal strategy:
- "What release strategy should we use?"
- "How should we version our microservices?"
- "Should we use coordinated or independent releases?"
Create release documentation:
- "Document our release process"
- "Create release-strategy.md"
- "Write down our versioning approach"
Plan multi-repo releases:
- "How to coordinate releases across 5 repos?"
- "Should we align versions?"
- "What's the best RC workflow for us?"
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)

# 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

# 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)

# 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:

/sw-release:init - Analyze & recommend strategy
/sw-release:align - Align versions across repos
/sw-release:rc - Create release candidate
/sw-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.

release-strategy-advisor