devflow-kit 0.8.1 → 1.0.0

package/plugins/devflow-core-skills/skills/core-patterns/references/violations.md

@@ -0,0 +1,369 @@
+# Extended Violation Examples
+
+Additional code smell patterns and violations beyond the core examples in SKILL.md.
+
+---
+
+## Result Types - Extended Violations
+
+### Try/Catch in Business Logic
+
+```typescript
+// VIOLATION: Try/catch in business logic
+function calculate(items: Item[]): number {
+  try {
+    return items.reduce((sum, i) => sum + i.price, 0);
+  } catch {
+    return 0;  // Silent failure - BAD
+  }
+}
+
+// VIOLATION: Nested try/catch
+async function processOrder(id: string): Promise<Order> {
+  try {
+    const order = await fetchOrder(id);
+    try {
+      await validateOrder(order);
+    } catch {
+      // Swallowed validation error
+    }
+    return order;
+  } catch {
+    return null;  // Silent failure
+  }
+}
+
+// VIOLATION: Error type erasure
+function parseConfig(raw: string): Config {
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new Error('Parse failed');  // Lost original error context
+  }
+}
+```
+
+### Implicit Error States
+
+```typescript
+// VIOLATION: Using null/undefined for errors
+function findUser(id: string): User | null {
+  // Caller can't distinguish "not found" from "error occurred"
+  return null;
+}
+
+// VIOLATION: Using sentinel values
+function calculateDiscount(userId: string): number {
+  // Returns -1 for errors - magic value
+  if (!userId) return -1;
+  return computeDiscount(userId);
+}
+
+// VIOLATION: Throwing in async without Result
+async function fetchData(url: string): Promise<Data> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error('Fetch failed');  // Should return Result
+  }
+  return response.json();
+}
+```
+
+---
+
+## Dependency Injection - Extended Violations
+
+### Hidden Dependencies
+
+```typescript
+// VIOLATION: Hidden dependencies via imports
+import { config } from './config';  // Global config
+import { analytics } from './analytics';  // Global analytics
+
+class UserService {
+  createUser(data: UserData) {
+    // Uses global config - can't test with different config
+    if (config.features.requireEmailVerification) {
+      // ...
+    }
+    // Uses global analytics - can't mock in tests
+    analytics.track('user_created', data);
+  }
+}
+
+// VIOLATION: Static method dependencies
+class OrderService {
+  processOrder(order: Order) {
+    // Can't mock static methods
+    const tax = TaxCalculator.calculate(order.total);
+    const shipping = ShippingService.getRate(order.address);
+  }
+}
+
+// VIOLATION: Service locator anti-pattern
+class PaymentService {
+  process(payment: Payment) {
+    // Runtime dependency resolution - untestable
+    const gateway = ServiceLocator.resolve<PaymentGateway>('paymentGateway');
+    return gateway.charge(payment);
+  }
+}
+```
+
+### Partial Injection
+
+```typescript
+// VIOLATION: Some dependencies injected, others not
+class ReportService {
+  constructor(private db: Database) {}  // Injected
+
+  generate(reportId: string) {
+    const data = this.db.query(reportId);
+    // But logger is global
+    logger.info('Report generated');  // BAD
+    // And config is imported
+    if (config.features.pdfExport) {  // BAD
+      // ...
+    }
+  }
+}
+```
+
+---
+
+## Immutability - Extended Violations
+
+### Array Mutations
+
+```typescript
+// VIOLATION: In-place array modifications
+function processItems(items: Item[]): Item[] {
+  items.push({ id: 'new' });  // BAD - mutates input
+  items.splice(0, 1);  // BAD - mutates input
+  items.reverse();  // BAD - mutates in place
+  items.fill({ id: 'default' });  // BAD - mutates in place
+  return items;
+}
+
+// VIOLATION: Sorting without copy
+function getSortedUsers(users: User[]): User[] {
+  return users.sort((a, b) => a.name.localeCompare(b.name));  // Mutates original!
+}
+
+// VIOLATION: Using forEach for transformation
+function transformItems(items: Item[]): Item[] {
+  items.forEach(item => {
+    item.processed = true;  // BAD - mutation
+  });
+  return items;
+}
+```
+
+### Object Mutations
+
+```typescript
+// VIOLATION: Nested object mutation
+function updateAddress(user: User, city: string): User {
+  user.address.city = city;  // BAD - nested mutation
+  return user;
+}
+
+// VIOLATION: Object.assign mutating first argument
+function mergeConfig(base: Config, overrides: Partial<Config>): Config {
+  return Object.assign(base, overrides);  // BAD - mutates base
+}
+
+// VIOLATION: Deleting properties
+function removeField(obj: Record<string, unknown>, field: string) {
+  delete obj[field];  // BAD - mutation
+  return obj;
+}
+```
+
+---
+
+## Pure Functions - Extended Violations
+
+### Side Effect Patterns
+
+```typescript
+// VIOLATION: Accessing global state
+let counter = 0;
+function getNextId(): string {
+  return `id-${counter++}`;  // BAD - global state modification
+}
+
+// VIOLATION: Date/time dependency
+function isExpired(expiry: Date): boolean {
+  return new Date() > expiry;  // BAD - depends on current time
+}
+
+// VIOLATION: Random values
+function generateToken(): string {
+  return Math.random().toString(36);  // BAD - non-deterministic
+}
+
+// VIOLATION: Environment access
+function getApiUrl(): string {
+  return process.env.API_URL || 'http://localhost';  // BAD - env dependency
+}
+```
+
+### Hidden I/O
+
+```typescript
+// VIOLATION: Caching with side effects
+const cache = new Map();
+function expensiveCalculation(input: string): number {
+  if (cache.has(input)) return cache.get(input);  // BAD - reads global state
+  const result = compute(input);
+  cache.set(input, result);  // BAD - writes global state
+  return result;
+}
+
+// VIOLATION: Lazy initialization
+let initialized = false;
+function ensureInitialized(): void {
+  if (!initialized) {
+    performSetup();  // BAD - side effect
+    initialized = true;  // BAD - global state
+  }
+}
+```
+
+---
+
+## Type Safety - Extended Violations
+
+### Type Assertions Abuse
+
+```typescript
+// VIOLATION: Unsafe type assertion
+const user = data as User;  // No runtime check
+
+// VIOLATION: Non-null assertion
+const name = user!.profile!.name!;  // Assumes non-null
+
+// VIOLATION: Any escape hatch
+function process(data: unknown) {
+  return (data as any).property.nested;  // BAD
+}
+
+// VIOLATION: Type assertion to bypass checks
+const items: Item[] = response.data as Item[];  // No validation
+```
+
+### Incomplete Discrimination
+
+```typescript
+// VIOLATION: Default case hiding missing patterns
+function handleEvent(event: Event): void {
+  switch (event.type) {
+    case 'click':
+      handleClick(event);
+      break;
+    default:
+      // Silently ignores new event types
+      break;
+  }
+}
+
+// VIOLATION: Using if/else instead of exhaustive switch
+function getLabel(status: Status): string {
+  if (status === 'pending') return 'Waiting';
+  if (status === 'active') return 'Running';
+  return 'Unknown';  // BAD - misses new status types
+}
+```
+
+---
+
+## Resource Cleanup - Extended Violations
+
+### Connection Leaks
+
+```typescript
+// VIOLATION: Connection not released on error
+async function queryDatabase(sql: string) {
+  const conn = await pool.getConnection();
+  const result = await conn.query(sql);  // If this throws, connection leaks
+  conn.release();
+  return result;
+}
+
+// VIOLATION: Stream not closed
+function readFile(path: string) {
+  const stream = fs.createReadStream(path);
+  stream.on('data', chunk => process(chunk));
+  // No close handler - stream never closed on error
+}
+
+// VIOLATION: Subscription not unsubscribed
+function setupListener(emitter: EventEmitter) {
+  emitter.on('event', handler);
+  // No cleanup - memory leak
+}
+```
+
+### Timer Leaks
+
+```typescript
+// VIOLATION: Interval not cleared
+function startPolling() {
+  setInterval(() => {
+    fetchData();
+  }, 1000);
+  // No way to stop polling
+}
+
+// VIOLATION: Timeout not cleared on early exit
+async function withTimeout(promise: Promise<unknown>, ms: number) {
+  const timeout = setTimeout(() => { throw new Error('Timeout'); }, ms);
+  const result = await promise;  // If this resolves, timeout still pending
+  return result;
+}
+```
+
+---
+
+## API Consistency - Extended Violations
+
+### Mixed Error Handling
+
+```typescript
+// VIOLATION: Mixed error handling in same module
+class UserRepository {
+  // Returns null for not found
+  findById(id: string): User | null { ... }
+
+  // Throws for not found
+  getById(id: string): User {
+    const user = this.findById(id);
+    if (!user) throw new NotFoundError();  // Inconsistent!
+    return user;
+  }
+
+  // Returns Result
+  findByEmail(email: string): Result<User, Error> { ... }  // Third pattern!
+}
+```
+
+### Mixed Async Patterns
+
+```typescript
+// VIOLATION: Mixing callbacks and promises
+function fetchUser(id: string, callback?: (err: Error, user: User) => void): Promise<User> {
+  const promise = api.get(`/users/${id}`);
+  if (callback) {
+    promise.then(user => callback(null, user)).catch(err => callback(err, null));
+  }
+  return promise;
+}
+
+// VIOLATION: Fire-and-forget async
+async function processOrder(order: Order) {
+  saveOrder(order);  // Missing await - fire and forget
+  await sendEmail(order.email);  // This one awaits
+  logAnalytics(order);  // Missing await again
+}
+```

