claude-autopm 2.8.2 → 2.8.3

package/packages/plugin-core/rules/no-pr-workflow.md

@@ -0,0 +1,183 @@
+# Hybrid Development Workflow
+
+## FLEXIBLE DEVELOPMENT STRATEGY
+
+**This project supports both direct commits and Pull Requests, adapting to different scenarios and team needs.**
+
+## Workflow Options
+
+### 1. Direct to Main (Trunk-Based)
+**When to use:**
+- ✅ You're a trusted core contributor
+- ✅ Making hotfixes or critical patches
+- ✅ Small, low-risk changes
+- ✅ Documentation updates
+- ✅ Working solo or in a small, high-trust team
+
+**Process:**
+```bash
+# Ensure main is up to date
+git checkout main
+git pull origin main
+
+# Make changes
+# ... edit files ...
+
+# Run tests locally
+npm test
+
+# Commit and push directly
+git add .
+git commit -m "fix: resolve critical issue"
+git push origin main
+```
+
+### 2. Pull Request Workflow
+**When to use:**
+- ✅ You're an external contributor
+- ✅ Making major features or breaking changes
+- ✅ Changes need review or discussion
+- ✅ Working in a larger team
+- ✅ Updating dependencies
+
+**Process:**
+```bash
+# Create feature branch
+git checkout -b feat/new-feature
+
+# Make changes
+# ... edit files ...
+
+# Commit and push to branch
+git add .
+git commit -m "feat: add new feature"
+git push origin feat/new-feature
+
+# Open PR on GitHub
+```
+
+## Decision Matrix
+
+| Scenario | Direct Commit | Pull Request |
+|----------|--------------|--------------|
+| **Hotfix** | ✅ Preferred | Use if complex |
+| **Documentation** | ✅ Preferred | Optional |
+| **Minor feature** | ✅ Allowed | Recommended |
+| **Major feature** | ❌ Discouraged | ✅ Required |
+| **Breaking change** | ❌ Not allowed | ✅ Required |
+| **External contributor** | ❌ Not allowed | ✅ Required |
+| **Dependency update** | ⚠️ Use caution | ✅ Preferred |
+| **Experimental work** | ❌ Not allowed | ✅ Required |
+
+## Commit Guidelines
+
+### Commit Message Format
+Always use conventional commits regardless of workflow:
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation
+- `style:` Formatting
+- `refactor:` Code restructuring
+- `test:` Testing
+- `chore:` Maintenance
+
+### Before Any Push
+1. **Run tests locally**: `npm test`
+2. **Check linting**: `npm run lint`
+3. **Verify build**: `npm run build`
+4. **Pull latest changes**: `git pull origin main`
+
+## Branch Protection Settings
+
+### Main Branch
+- ✅ Allow direct commits from administrators
+- ✅ Require status checks for PRs
+- ✅ Run CI/CD on both direct commits and PRs
+- ❌ Do NOT require PRs for all changes
+
+### Feature Branches
+- Naming: `feat/*`, `fix/*`, `docs/*`, `chore/*`
+- Auto-delete after merge
+- Can be force-pushed by creator
+
+## CI/CD Behavior
+
+### On Direct Commits
+- Run essential tests quickly
+- Deploy if tests pass
+- Rollback on failure
+
+### On Pull Requests
+- Run comprehensive test suite
+- Generate coverage reports
+- Preview deployments (if applicable)
+- Security scanning
+
+## Safety Measures
+
+Both workflows maintain quality through:
+- **Pre-commit hooks** for formatting and linting
+- **Automated testing** on every push
+- **Rollback capability** via git tags
+- **Protected credentials** via secrets management
+
+## Team Evolution Path
+
+Teams can adapt their workflow over time:
+
+1. **Starting Out** → Use PRs for everything
+2. **Building Trust** → Allow direct commits for docs
+3. **High Trust** → Direct commits for most changes
+4. **Optimal** → Hybrid based on change type
+
+## Git Aliases for Efficiency
+
+```bash
+# Add to ~/.gitconfig
+[alias]
+    # Direct commit and push
+    dcp = !git add . && git commit -m "$1" && git push origin main
+
+    # Create PR branch
+    pr = checkout -b
+
+    # Update main
+    update = !git checkout main && git pull origin main
+
+    # Quick status
+    st = status -sb
+```
+
+## Key Benefits
+
+### Direct Commits
+- 🚀 Maximum speed
+- 🎯 Minimal overhead
+- ⚡ Instant integration
+
+### Pull Requests
+- 🔍 Code review
+- 💬 Discussion platform
+- 📝 Change documentation
+- 🛡️ Additional safety
+
+## Important Notes
+
+1. **This is intentional design** - Supporting both workflows provides flexibility
+2. **Choose based on context** - Not all changes are equal
+3. **Trust is earned** - Start with PRs, earn direct commit access
+4. **Quality over speed** - When in doubt, use a PR
+
+## Migration Support
+
+### From PR-Only
+- Grant direct access gradually
+- Start with documentation commits
+- Monitor quality metrics
+
+### From Direct-Only
+- Introduce PRs for major changes
+- Use branch protection rules
+- Educate on PR benefits
+
+This hybrid approach ensures the project can adapt to different team sizes, trust levels, and development phases while maintaining code quality and velocity.

