zhongwei/gh-anton-abyzov-specweave-plugins-specweave-release
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 17:57:06 +08:00
commit a81cf788f6
14 changed files with 5537 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

505
commands/specweave-release-align.md Normal file
View File

@@ -0,0 +1,505 @@
---
name: specweave-release:align
description: Align versions across multiple repositories according to release strategy. Analyzes conventional commits to suggest version bumps, detects version conflicts, validates cross-repo compatibility, and executes version alignment (updates package.json, creates git tags, updates changelogs). Supports lockstep, independent, and umbrella versioning strategies.
---
# /specweave-release:align - Align Repository Versions
Align versions across multiple repositories according to your release strategy.
## What This Command Does
1. **Analyzes Current Versions**: Reads current version from each repository
2. **Analyzes Commits**: Uses conventional commits to suggest version bumps
3. **Detects Conflicts**: Identifies version incompatibilities across repos
4. **Suggests Bumps**: Recommends new versions based on changes
5. **Validates Compatibility**: Ensures new versions are compatible
6. **Executes Alignment**: Updates versions, creates tags, updates changelogs
## Usage
```bash
# Interactive alignment (prompts for confirmation)
/specweave-release:align
# Align specific repositories only
/specweave-release:align --repos frontend,backend
# Dry run (show what would change, don't execute)
/specweave-release:align --dry-run
# Force alignment (skip validation)
/specweave-release:align --force
# Align for specific strategy
/specweave-release:align --strategy lockstep
/specweave-release:align --strategy independent
/specweave-release:align --strategy umbrella
```
## Workflow
### Step 1: Analyze Current State
```markdown
Scanning repositories...
frontend:
Current: v4.2.0
Location: ~/projects/myapp/frontend
Git status: Clean ✓
backend:
Current: v2.8.0
Location: ~/projects/myapp/backend
Git status: Clean ✓
api-gateway:
Current: v3.1.0
Location: ~/projects/myapp/api-gateway
Git status: Uncommitted changes ✗
shared-lib:
Current: v1.5.0
Location: ~/projects/myapp/shared-lib
Git status: Clean ✓
Blockers:
❌ api-gateway has uncommitted changes
Action: Commit or stash changes before aligning
[Abort alignment]
```
### Step 2: Analyze Commits
```markdown
Analyzing commits since last release...
frontend (v4.2.0):
Commits since v4.2.0: 18
- Breaking changes: 1 (feat!: upgrade to React 18)
- Features: 4
- Bug fixes: 10
- Other: 3 (docs, chore)
Suggested: v5.0.0 (MAJOR)
Rationale: Breaking change detected
backend (v2.8.0):
Commits since v2.8.0: 12
- Breaking changes: 0
- Features: 3 (feat: add real-time notifications)
- Bug fixes: 7
- Other: 2
Suggested: v2.9.0 (MINOR)
Rationale: New features added
api-gateway (v3.1.0):
Commits since v3.1.0: 22
- Breaking changes: 2 (feat!: remove /v2 endpoints)
- Features: 5
- Bug fixes: 12
- Other: 3
Suggested: v4.0.0 (MAJOR)
Rationale: Breaking changes detected
shared-lib (v1.5.0):
Commits since v1.5.0: 3
- Breaking changes: 0
- Features: 0
- Bug fixes: 3
- Other: 0
Suggested: v1.5.1 (PATCH)
Rationale: Bug fixes only
```
### Step 3: Check Alignment Strategy
```markdown
Reading release strategy...
Location: .specweave/docs/internal/delivery/release-strategy.md
Strategy: Independent Versioning
- Each repository versions separately
- Only bump repos with changes
- Validate compatibility constraints
Applying strategy rules...
✓ frontend: Independent bump (v5.0.0)
✓ backend: Independent bump (v2.9.0)
✓ api-gateway: Independent bump (v4.0.0)
✓ shared-lib: Independent bump (v1.5.1)
```
### Step 4: Validate Compatibility
```markdown
Validating cross-repo compatibility...
Dependency Check 1: shared-lib versions
frontend package.json: "shared-lib": "^1.5.0"
Current shared-lib: v1.5.0
Proposed shared-lib: v1.5.1
Compatible? ✓ (within ^1.5.0 range)
Dependency Check 2: API versions
frontend API client: Expects /api/v3
api-gateway: Provides /api/v3, /api/v4 (removing /api/v2)
Compatible? ✓ (v3 still supported)
Dependency Check 3: Database schema
backend requires: Schema v12
Current production: Schema v12
Compatible? ✓
Overall: All compatibility checks passed ✓
```
### Step 5: Review and Confirm
```markdown
Proposed version alignment:
┌──────────────┬──────────┬──────────┬───────────────────────┐
│ Repository │ Current │ Proposed │ Reason │
├──────────────┼──────────┼──────────┼───────────────────────┤
│ frontend │ v4.2.0 │ v5.0.0 │ Breaking: React 18 │
│ backend │ v2.8.0 │ v2.9.0 │ Feature: Notifications│
│ api-gateway │ v3.1.0 │ v4.0.0 │ Breaking: Remove v2 │
│ shared-lib │ v1.5.0 │ v1.5.1 │ Bug fixes │
└──────────────┴──────────┴──────────┴───────────────────────┘
Breaking Changes Summary:
- frontend: React 16 → 18 (requires Node.js 18+)
- api-gateway: Removed /api/v2 endpoints (use /api/v3)
Actions to perform:
1. Update package.json versions
2. Create git tags
3. Update CHANGELOG.md files
4. Push tags to origin
? Proceed with alignment? [Yes / No / Edit]
```
### Step 6: Execute Alignment
```markdown
Executing version alignment...
frontend (v4.2.0 → v5.0.0):
✓ Updated package.json
✓ Generated CHANGELOG.md
✓ Created git tag v5.0.0
✓ Committed changes
✓ Pushed tag to origin
backend (v2.8.0 → v2.9.0):
✓ Updated package.json
✓ Generated CHANGELOG.md
✓ Created git tag v2.9.0
✓ Committed changes
✓ Pushed tag to origin
api-gateway (v3.1.0 → v4.0.0):
✓ Updated package.json
✓ Generated CHANGELOG.md
✓ Created git tag v4.0.0
✓ Committed changes
✓ Pushed tag to origin
shared-lib (v1.5.0 → v1.5.1):
✓ Updated package.json
✓ Generated CHANGELOG.md
✓ Created git tag v1.5.1
✓ Committed changes
✓ Pushed tag to origin
Version alignment complete! ✓
Next steps:
1. Create release increment: /specweave:increment "0080-product-v5-release"
2. Or trigger CI/CD: Git tags will trigger automated releases
3. Monitor: Check CI/CD pipelines for build/test/publish
```
## Alignment Strategies
### Lockstep Versioning
**All repos share same version**:
```markdown
Strategy: Lockstep
Current State:
- frontend: v2.5.0
- backend: v2.5.0
- api: v2.5.0
Analysis:
- frontend: Breaking change detected
- backend: Bug fix
- api: No changes
Alignment Rule: Use highest bump type (MAJOR)
Proposed:
- frontend: v3.0.0 (breaking)
- backend: v3.0.0 (forced, no changes)
- api: v3.0.0 (forced, no changes)
⚠️ Warning: backend and api have no changes but must bump for lockstep
```
### Independent Versioning
**Each repo versions separately**:
```markdown
Strategy: Independent
Current State:
- frontend: v4.2.0
- backend: v2.8.0
- api: v3.1.0
Analysis:
- frontend: Breaking change
- backend: New feature
- api: Bug fix
Alignment Rule: Bump each independently
Proposed:
- frontend: v5.0.0 (major)
- backend: v2.9.0 (minor)
- api: v3.1.1 (patch)
✓ Each repo versions at its own pace
```
### Umbrella Versioning
**Product version spans service versions**:
```markdown
Strategy: Umbrella
Current Product: v4.0.0
- frontend: v4.2.0
- backend: v2.8.0
- api: v3.1.0
Analysis:
- frontend: Breaking change (React 18)
- backend: New feature (notifications)
- api: Breaking change (remove v2)
Alignment Rule: Product major bump (any service has breaking)
Proposed Product: v5.0.0
- frontend: v5.0.0
- backend: v2.9.0
- api: v4.0.0
Updated Version Matrix:
Product v5.0.0 = {frontend: v5.0.0, backend: v2.9.0, api: v4.0.0}
```
## Version Conflict Detection
**Example: Dependency Version Mismatch**
```markdown
Validating compatibility...
❌ Conflict detected!
service-a:
package.json: "shared-lib": "^2.0.0"
Requires: shared-lib v2.x
service-b:
package.json: "shared-lib": "^1.5.0"
Requires: shared-lib v1.x
Current:
shared-lib: v2.0.0
Problem:
service-b is incompatible with shared-lib v2.0.0
(requires v1.x, but v2.0.0 has breaking changes)
Resolution Options:
1. Update service-b to use "shared-lib": "^2.0.0"
2. Test service-b with shared-lib v2.0.0
3. Fix any breaking changes
4. Then retry alignment
[Abort alignment]
```
## Conventional Commits
**This command relies on conventional commits**:
```bash
# Breaking change (MAJOR bump)
feat!: upgrade to React 18
BREAKING CHANGE: Requires Node.js 18+
# Feature (MINOR bump)
feat: add real-time notifications
feat(api): add WebSocket support
# Bug fix (PATCH bump)
fix: prevent null pointer in user service
fix(ui): correct button alignment
# No version bump
docs: update README
chore: upgrade dependencies
style: format code
refactor: extract helper function
test: add unit tests
```
**Commit Analysis**:
- Scans commits: `git log <last-tag>..HEAD`
- Parses commit messages
- Categorizes: breaking / feature / fix / other
- Suggests bump: MAJOR / MINOR / PATCH
## Integration with Release Strategy
**Reads strategy from**:
```
.specweave/docs/internal/delivery/release-strategy.md
```
**Uses strategy to**:
- Determine alignment approach (lockstep/independent/umbrella)
- Apply version bump rules
- Validate compatibility constraints
- Generate appropriate documentation
## Multi-Project Support
**For multi-project setups**:
```bash
# Align versions within a specific project
/specweave-release:align --project frontend-team
# Align across all projects
/specweave-release:align --all-projects
# Align specific project's repos only
/specweave-release:align --project backend-team --repos api,database
```
## Best Practices
**Before Aligning**:
- Ensure all repos are clean (no uncommitted changes)
- Pull latest changes from origin
- Review conventional commits
- Check release strategy is up-to-date
**During Alignment**:
- Use dry-run first to preview changes
- Review version bumps carefully
- Validate compatibility thoroughly
- Document breaking changes
**After Alignment**:
- Monitor CI/CD pipelines
- Create release increment
- Update living docs
- Notify team of new versions
## Example Interactions
### Lockstep Alignment
```bash
User: /specweave-release:align --strategy lockstep
Release Manager: Analyzing repositories with lockstep strategy...
Current State:
- service-a: v2.5.0
- service-b: v2.5.0
- service-c: v2.5.0
Commit Analysis:
- service-a: Breaking change detected
- service-b: Bug fix only
- service-c: No changes
Lockstep Rule: All repos must bump together (use highest: MAJOR)
Proposed:
- service-a: v3.0.0 (breaking change)
- service-b: v3.0.0 (forced, for alignment)
- service-c: v3.0.0 (forced, for alignment)
⚠️ Note: service-b and service-c have no changes but must bump for lockstep
? Proceed? [Yes / No]
```
### Independent Alignment with Conflict
```bash
User: /specweave-release:align
Release Manager: Analyzing repositories with independent strategy...
...
Validating compatibility...
❌ Conflict detected!
frontend requires: api-client v4.0.0
api-gateway provides: v3.1.0 (proposed bump to v3.1.1)
Problem: Frontend expects v4 API, but gateway hasn't released v4 yet
Resolution:
Option 1: Release api-gateway v4.0.0 first (breaking changes)
Option 2: Update frontend to use api-client v3.x (delay v4 features)
Option 3: Coordinate release (release gateway v4 with frontend v5)
Recommendation: Option 3 (coordinated release)
Would you like me to create a coordinated release increment?
```
## Related Commands
- `/specweave-release:init` - Initialize release strategy
- `/specweave-release:rc` - Create release candidates for aligned versions
- `/specweave-release:coordinate` - Plan coordinated multi-repo release
- `/specweave-release:publish` - Execute release after alignment
## Dependencies
**Required**:
- Git (version control)
- Release strategy document
**Optional**:
- NPM (`npm version`) - Automated versioning
- Conventional Commits - Commit analysis
- Semantic Release - Automation integration
---
**Use this command** to ensure version consistency across repositories while following your project's release strategy.

