specweave 0.17.0 → 0.17.2

package/plugins/specweave-mobile/skills/react-native-setup/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: react-native-setup
+description: Expert in React Native environment setup and configuration. Helps with Node.js, Xcode, Android Studio, watchman installation, CocoaPods, simulators, emulators, and troubleshooting setup issues. Activates for environment setup, installation issues, xcode setup, android studio, simulators, emulators, react-native init, expo init, development environment, SDK configuration.
+---
+
+# React Native Setup Expert
+
+Expert in React Native and Expo environment configuration across macOS, Windows, and Linux. Specializes in troubleshooting installation issues, SDK configuration, and development environment optimization.
+
+## What I Know
+
+### Prerequisites & Installation
+
+**Node.js & npm**
+- Node.js 18.x or later required
+- Version verification: `node --version && npm --version`
+- Troubleshooting Node.js installation issues
+- npm vs yarn vs pnpm for React Native projects
+
+**Xcode (macOS - iOS Development)**
+- Xcode 15.x or later required
+- Command line tools installation: `xcode-select --install`
+- License acceptance: `sudo xcodebuild -license accept`
+- Platform installation verification
+- Common Xcode errors and fixes
+
+**Android Studio (Android Development)**
+- Android Studio Hedgehog or later
+- Required SDK components:
+  - Android SDK Platform 34 or later
+  - Android SDK Build-Tools
+  - Android Emulator
+  - Android SDK Platform-Tools
+- ANDROID_HOME environment variable setup
+- SDK Manager configuration
+- Common Android Studio issues
+
+**Watchman**
+- Installation via Homebrew (macOS): `brew install watchman`
+- Purpose: File watching for fast refresh
+- Troubleshooting watchman errors
+- Cache clearing strategies
+
+### Environment Configuration
+
+**iOS Setup**
+- CocoaPods installation and troubleshooting
+- Pod install issues and resolutions
+- Xcode project configuration
+- Provisioning profiles and certificates
+- iOS Simulator management
+- Device selection: `xcrun simctl list devices`
+
+**Android Setup**
+- Gradle configuration
+- Android SDK path configuration
+- Environment variables (ANDROID_HOME, PATH)
+- AVD (Android Virtual Device) creation
+- Emulator performance optimization
+- ADB troubleshooting
+
+**Metro Bundler**
+- Port 8081 configuration
+- Cache clearing: `npx react-native start --reset-cache`
+- Custom Metro config
+- Asset resolution issues
+
+### Common Setup Issues
+
+**"Command not found" Errors**
+- PATH configuration
+- Shell profile updates (.zshrc, .bash_profile)
+- Symlink issues
+
+**SDK Not Found**
+- SDK path verification
+- Environment variable troubleshooting
+- SDK Manager reinstallation
+
+**Pod Install Failures**
+- CocoaPods version issues
+- Ffi gem compilation errors
+- Ruby version compatibility
+- `pod deintegrate && pod install` strategy
+
+**Build Failures**
+- Clean build strategies
+- Dependency conflicts
+- Native module compilation errors
+- Xcode derived data clearing
+
+## When to Use This Skill
+
+Ask me when you need help with:
+- Initial React Native environment setup
+- Installing and configuring Xcode or Android Studio
+- Setting up iOS simulators or Android emulators
+- Troubleshooting "Command not found" errors
+- Resolving SDK path or ANDROID_HOME issues
+- Fixing CocoaPods installation problems
+- Clearing Metro bundler cache
+- Configuring development environment variables
+- Troubleshooting build failures
+- Setting up watchman for file watching
+- Verifying development environment prerequisites
+
+## Quick Setup Commands
+
+### iOS (macOS)
+```bash
+# Install Xcode command line tools
+xcode-select --install
+
+# Accept Xcode license
+sudo xcodebuild -license accept
+
+# Install CocoaPods
+sudo gem install cocoapods
+
+# Install watchman
+brew install watchman
+
+# Verify setup
+xcodebuild -version
+pod --version
+watchman version
+```
+
+### Android (All Platforms)
+```bash
+# Verify Android setup
+echo $ANDROID_HOME
+adb --version
+emulator -version
+
+# List available emulators
+emulator -list-avds
+
+# List connected devices
+adb devices
+```
+
+### React Native Project
+```bash
+# Create new React Native project
+npx react-native init MyProject
+
+# Navigate to project
+cd MyProject
+
+# Install iOS dependencies
+cd ios && pod install && cd ..
+
+# Start Metro bundler
+npm start
+
+# Run on iOS (separate terminal)
+npm run ios
+
+# Run on Android (separate terminal)
+npm run android
+```
+
+## Pro Tips
+
+1. **Clean Builds**: When in doubt, clean everything
+   ```bash
+   # iOS
+   cd ios && rm -rf build Pods && pod install && cd ..
+
+   # Android
+   cd android && ./gradlew clean && cd ..
+
+   # Metro
+   npx react-native start --reset-cache
+   ```
+
+2. **Environment Variables**: Always verify environment variables after changes
+   ```bash
+   # Add to ~/.zshrc or ~/.bash_profile
+   export ANDROID_HOME=$HOME/Library/Android/sdk
+   export PATH=$PATH:$ANDROID_HOME/emulator
+   export PATH=$PATH:$ANDROID_HOME/platform-tools
+
+   # Reload shell
+   source ~/.zshrc
+   ```
+
+3. **Simulator Management**: List and boot specific devices
+   ```bash
+   # iOS
+   xcrun simctl list devices
+   xcrun simctl boot "iPhone 15 Pro"
+
+   # Android
+   emulator -list-avds
+   emulator -avd Pixel_6_API_34
+   ```
+
+4. **Quick Health Check**: Verify entire environment
+   ```bash
+   node --version      # Node.js
+   npm --version       # npm
+   xcodebuild -version # Xcode (macOS)
+   pod --version       # CocoaPods (macOS)
+   adb --version       # Android tools
+   watchman version    # Watchman
+   ```
+
+## Integration with SpecWeave
+
+This skill integrates with SpecWeave's increment workflow:
+- Use during `/specweave:increment` planning for environment setup tasks
+- Reference in `tasks.md` for setup-related acceptance criteria
+- Include in `spec.md` for mobile-specific prerequisites
+- Document setup issues in increment `reports/` folder

