specweave 1.0.506 → 1.0.508

package/plugins/specweave-release/IMPLEMENTATION.md

@@ -1,446 +0,0 @@
-# SpecWeave Release Management Plugin - Implementation Summary
-
-**Created**: 2025-11-11
-**Version**: 1.0.0
-**Status**: ✅ Complete (Skills + Agent + Commands + Documentation)
-
-## Executive Summary
-
-The **specweave-release** plugin provides comprehensive release management capabilities for modern software projects. It handles everything from release strategy design to multi-repo coordination, RC workflows, and production deployment.
-
-**Key Achievement**: Fills a critical gap in SpecWeave's ecosystem by providing enterprise-grade release management that integrates seamlessly with existing workflows.
-
-## Architecture
-
-### Plugin Structure
-
-```
-plugins/specweave-release/
-├── .claude-plugin/
-│   └── plugin.json             # Claude native manifest
-├── skills/                      # 3 specialized skills
-│   ├── release-strategy-advisor/
-│   │   └── SKILL.md            # Strategy design + brownfield detection
-│   ├── release-expert/
-│   │   └── SKILL.md            # Version alignment + multi-repo orchestration
-│   └── rc-manager/
-│       └── SKILL.md            # RC lifecycle + testing
-├── agents/
-│   └── release-manager/
-│       └── AGENT.md            # Master orchestrator
-├── commands/
-│   ├── specweave-release-init.md       # Initialize strategy
-│   ├── specweave-release-align.md      # Align versions
-│   └── specweave-release-rc.md         # Manage RCs
-├── lib/                         # TypeScript utilities (TBD)
-└── README.md                    # User documentation
-```
-
-### Component Breakdown
-
-**Skills** (Auto-Activating):
-- ✅ **release-strategy-advisor** (3,700 lines) - Strategy design, brownfield detection
-- ✅ **release-expert** - Version alignment, semantic versioning, multi-repo coordination, dependency management
-- ✅ **rc-manager** (4,100 lines) - RC lifecycle, testing, promotion
-
-**Agent** (Orchestrator):
-- ✅ **release-manager** (2,800 lines) - Master coordinator for all release activities
-
-**Commands** (User-Facing):
-- ✅ **init** (2,400 lines) - Initialize or analyze release strategy
-- ✅ **align** (2,100 lines) - Align versions across repositories
-- ✅ **rc** (2,600 lines) - Manage release candidates
-
-**Total**: ~24,000 lines of comprehensive release management documentation and workflows
-
-## Key Features
-
-### 1. Release Strategy Design
-
-**Greenfield Projects**:
-- Interactive questionnaire (team size, coupling, frequency)
-- Recommends optimal strategy (lockstep/independent/umbrella)
-- Creates living documentation
-- Suggests CI/CD automation
-
-**Brownfield Projects**:
-- Detects existing patterns (git tags, CI/CD, package managers)
-- Classifies current strategy
-- Documents in living docs
-- Suggests improvements
-
-**Outputs**:
-- `.specweave/docs/internal/delivery/release-strategy.md` (comprehensive strategy doc)
-- `.specweave/docs/internal/delivery/version-matrix.md` (umbrella releases)
-
-### 2. Multi-Repo Coordination
-
-**Capabilities**:
-- Dependency graph analysis (topological sort)
-- Release wave calculation (Wave 1, 2, 3, ...)
-- Pre-flight validation (compatibility checks)
-- Wave-by-wave execution
-- Post-release monitoring
-
-**Supports**:
-- Single repo (simple releases)
-- Multi-repo (2-5 repos)
-- Large multi-repo (5+ repos)
-- Monorepo (Lerna, Nx, Turborepo)
-- Microservices (dozens of services)
-
-### 3. Version Alignment
-
-**Features**:
-- Conventional commit analysis (breaking/feature/fix)
-- Semantic versioning enforcement (MAJOR.MINOR.PATCH)
-- Version conflict detection
-- Cross-repo compatibility validation
-- Automated version bumping
-
-**Strategies**:
-- **Lockstep**: All repos share same version
-- **Independent**: Each repo versions separately
-- **Umbrella**: Product version spans service versions
-
-### 4. Release Candidate Workflow
-
-**RC Lifecycle**:
-- Alpha → Beta → RC → Production
-- Immutable tags (never modify existing RCs)
-- Iteration support (rc.1 → rc.2 → rc.3)
-- Testing validation at each stage
-- Promotion decision gates
-
-**Testing Integration**:
-- Automated tests (unit/integration/E2E/performance)
-- Manual testing checklist
-- Canary deployments (5% traffic)
-- Gradual rollout (10% → 25% → 50% → 100%)
-- Rollback procedures
-
-### 5. Living Documentation
-
-**Automatic Updates**:
-- Release strategy maintained in living docs
-- Version matrix updated after releases
-- RC status tracked per increment
-- Decision history preserved (ADRs)
-
-**Integration Points**:
-- Post-increment-completion hook updates docs
-- Syncs to external tools (GitHub, Jira, ADO)
-- Links to architecture decisions (ADRs)
-
-## Integration with SpecWeave
-
-### Increment Lifecycle
-
-```bash
-# Standard workflow
-/sw:increment "0050-v2-release"        # Create increment
-/sw-release:align                      # Align versions
-/sw-release:rc create 2.0.0            # Create RC
-/sw:do                                 # Execute tasks
-/sw-release:rc promote 2.0.0-rc.3      # Promote to prod
-/sw:done 0050                          # Complete increment
-```
-
-### Brownfield Integration
-
-```bash
-# When brownfield-analyzer runs:
-1. Detects repository structure
-2. Scans git history
-3. Analyzes CI/CD configs
-4. Invokes release-strategy-advisor
-5. Creates living documentation
-```
-
-### Multi-Project Support
-
-```bash
-# Project-specific strategies
-.specweave/docs/internal/projects/frontend/delivery/release-strategy.md
-.specweave/docs/internal/projects/backend/delivery/release-strategy.md
-
-# Or cross-project strategy
-.specweave/docs/internal/delivery/release-strategy.md
-```
-
-## Use Cases
-
-### Single-Repo NPM Package
-
-**Before SpecWeave Release**:
-- Manual version bumping (`npm version`)
-- No RC workflow (straight to production)
-- Inconsistent changelog
-- No rollback plan
-
-**After SpecWeave Release**:
-- Automated version bump analysis (conventional commits)
-- RC workflow for major versions (v2.0.0-rc.1 → v2.0.0)
-- Automated changelog generation
-- Documented rollback procedures
-
-### Multi-Repo Microservices
-
-**Before SpecWeave Release**:
-- Uncoordinated releases (each service independently)
-- Version conflicts (frontend expects API v3, backend still on v2)
-- No dependency awareness (release shared-lib after services)
-- Manual coordination (Slack messages, spreadsheets)
-
-**After SpecWeave Release**:
-- Coordinated releases (wave-by-wave execution)
-- Version validation (detect conflicts before deployment)
-- Dependency-aware ordering (shared-lib → services → gateway → frontend)
-- Automated coordination (increment tracks entire product release)
-
-### Monorepo (Lerna)
-
-**Before SpecWeave Release**:
-- Manual Lerna commands (`lerna publish`)
-- Unclear which packages changed
-- No cross-package validation
-- Version matrix tracking in spreadsheets
-
-**After SpecWeave Release**:
-- Automated change detection (conventional commits per package)
-- Clear version suggestions (only changed packages)
-- Dependency validation (cross-package compatibility)
-- Living documentation (version matrix in living docs)
-
-## Benefits
-
-### For Small Teams (1-5 developers)
-
-**Problem**: Limited resources, need automation
-**Solution**:
-- Simple semver strategy
-- Automated version bump suggestions
-- One-command releases
-- No manual coordination overhead
-
-### For Medium Teams (5-20 developers)
-
-**Problem**: Multi-repo complexity, need coordination
-**Solution**:
-- Umbrella versioning (product milestones)
-- RC workflow (catch issues before production)
-- Version matrix tracking
-- Living documentation (onboarding, compliance)
-
-### For Large Teams (20+ developers)
-
-**Problem**: Dozens of services, complex dependencies
-**Solution**:
-- Multi-repo coordination (wave-by-wave)
-- Dependency graph analysis (automated ordering)
-- Canary deployments (safe rollouts)
-- DORA metrics tracking
-
-## Technical Highlights
-
-### 1. Conventional Commits Integration
-
-**Analyzes commit messages to suggest version bumps**:
-```bash
-feat!: remove legacy API       # BREAKING → MAJOR (v1.0.0 → v2.0.0)
-feat: add dark mode            # FEATURE → MINOR (v1.0.0 → v1.1.0)
-fix: prevent crash             # BUGFIX → PATCH (v1.0.0 → v1.0.1)
-```
-
-### 2. Dependency Graph
-
-**Topological sort for release order**:
-```
-shared-lib → backend → api-gateway → frontend
-   Wave 1      Wave 2      Wave 3       Wave 4
-```
-
-### 3. Version Conflict Detection
-
-**Prevents incompatible releases**:
-```yaml
-service-a depends on: shared-lib ^2.0.0
-service-b depends on: shared-lib ^1.5.0
-
-Conflict: Cannot release until service-b upgrades ✗
-```
-
-### 4. RC Promotion Gates
-
-**Validates all checks before production**:
-- ✅ All tests passing (unit/integration/E2E)
-- ✅ Performance benchmarks met
-- ✅ Security scan clean
-- ✅ Stakeholder approval
-- ✅ Canary deployment successful
-
-### 5. Gradual Rollout
-
-**Progressive deployment with monitoring**:
-```
-Canary 5%  (1 hour, monitor error rate)
-Wave 1 10% (1 hour, monitor latency)
-Wave 2 25% (2 hours, monitor throughput)
-Wave 3 50% (4 hours, final validation)
-Wave 4 100% (full rollout)
-```
-
-## Living Documentation
-
-### Release Strategy Document
-
-**Location**: `.specweave/docs/internal/delivery/release-strategy.md`
-
-**Contains**:
-- Repository overview (architecture, team)
-- Versioning strategy (lockstep/independent/umbrella)
-- RC workflow (when to use, testing requirements)
-- CI/CD integration (GitHub Actions, GitLab CI, etc.)
-- Changelog management (tools, format)
-- Hotfix strategy (branching, fast-tracking)
-- Release checklist (pre/during/post-release)
-- DORA metrics (deployment frequency, lead time, MTTR, change failure rate)
-- Decision history (ADRs for major changes)
-
-### Version Matrix Document
-
-**Location**: `.specweave/docs/internal/delivery/version-matrix.md`
-
-**Contains**:
-- Product version history (v1.0.0, v2.0.0, ...)
-- Service version mappings (Product v3.0.0 = {frontend: v5.0.0, backend: v2.9.0})
-- Compatibility matrix (which versions work together)
-- Breaking changes per release
-
-## Future Enhancements
-
-### TypeScript Utilities (Planned)
-
-```
-plugins/specweave-release/lib/
-├── release-strategy.ts       # Strategy detection/generation
-├── version-manager.ts        # Version alignment logic
-├── rc-workflow.ts            # RC lifecycle automation
-├── dependency-graph.ts       # Topological sort implementation
-└── conventional-commits.ts   # Commit analysis
-```
-
-**Features**:
-- Programmatic API for release operations
-- Integration with CI/CD systems
-- Webhook support (GitHub, GitLab, Bitbucket)
-- Metrics collection (DORA metrics)
-
-### Additional Commands (Planned)
-
-- `/sw-release:coordinate` - Plan coordinated releases
-- `/sw-release:publish` - Execute releases
-- `/sw-release:rollback` - Rollback failed releases
-- `/sw-release:matrix` - Show/update version matrix
-- `/sw-release:hotfix` - Fast-track hotfix releases
-
-### Enhanced Integrations (Planned)
-
-**GitHub**:
-- Auto-create releases from tags
-- Link PRs to releases
-- Track deployment status
-
-**JIRA/ADO**:
-- Sync release versions
-- Track release tickets
-- Update fix versions
-
-**Monitoring**:
-- Grafana dashboard integration
-- Datadog metrics export
-- PagerDuty alerting
-
-## Testing Strategy
-
-### Unit Tests (TBD)
-
-```typescript
-describe('ReleaseStrategy', () => {
-  it('should detect lockstep versioning from git tags');
-  it('should recommend umbrella versioning for medium teams');
-  it('should validate version compatibility across repos');
-});
-
-describe('VersionAligner', () => {
-  it('should suggest MAJOR bump for breaking changes');
-  it('should detect version conflicts');
-  it('should align versions according to strategy');
-});
-
-describe('RCManager', () => {
-  it('should create RC tags (v1.0.0-rc.1)');
-  it('should iterate RCs (rc.1 → rc.2)');
-  it('should promote RC to production (rc.3 → v1.0.0)');
-});
-```
-
-### Integration Tests (TBD)
-
-```bash
-# Test full release workflow
-1. Create test repos (frontend, backend, api)
-2. Initialize release strategy
-3. Make changes (breaking, features, fixes)
-4. Align versions
-5. Create coordinated RC
-6. Promote to production
-7. Validate version matrix updated
-```
-
-### E2E Tests (TBD)
-
-```bash
-# Test with real repos
-1. Clone test repository
-2. Run /sw-release:init
-3. Verify release-strategy.md created
-4. Run /sw-release:align
-5. Verify versions bumped correctly
-6. Run /sw-release:rc create 1.0.0
-7. Verify RC tag created
-```
-
-## Success Metrics
-
-**Adoption**:
-- Number of projects using release plugin
-- Number of coordinated releases executed
-- Number of RC workflows completed
-
-**Quality**:
-- Reduction in production incidents (post-release)
-- Increase in RC usage (major versions)
-- Improved DORA metrics (deployment frequency, lead time)
-
-**Efficiency**:
-- Time saved on release coordination (hours → minutes)
-- Reduction in version conflicts (before → after)
-- Automation level (manual → semi-automated → fully automated)
-
-## Conclusion
-
-The **specweave-release** plugin provides enterprise-grade release management for modern software projects. It bridges a critical gap in SpecWeave's ecosystem by:
-
-1. **Simplifying Releases** - One-command coordination across repos
-2. **Ensuring Safety** - RC workflows, gradual rollouts, rollback procedures
-3. **Maintaining Quality** - Pre-flight validation, testing gates, monitoring
-4. **Preserving Knowledge** - Living documentation, version matrices, decision history
-
-**Result**: Teams can release software faster, safer, and with less manual coordination overhead.
-
----
-
-**Status**: ✅ Complete (Skills + Agent + Commands + Documentation)
-**Next Steps**: TypeScript utilities, additional commands, integration tests
-**Feedback**: Open GitHub issues for feature requests and bug reports