430
commands/specweave-release-init.md Normal file
View File

@@ -0,0 +1,430 @@
---
name: specweave-release:init
description: Initialize or analyze release strategy for the project. For new projects, recommends optimal release approach based on architecture, team size, and deployment frequency. For brownfield projects, detects existing release patterns from git history, CI/CD configs, and package managers, then documents the strategy. Creates release-strategy.md in living docs with comprehensive release process documentation.
---
# /specweave-release:init - Initialize Release Strategy
Initialize or analyze the release strategy for your project.
## What This Command Does
**For New Projects (Greenfield)**:
1. Analyzes project architecture (single-repo, multi-repo, monorepo)
2. Asks about team size, deployment frequency, coupling between services
3. Recommends optimal release strategy (lockstep, independent, umbrella)
4. Creates `.specweave/docs/internal/delivery/release-strategy.md`
5. Suggests CI/CD automation opportunities
**For Existing Projects (Brownfield)**:
1. Scans git history for version tags and patterns
2. Analyzes CI/CD configurations (.github/workflows/, .gitlab-ci.yml, etc.)
3. Checks package manager files (package.json, setup.py, pom.xml, etc.)
4. Detects monorepo tools (Lerna, Nx, Turborepo, Changesets)
5. Documents existing strategy in living docs
6. Suggests improvements and best practices
## Usage
```bash
# Interactive analysis and recommendation
/specweave-release:init
# Force re-analysis (overwrite existing strategy)
/specweave-release:init --force
# Quick analysis (no interactive prompts, use defaults)
/specweave-release:init --quick
```
## Workflow
### Greenfield Projects
```markdown
1. Project Structure Analysis
→ Detect repositories (scan for .git/)
→ Count services/packages
→ Identify architecture pattern
2. Interactive Questionnaire
? How many repositories? [1 / 2-5 / 5+]
? Team structure? [One team / Per-service teams / Mixed]
? Deployment frequency? [Daily / Weekly / Monthly / Ad-hoc]
? Coupling between services? [Tight / Moderate / Loose]
? Planning to use RC workflow? [Yes / No / For major versions only]
3. Strategy Recommendation
Based on your answers:
→ Recommended: Umbrella Versioning
→ Rationale: Medium-sized team, weekly releases, moderate coupling
→ RC workflow: For major versions (breaking changes)
4. Documentation Creation
→ Create: .specweave/docs/internal/delivery/release-strategy.md
→ Include: Versioning approach, RC workflow, CI/CD integration
→ Add: Release checklist, rollback procedures
5. Next Steps Guidance
→ Set up CI/CD automation (GitHub Actions template provided)
→ Configure semantic-release or Changesets
→ Define release waves (dependency order)
→ Create first release increment: /specweave:increment "0001-v1-release"
```
### Brownfield Projects
```markdown
1. Git History Scan
→ Analyzing tags: git tag --list
→ Found: 45 tags (v1.0.0, v1.1.0, ..., v3.2.0)
→ Pattern: Semantic versioning ✓
→ RC usage: Detected for major versions (v2.0.0-rc.1, v3.0.0-rc.1)
→ Cadence: ~1 release per week
2. CI/CD Detection
→ Found: .github/workflows/release.yml
→ Tool: semantic-release ✓
→ Triggers: Push to main with version tags
→ Actions: Build → Test → Publish to NPM → Create GitHub Release
3. Package Manager Analysis
→ Found: package.json (NPM project)
→ Current version: 3.2.0 (matches git tag ✓)
→ Scripts: npm version, npm publish ✓
→ Dependencies: 25 packages
4. Monorepo Detection (if applicable)
→ Found: lerna.json
→ Mode: independent (packages version separately)
→ Packages: 12
→ Tool: Lerna v7.4.0
5. Strategy Classification
Current Strategy:
→ Type: Monorepo with independent versioning
→ Tool: Lerna + semantic-release
→ RC: For major versions only
→ Frequency: Weekly
→ Automation: High (GitHub Actions)
6. Documentation Creation
→ Create: .specweave/docs/internal/delivery/release-strategy.md
→ Document: Existing process, tools, patterns
→ Add: Version matrix (for umbrella releases if applicable)
7. Improvement Suggestions
Recommendations:
✓ Current strategy is solid
→ Consider: Changesets for better changelog management
→ Consider: Umbrella versioning for product milestones
→ Add: Version matrix documentation (.specweave/docs/internal/delivery/version-matrix.md)
→ Enhance: RC workflow with canary deployments
```
## What Gets Created
**File**: `.specweave/docs/internal/delivery/release-strategy.md`
**Structure**:
```markdown
# Release Strategy: {Project Name}
## Overview
- Repository Type: Single-repo / Multi-repo / Monorepo
- Versioning Strategy: Lockstep / Independent / Umbrella
- RC Workflow: Yes / No / Major versions only
- Release Frequency: Daily / Weekly / Monthly
- Automation Level: Manual / Semi-automated / Fully automated
## Repositories
| Repo | Purpose | Current Version | Frequency |
|------|---------|----------------|-----------|
| frontend | User interface | v5.2.0 | Weekly |
| backend | API server | v3.8.0 | Bi-weekly |
| shared-lib | Shared utilities | v2.1.0 | Monthly |
## Version Alignment
- **Major versions**: Coordinated (breaking changes affect all)
- **Minor versions**: Independent (services evolve separately)
- **Patch versions**: Independent (bug fixes as needed)
## Release Candidate Workflow
1. Create RC tag: v{major}.{minor}.{patch}-rc.1
2. Deploy to staging environment
3. Run validation tests (unit + integration + E2E + performance)
4. Testing phase: 1-2 weeks
5. Bug fixes → Iterate to rc.2, rc.3, ...
6. All tests pass → Promote to production: v{major}.{minor}.{patch}
7. Gradual rollout: 10% → 25% → 50% → 100%
## CI/CD Integration
- **Tool**: GitHub Actions / GitLab CI / Jenkins / CircleCI
- **Trigger**: Push tags matching v*.*.* pattern
- **Workflow**:
1. Build: Compile, bundle, create artifacts
2. Test: Run all automated tests
3. Publish: NPM / PyPI / Docker Registry / Maven Central
4. Release: Create GitHub/GitLab release with changelog
5. Deploy: Push to staging/production (Kubernetes/AWS/etc.)
## Changelog Management
- **Tool**: Conventional Changelog / Keep a Changelog / semantic-release
- **Format**: CHANGELOG.md (root or per-package)
- **Automation**: Generate from conventional commits
- **Manual curation**: For major releases (highlight key features)
## Hotfix Strategy
- **Branch**: hotfix/* from production tag
- **Version**: Patch bump (v1.0.1)
- **Process**:
1. Branch from production tag (v1.0.0)
2. Fix bug
3. Fast-track testing (critical tests only)
4. Tag hotfix version (v1.0.1)
5. Deploy immediately
6. Merge back to main branch
## Release Checklist
### Pre-Release
- [ ] All tests passing (unit + integration + E2E)
- [ ] Changelog updated
- [ ] Version bumped (package.json, etc.)
- [ ] Breaking changes documented
- [ ] Migration guide written (if applicable)
- [ ] Performance benchmarks met
- [ ] Security scan clean
### Release Execution
- [ ] Git tag created
- [ ] CI/CD pipeline triggered
- [ ] Build successful
- [ ] Tests passed
- [ ] Package published (NPM/PyPI/Docker)
- [ ] GitHub release created
- [ ] Deployment successful
### Post-Release
- [ ] Smoke tests passed
- [ ] Monitoring for 1+ hour
- [ ] No increase in error rate
- [ ] Performance stable
- [ ] Documentation updated
- [ ] Living docs synced
- [ ] Stakeholders notified
## Rollback Procedures
- **Detection**: Error rate > 5%, latency > 2x baseline, critical bugs
- **Execution**:
1. Kubernetes: kubectl rollout undo
2. Docker: Deploy previous image tag
3. Verify: Health checks passing
4. Monitor: Error rate back to baseline
- **Communication**: Notify team, update incident channel
- **Follow-up**: Root cause analysis, postmortem
## DORA Metrics
- **Deployment Frequency**: {weekly / daily / monthly}
- **Lead Time for Changes**: {target: <1 day}
- **Mean Time to Recovery (MTTR)**: {target: <1 hour}
- **Change Failure Rate**: {target: <5%}
## Decision History
- 2025-01-15: Adopted umbrella versioning (ADR-023)
- 2025-02-01: Introduced RC workflow for majors (ADR-025)
- 2025-03-10: Migrated to semantic-release (ADR-028)
## Related Documentation
- Version Matrix: .specweave/docs/internal/delivery/version-matrix.md
- ADRs: .specweave/docs/internal/architecture/adr/
- CI/CD Configs: .github/workflows/release.yml
```
## Multi-Project Support
**For multi-project setups**, the strategy can be project-specific:
```
.specweave/docs/internal/projects/frontend/delivery/release-strategy.md
.specweave/docs/internal/projects/backend/delivery/release-strategy.md
.specweave/docs/internal/projects/mobile/delivery/release-strategy.md
```
Or cross-project if all projects share the same strategy:
```
.specweave/docs/internal/delivery/release-strategy.md
```
## Integration with SpecWeave
**After initialization**:
1. **Create first release increment**:
```bash
/specweave:increment "0001-v1-0-0-release"
```
2. **Align versions** (for multi-repo):
```bash
/specweave-release:align
```
3. **Create RC** (for major versions):
```bash
/specweave-release:rc create 1.0.0
```
4. **Execute release**:
```bash
/specweave:do
```
5. **Complete release**:
```bash
/specweave:done 0001
```
## Brownfield Integration
**This command integrates with brownfield-analyzer skill**:
```bash
# If brownfield-analyzer already ran:
# → Uses detected patterns
# → Validates findings
# → Enhances documentation
# If not yet analyzed:
# → Triggers brownfield-analyzer
# → Detects release patterns
# → Documents strategy
```
## Best Practices
**Documentation**:
- Keep release-strategy.md up-to-date
- Document lessons learned after each release
- Link to ADRs for major decisions
- Update when process changes
**Versioning**:
- Always follow semantic versioning
- Use RC for major versions
- Document breaking changes clearly
- Maintain version matrix for umbrella releases
**Automation**:
- Automate as much as possible (CI/CD)
- Use conventional commits (enables automated changelogs)
- Validate releases in CI/CD pipeline
- Monitor releases automatically
**Communication**:
- Notify team before releases
- Document rollback procedures
- Track DORA metrics
- Share postmortems
## Example Interactions
### Greenfield Project
```bash
User: /specweave-release:init
Release Manager: I'll help you set up your release strategy.
1. Analyzing project structure...
✓ Detected: Single repository
✓ Package: myapp (NPM)
✓ No monorepo tools detected
2. Let me ask a few questions:
? Deployment frequency? [Weekly]
? Planning to use RC workflow? [For major versions only]
? CI/CD platform? [GitHub Actions]
3. Recommendation:
→ Strategy: Simple Semantic Versioning
→ RC: For major versions (breaking changes)
→ Automation: GitHub Actions + semantic-release
4. Creating documentation...
✓ Created: .specweave/docs/internal/delivery/release-strategy.md
5. Next steps:
- Set up GitHub Actions workflow
- Configure semantic-release
- Create first release: /specweave:increment "0001-v1-0-0-release"
Would you like me to create a GitHub Actions workflow template?
```
### Brownfield Project
```bash
User: /specweave-release:init
Release Manager: I'll analyze your existing release process.
1. Scanning git history...
✓ Found 45 tags (v1.0.0 to v3.2.0)
✓ Pattern: Semantic versioning
✓ RC usage: For major versions (v2.0.0-rc.1, v3.0.0-rc.1)
2. Analyzing CI/CD...
✓ Found: .github/workflows/release.yml
✓ Tool: semantic-release
✓ Automation: High
3. Checking package managers...
✓ Found: lerna.json (12 packages)
✓ Mode: independent versioning
✓ Tool: Lerna v7.4.0
4. Current Strategy Classification:
→ Type: Monorepo with independent versioning
→ RC: For major versions
→ Frequency: Weekly
→ Automation: High
5. Creating documentation...
✓ Created: .specweave/docs/internal/delivery/release-strategy.md
✓ Documented: Existing process
✓ Added: Improvement recommendations
6. Recommendations:
✓ Current strategy is solid
→ Consider: Umbrella versioning for product milestones
→ Add: Version matrix documentation
→ Enhance: RC workflow with canary deployments
Would you like me to create version matrix documentation?
```
## Related Commands
- `/specweave-release:align` - Align versions across repos
- `/specweave-release:rc` - Manage release candidates
- `/specweave-release:coordinate` - Plan multi-repo releases
- `/specweave-release:publish` - Execute releases
- `/specweave:increment` - Create release increment
## Dependencies
**Required**:
- Git (version control)
- SpecWeave core (living docs)
**Optional**:
- GitHub CLI (`gh`) - GitHub integration
- NPM (`npm`) - NPM projects
- Lerna (`lerna`) - Monorepo detection
- Semantic Release - Automation detection
---
**Use this command** as the first step in establishing a clear, documented, repeatable release process for your project.

