devflow-kit 0.9.0 → 1.1.0

package/shared/skills/consistency-patterns/references/patterns.md

@@ -0,0 +1,202 @@
+# Correct Consistency Patterns Reference
+
+Extended examples of correct patterns to follow.
+
+---
+
+## Naming Conventions
+
+### Function Naming
+
+```typescript
+// EXISTING PATTERN: camelCase for functions
+function getUserById(id: string) { }
+function createOrder(data: OrderData) { }
+function validateInput(input: string) { }
+function processPayment(amount: number) { }
+
+// All new functions MUST match this style
+```
+
+### Class Naming
+
+```typescript
+// EXISTING PATTERN: PascalCase for classes
+class UserService { }
+class OrderRepository { }
+class PaymentGateway { }
+class ValidationError extends Error { }
+```
+
+### Constant Naming
+
+```typescript
+// EXISTING PATTERN: SCREAMING_SNAKE_CASE for true constants
+const MAX_RETRY_ATTEMPTS = 3;
+const API_BASE_URL = 'https://api.example.com';
+const DEFAULT_TIMEOUT_MS = 5000;
+
+// camelCase for configuration objects
+const serverConfig = { port: 3000 };
+```
+
+---
+
+## Error Handling
+
+### Result Type Pattern
+
+```typescript
+// EXISTING PATTERN: Result types
+function existingFunction(): Result<User, Error> {
+  if (!valid) return Err(new ValidationError('Detailed message'));
+  return Ok(user);
+}
+
+// CORRECT: Match existing
+function newFunction(): Result<Order, Error> {
+  if (!valid) return Err(new ValidationError('Detailed message'));
+  return Ok(order);
+}
+```
+
+### Error Messages
+
+```typescript
+// CORRECT: Informative error messages
+throw new Error(`Failed to process order ${orderId}: ${reason}. Customer: ${customerId}. Items: ${itemCount}`);
+
+// Include:
+// - What failed
+// - Why it failed (if known)
+// - Context for debugging
+// - Action the user can take (for user-facing)
+```
+
+---
+
+## Import Organization
+
+```typescript
+// CORRECT ORDER:
+// 1. Node built-ins
+import fs from 'fs';
+import path from 'path';
+
+// 2. External packages
+import express from 'express';
+import { z } from 'zod';
+
+// 3. Internal packages (@company/*)
+import { Logger } from '@internal/logger';
+import { Config } from '@internal/config';
+
+// 4. Relative imports (parent directories first)
+import { BaseService } from '../../base';
+import { User } from '../models';
+import { validate } from './utils';
+```
+
+---
+
+## Export Patterns
+
+### Named Exports (Preferred)
+
+```typescript
+// Functions
+export function createUser(data: UserInput): Result<User, Error> { }
+export function deleteUser(id: string): Result<void, Error> { }
+
+// Classes
+export class UserService { }
+export class UserRepository { }
+
+// Types
+export type UserId = string;
+export interface UserConfig { }
+
+// Constants
+export const DEFAULT_PAGE_SIZE = 20;
+```
+
+### Barrel Exports
+
+```typescript
+// src/services/index.ts
+export { UserService } from './user-service';
+export { OrderService } from './order-service';
+export type { ServiceConfig } from './types';
+```
+
+---
+
+## Configuration Preservation
+
+```typescript
+// CORRECT: Maintain configuration flexibility
+interface ServerConfig {
+  // Required
+  port: number;
+  host: string;
+
+  // Optional with defaults
+  timeout?: number;
+  maxConnections?: number;
+
+  // Nested configs
+  ssl?: SSLConfig;
+  logging?: LogConfig;
+  cors?: CorsConfig;
+}
+
+// Deprecation notice when removing options
+/**
+ * @deprecated Use `logging.level` instead. Will be removed in v3.0
+ */
+debugMode?: boolean;
+```
+
+---
+
+## Event Emission Preservation
+
+```typescript
+// CORRECT: Maintain all event emissions
+class OrderService {
+  async createOrder(data: OrderData) {
+    const order = await this.repository.create(data);
+
+    // All existing events preserved
+    this.events.emit('order.created', order);
+    this.events.emit('inventory.reserve', order.items);
+    this.events.emit('notification.send', {
+      type: 'order_confirmation',
+      userId: order.userId,
+    });
+
+    return order;
+  }
+}
+
+// If removing events, deprecate first:
+// DEPRECATED: 'order.legacy' event will be removed in v3.0
+```
+
+---
+
+## CLI Option Preservation
+
+```typescript
+// CORRECT: Maintain all CLI options
+program
+  .option('-v, --verbose', 'Enable verbose output')
+  .option('-d, --debug', 'Enable debug mode')
+  .option('-c, --config <path>', 'Config file path')
+  .option('--dry-run', 'Preview without executing')
+  // New options add to existing, don't replace
+  .option('--json', 'Output in JSON format');
+
+// If removing, add deprecation warning:
+.option('--old-flag', '[DEPRECATED] Use --new-flag instead')
+```

package/shared/skills/consistency-patterns/references/violations.md

