specweave 0.23.18 → 0.24.0

package/plugins/specweave-core/commands/refactor-plan.md

@@ -0,0 +1,249 @@
+# /specweave-core:refactor-plan
+
+Generate comprehensive refactoring plans with risk assessment, step-by-step execution, and rollback strategies.
+
+You are an expert software architect who plans safe, incremental refactoring strategies.
+
+## Your Task
+
+Create detailed refactoring plans that minimize risk while improving code quality.
+
+### 1. Refactoring Patterns
+
+**Extract Method**:
+```typescript
+// Before: Long function with multiple responsibilities
+function processOrder(order: Order) {
+  // 50 lines of validation
+  // 30 lines of calculation
+  // 40 lines of persistence
+}
+
+// After: Small, focused functions
+function processOrder(order: Order) {
+  validateOrder(order);
+  const total = calculateTotal(order);
+  saveOrder(order, total);
+}
+```
+
+**Extract Class**:
+```typescript
+// Before: God class
+class User {
+  // User properties
+  // Email sending logic
+  // Password hashing logic
+  // Notification logic
+}
+
+// After: Single responsibility
+class User { /* core user data */ }
+class EmailService { /* email logic */ }
+class PasswordHasher { /* password logic */ }
+class NotificationService { /* notifications */ }
+```
+
+**Replace Conditional with Polymorphism**:
+```typescript
+// Before: Switch statements
+function calculateShipping(type: string, weight: number) {
+  switch (type) {
+    case 'express': return weight * 5;
+    case 'standard': return weight * 2;
+    case 'economy': return weight * 1;
+  }
+}
+
+// After: Strategy pattern
+interface ShippingStrategy {
+  calculate(weight: number): number;
+}
+
+class ExpressShipping implements ShippingStrategy {
+  calculate(weight: number) { return weight * 5; }
+}
+```
+
+**Introduce Parameter Object**:
+```typescript
+// Before: Long parameter lists
+function createUser(name: string, email: string, age: number, address: string, phone: string)
+
+// After: Parameter object
+interface UserData {
+  name: string;
+  email: string;
+  age: number;
+  address: string;
+  phone: string;
+}
+
+function createUser(data: UserData)
+```
+
+### 2. Refactoring Plan Template
+
+```markdown
+## Refactoring Plan: Extract Payment Processing
+
+### Current State
+- 500-line PaymentController with mixed responsibilities
+- Tightly coupled to database layer
+- No unit tests (integration tests only)
+- Duplicate payment validation logic in 3 places
+
+### Target State
+- Payment domain services (validation, processing, reconciliation)
+- Repository pattern for data access
+- 80%+ unit test coverage
+- Single source of truth for validation
+
+### Risk Assessment
+**Risk Level**: Medium
+
+**Risks**:
+1. Breaking existing payment flows (HIGH IMPACT)
+2. Race conditions in concurrent payments (MEDIUM)
+3. Performance regression (LOW)
+
+**Mitigation**:
+1. Feature flag + parallel run (old + new code)
+2. Transaction isolation + row-level locking
+3. Performance testing before rollout
+
+### Prerequisites
+- [ ] 100% integration test coverage of current behavior
+- [ ] Performance baseline established
+- [ ] Database migrations prepared
+- [ ] Rollback plan documented
+- [ ] Team review and approval
+
+### Execution Steps (10 steps, 2 weeks)
+
+**Week 1: Preparation + Safe Extractions**
+
+**Step 1** (Day 1): Add comprehensive integration tests
+- Test all payment flows
+- Test error scenarios
+- Test edge cases (concurrent payments, retries)
+
+**Step 2** (Day 2): Extract validation logic
+- Create PaymentValidator class
+- Move validation from controller
+- Tests: unit tests for validator
+- **Safe**: Pure functions, no state changes
+
+**Step 3** (Day 3): Extract payment processing
+- Create PaymentProcessor service
+- Move core processing logic
+- Tests: unit tests with mocks
+- **Safe**: Existing controller calls new service
+
+**Week 2: Risky Changes + Rollout**
+
+**Step 7** (Day 8): Introduce repository pattern
+- Create PaymentRepository interface
+- Implement with existing DB calls
+- **Risk**: Data access changes
+- **Mitigation**: Feature flag, parallel run
+
+**Step 10** (Day 10): Final cutover
+- Enable new code for 100% traffic
+- Monitor for 48 hours
+- Remove old code if stable
+
+### Testing Strategy
+- Unit tests: 80%+ coverage
+- Integration tests: All payment flows
+- Load testing: 2x expected peak traffic
+- Canary deployment: 1% → 10% → 50% → 100%
+
+### Rollback Plan
+- Feature flag: Instant rollback to old code
+- Database: Backward-compatible migrations
+- Monitoring: Alert on error rate > 0.1%
+- Rollback trigger: Any payment processing failure
+
+### Success Metrics
+- ✅ All tests passing
+- ✅ Code coverage > 80%
+- ✅ Performance within 10% of baseline
+- ✅ Zero production incidents
+- ✅ Team velocity unchanged
+```
+
+### 3. Safety Strategies
+
+**Strangler Fig Pattern**:
+```typescript
+// Gradually replace old system
+class PaymentController {
+  async processPayment(order: Order) {
+    if (featureFlags.newPaymentFlow) {
+      return newPaymentService.process(order); // New code
+    } else {
+      return legacyPaymentLogic(order); // Old code
+    }
+  }
+}
+```
+
+**Parallel Run**:
+```typescript
+// Run both old and new, compare results
+async function processPayment(order: Order) {
+  const oldResult = await legacyPayment(order);
+  
+  // Run new code in background, don't block
+  backgroundTask(async () => {
+    const newResult = await newPayment(order);
+    if (!isEqual(oldResult, newResult)) {
+      logger.warn('Payment results differ', { old: oldResult, new: newResult });
+    }
+  });
+  
+  return oldResult; // Use old result (safe)
+}
+```
+
+### 4. Code Smell Prioritization
+
+**High Priority** (Security/Bugs):
+- Null reference errors
+- Memory leaks
+- Race conditions
+- Security vulnerabilities
+
+**Medium Priority** (Maintainability):
+- God classes (> 500 lines)
+- Long functions (> 50 lines)
+- Cyclomatic complexity > 10
+- Code duplication (> 5 instances)
+
+**Low Priority** (Cleanup):
+- Dead code
+- Unused imports
+- TODOs
+- Console.log statements
+
+### 5. Workflow
+
+1. **Identify Target**: What needs refactoring?
+2. **Assess Risk**: Impact analysis
+3. **Create Plan**: Step-by-step breakdown
+4. **Get Buy-in**: Team review
+5. **Prepare**: Tests, baselines, migrations
+6. **Execute**: Incremental changes
+7. **Monitor**: Metrics, alerts
+8. **Document**: Update architecture docs
+
+## When to Use
+
+- Planning large-scale refactoring
+- Improving legacy codebases
+- Reducing technical debt
+- Preparing for new features
+- Post-incident code improvements
+
+Refactor safely with detailed planning!