499
commands/specweave-release-npm.md Normal file
View File

@@ -0,0 +1,499 @@
---
name: specweave-release:npm
description: Bump patch version, create git tag, and trigger npm publish via GitHub Actions. Automates the complete release workflow with pre-flight checks, version bumping, tag creation, and GitHub Actions triggering. Use --only flag for quick local release (bumps version, builds, publishes to npm directly - NO git push, NO pipeline). Add --push to --only for complete local release with git sync. Use --only --local for FASTEST local-only version bump (no npm publish, no git, just version increment for local testing).
---
# /specweave-release:npm - NPM Release Automation
You are the NPM Release Assistant. Your job is to automate the patch version release process.
## Command Modes
| Command | Flow | Use Case |
|---------|------|----------|
| `/specweave-release:npm` | Bump → Push → **CI publishes** | Standard release (CI handles npm) |
| `/specweave-release:npm --only` | Bump → Build → **Publish locally** → NO push | Quick local release, push later |
| `/specweave-release:npm --only --push` | Bump → Build → **Publish locally** → Push | Complete local release + git sync |
| `/specweave-release:npm --only --local` | **Bump ONLY** → NO build, NO publish, NO git | FASTEST: Local testing only |
## Detecting Mode
Check flags in the command invocation:
```
--only --local → Version bump ONLY (no build, no publish, no git) - FASTEST
--only --push → Direct publish + push to git after
--only → Direct publish to npm (bypass CI)
(no flags) → Default: push to git, CI publishes
```
**Flag Detection Order:**
1. Check for `--only` flag
2. If `--only` present, check for `--local` flag → LOCAL MODE (fastest)
3. If `--only` present, check for `--push` flag → DIRECT MODE + PUSH
4. If `--only` only → DIRECT MODE
5. No flags → DEFAULT MODE
**If `--only --local`**: Use LOCAL MODE (section "Local Mode Workflow") - FASTEST!
**If `--only --push`**: Use DIRECT MODE WITH PUSH (section "Direct Mode + Push Workflow")
**If `--only` only**: Use DIRECT MODE (section "Direct Mode Workflow")
**If no flags**: Use DEFAULT MODE (continue with steps below)
## Your Task
Execute the following steps in order:
### 1. Pre-flight Checks
```bash
# Verify we're on develop branch
git rev-parse --abbrev-ref HEAD
# Check for uncommitted changes
git status --porcelain
# Verify current version
node -p "require('./package.json').version"
```
**STOP if**:
- Not on `develop` branch (ask user to switch)
- Uncommitted changes exist (ask user to commit first)
### 2. Bump Patch Version
```bash
# This creates commit + tag automatically
npm version patch -m "chore: bump version to %s"
```
**What this does**:
- Updates `package.json` and `package-lock.json`
- Creates git commit with message "chore: bump version to X.Y.Z"
- Creates git tag `vX.Y.Z`
### 3. Extract New Version
```bash
# Get the new version
node -p "require('./package.json').version"
```
### 4. Push to GitHub
```bash
# Push commit and tag to trigger GitHub Actions
git push origin develop --follow-tags
```
**What happens next**:
- GitHub Actions workflow detects the tag
- Runs tests
- Publishes to npm
- Creates GitHub release
### 5. Report Results
Show the user:
```markdown
✅ Release initiated successfully!
📦 **Version**: vX.Y.Z
🔗 **Tag**: https://github.com/anton-abyzov/specweave/releases/tag/vX.Y.Z
⏳ **GitHub Actions**: https://github.com/anton-abyzov/specweave/actions
**Next steps**:
1. Monitor GitHub Actions workflow (1-2 minutes)
2. Verify npm publish: https://www.npmjs.com/package/specweave
3. Check GitHub release notes
**Note**: GitHub Actions will automatically:
- Build and test the package
- Publish to npm
- Create GitHub release with CHANGELOG notes
```
## Error Handling
**If `npm version` fails**:
- Check if version already exists
- Verify package.json is valid
- Ask user to manually fix and retry
**If `git push` fails**:
- Check network connection
- Verify git credentials
- Check branch protection rules
## Safety Rules
- ✅ ONLY bump patch version (never minor/major without confirmation)
- ✅ ALWAYS check for uncommitted changes first
- ✅ ALWAYS verify on develop branch
- ✅ NEVER force push
- ✅ NEVER skip pre-flight checks
## Success Criteria (Default Mode)
✅ Version bumped in package.json
✅ Git commit created
✅ Git tag created
✅ Changes pushed to GitHub
✅ GitHub Actions workflow triggered
---
## DIRECT MODE WORKFLOW (--only flag)
Use this workflow when `--only` flag is detected. This publishes directly to npm WITHOUT git push or GitHub Actions.
### 1. Pre-flight Checks (Same as Default)
```bash
# Verify we're on develop branch
git rev-parse --abbrev-ref HEAD
# Check for uncommitted changes
git status --porcelain
# Verify current version
node -p "require('./package.json').version"
```
**STOP if**:
- Not on `develop` branch (ask user to switch)
- Uncommitted changes exist (ask user to commit first)
### 2. Bump Patch Version (Same as Default)
```bash
# This creates commit + tag automatically
npm version patch -m "chore: bump version to %s"
```
**What this does**:
- Updates `package.json` and `package-lock.json`
- Creates git commit with message "chore: bump version to X.Y.Z"
- Creates git tag `vX.Y.Z`
### 3. Extract New Version
```bash
# Get the new version
node -p "require('./package.json').version"
```
### 4. Build Package
```bash
# Build the package before publishing
npm run rebuild
```
**Critical**: Must rebuild to ensure dist/ is up-to-date before publishing.
### 5. Publish to NPM Directly
```bash
# Publish directly to npm (bypasses GitHub Actions)
npm publish
```
**What this does**:
- Builds package tarball
- Publishes to npm registry immediately
- No GitHub Actions involvement
### 6. Report Results (Direct Mode)
Show the user:
```markdown
✅ **Published directly to npm!**
📦 **Version**: vX.Y.Z
🔗 **NPM**: https://www.npmjs.com/package/specweave
🏷️ **Git Tag**: vX.Y.Z (local only)
**What happened**:
- ✅ Version bumped and committed locally
- ✅ Git tag created locally
- ✅ Package built (npm run rebuild)
- ✅ Published to npm directly
- ⏸️ Git NOT pushed (use `git push origin develop --follow-tags` later if needed)
**Verify**:
- Check npm: https://www.npmjs.com/package/specweave
- Verify version: `npm view specweave version`
- Install globally: `npm install -g specweave@X.Y.Z`
**Note**: Local release only. Push to GitHub manually when ready:
`git push origin develop --follow-tags`
```
## Direct Mode Safety Rules
- ✅ ALWAYS rebuild before publishing (`npm run rebuild`)
- ✅ Use `--only` for emergency/quick releases or local testing
- ✅ Default mode (GitHub Actions) is preferred for regular releases
- ✅ Direct mode gives immediate feedback (no CI wait time)
- ⚠️ Remember to push git changes later to sync GitHub
## Success Criteria (Direct Mode)
✅ Version bumped in package.json
✅ Git commit created locally
✅ Git tag created locally
✅ Package rebuilt
✅ Published to npm directly
⏸️ Git NOT pushed (manual sync later)
---
## DIRECT MODE + PUSH WORKFLOW (--only --push flags)
Use this workflow when BOTH `--only` AND `--push` flags are detected. This is the **complete local release** - publishes to npm directly AND pushes to git.
**Use case**: You want full control - publish immediately, then sync git. No CI involvement in npm publish.
### 1. Pre-flight Checks
```bash
# Verify we're on develop branch
git rev-parse --abbrev-ref HEAD
# Check for uncommitted changes
git status --porcelain
# Verify current version
node -p "require('./package.json').version"
```
**STOP if**:
- Not on `develop` branch (ask user to switch)
**If uncommitted changes exist → AUTO-COMMIT FIRST (Step 1b)**
### 1b. Auto-Commit Uncommitted Changes (if any)
When `--only --push` is used, uncommitted changes should be committed automatically before version bump.
**Algorithm to generate commit message:**
1. Run `git status --porcelain` and categorize files:
- `src/**` → code changes
- `*.md`, `docs/` → documentation
- `.specweave/docs/internal/**` → internal docs
- `plugins/**` → plugin changes
- `tests/**`, `*.test.ts` → test changes
- `package*.json`, `*.config.*` → config/deps
2. Determine primary category (most files) and action (add/update/remove):
- New files (`??`, `A`) → "add"
- Modified (`M`) → "update"
- Deleted (`D`) → "remove"
3. Generate concise message: `type: action description`
**Examples:**
- Many ADR renames + docs moves → `chore: reorganize internal docs structure`
- Plugin command updates → `feat(release): add --push flag to npm release`
- Mixed code + docs → `chore: update code and documentation`
**Execute auto-commit:**
```bash
git add -A
git commit -m "[generated message]"
```
Then continue with version bump.
### 2. Bump Patch Version
```bash
# This creates commit + tag automatically
npm version patch -m "chore: bump version to %s"
```
### 3. Extract New Version
```bash
# Get the new version
node -p "require('./package.json').version"
```
### 4. Build Package
```bash
# Build the package before publishing
npm run rebuild
```
**Critical**: Must rebuild to ensure dist/ is up-to-date before publishing.
### 5. Publish to NPM Directly
```bash
# Publish directly to npm (bypasses GitHub Actions)
npm publish
```
### 6. Push to Git (NEW!)
```bash
# Push commit and tag to sync with remote
git push origin develop --follow-tags
```
**What this does**:
- Syncs your version bump commit to GitHub
- Pushes the version tag (vX.Y.Z)
- Does NOT trigger CI npm publish (already published!)
### 7. Report Results (Direct Mode + Push)
Show the user:
```markdown
✅ **Complete local release!**
📦 **Version**: vX.Y.Z
🔗 **NPM**: https://www.npmjs.com/package/specweave
🏷️ **Git Tag**: https://github.com/anton-abyzov/specweave/releases/tag/vX.Y.Z
**What happened**:
- ✅ Version bumped and committed
- ✅ Git tag created
- ✅ Package built (npm run rebuild)
- ✅ Published to npm directly
- ✅ Pushed to GitHub (commit + tag)
**Verify**:
- NPM: https://www.npmjs.com/package/specweave
- Version: `npm view specweave version`
- GitHub: Check releases page
**Note**: This was a direct publish. GitHub Actions will NOT republish
(the tag already exists, CI skips existing versions).
```
## Direct Mode + Push Safety Rules
- ✅ ALWAYS rebuild before publishing
- ✅ Publishes FIRST, then pushes (ensures npm has the version)
- ✅ If push fails, npm already has the release (safe state)
- ✅ CI will skip publishing for this version (tag already exists)
- ⚠️ Use when you need immediate npm availability + git sync
## Success Criteria (Direct Mode + Push)
✅ Version bumped in package.json
✅ Git commit created
✅ Git tag created
✅ Package rebuilt
✅ Published to npm directly
✅ Pushed to GitHub (commit + tag synced)
---
## Quick Reference
```bash
# Standard release (CI handles npm publish)
/specweave-release:npm
# Quick local publish, sync git later
/specweave-release:npm --only
# Complete local release (publish + push)
/specweave-release:npm --only --push
# FASTEST: Version bump only (no publish, no git, no build)
/specweave-release:npm --only --local
```
| Scenario | Command | NPM Published By | Git Pushed |
|----------|---------|------------------|------------|
| Normal release | (no flags) | GitHub Actions | ✅ Yes |
| Quick local, push later | `--only` | You (local) | ❌ No |
| Complete local release | `--only --push` | You (local) | ✅ Yes |
| **FASTEST local test** | `--only --local` | ❌ None | ❌ No |
---
## LOCAL MODE WORKFLOW (--only --local flags) - FASTEST!
Use this workflow when BOTH `--only` AND `--local` flags are detected. This is the **fastest possible** version bump - NO npm publish, NO git operations, NO build. Just increment the version number for local testing.
**Use case**: You need to quickly test a new version locally without publishing anywhere. Perfect for:
- Testing version-dependent features
- Local development iterations
- Quick version bumps before a real release
### 1. Minimal Pre-flight Check
```bash
# Just verify current version (no git checks needed!)
node -p "require('./package.json').version"
```
**NO git checks** - we're not committing or pushing anything!
### 2. Bump Version (NO git commit, NO tag)
```bash
# Bump version WITHOUT creating git commit or tag
npm version patch --no-git-tag-version
```
**What this does**:
- Updates `package.json` version ONLY
- Updates `package-lock.json` version ONLY
- NO git commit created
- NO git tag created
- INSTANT (< 1 second)
### 3. Report Results (Local Mode)
Show the user:
```markdown
⚡ **FAST local version bump!**
📦 **Version**: X.Y.Z → X.Y.(Z+1)
**What happened**:
- ✅ package.json version bumped
- ✅ package-lock.json updated
- ⏭️ NO git commit (use `git add . && git commit` later)
- ⏭️ NO git tag (use `git tag vX.Y.Z` later)
- ⏭️ NO npm publish (use `npm publish` later)
- ⏭️ NO build (use `npm run rebuild` later)
**Next steps when ready to release**:
1. Build: `npm run rebuild`
2. Test: `npm test`
3. Commit: `git add . && git commit -m "chore: bump version to X.Y.Z"`
4. Tag: `git tag vX.Y.Z`
5. Publish: `npm publish`
6. Push: `git push origin develop --follow-tags`
**Or use**: `/specweave-release:npm --only --push` for full release
```
## Local Mode Safety Rules
- ✅ FASTEST possible - single npm command
- ✅ NO network operations (no npm publish, no git push)
- ✅ NO disk-heavy operations (no build)
- ✅ Safe to run multiple times (just increments version)
- ⚠️ Remember: version is NOT published or committed!
- ⚠️ Run `npm run rebuild` before testing locally
## Success Criteria (Local Mode)
✅ Version bumped in package.json
✅ Version bumped in package-lock.json
⏭️ NO git commit
⏭️ NO git tag
⏭️ NO npm publish
⏭️ NO build
**Time**: < 1 second