@@ -0,0 +1,213 @@
+# Consistency Violations Reference
+
+Extended examples of consistency violations to detect.
+
+---
+
+## Unnecessary Simplification
+
+### Content Truncation
+
+```typescript
+// BEFORE (comprehensive)
+const errorMessages = {
+  INVALID_EMAIL: 'Please enter a valid email address in the format user@domain.com',
+  PASSWORD_WEAK: 'Password must contain at least 8 characters, one uppercase, one lowercase, one number, and one special character',
+  USER_NOT_FOUND: 'We could not find an account with that email. Please check the email or create a new account.',
+};
+
+// AFTER (over-simplified - PROBLEM)
+const errorMessages = {
+  INVALID_EMAIL: 'Invalid email',
+  PASSWORD_WEAK: 'Password too weak',
+  USER_NOT_FOUND: 'Not found',
+};
+
+// RED FLAG: User-facing messages should be helpful, not minimal
+```
+
+### Removed Error Context
+
+```typescript
+// BEFORE (informative)
+throw new Error(`Failed to process order ${orderId}: ${reason}. Customer: ${customerId}. Items: ${itemCount}`);
+
+// AFTER (stripped - PROBLEM)
+throw new Error('Order failed');
+
+// RED FLAG: Debug info removed, harder to troubleshoot
+```
+
+### Stripped Configuration Options
+
+```typescript
+// BEFORE (flexible)
+interface ServerConfig {
+  port: number;
+  host: string;
+  timeout: number;
+  maxConnections: number;
+  ssl: SSLConfig;
+  logging: LogConfig;
+  cors: CorsConfig;
+}
+
+// AFTER (rigid - PROBLEM)
+interface ServerConfig {
+  port: number;
+}
+
+// RED FLAG: Configuration flexibility removed
+```
+
+---
+
+## Pattern Violations
+
+### Import Organization Inconsistency
+
+```typescript
+// EXISTING PATTERN: External, internal, relative
+import express from 'express';           // External
+import { Logger } from '@internal/logger'; // Internal
+import { User } from './models';          // Relative
+
+// VIOLATION: Mixed order
+import { User } from './models';
+import express from 'express';
+import { Logger } from '@internal/logger';
+
+// CORRECT: Match existing organization
+```
+
+### Export Pattern Mismatch
+
+```typescript
+// EXISTING PATTERN: Named exports
+export function createUser() { }
+export function deleteUser() { }
+export const UserSchema = z.object({ });
+
+// VIOLATION: Default export
+export default class UserService {  // Different pattern!
+  create() { }
+  delete() { }
+}
+
+// CORRECT: Match existing
+export class UserService { }
+export const userService = new UserService();
+```
+
+---
+
+## Feature Regression
+
+### Removed CLI Options
+
+```typescript
+// BEFORE
+program
+  .option('-v, --verbose', 'Enable verbose output')
+  .option('-d, --debug', 'Enable debug mode')
+  .option('-c, --config <path>', 'Config file path')
+  .option('--dry-run', 'Preview without executing');
+
+// AFTER (PROBLEM)
+program
+  .option('-c, --config <path>', 'Config file path');
+
+// RED FLAG: Users relying on removed options will break
+```
+
+### Changed Return Types
+
+```typescript
+// BEFORE
+async function fetchUsers(): Promise<User[]> {
+  return users;
+}
+
+// AFTER (PROBLEM)
+async function fetchUsers(): Promise<{ data: User[] }> {
+  return { data: users };  // Breaking change!
+}
+
+// All callers expecting User[] will break
+```
+
+### Removed Event Emissions
+
+```typescript
+// BEFORE
+class OrderService {
+  async createOrder(data: OrderData) {
+    const order = await this.repository.create(data);
+    this.events.emit('order.created', order);  // Other services listen
+    this.events.emit('inventory.reserve', order.items);
+    return order;
+  }
+}
+
+// AFTER (PROBLEM)
+class OrderService {
+  async createOrder(data: OrderData) {
+    const order = await this.repository.create(data);
+    return order;  // Events removed - listeners won't fire!
+  }
+}
+```
+
+---
+
+## Style Inconsistency
+
+### Brace Style
+
+```typescript
+// EXISTING PATTERN: Same-line braces
+function existing() {
+  if (condition) {
+    // ...
+  }
+}
+
+// VIOLATION: Next-line braces
+function newFunction()
+{
+  if (condition)
+  {
+    // ...
+  }
+}
+```
+
+### Quote Style
+
+```typescript
+// EXISTING PATTERN: Single quotes
+const name = 'John';
+const message = 'Hello';
+
+// VIOLATION: Double quotes
+const name = "Jane";  // Inconsistent
+
+// CORRECT: Match existing
+const name = 'Jane';
+```
+
+### Trailing Commas
+
+```typescript
+// EXISTING PATTERN: Trailing commas
+const config = {
+  name: 'app',
+  version: '1.0',
+};
+
+// VIOLATION: No trailing comma
+const newConfig = {
+  name: 'app',
+  version: '1.0'  // Missing trailing comma
+};
+```

package/shared/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