package/plugins/devflow-core-skills/skills/docs-framework/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: docs-framework
+description: This skill should be used when the user asks to "create a review report", "write a status log", "add documentation", "name this artifact", or creates files in the .docs/ directory. Provides naming conventions, templates, and directory structure for reviews, debug sessions, design docs, and all persistent DevFlow documentation artifacts.
+user-invocable: false
+allowed-tools: Read, Bash, Glob
+---
+
+# Documentation Framework
+
+The canonical source for documentation conventions in DevFlow. All agents that persist artifacts must follow these standards.
+
+## Iron Law
+
+> **ALL ARTIFACTS FOLLOW NAMING CONVENTIONS**
+>
+> Timestamps are `YYYY-MM-DD_HHMM`. Branch slugs replace `/` with `-`. Topic slugs are
+> lowercase alphanumeric with dashes. No exceptions. Inconsistent naming breaks tooling,
+> searching, and automation. Follow the pattern or fix the pattern for everyone.
+
+---
+
+## Directory Structure
+
+All generated documentation lives under `.docs/` in the project root:
+
+```
+.docs/
+├── reviews/{branch-slug}/              # Code review reports per branch
+│   ├── {type}-report.{timestamp}.md
+│   └── review-summary.{timestamp}.md
+├── status/                             # Development logs
+│   ├── {timestamp}.md
+│   ├── compact/{timestamp}.md
+│   └── INDEX.md
+├── swarm/                              # Swarm operation state
+│   ├── state.json
+│   └── plans/
+└── WORKING-MEMORY.md                   # Auto-maintained by Stop hook (overwritten)
+```
+
+---
+
+## Naming Conventions
+
+### Timestamps
+Format: `YYYY-MM-DD_HHMM` (sortable, readable)
+```bash
+TIMESTAMP=$(date +%Y-%m-%d_%H%M)  # Example: 2025-12-26_1430
+```
+
+### Branch Slugs
+Replace `/` with `-`, sanitize special characters:
+```bash
+BRANCH_SLUG=$(git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "standalone")
+```
+
+### Topic Slugs
+Lowercase, dashes, alphanumeric only, max 50 chars:
+```bash
+TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^a-z0-9-]//g' | cut -c1-50)
+```
+
+### File Naming Patterns
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Special indexes | `UPPERCASE.md` | `WORKING-MEMORY.md`, `INDEX.md` |
+| Reports | `{type}-report.{timestamp}.md` | `security-report.2025-12-26_1430.md` |
+| Status logs | `{timestamp}.md` | `2025-12-26_1430.md` |
+
+---
+
+## Helper Functions
+
+Source helpers for consistent naming:
+
+```bash
+source .devflow/scripts/docs-helpers.sh 2>/dev/null || {
+    get_timestamp() { date +%Y-%m-%d_%H%M; }
+    get_branch_slug() { git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "standalone"; }
+    get_topic_slug() { echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^a-z0-9-]//g' | cut -c1-50; }
+    ensure_docs_dir() { mkdir -p ".docs/$1"; }
+}
+```
+
+---
+
+## Agent Persistence Rules
+
+### Agents That Persist Artifacts
+
+| Agent | Output Location | Behavior |
+|-------|-----------------|----------|
+| Reviewer | `.docs/reviews/{branch-slug}/{type}-report.{timestamp}.md` | Creates new |
+| Working Memory | `.docs/WORKING-MEMORY.md` | Overwrites (auto-maintained by Stop hook) |
+
+### Agents That Don't Persist
+
+- Git (fetch-issue: read-only, comment-pr: PR comments only)
+- Coder (commits to git, no .docs/ output)
+
+---
+
+## Implementation Checklist
+
+When creating or modifying persisting agents:
+
+- [ ] Use standard timestamp format (`YYYY-MM-DD_HHMM`)
+- [ ] Sanitize branch names (replace `/` with `-`)
+- [ ] Sanitize topic names (lowercase, dashes, alphanumeric)
+- [ ] Create directory with `mkdir -p .docs/{subdir}`
+- [ ] Document output location in agent's final message
+- [ ] Follow special file naming (UPPERCASE for indexes)
+- [ ] Use helper functions when possible
+- [ ] Update relevant index files
+
+---
+
+## Integration
+
+This framework is used by:
+- **Review agents**: Creates review reports
+- **Working Memory hooks**: Auto-maintains `.docs/WORKING-MEMORY.md`
+
+All persisting agents should load this skill to ensure consistent documentation.
+
+---
+
+## Extended References
+
+For detailed patterns and violation examples:
+
+- **[patterns.md](./references/patterns.md)** - Full templates, helper functions, naming examples, edge cases
+- **[violations.md](./references/violations.md)** - Common violations with detection patterns and fixes