439
commands/specweave-release-platform.md Normal file
View File

@@ -0,0 +1,439 @@
---
name: specweave-release:platform
description: "Coordinate multi-repo platform releases with synchronized versioning, RC workflow, and GitFlow integration. Usage: /specweave-release:platform create|promote|status"
---
# Platform Release Coordination
**Purpose**: Orchestrate releases across multiple repositories as a unified platform version.
**When to Use**: Multi-repo architectures where services must release together (umbrella versioning).
---
## Commands
### Create Platform RC
```bash
/specweave-release:platform create <platform-version>
```
**Example**:
```bash
/specweave-release:platform create v3.0.0
```
**What it does**:
1. Validates all repos have clean working directories
2. Creates `release/v*` branches in all repos (GitFlow)
3. Aligns versions across repos (using semantic versioning)
4. Tags RC.1 in all repos: `v5.0.0-rc.1`, `v2.9.0-rc.1`, etc.
5. Updates platform manifest: `.specweave/platform-releases.json`
6. Creates version matrix: `.specweave/docs/internal/delivery/version-matrix.md`
**Output**:
```
🚀 Creating Platform Release: v3.0.0
Step 1: Validating repositories...
✓ frontend: Clean (current: v4.2.0)
✓ backend: Clean (current: v2.8.0)
✓ api-gateway: Clean (current: v3.1.0)
Step 2: Analyzing changes...
📊 frontend: 12 commits (3 breaking, 5 features, 4 fixes) → Suggest v5.0.0
📊 backend: 8 commits (0 breaking, 7 features, 1 fix) → Suggest v2.9.0
📊 api-gateway: 15 commits (2 breaking, 8 features, 5 fixes) → Suggest v4.0.0
Step 3: Creating release branches...
✓ frontend: release/v5.0.0
✓ backend: release/v2.9.0
✓ api-gateway: release/v4.0.0
Step 4: Tagging RC.1...
✓ frontend: v5.0.0-rc.1
✓ backend: v2.9.0-rc.1
✓ api-gateway: v4.0.0-rc.1
Step 5: Updating platform manifest...
✓ Created .specweave/platform-releases.json
Step 6: Updating version matrix...
✓ Created .specweave/docs/internal/delivery/version-matrix.md
✅ Platform v3.0.0-rc.1 created!
Next steps:
1. Deploy to staging
2. Run E2E tests
3. If tests pass: /specweave-release:platform promote v3.0.0-rc.1
4. If tests fail: /specweave-release:platform iterate v3.0.0-rc.1
```
---
### Iterate Platform RC
```bash
/specweave-release:platform iterate <platform-rc-version>
```
**Example**:
```bash
/specweave-release:platform iterate v3.0.0-rc.1
```
**What it does**:
1. Identifies which repos need fixes
2. Bumps RC number (rc.1 → rc.2)
3. Tags new RC in affected repos only
4. Updates platform manifest
**Output**:
```
🔄 Iterating Platform RC: v3.0.0-rc.1
Which repos need fixes?
[x] frontend
[ ] backend (no changes needed)
[x] api-gateway
Creating RC.2 for changed repos:
✓ frontend: v5.0.0-rc.2
✓ api-gateway: v4.0.0-rc.2
ℹ️ backend: v2.9.0-rc.1 (unchanged)
✅ Platform v3.0.0-rc.2 created!
```
---
### Promote Platform RC to Production
```bash
/specweave-release:platform promote <platform-rc-version>
```
**Example**:
```bash
/specweave-release:platform promote v3.0.0-rc.3
```
**What it does**:
1. Validates all RCs passed tests
2. Merges release branches to main (GitFlow)
3. Tags final versions (removes -rc.N suffix)
4. Merges main back to develop (GitFlow)
5. Deletes release branches (optional)
6. Updates platform manifest with "released" status
7. Updates version matrix
8. Tracks DORA metrics
**Pre-Flight Checklist**:
- ✅ All E2E tests passing
- ✅ Performance benchmarks met
- ✅ Security scan clean
- ✅ Stakeholder approval received
- ✅ Canary deployment successful (if applicable)
**Output**:
```
🎉 Promoting Platform RC to Production: v3.0.0-rc.3
Pre-Flight Checks:
✓ All repos on latest RC
✓ Tests passing: frontend ✅, backend ✅, api-gateway ✅
✓ No blocking issues
Step 1: Merging to main...
✓ frontend: release/v5.0.0 → main
✓ backend: release/v2.9.0 → main
✓ api-gateway: release/v4.0.0 → main
Step 2: Tagging final versions...
✓ frontend: v5.0.0
✓ backend: v2.9.0
✓ api-gateway: v4.0.0
Step 3: Merging back to develop...
✓ frontend: main → develop
✓ backend: main → develop
✓ api-gateway: main → develop
Step 4: Cleaning up release branches...
✓ frontend: Deleted release/v5.0.0
✓ backend: Deleted release/v2.9.0
✓ api-gateway: Deleted release/v4.0.0
Step 5: Updating platform manifest...
✓ Status: released
Step 6: Tracking DORA metrics...
✓ Deployment frequency updated
✓ Lead time calculated
✓ Dashboard updated
✅ Platform v3.0.0 released to production!
Platform Version Matrix:
Product: v3.0.0
├─ frontend: v5.0.0
├─ backend: v2.9.0
└─ api-gateway: v4.0.0
Deployment URLs:
- Production: https://app.example.com
- Docs: .specweave/docs/internal/delivery/version-matrix.md
```
---
### Platform Release Status
```bash
/specweave-release:platform status [platform-version]
```
**Example**:
```bash
/specweave-release:platform status v3.0.0
```
**Output**:
```
📊 Platform Release Status: v3.0.0
Status: 🟡 In Progress (RC.2)
Service Versions:
✓ frontend: v5.0.0-rc.2 (from v4.2.0)
✓ backend: v2.9.0-rc.1 (from v2.8.0)
✓ api-gateway: v4.0.0-rc.2 (from v3.1.0)
RC History:
- v3.0.0-rc.1: Created 2025-11-11 10:00 UTC
- v3.0.0-rc.2: Created 2025-11-11 14:30 UTC (frontend, api-gateway fixed)
Tests:
✓ frontend: All passing
✓ backend: All passing
🔴 api-gateway: 2 E2E tests failing
Blockers:
- api-gateway: Auth flow broken (issue #145)
Next Steps:
1. Fix api-gateway auth flow
2. Create RC.3: /specweave-release:platform iterate v3.0.0-rc.2
3. Re-test
4. Promote: /specweave-release:platform promote v3.0.0-rc.3
```
---
## Platform Manifest Format
**Location**: `.specweave/platform-releases.json`
```json
{
"v3.0.0": {
"status": "rc",
"currentRC": "rc.2",
"created": "2025-11-11T10:00:00Z",
"services": {
"frontend": {
"version": "v5.0.0-rc.2",
"previousVersion": "v4.2.0",
"changeType": "major",
"releaseNotes": "Breaking changes: New auth API"
},
"backend": {
"version": "v2.9.0-rc.1",
"previousVersion": "v2.8.0",
"changeType": "minor",
"releaseNotes": "Added dark mode support"
},
"api-gateway": {
"version": "v4.0.0-rc.2",
"previousVersion": "v3.1.0",
"changeType": "major",
"releaseNotes": "Breaking changes: Removed legacy endpoints"
}
},
"rcHistory": [
{
"rc": "rc.1",
"created": "2025-11-11T10:00:00Z",
"services": {
"frontend": "v5.0.0-rc.1",
"backend": "v2.9.0-rc.1",
"api-gateway": "v4.0.0-rc.1"
}
},
{
"rc": "rc.2",
"created": "2025-11-11T14:30:00Z",
"services": {
"frontend": "v5.0.0-rc.2",
"backend": "v2.9.0-rc.1",
"api-gateway": "v4.0.0-rc.2"
},
"changes": ["frontend: Fixed auth bug", "api-gateway: Fixed CORS issue"]
}
]
}
}
```
---
## Version Matrix Document
**Location**: `.specweave/docs/internal/delivery/version-matrix.md`
**Content**:
```markdown
# Platform Version Matrix
**Last Updated**: 2025-11-11 15:00 UTC
## Current Production
**Platform Version**: v2.0.0
**Released**: 2025-10-15
| Service | Version | Changelog |
|---------|---------|-----------|
| frontend | v4.2.0 | Added user preferences |
| backend | v2.8.0 | Performance improvements |
| api-gateway | v3.1.0 | Rate limiting updates |
---
## In Progress
**Platform Version**: v3.0.0-rc.2
**Status**: Testing
| Service | RC Version | Change Type | Release Notes |
|---------|------------|-------------|---------------|
| frontend | v5.0.0-rc.2 | MAJOR | Breaking: New auth API |
| backend | v2.9.0-rc.1 | MINOR | Dark mode support |
| api-gateway | v4.0.0-rc.2 | MAJOR | Breaking: Removed legacy endpoints |
**Blockers**: api-gateway auth flow (issue #145)
---
## Release History
### v2.0.0 (2025-10-15)
- frontend: v4.2.0
- backend: v2.8.0
- api-gateway: v3.1.0
### v1.5.0 (2025-09-01)
- frontend: v4.0.0
- backend: v2.7.0
- api-gateway: v3.0.0
(Complete history...)
```
---
## Configuration
**In `.specweave/config.json`**:
```json
{
"release": {
"platformMode": true,
"repositories": [
{
"name": "frontend",
"path": "../frontend",
"git": "https://github.com/org/frontend.git"
},
{
"name": "backend",
"path": "../backend",
"git": "https://github.com/org/backend.git"
},
{
"name": "api-gateway",
"path": "../api-gateway",
"git": "https://github.com/org/api-gateway.git"
}
],
"gitflow": {
"enabled": true,
"releaseBranchPrefix": "release/",
"deleteAfterMerge": true
}
}
}
```
---
## Best Practices
**When to Use Platform Releases**:
- ✅ Services have tight coupling (breaking changes affect multiple repos)
- ✅ Product milestones important (v3.0.0 marketing launch)
- ✅ Need coordinated testing (E2E tests span services)
- ✅ Compliance requirements (audit trail for version combinations)
**When NOT to Use**:
- ❌ Services are fully independent (no coupling)
- ❌ Different release cadences (frontend weekly, backend monthly)
- ❌ Large number of services (>10 repos - use independent versioning)
**RC Best Practices**:
- Create RC.1 early (at least 1 week before planned release)
- Limit RC iterations (ideally ≤3, if >5 something is wrong)
- Test cross-service integration thoroughly
- Document all changes between RCs
---
## Troubleshooting
**Issue**: Git conflicts during merge
```bash
# Solution: Resolve conflicts manually, then resume
git add .
git commit -m "Resolved conflicts"
/specweave-release:platform promote v3.0.0-rc.3 --resume
```
**Issue**: One service fails tests
```bash
# Solution: Fix the service, create new RC
# (Don't bump other services that passed)
/specweave-release:platform iterate v3.0.0-rc.2
```
**Issue**: Need to rollback
```bash
# Solution: Revert main to previous tag, create hotfix
git revert <commit>
/specweave-release:platform create v3.0.1
```
---
## Related Documentation
- [Release Strategy](../../docs/internal/delivery/release-strategy.md)
- [Version Matrix](../../docs/internal/delivery/version-matrix.md)
- [GitFlow Guide](../../docs/internal/delivery/guides/gitflow.md)
- [DORA Metrics](../../docs/internal/delivery/dora-dashboard.md)
---
**Note**: This command integrates with existing SpecWeave increment workflow. Each platform release should have its own increment (e.g., `0050-platform-v3-release`).