package/packages/plugin-core/rules/performance-guidelines.md

@@ -0,0 +1,403 @@
+# ⚡ Performance Guidelines & Optimization
+
+> **Performance is a feature. Slow is broken.**
+
+## Performance Targets
+
+### 🌐 Web Performance Metrics
+
+#### Core Web Vitals
+
+- **LCP (Largest Contentful Paint)**: < 2.5s
+- **FID (First Input Delay)**: < 100ms
+- **CLS (Cumulative Layout Shift)**: < 0.1
+- **FCP (First Contentful Paint)**: < 1.5s
+- **TTI (Time to Interactive)**: < 5s
+- **TBT (Total Blocking Time)**: < 300ms
+
+#### Page Load Targets
+
+- **3G Network**: < 3 seconds
+- **4G Network**: < 1.5 seconds
+- **Broadband**: < 1 second
+- **Repeat Visit**: < 500ms (with cache)
+
+### 🔧 API Performance Targets
+
+| Operation Type | Target | Maximum |
+|---------------|--------|----------|
+| Simple Query | < 50ms | 100ms |
+| Complex Query | < 200ms | 500ms |
+| Search | < 300ms | 1s |
+| File Upload | < 1s/MB | 2s/MB |
+| Batch Operation | < 5s | 10s |
+| Real-time Updates | < 100ms | 200ms |
+
+### 🗄️ Database Performance
+
+| Query Type | Target | Action if Exceeded |
+|-----------|--------|--------------------|
+| Indexed SELECT | < 10ms | Add index |
+| Complex JOIN | < 50ms | Optimize query |
+| Full Table Scan | < 100ms | Add index/partition |
+| Write Operation | < 20ms | Check locks |
+| Transaction | < 100ms | Break down |
+
+## Frontend Performance Optimization
+
+### 📦 Bundle Size Budgets
+
+```javascript
+// Maximum bundle sizes
+const budgets = {
+  javascript: {
+    initial: 200,     // KB (gzipped)
+    lazy: 300,        // KB (gzipped)
+  },
+  css: {
+    initial: 50,      // KB (gzipped)
+    lazy: 100,        // KB (gzipped)
+  },
+  images: {
+    hero: 200,        // KB
+    thumbnail: 20,    // KB
+    icon: 5,          // KB
+  },
+  total: {
+    initial: 500,     // KB (all assets)
+    full: 2000,       // KB (entire app)
+  }
+};
+```
+
+### 🎯 Optimization Checklist
+
+#### Code Optimization
+
+- [ ] Code splitting implemented
+- [ ] Lazy loading for routes
+- [ ] Tree shaking enabled
+- [ ] Dead code eliminated
+- [ ] Minification enabled
+- [ ] Compression (gzip/brotli)
+- [ ] Source maps in production
+
+#### Asset Optimization
+
+- [ ] Images optimized (WebP with fallback)
+- [ ] Responsive images (srcset)
+- [ ] Lazy loading images
+- [ ] SVG optimization
+- [ ] Font subsetting
+- [ ] Critical CSS inlined
+- [ ] Unused CSS removed
+
+#### Caching Strategy
+
+- [ ] Service Worker implemented
+- [ ] Cache headers configured
+- [ ] CDN for static assets
+- [ ] Browser cache utilized
+- [ ] API response caching
+- [ ] Database query caching
+
+#### Runtime Performance
+
+- [ ] Virtual scrolling for long lists
+- [ ] Debounced search inputs
+- [ ] Throttled scroll handlers
+- [ ] Web Workers for heavy computation
+- [ ] RequestAnimationFrame for animations
+- [ ] Avoid layout thrashing
+
+### 📊 Performance Monitoring
+
+```javascript
+// Performance monitoring setup
+const perfObserver = new PerformanceObserver((list) => {
+  for (const entry of list.getEntries()) {
+    // Log to analytics
+    analytics.track('performance', {
+      metric: entry.name,
+      value: entry.value,
+      page: window.location.pathname
+    });
+  }
+});
+
+// Observe all performance metrics
+perfObserver.observe({ 
+  entryTypes: ['navigation', 'resource', 'paint', 'measure'] 
+});
+```
+
+## Backend Performance Optimization
+
+### 🔄 API Optimization
+
+#### Response Time Optimization
+
+- [ ] Database connection pooling
+- [ ] Query optimization (EXPLAIN ANALYZE)
+- [ ] Proper indexing strategy
+- [ ] N+1 query prevention
+- [ ] Pagination implemented
+- [ ] Response compression
+- [ ] Field filtering (GraphQL/sparse fieldsets)
+
+#### Caching Layers
+
+```python
+# Caching hierarchy
+1. Browser Cache      → 0ms
+2. CDN Edge Cache    → 10-50ms
+3. Redis/Memcached   → 1-5ms
+4. Application Cache → 0.1ms
+5. Database Cache    → 5-10ms
+6. Database Query    → 10-100ms
+```
+
+#### Concurrency & Scaling
+
+- [ ] Async/await for I/O operations
+- [ ] Worker threads for CPU-intensive tasks
+- [ ] Queue for background jobs
+- [ ] Rate limiting per endpoint
+- [ ] Circuit breakers for external services
+- [ ] Load balancing configured
+- [ ] Auto-scaling policies
+
+### 📈 Database Optimization
+
+#### Query Optimization
+
+```sql
+-- Before optimization
+SELECT * FROM orders o
+JOIN users u ON o.user_id = u.id
+WHERE u.country = 'US';
+
+-- After optimization
+SELECT o.id, o.total, u.name
+FROM orders o
+JOIN users u ON o.user_id = u.id
+WHERE u.country = 'US'
+AND o.created_at > NOW() - INTERVAL '30 days'
+LIMIT 100;
+
+-- With proper indexes
+CREATE INDEX idx_users_country ON users(country);
+CREATE INDEX idx_orders_user_created ON orders(user_id, created_at DESC);
+```
+
+#### Index Strategy
+
+- [ ] Primary keys on all tables
+- [ ] Foreign key indexes
+- [ ] Composite indexes for common queries
+- [ ] Covering indexes for read-heavy queries
+- [ ] Partial indexes for filtered queries
+- [ ] Monitor index usage
+
+## Performance Testing
+
+### 🧪 Load Testing
+
+```javascript
+// Performance test scenarios
+const scenarios = {
+  baseline: {
+    users: 100,
+    duration: '5m',
+    rampUp: '30s'
+  },
+  stress: {
+    users: 1000,
+    duration: '15m',
+    rampUp: '2m'
+  },
+  spike: {
+    users: 5000,
+    duration: '10m',
+    rampUp: '10s'
+  },
+  endurance: {
+    users: 500,
+    duration: '2h',
+    rampUp: '5m'
+  }
+};
+```
+
+### 📏 Performance Benchmarks
+
+| Metric | Excellent | Good | Needs Work | Unacceptable |
+|--------|-----------|------|------------|---------------|
+| Page Load | < 1s | < 2s | < 3s | > 3s |
+| API Response | < 100ms | < 300ms | < 1s | > 1s |
+| Database Query | < 10ms | < 50ms | < 200ms | > 200ms |
+| CPU Usage | < 40% | < 60% | < 80% | > 80% |
+| Memory Usage | < 50% | < 70% | < 85% | > 85% |
+| Error Rate | < 0.1% | < 1% | < 5% | > 5% |
+
+## Performance Monitoring Tools
+
+### Frontend Monitoring
+
+```javascript
+// Real User Monitoring (RUM)
+- Google Analytics / GA4
+- New Relic Browser
+- Datadog RUM
+- Sentry Performance
+
+// Synthetic Monitoring
+- Lighthouse CI
+- WebPageTest
+- GTmetrix
+- SpeedCurve
+```
+
+### Backend Monitoring
+
+```yaml
+# APM Tools
+- New Relic APM
+- Datadog APM
+- AppDynamics
+- Elastic APM
+
+# Custom Metrics
+- Prometheus + Grafana
+- StatsD
+- CloudWatch (AWS)
+- Application Insights (Azure)
+```
+
+## Performance Budget Enforcement
+
+### CI/CD Integration
+
+```yaml
+# Performance gates in pipeline
+performance-check:
+  stage: test
+  script:
+    - lighthouse ci --budget=./budget.json
+    - bundlesize --max-size 200KB
+    - npm run test:performance
+  rules:
+    fail_on:
+      - lcp > 2500
+      - fid > 100
+      - cls > 0.1
+      - bundle_size > budget
+```
+
+### Performance Reviews
+
+#### Weekly Checks
+
+- [ ] Core Web Vitals trends
+- [ ] API response times
+- [ ] Error rates
+- [ ] Database slow query log
+
+#### Monthly Analysis
+
+- [ ] Performance regression analysis
+- [ ] User impact assessment
+- [ ] Infrastructure cost vs performance
+- [ ] Optimization opportunities
+
+## Quick Performance Wins
+
+### Immediate Improvements
+
+```bash
+# Frontend
+✅ Enable compression (gzip/brotli)
+✅ Add Cache-Control headers
+✅ Optimize images (WebP, lazy load)
+✅ Minify CSS/JS
+✅ Remove unused dependencies
+
+# Backend
+✅ Add database indexes
+✅ Enable query caching
+✅ Implement pagination
+✅ Use connection pooling
+✅ Add Redis caching
+
+# Infrastructure
+✅ Enable CDN
+✅ Configure auto-scaling
+✅ Optimize container size
+✅ Use HTTP/2
+✅ Enable keep-alive
+```
+
+## Performance Anti-Patterns
+
+### Things to Avoid
+
+```javascript
+// ❌ DON'T DO THIS
+- Synchronous API calls in loops
+- Unbounded queries (SELECT * without LIMIT)
+- Large DOM manipulations
+- Inline styles/scripts
+- Blocking resources in <head>
+- Memory leaks (event listeners, timers)
+- N+1 database queries
+- Premature optimization
+
+// ✅ DO THIS INSTEAD
+- Batch API calls
+- Paginate large datasets
+- Virtual DOM / React
+- External stylesheets
+- Async/defer scripts
+- Cleanup in useEffect/componentWillUnmount
+- Eager loading with includes
+- Measure first, optimize second
+```
+
+## Performance Culture
+
+### Team Responsibilities
+
+#### Developers
+
+- Write performant code
+- Test performance locally
+- Monitor PR impact
+
+#### DevOps
+
+- Infrastructure optimization
+- Monitoring setup
+- Scaling policies
+
+#### Product
+
+- Define performance requirements
+- Prioritize performance work
+- Balance features vs speed
+
+### Performance Reviews
+
+- Include performance in code reviews
+- Regular performance audits
+- Performance retrospectives
+- Celebrate performance wins
+
+## Remember
+
+**Every millisecond counts.**
+
+- 100ms delay → 1% drop in sales
+- 1 second delay → 7% reduction in conversions
+- 3 seconds load → 53% mobile users leave
+
+**Performance is not a one-time task—it's a continuous process.**