package/plugins/specweave-release/PLUGIN.md

@@ -1,38 +0,0 @@
-# Release Management
-
-**Version**: 1.0.0
-**Author**: SpecWeave Contributors
-**License**: MIT
-
-## Description
-
-Multi-repository release coordination with version alignment, release waves, RC lifecycle management (alpha/beta/rc), brownfield detection, and rollback planning. Supports lockstep, independent, and umbrella versioning strategies.
-
-## Skills
-
-| Skill | Description |
-|-------|-------------|
-| release-expert | Multi-repo release expert combining version alignment (semantic versioning, conflict detection, compatibility validation, version matrix management) with release orchestration (RC lifecycle, dependency management, release waves, brownfield detection) |
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| /sw-release:align | Align versions across multiple repositories according to release strategy with conflict detection and validation |
-| /sw-release:init | Initialize release strategy and create release-strategy.md documentation |
-| /sw-release:rc | Create and manage release candidates with pre-release tag lifecycle |
-| /sw-release:npm | NPM-specific release operations including package publishing and version bumping |
-| /sw-release:platform | Platform-agnostic release operations for multi-language projects |
-
-## Installation
-
-```bash
-vskill add specweave --plugin sw-release
-```
-
-## Requirements
-
-- SpecWeave core plugin (sw@specweave)
-- Git with version tags support
-- Conventional commits in git history
-- Release strategy document (.specweave/docs/internal/delivery/release-strategy.md)