package/plugins/specweave-core/skills/code-quality/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: code-quality
+description: Expert code quality engineering covering clean code principles, SOLID, DRY, KISS, YAGNI, code smells, refactoring patterns, static analysis, linting, code coverage, mutation testing, and software craftsmanship. Activates for code quality, clean code, SOLID principles, code smells, refactoring, technical debt, code review, linting, eslint, prettier, static analysis, code coverage.
+---
+
+# Code Quality Expert
+
+Master of clean code principles, SOLID, and software craftsmanship.
+
+## SOLID Principles
+
+**Single Responsibility**:
+```typescript
+// ❌ Bad: Multiple responsibilities
+class User {
+  save() { /* database logic */ }
+  sendEmail() { /* email logic */ }
+  hashPassword() { /* crypto logic */ }
+}
+
+// ✅ Good: Single responsibility
+class User { /* user data only */ }
+class UserRepository { save(user: User) {} }
+class EmailService { send(to: string, message: string) {} }
+class PasswordHasher { hash(password: string) {} }
+```
+
+**Open/Closed**:
+```typescript
+// ✅ Open for extension, closed for modification
+interface PaymentMethod {
+  processPayment(amount: number): Promise<void>;
+}
+
+class CreditCardPayment implements PaymentMethod {
+  async processPayment(amount: number) { /* ... */ }
+}
+
+class PayPalPayment implements PaymentMethod {
+  async processPayment(amount: number) { /* ... */ }
+}
+
+// Add new payment methods without modifying existing code
+```
+
+**Liskov Substitution**:
+```typescript
+// Subtypes must be substitutable for base types
+class Bird {
+  fly() { /* ... */ }
+}
+
+// ❌ Bad: Penguin can't fly, violates LSP
+class Penguin extends Bird {
+  fly() { throw new Error('Cannot fly'); }
+}
+
+// ✅ Good: Proper abstraction
+interface Bird {}
+interface FlyingBird extends Bird { fly(): void; }
+class Sparrow implements FlyingBird { fly() {} }
+class Penguin implements Bird {} // No fly method
+```
+
+**Interface Segregation**:
+```typescript
+// ❌ Bad: Fat interface
+interface Worker {
+  work(): void;
+  eat(): void;
+  sleep(): void;
+}
+
+// ✅ Good: Segregated interfaces
+interface Workable { work(): void; }
+interface Eatable { eat(): void; }
+interface Sleepable { sleep(): void; }
+
+class Human implements Workable, Eatable, Sleepable {}
+class Robot implements Workable {} // Doesn't need eat/sleep
+```
+
+**Dependency Inversion**:
+```typescript
+// ❌ Bad: High-level depends on low-level
+class EmailService {
+  private smtp = new SMTPClient(); // Direct dependency
+}
+
+// ✅ Good: Depend on abstraction
+interface EmailClient {
+  send(to: string, message: string): Promise<void>;
+}
+
+class EmailService {
+  constructor(private client: EmailClient) {}
+}
+```
+
+## Clean Code Principles
+
+**DRY (Don't Repeat Yourself)**:
+```typescript
+// ❌ Duplication
+function validateEmail(email: string) {
+  return /^\S+@\S+\.\S+$/.test(email);
+}
+function validateUserEmail(email: string) {
+  return /^\S+@\S+\.\S+$/.test(email); // Duplicate
+}
+
+// ✅ Single source of truth
+const EMAIL_REGEX = /^\S+@\S+\.\S+$/;
+const isValidEmail = (email: string) => EMAIL_REGEX.test(email);
+```
+
+**KISS (Keep It Simple)**:
+```typescript
+// ❌ Over-engineered
+class AdvancedCalculatorFactoryBuilderSingleton {
+  private static instance: AdvancedCalculatorFactoryBuilderSingleton;
+  // 50 lines of unnecessary abstraction
+}
+
+// ✅ Simple
+const add = (a: number, b: number) => a + b;
+```
+
+**YAGNI (You Aren't Gonna Need It)**:
+```typescript
+// ❌ Premature abstraction
+class User {
+  futureFeature1() {} // Not used yet
+  futureFeature2() {} // Not used yet
+  futureFeature3() {} // Not used yet
+}
+
+// ✅ Only what's needed now
+class User {
+  getCurrentFeatures() {} // Actually used
+}
+```
+
+## Code Smells
+
+**Long Method**: > 50 lines → Extract methods
+**Large Class**: > 300 lines → Extract classes
+**Long Parameter List**: > 3 params → Parameter object
+**Primitive Obsession**: Use value objects
+**Data Clumps**: Group related data
+**Switch Statements**: Replace with polymorphism
+
+## Testing Strategies
+
+**Test Coverage**: 80%+ for critical paths
+**Mutation Testing**: Ensure test quality
+**Test Pyramid**: Many unit, few integration, minimal E2E

package/plugins/specweave-core/skills/design-patterns/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: design-patterns
+description: Expert knowledge of Gang of Four (GoF) design patterns including creational (Singleton, Factory, Builder, Prototype), structural (Adapter, Decorator, Proxy, Facade), and behavioral (Strategy, Observer, Command, Template Method, Chain of Responsibility). Modern TypeScript/JavaScript implementations with real-world use cases. Activates for design patterns, factory pattern, singleton, strategy pattern, observer pattern, decorator pattern, adapter pattern, builder pattern, proxy pattern, facade pattern, template method.
+---
+
+# Design Patterns Expert
+
+Master of GoF design patterns with modern TypeScript implementations.
+
+## Creational Patterns
+
+**Factory Pattern**:
+```typescript
+interface Animal {
+  speak(): string;
+}
+
+class Dog implements Animal {
+  speak() { return 'Woof!'; }
+}
+
+class Cat implements Animal {
+  speak() { return 'Meow!'; }
+}
+
+class AnimalFactory {
+  static create(type: 'dog' | 'cat'): Animal {
+    switch (type) {
+      case 'dog': return new Dog();
+      case 'cat': return new Cat();
+    }
+  }
+}
+```
+
+**Singleton Pattern**:
+```typescript
+class Database {
+  private static instance: Database;
+  
+  private constructor() {} // Private constructor
+  
+  static getInstance(): Database {
+    if (!Database.instance) {
+      Database.instance = new Database();
+    }
+    return Database.instance;
+  }
+}
+```
+
+**Builder Pattern**:
+```typescript
+class UserBuilder {
+  private user: Partial<User> = {};
+  
+  setName(name: string) {
+    this.user.name = name;
+    return this;
+  }
+  
+  setEmail(email: string) {
+    this.user.email = email;
+    return this;
+  }
+  
+  build(): User {
+    if (!this.user.name || !this.user.email) {
+      throw new Error('Missing required fields');
+    }
+    return this.user as User;
+  }
+}
+
+// Usage
+const user = new UserBuilder()
+  .setName('John')
+  .setEmail('john@example.com')
+  .build();
+```
+
+## Structural Patterns
+
+**Adapter Pattern**:
+```typescript
+// Old API
+class OldLogger {
+  logMessage(message: string) { console.log(message); }
+}
+
+// New interface
+interface Logger {
+  log(level: string, message: string): void;
+}
+
+// Adapter
+class LoggerAdapter implements Logger {
+  constructor(private oldLogger: OldLogger) {}
+  
+  log(level: string, message: string) {
+    this.oldLogger.logMessage(`[${level}] ${message}`);
+  }
+}
+```
+
+**Decorator Pattern**:
+```typescript
+interface Coffee {
+  cost(): number;
+  description(): string;
+}
+
+class SimpleCoffee implements Coffee {
+  cost() { return 5; }
+  description() { return 'Simple coffee'; }
+}
+
+class MilkDecorator implements Coffee {
+  constructor(private coffee: Coffee) {}
+  
+  cost() { return this.coffee.cost() + 2; }
+  description() { return this.coffee.description() + ', milk'; }
+}
+
+// Usage
+let coffee: Coffee = new SimpleCoffee();
+coffee = new MilkDecorator(coffee);
+coffee.cost(); // 7
+```
+
+**Proxy Pattern**:
+```typescript
+class RealImage {
+  constructor(private filename: string) {
+    this.loadFromDisk();
+  }
+  
+  private loadFromDisk() {
+    console.log('Loading:', this.filename);
+  }
+  
+  display() {
+    console.log('Displaying:', this.filename);
+  }
+}
+
+class ProxyImage {
+  private realImage?: RealImage;
+  
+  constructor(private filename: string) {}
+  
+  display() {
+    if (!this.realImage) {
+      this.realImage = new RealImage(this.filename); // Lazy loading
+    }
+    this.realImage.display();
+  }
+}
+```
+
+## Behavioral Patterns
+
+**Strategy Pattern**:
+```typescript
+interface SortStrategy {
+  sort(data: number[]): number[];
+}
+
+class QuickSort implements SortStrategy {
+  sort(data: number[]) { /* quicksort */ return data; }
+}
+
+class MergeSort implements SortStrategy {
+  sort(data: number[]) { /* mergesort */ return data; }
+}
+
+class Sorter {
+  constructor(private strategy: SortStrategy) {}
+  
+  setStrategy(strategy: SortStrategy) {
+    this.strategy = strategy;
+  }
+  
+  sort(data: number[]) {
+    return this.strategy.sort(data);
+  }
+}
+```
+
+**Observer Pattern**:
+```typescript
+interface Observer {
+  update(data: any): void;
+}
+
+class Subject {
+  private observers: Observer[] = [];
+  
+  attach(observer: Observer) {
+    this.observers.push(observer);
+  }
+  
+  notify(data: any) {
+    this.observers.forEach(o => o.update(data));
+  }
+}
+
+class EmailObserver implements Observer {
+  update(data: any) {
+    console.log('Sending email:', data);
+  }
+}
+```
+
+**Command Pattern**:
+```typescript
+interface Command {
+  execute(): void;
+  undo(): void;
+}
+
+class SaveCommand implements Command {
+  constructor(private editor: Editor) {}
+  
+  execute() { this.editor.save(); }
+  undo() { this.editor.restore(); }
+}
+
+class CommandInvoker {
+  private history: Command[] = [];
+  
+  execute(command: Command) {
+    command.execute();
+    this.history.push(command);
+  }
+  
+  undo() {
+    const command = this.history.pop();
+    command?.undo();
+  }
+}
+```
+
+Apply design patterns to solve common problems elegantly!