devflow-kit 0.8.1 → 1.0.0

package/plugins/devflow-self-review/skills/core-patterns/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: core-patterns
+description: This skill should be used when the user asks to "handle errors", "inject dependencies", "return Result", "make it immutable", "compose with pipes", or implements business logic, error handling, or service composition. Provides Result type patterns, dependency injection, immutability by default, pipe composition, and structured logging for robust application architecture.
+user-invocable: false
+allowed-tools: Read, Grep, Glob, AskUserQuestion
+---
+
+# Core Engineering Patterns
+
+The canonical source of architectural patterns and principles for consistent, high-quality code.
+
+## Iron Law
+
+> **NEVER THROW IN BUSINESS LOGIC**
+>
+> All operations that can fail MUST return Result types. Exceptions are allowed
+> ONLY at system boundaries (API handlers, database adapters). Any `throw` statement
+> in business logic is a violation. No exceptions.
+
+## Philosophy
+
+1. **Type Safety First** - Strict type checking, avoid dynamic types
+2. **Functional Core, Imperative Shell** - Business logic pure, side effects isolated
+3. **Explicit Error Handling** - Result types instead of exceptions
+4. **Immutability by Default** - Return new objects, don't mutate
+5. **Dependency Injection** - Inject dependencies for testability
+6. **Test Behaviors** - Simple tests that validate behavior, not implementation
+7. **No Fake Solutions** - Be honest about limitations and workarounds
+8. **Fix Root Causes** - Never work around bad architecture
+
+---
+
+## Pattern 1: Result Types
+
+```typescript
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+function createUser(data: unknown): Result<User, ValidationError> {
+  if (!valid(data)) return Err({ type: 'ValidationFailed', details: validate(data).errors });
+  return Ok(buildUser(data));
+}
+```
+
+## Pattern 2: Dependency Injection
+
+```typescript
+class UserService {
+  constructor(private db: Database, private emailer: EmailService) {}
+}
+// Easy to test: new UserService(mockDb, mockEmailer)
+```
+
+Never: `private db = new Database()` - can't mock.
+
+## Pattern 3: Immutability
+
+```typescript
+function updateUser(user: User, changes: Partial<User>): User {
+  return { ...user, ...changes };  // New object, no mutation
+}
+```
+
+Never mutate inputs. Copy before `.sort()`.
+
+## Pattern 4: Pure Functions
+
+```typescript
+function calculateTotal(items: Item[], taxRate: number): number {
+  return items.reduce((sum, i) => sum + i.price, 0) * (1 + taxRate);
+}
+```
+
+No side effects in pure functions.
+
+## Pattern 5: Type Safety
+
+```typescript
+type Status = 'pending' | 'completed' | 'failed';
+function handleStatus(status: Status): string {
+  switch (status) {
+    case 'pending': return 'Waiting';
+    case 'completed': return 'Done';
+    case 'failed': return 'Error';
+  }  // Exhaustive - no default needed
+}
+```
+
+## Pattern 6: Error Type Design
+
+```typescript
+type UserError =
+  | { type: 'NotFound'; userId: string }
+  | { type: 'ValidationFailed'; field: string; message: string };
+```
+
+## Pattern 7: Resource Cleanup
+
+```typescript
+const handle = await fs.open(path);
+try {
+  return Ok(parse(await handle.readFile()));
+} finally {
+  await handle.close();
+}
+```
+
+## Pattern 8: Architecture Documentation
+
+```typescript
+// ARCHITECTURE: Repository returns domain objects only
+// ARCHITECTURE EXCEPTION: Direct DB for health check - must work if service layer down
+```
+
+## Pattern 9: Naming Conventions
+
+- **Types/Classes**: PascalCase (`UserProfile`)
+- **Functions/Variables**: camelCase (`calculateTotal`)
+- **Constants**: SCREAMING_SNAKE_CASE (`MAX_RETRY`)
+
+## Pattern 10: Performance Awareness
+
+```typescript
+const customerMap = new Map(customers.map(c => [c.id, c]));  // O(1) vs O(n)
+```
+
+---
+
+## Consistency Rules
+
+- Result types: if one method returns Result, ALL must
+- DI: apply consistently throughout
+- Async: single pattern (don't mix callbacks/promises)
+
+## Anti-Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| Fake Solutions | Hardcoded responses simulating functionality |
+| Silent Failures | Catch blocks that swallow errors |
+| Magic Values | Unlabeled constants with special meaning |
+| Deceptive Code | Functions that pretend to work (e.g., `return true` with no logic) |
+
+### Workaround Labeling (Required)
+
+All workarounds, hacks, and temporary solutions MUST be labeled:
+
+| Label | Use When |
+|-------|----------|
+| `HACK:` | Workaround for specific problem |
+| `MOCK:` | Fake data for testing/development |
+| `TODO:` | Work that needs to be done |
+| `TEMPORARY:` | Short-term solution with deadline |
+| `NOT-PRODUCTION:` | Code that should never ship |
+| `ARCHITECTURE EXCEPTION:` | Violates pattern with justification |
+
+Unlabeled workarounds, empty catch blocks, and early returns without rationale are violations. See `references/code-smell-violations.md` for extended examples.
+
+---
+
+## Extended References
+
+See `references/` for: violations.md, patterns.md, detection.md, checklist.md

package/plugins/devflow-self-review/skills/core-patterns/references/checklist.md

@@ -0,0 +1,276 @@
+# Validation Checklist
+
+Comprehensive checklist for code review and validation against core engineering patterns.
+
+---
+
+## Pre-Implementation Checklist
+
+Before writing code, verify:
+
+- [ ] Understood the existing patterns in the codebase
+- [ ] Identified similar implementations to follow
+- [ ] Determined if Result types are used (and will follow same pattern)
+- [ ] Identified dependencies that need injection
+- [ ] Planned separation of pure logic from side effects
+
+---
+
+## Result Types Checklist
+
+### Functions That Can Fail
+
+- [ ] All business functions return `Result<T, E>` types
+- [ ] No `throw` statements in business logic
+- [ ] Error types are discriminated unions (not generic Error)
+- [ ] Each error type has all context needed to handle it
+- [ ] Async functions return `Promise<Result<T, E>>`
+
+### Exception Boundaries
+
+- [ ] Try/catch ONLY at system boundaries (API handlers, DB adapters)
+- [ ] Boundaries convert exceptions to Result types
+- [ ] HTTP responses derived from Result errors
+- [ ] No silent error swallowing (empty catch blocks)
+
+### Error Handling
+
+- [ ] All Result errors are handled explicitly
+- [ ] No `if (!result.ok) return;` without proper handling
+- [ ] Error propagation preserves context
+- [ ] Logging happens before converting errors
+
+---
+
+## Dependency Injection Checklist
+
+### Constructor Injection
+
+- [ ] All dependencies passed through constructor
+- [ ] No `new` keyword for dependencies inside classes
+- [ ] No imported singletons used directly
+- [ ] No static method calls on external services
+
+### Interfaces
+
+- [ ] Dependencies typed as interfaces, not implementations
+- [ ] Interfaces are small and focused (ISP)
+- [ ] Mock implementations easy to create
+- [ ] No concrete class imports in business logic
+
+### Testing
+
+- [ ] Can instantiate class with mock dependencies
+- [ ] No test requires real database/network
+- [ ] No environment manipulation in tests
+- [ ] Test setup is < 10 lines
+
+---
+
+## Immutability Checklist
+
+### Objects
+
+- [ ] All updates return new objects (spread operator)
+- [ ] No direct property assignment on inputs
+- [ ] No `delete` operator on inputs
+- [ ] Nested updates also create new objects
+
+### Arrays
+
+- [ ] No `.push()`, `.pop()`, `.shift()`, `.unshift()`
+- [ ] No `.splice()`, `.reverse()`, `.sort()` on originals
+- [ ] Use `.map()`, `.filter()`, `.reduce()` for transformations
+- [ ] Copy before sorting: `[...arr].sort()`
+
+### State
+
+- [ ] No module-level `let` or `var`
+- [ ] No global mutable state
+- [ ] Configuration is frozen after initialization
+- [ ] Caches use immutable entries
+
+---
+
+## Pure Functions Checklist
+
+### Business Logic
+
+- [ ] Pure functions have no side effects
+- [ ] Same input always produces same output
+- [ ] No date/time access (inject clock)
+- [ ] No random values (inject generator)
+- [ ] No environment variable access
+
+### Side Effect Isolation
+
+- [ ] I/O operations in wrapper functions
+- [ ] Pure calculations extracted and tested separately
+- [ ] Side effects clearly documented
+- [ ] Logging/metrics in wrappers, not core logic
+
+### Dependencies
+
+- [ ] Time/random injected as dependencies
+- [ ] Environment config loaded once at startup
+- [ ] File system access at boundaries only
+- [ ] Network calls at boundaries only
+
+---
+
+## Type Safety Checklist
+
+### Strict Types
+
+- [ ] No `any` types (use `unknown` for dynamic data)
+- [ ] All function parameters typed
+- [ ] All return types explicit
+- [ ] Strict null checks enabled
+
+### Pattern Matching
+
+- [ ] Switch statements are exhaustive
+- [ ] Discriminated unions for state/variants
+- [ ] No default case that hides missing patterns
+- [ ] Type guards for runtime narrowing
+
+### Type Design
+
+- [ ] Domain types prevent primitive obsession
+- [ ] Branded types for IDs that shouldn't mix
+- [ ] Optional fields explicit (`field?: Type`)
+- [ ] Readonly where appropriate
+
+---
+
+## Error Type Design Checklist
+
+### Discriminated Unions
+
+- [ ] Each error type has a `type` discriminator
+- [ ] Error types include all context needed
+- [ ] Related errors grouped in union types
+- [ ] Error unions are exhaustive
+
+### Error Information
+
+- [ ] Error messages are actionable
+- [ ] Technical details preserved for logging
+- [ ] User-facing messages are sanitized
+- [ ] Error codes are unique and documented
+
+---
+
+## Resource Cleanup Checklist
+
+### File/Connection Handling
+
+- [ ] All file handles closed in `finally`
+- [ ] All connections released in `finally`
+- [ ] Using context managers (Python) or `using` (TS)
+- [ ] Pool resources released after use
+
+### Subscriptions/Timers
+
+- [ ] Event listeners removed on cleanup
+- [ ] Intervals cleared when done
+- [ ] Timeouts cleared if operation completes early
+- [ ] Subscription manager for complex lifecycles
+
+### Memory
+
+- [ ] Large data structures released when done
+- [ ] Caches have size limits or TTL
+- [ ] Circular references avoided
+- [ ] WeakMap/WeakSet for object keys
+
+---
+
+## API Consistency Checklist
+
+### Error Handling Pattern
+
+- [ ] Same error handling pattern across module
+- [ ] All methods return Result OR all throw (not mixed)
+- [ ] Error types consistent across related methods
+- [ ] HTTP error mapping centralized
+
+### Async Pattern
+
+- [ ] Single async pattern (async/await preferred)
+- [ ] No mixing callbacks and promises
+- [ ] All async calls awaited (no fire-and-forget)
+- [ ] Promise.all for parallel operations
+
+### Naming
+
+- [ ] Consistent naming across codebase
+- [ ] PascalCase for types/classes
+- [ ] camelCase for functions/variables
+- [ ] SCREAMING_SNAKE_CASE for constants
+
+---
+
+## Architecture Documentation Checklist
+
+### Code Comments
+
+- [ ] Public APIs have JSDoc/docstrings
+- [ ] Complex algorithms explained
+- [ ] Non-obvious decisions documented
+- [ ] Architecture boundaries marked
+
+### Exceptions/Workarounds
+
+- [ ] All workarounds labeled (HACK:, TODO:, TEMPORARY:)
+- [ ] Architecture exceptions have justification
+- [ ] Technical debt has tracking ticket
+- [ ] Deadlines on temporary solutions
+
+---
+
+## Performance Checklist
+
+### Measurement
+
+- [ ] Performance claims have benchmarks
+- [ ] Hot paths identified and measured
+- [ ] No premature optimization
+- [ ] Trade-offs documented
+
+### Common Issues
+
+- [ ] No N+1 queries
+- [ ] Appropriate data structures (Map vs Array)
+- [ ] Lazy evaluation for expensive operations
+- [ ] Batch operations where possible
+
+---
+
+## Anti-Pattern Checklist
+
+Verify NONE of these exist:
+
+- [ ] No hardcoded responses simulating functionality
+- [ ] No silent error swallowing
+- [ ] No unlabeled magic values
+- [ ] No global mutable state
+- [ ] No tight coupling to concrete implementations
+- [ ] No mixing error handling patterns
+- [ ] No fire-and-forget async calls
+- [ ] No resource leaks
+
+---
+
+## Final Review Checklist
+
+Before considering code complete:
+
+- [ ] All tests pass
+- [ ] No TypeScript errors
+- [ ] No ESLint warnings
+- [ ] Code matches existing patterns
+- [ ] Documentation updated
+- [ ] No TODO without ticket
+- [ ] No console.log in production code
+- [ ] No commented-out code

package/plugins/devflow-self-review/skills/core-patterns/references/code-smell-violations.md

@@ -0,0 +1,144 @@
+# Code Smell Violations Reference
+
+Extended examples of fake solutions, unlabeled workarounds, deceptive code, and magic values. Absorbed from the former `code-smell` skill into `core-patterns`.
+
+---
+
+## 1. Hardcoded Data (FAKE SOLUTIONS)
+
+### Violation: Mock data masquerading as real functionality
+
+```typescript
+async function fetchRecommendations(userId: string): Promise<Product[]> {
+  // TODO: Connect to recommendation engine
+  return [
+    { id: "1", name: "Product 1", price: 99.99 },
+    { id: "2", name: "Product 2", price: 149.99 }
+  ];
+}
+```
+
+**Problem**: Returns static data instead of fetching from actual service.
+
+### Correct: Honest implementation with Result type
+
+```typescript
+async function getUserProfile(userId: string): Promise<Result<UserProfile, Error>> {
+  try {
+    const response = await api.get(`/users/${userId}`);
+    return { ok: true, value: response.data };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+```
+
+### Correct: Clearly labeled mock for testing
+
+```typescript
+// MOCK: For development only, not production-ready
+async function getUserProfileMock(userId: string): Promise<UserProfile> {
+  return { id: userId, name: "Test User", email: "test@example.com" };
+}
+```
+
+---
+
+## 2. Missing Labels (UNDOCUMENTED WORKAROUNDS)
+
+### Violation: Temporary fix without documentation
+
+```typescript
+async function syncData() {
+  await sleep(1000); // Wait for previous operation
+  await performSync();
+}
+```
+
+### Correct: Clearly labeled workaround
+
+```typescript
+function processPayment(amount: number): boolean {
+  // TEMPORARY: Validation disabled until payment gateway integration complete
+  // TODO: Add amount validation, currency checks, fraud detection
+  // Target: Sprint 23 (2025-11-15)
+  // Ticket: PAY-456
+  return true;
+}
+```
+
+### Correct: Documented hack with rationale
+
+```typescript
+async function syncData() {
+  // HACK: Sleep required due to race condition in legacy sync system
+  // Root cause: Event system doesn't guarantee order
+  // Proper fix: Implement event sequencing (3-week effort)
+  await sleep(1000);
+  await performSync();
+}
+```
+
+---
+
+## 3. Fake Functionality (DECEPTIVE CODE)
+
+### Violation: Fake error handling
+
+```typescript
+async function sendEmail(to: string, subject: string, body: string): Promise<void> {
+  try {
+    // TODO: Implement SMTP
+    console.log(`Email sent to ${to}`);
+  } catch (error) {
+    // Ignore errors
+  }
+}
+```
+
+### Correct: Honest unimplemented function
+
+```typescript
+function validateEmail(email: string): Result<boolean, Error> {
+  return {
+    ok: false,
+    error: new Error('NOT-IMPLEMENTED: Email validation pending regex pattern approval')
+  };
+}
+```
+
+---
+
+## 4. Magic Values (UNEXPLAINED CONSTANTS)
+
+### Violation: Magic numbers
+
+```typescript
+function calculateDiscount(price: number, userLevel: number): number {
+  if (userLevel >= 5) return price * 0.15;
+  return 0;
+}
+```
+
+### Correct: Named constants with documentation
+
+```typescript
+const USER_LEVEL_THRESHOLD = { PREMIUM: 5 } as const;
+const DISCOUNT_RATE = { PREMIUM: 0.15 } as const;
+
+function calculateDiscount(price: number, userLevel: number): number {
+  if (userLevel >= USER_LEVEL_THRESHOLD.PREMIUM) return price * DISCOUNT_RATE.PREMIUM;
+  return 0;
+}
+```
+
+---
+
+## Detection Quick Reference
+
+Code passes smell check when:
+- No hardcoded return data in business logic
+- All workarounds have required labels (HACK:, MOCK:, TODO:, TEMPORARY:, NOT-PRODUCTION:, ARCHITECTURE EXCEPTION:)
+- All fake/mock code clearly marked
+- Magic values extracted to named constants
+- Functions do what their names promise