package/plugins/specweave-release/.claude-plugin/plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "specweave-release",
+  "version": "1.0.0",
+  "description": "Comprehensive release management for single-repo, multi-repo, and monorepo architectures. Detects existing release strategies, aligns versions across repositories, manages Release Candidates (RC), and integrates with CI/CD workflows. Supports semantic versioning, coordinated releases, and brownfield strategy detection.",
+  "author": {
+    "name": "Anton Abyzov",
+    "url": "https://github.com/anton-abyzov"
+  },
+  "keywords": [
+    "release",
+    "versioning",
+    "semver",
+    "multi-repo",
+    "monorepo",
+    "release-candidate",
+    "rc",
+    "deployment",
+    "ci-cd",
+    "changelog",
+    "git-tags",
+    "npm-publish",
+    "version-alignment",
+    "coordinated-release",
+    "independent-release",
+    "brownfield-release"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anton-abyzov/specweave",
+    "directory": "plugins/specweave-release"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "specweave": ">=0.14.0"
+  },
+  "skills": "skills",
+  "agents": "agents",
+  "commands": "commands",
+  "hooks": "hooks/hooks.json"
+}

package/plugins/specweave-release/IMPLEMENTATION.md

@@ -0,0 +1,449 @@
+# 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/                      # 4 specialized skills
+│   ├── release-strategy-advisor/
+│   │   └── SKILL.md            # Strategy design + brownfield detection
+│   ├── release-coordinator/
+│   │   └── SKILL.md            # Multi-repo orchestration
+│   ├── version-aligner/
+│   │   └── SKILL.md            # Version management + semver
+│   └── 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-coordinator** (3,200 lines) - Multi-repo coordination, dependency management
+- ✅ **version-aligner** (2,900 lines) - Semantic versioning, version alignment
+- ✅ **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
+/specweave:increment "0050-v2-release"        # Create increment
+/specweave-release:align                      # Align versions
+/specweave-release:rc create 2.0.0            # Create RC
+/specweave:do                                 # Execute tasks
+/specweave-release:rc promote 2.0.0-rc.3      # Promote to prod
+/specweave: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)
+
+- `/specweave-release:coordinate` - Plan coordinated releases
+- `/specweave-release:publish` - Execute releases
+- `/specweave-release:rollback` - Rollback failed releases
+- `/specweave-release:matrix` - Show/update version matrix
+- `/specweave-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 /specweave-release:init
+3. Verify release-strategy.md created
+4. Run /specweave-release:align
+5. Verify versions bumped correctly
+6. Run /specweave-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