package/packages/plugin-core/rules/pipeline-mandatory.md

@@ -0,0 +1,109 @@
+# Mandatory Pipeline Execution
+
+> **CRITICAL**: These pipelines are MANDATORY for specific scenarios. No exceptions.
+
+## 1. ERROR HANDLING PIPELINE
+
+**Trigger**: ANY error encountered
+**Sequence**:
+
+```
+1. code-analyzer → Identify root cause and affected files
+2. code-analyzer → Implement fix following TDD:
+   - Write failing test (RED)
+   - Implement minimum code to pass (GREEN)
+   - Refactor while tests pass (REFACTOR)
+3. test-runner → Verify fix across entire codebase
+4. file-analyzer → Document fix in error log
+5. Update CLAUDE.md with new error pattern
+```
+
+## 2. FEATURE IMPLEMENTATION PIPELINE
+
+**Trigger**: Any new feature request
+**Sequence**:
+
+```
+1. /pm:issue-analyze → Decompose into work streams
+2. parallel-worker → Spawn sub-agents for each stream:
+   - Write failing tests first (RED phase)
+   - Implement minimal solution (GREEN phase)
+   - Refactor for quality (REFACTOR phase)
+3. test-runner → Run full test suite
+4. code-analyzer → Review for bugs and edge cases
+5. Update README.md with feature documentation
+6. Update CLAUDE.md with new patterns learned
+```
+
+## 3. BUG FIX PIPELINE
+
+**Trigger**: Bug reported or discovered
+**Sequence**:
+
+```
+1. code-analyzer → Trace bug through codebase
+2. Write test that reproduces bug (must fail)
+3. code-analyzer → Implement fix
+4. test-runner → Verify fix doesn't break other tests
+5. test-runner → Run regression tests
+6. Document bug pattern in CLAUDE.md
+```
+
+## 4. CODE SEARCH/RESEARCH PIPELINE
+
+**Trigger**: Any code exploration need
+**Sequence**:
+
+```
+1. code-analyzer → Initial search and analysis
+2. file-analyzer → Summarize findings
+3. Never use grep/find directly - always use agents
+```
+
+## 5. LOG/OUTPUT ANALYSIS PIPELINE
+
+**Trigger**: Verbose outputs or logs to analyze
+**Sequence**:
+
+```
+1. file-analyzer → Extract critical information
+2. Return only actionable insights (10-20% of original)
+3. Never dump raw logs to main conversation
+```
+
+## 6. EMERGENCY DEBUG PIPELINE
+
+**Trigger**: Critical blocker or production issue
+**Sequence**:
+
+```
+1. /pm:blocked → Document blocker
+2. code-analyzer → Trace bug through codebase
+3. Write failing test → Reproduce issue (RED)
+4. Fix implementation → Make test pass (GREEN)
+5. test-runner → Verify no regressions
+6. /pm:issue-close → Mark resolved
+```
+
+## Pipeline Bypass Violations
+
+### NEVER ALLOWED
+
+- ❌ Skipping any step in a pipeline
+- ❌ Using direct commands instead of agents
+- ❌ Implementing without the required pipeline
+- ❌ Merging code without pipeline completion
+
+### Enforcement
+
+- Pipelines are atomic - all steps or none
+- Each step must complete before next
+- Failures require pipeline restart
+- No manual overrides permitted
+
+## Success Verification
+
+- Pipeline completion logged
+- All agents return success codes
+- Tests pass at pipeline end
+- Documentation updated as required