devflow-kit 1.8.2 → 2.0.0

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

@@ -1,369 +0,0 @@
-# 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

@@ -1,143 +0,0 @@
----
-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/
-
-.memory/
-├── WORKING-MEMORY.md                   # Auto-maintained by Stop hook (overwritten)
-├── backup.json                         # Pre-compact git state snapshot
-└── knowledge/
-    ├── decisions.md                    # Architectural decisions (ADR-NNN format)
-    └── pitfalls.md                     # Known pitfalls (PF-NNN format)
-```
-
----
-
-## 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 | `.memory/WORKING-MEMORY.md` | Overwrites (auto-maintained by Stop hook) |
-| Knowledge (decisions) | `.memory/knowledge/decisions.md` | Append-only (ADR-NNN sequential IDs) |
-| Knowledge (pitfalls) | `.memory/knowledge/pitfalls.md` | Append-only (PF-NNN sequential IDs) |
-
-### 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 `.memory/WORKING-MEMORY.md`
-- **Command flows**: `/implement` appends ADRs to `decisions.md`; `/code-review`, `/debug`, `/resolve` append PFs to `pitfalls.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