495
commands/specweave-release-rc.md Normal file
View File

@@ -0,0 +1,495 @@
---
name: specweave-release:rc
description: Manage Release Candidate (RC) lifecycle including creation, testing, validation, and promotion to production. Handles RC iteration (rc.1, rc.2, rc.3), tracks testing status, coordinates RC across multiple repositories, manages canary deployments, and promotes RC to final release when validation passes.
---
# /specweave-release:rc - Manage Release Candidates
Manage the complete Release Candidate (RC) lifecycle from creation to production promotion.
## What This Command Does
**RC Creation**:
- Creates pre-release tags (v1.0.0-rc.1)
- Deploys to staging environment
- Initializes RC testing checklist
**RC Testing**:
- Tracks validation status
- Runs automated tests
- Manages manual testing
- Documents issues found
**RC Iteration**:
- Fixes bugs → creates rc.2, rc.3, ...
- Never modifies existing RC tags (immutable)
- Maintains iteration history
**RC Promotion**:
- Validates all checks passed
- Promotes to production release (v1.0.0)
- Gradual rollout (canary → 100%)
- Updates living docs
## Usage
```bash
# Create new RC
/specweave-release:rc create <version>
/specweave-release:rc create 1.0.0
# Create RC iteration (bug fixes)
/specweave-release:rc iterate <rc-version>
/specweave-release:rc iterate 1.0.0-rc.2
# Show RC status
/specweave-release:rc status <rc-version>
/specweave-release:rc status 1.0.0-rc.3
# Run RC validation tests
/specweave-release:rc test <rc-version>
/specweave-release:rc test 1.0.0-rc.3
# Promote RC to production
/specweave-release:rc promote <rc-version>
/specweave-release:rc promote 1.0.0-rc.3
# Rollback failed RC
/specweave-release:rc rollback <rc-version>
/specweave-release:rc rollback 1.0.0-rc.2
# Multi-repo RC (creates RC for all repos)
/specweave-release:rc create-multi <product-version>
/specweave-release:rc create-multi product-v3.0.0
```
## Workflow: Single-Repo RC
### Step 1: Create Initial RC
```bash
/specweave-release:rc create 1.0.0
```
```markdown
Creating Release Candidate for v1.0.0...
Step 1: Analyzing changes since v0.9.0
- Commits: 45
- Breaking changes: 2
- Features: 8
- Bug fixes: 12
→ Major version bump confirmed ✓
Step 2: Creating RC tag
✓ Tagged: v1.0.0-rc.1
✓ Pushed to origin
Step 3: Triggering CI/CD
✓ GitHub Actions workflow started
✓ Build: #542 (running)
✓ Estimated time: 15 minutes
Step 4: Creating RC tracking document
✓ Created: .specweave/increments/0090-v1-release/reports/RC-STATUS-v1.0.0-rc.1.md
RC created successfully! ✓
Next steps:
1. Wait for CI/CD to complete
2. Deploy to staging: (automated via CI/CD)
3. Run validation: /specweave-release:rc test 1.0.0-rc.1
4. Review status: /specweave-release:rc status 1.0.0-rc.1
5. If issues: Fix and iterate to rc.2
6. If pass: Promote to v1.0.0
Monitor build: https://github.com/myorg/myapp/actions/runs/542
```
### Step 2: Monitor RC Testing
```bash
/specweave-release:rc status 1.0.0-rc.1
```
```markdown
# RC Status: v1.0.0-rc.1
## Timeline
- Created: 2025-01-15 10:00 UTC
- Deployed to staging: 2025-01-15 10:15 UTC
- Testing phase: In progress (Day 2 of 7)
## Build Status
- CI/CD: ✓ Passed (Build #542)
- Build time: 14m 23s
- Artifacts: Published
## Deployment Status
- Staging: ✓ Deployed (10:15 UTC)
- Pods: 3/3 healthy
- Health check: ✓ Passing
## Testing Progress
### Automated Tests
- [x] Unit tests: 2,345 tests passed
- [x] Integration tests: 456 tests passed
- [x] E2E tests: 123 tests passed
- [x] Performance tests: p95 latency 185ms ✓ (<200ms target)
- [x] Load tests: 12K req/s sustained ✓ (10K target)
- [x] Security scan: No critical/high vulnerabilities ✓
### Manual Testing
- [x] Smoke tests: All critical paths working
- [ ] Exploratory testing: In progress (QA team)
- [x] Cross-browser testing: Chrome ✓, Firefox ✓, Safari ✓
- [ ] Mobile testing: iOS (pending), Android (pending)
### Performance Benchmarks
- API latency p50: 45ms (baseline: 42ms) ✓
- API latency p95: 185ms (baseline: 180ms) ✓
- API latency p99: 320ms (baseline: 310ms) ✓
- Database queries: 1.2ms avg (baseline: 1.1ms) ✓
- Memory usage: 512MB (baseline: 500MB) ✓
## Issues Found
None yet ✓
## Next Actions
- [ ] Complete mobile testing (iOS, Android)
- [ ] Exploratory testing (2 days remaining)
- [ ] Stakeholder approval
- [ ] Promote to canary (5% traffic)
## Decision
Status: NOT READY (testing in progress)
Blocking: Mobile testing, exploratory testing incomplete
```
### Step 3: Found Bug → Iterate to rc.2
```bash
/specweave-release:rc iterate 1.0.0-rc.1
```
```markdown
Iterating Release Candidate v1.0.0-rc.1...
Issues found in rc.1:
1. Authentication fails for SSO users
- Impact: Critical (blocks SSO users from logging in)
- Fix: Add SSO provider check in auth flow
- Commit: abc123
Please fix the issue and commit changes.
? Ready to create rc.2? [Yes / No]
[User fixes bug and confirms]
Creating rc.2...
Step 1: Creating new RC tag
✓ Tagged: v1.0.0-rc.2
✓ Pushed to origin
Step 2: Triggering CI/CD
✓ GitHub Actions workflow started (Build #548)
Step 3: Updating RC tracking
✓ Updated: RC-STATUS-v1.0.0.md
✓ Added iteration history: rc.1 → rc.2
RC iteration complete! ✓
The testing process restarts for rc.2.
Monitor: https://github.com/myorg/myapp/actions/runs/548
```
### Step 4: All Tests Pass → Promote to Production
```bash
/specweave-release:rc promote 1.0.0-rc.3
```
```markdown
Promoting Release Candidate v1.0.0-rc.3 to production...
Step 1: Pre-promotion validation
✓ All automated tests passing
✓ Manual testing complete
✓ No blocking issues
✓ Stakeholder approval received
✓ Release notes drafted
Step 2: Creating production tag
✓ Tagged: v1.0.0
✓ Pushed to origin
Step 3: Deployment strategy
Plan: Gradual rollout
- Canary: 5% traffic (1 hour)
- Wave 1: 10% traffic (1 hour)
- Wave 2: 25% traffic (2 hours)
- Wave 3: 50% traffic (4 hours)
- Wave 4: 100% traffic (8 hours)
Total duration: ~16 hours
Step 4: Starting canary deployment
✓ Deployed v1.0.0 to canary namespace
✓ Traffic: 5% routed to canary
✓ Monitoring: Active
Metrics to watch:
- Error rate (target: <1%)
- Latency p95 (target: <200ms)
- Throughput (target: >10K req/s)
Next check: In 1 hour (11:00 UTC)
Canary deployment started! ✓
I'll monitor the metrics and notify you when ready for next wave.
Monitor dashboard: https://grafana.example.com/d/prod-release
Rollback command: /specweave-release:rc rollback 1.0.0-rc.3
```
## Workflow: Multi-Repo RC
### Create Coordinated RC
```bash
/specweave-release:rc create-multi product-v3.0.0
```
```markdown
Creating coordinated Release Candidate for Product v3.0.0...
Step 1: Analyzing repositories
Detected: 4 repos (frontend, backend, api-gateway, shared-lib)
Step 2: Analyzing changes per repo
frontend (v4.2.0 → v5.0.0):
- Breaking: React 18 upgrade
- RC: v5.0.0-rc.1
backend (v2.8.0 → v3.0.0):
- Breaking: Remove legacy API
- RC: v3.0.0-rc.1
api-gateway (v3.1.0 → v4.0.0):
- Breaking: Remove /v2 endpoints
- RC: v4.0.0-rc.1
shared-lib (v1.5.0 → v1.5.1):
- Patch: Bug fixes only
- RC: v1.5.1-rc.1
Step 3: Creating RC tags for all repos
✓ frontend: v5.0.0-rc.1
✓ backend: v3.0.0-rc.1
✓ api-gateway: v4.0.0-rc.1
✓ shared-lib: v1.5.1-rc.1
Step 4: Triggering coordinated CI/CD
✓ All workflows started
✓ Estimated time: ~20 minutes
Step 5: Creating coordinated RC tracking
✓ Created: .specweave/increments/0095-product-v3-release/reports/RC-STATUS-product-v3.0.0-rc.1.md
Multi-repo RC created! ✓
Next steps:
1. Wait for all builds to complete
2. Deploy to staging (coordinated)
3. Run cross-service E2E tests
4. Validate: /specweave-release:rc status product-v3.0.0-rc.1
5. Iterate if needed: Fix issues → rc.2
6. Promote: /specweave-release:rc promote product-v3.0.0-rc.3
```
## RC Testing Checklist
**Automatically created for each RC**:
```markdown
# RC Validation Checklist: v1.0.0-rc.3
## Automated Tests
- [x] Unit tests: 2,345 tests (100% pass)
- [x] Integration tests: 456 tests (100% pass)
- [x] E2E tests: 123 tests (100% pass)
- [x] Performance tests: All benchmarks met
- [x] Load tests: 10K req/s sustained
- [x] Security scan: No critical/high issues
## Manual Tests
- [x] Smoke tests: All critical paths work
- [x] Exploratory testing: No major issues
- [x] Cross-browser: Chrome, Firefox, Safari
- [x] Mobile: iOS, Android
## Infrastructure
- [x] Database migrations: Tested (forward + rollback)
- [x] Canary deployment: 5% traffic, 24 hours
- [x] No error rate increase
- [x] No performance degradation
- [x] Rollback plan validated
## Documentation
- [x] CHANGELOG.md updated
- [x] API documentation updated
- [x] Migration guide (breaking changes)
- [x] Release notes drafted
## Approvals
- [x] Product Manager: @jane ✓
- [x] Engineering Lead: @john ✓
- [x] Security Team: @alice ✓
- [x] QA Lead: @bob ✓
## Monitoring
- [x] Alerts configured
- [x] Dashboards updated
- [x] On-call schedule confirmed
## Final Decision
Status: APPROVED ✅
Ready for production: Yes
Promote to: v1.0.0
Scheduled: 2025-01-16 10:00 UTC
```
## RC Rollback
**If issues detected during canary**:
```bash
/specweave-release:rc rollback 1.0.0-rc.3
```
```markdown
Rolling back v1.0.0-rc.3...
Reason: Error rate increased to 8% in canary
Step 1: Stopping new traffic to canary
✓ Kubernetes: kubectl rollout pause
Step 2: Routing traffic back to previous version
✓ 100% traffic → v0.9.0 (previous stable)
✓ 0% traffic → v1.0.0-rc.3 (canary)
Step 3: Verifying rollback
✓ Error rate back to 0.5% (normal)
✓ Latency back to baseline
✓ All health checks passing
Step 4: Documenting rollback
✓ Updated: RC-STATUS-v1.0.0.md
✓ Incident logged: INC-456
Step 5: Root cause analysis
Issue: Database connection pool exhausted
Fix required: Increase pool size + add connection retry logic
Rollback complete! ✓
Next steps:
1. Fix identified issue
2. Create rc.4 with fix
3. Re-test in staging
4. Retry canary deployment
```
## RC Status Tracking
**Creates detailed status document**:
```
.specweave/increments/0090-v1-release/reports/RC-STATUS-v1.0.0.md
```
**Tracks**:
- RC iteration history (rc.1, rc.2, rc.3, ...)
- Testing status per iteration
- Issues found and fixes applied
- Deployment history
- Promotion decision
## Integration with SpecWeave
**RC Command Integration**:
```bash
# 1. Create release increment
/specweave:increment "0090-v1-0-0-release"
# 2. Create RC
/specweave-release:rc create 1.0.0
# → Creates v1.0.0-rc.1
# 3. Testing phase
/specweave-release:rc test 1.0.0-rc.1
# → Runs automated tests
# 4. Iterate if needed
/specweave-release:rc iterate 1.0.0-rc.1
# → Creates v1.0.0-rc.2
# 5. Promote when ready
/specweave-release:rc promote 1.0.0-rc.3
# → Creates v1.0.0, deploys to production
# 6. Mark increment complete
/specweave:done 0090
# → Updates living docs
```
## Best Practices
**RC Creation**:
- Always start with rc.1
- Never modify existing RC tags
- Create new iteration for fixes
**RC Testing**:
- Run ALL tests for each iteration
- Never skip validation steps
- Use production-like staging data
**RC Promotion**:
- Gradual rollout (canary → waves)
- Monitor 1+ hour at each stage
- Have rollback plan ready
**RC Documentation**:
- Track all iterations
- Document bugs and fixes
- Record promotion rationale
## Related Commands
- `/specweave-release:init` - Initialize release strategy
- `/specweave-release:align` - Align versions before RC
- `/specweave-release:coordinate` - Coordinate multi-repo RC
- `/specweave:done` - Complete release increment
## Dependencies
**Required**:
- Git (version control)
- Release strategy document
**Optional**:
- Kubernetes (`kubectl`) - Deployment management
- Docker (`docker`) - Container testing
- GitHub CLI (`gh`) - Release notes
---
**Use this command** to safely validate changes before production release through comprehensive RC testing and gradual rollout.