devflow-kit 1.8.2 → 2.0.0

package/src/assets/skills/software-design/references/violations.md

@@ -0,0 +1,341 @@
+# Extended Violation Examples
+
+Additional code smell patterns and violations beyond the core examples in SKILL.md.
+All violations cite `references/sources.md`.
+
+---
+
+## Result Types — Extended Violations [1][10]
+
+### Try/Catch in Business Logic [1][11]
+
+Throwing in business logic is the core violation of Railway Oriented Programming [1].
+Functional Core, Imperative Shell mandates that only the shell catches exceptions [11].
+
+```typescript
+// VIOLATION: Try/catch in business logic [1]
+function calculate(items: Item[]): number {
+  try {
+    return items.reduce((sum, i) => sum + i.price, 0);
+  } catch {
+    return 0;  // Silent failure — caller has no idea [10]
+  }
+}
+
+// VIOLATION: Nested try/catch swallowing errors [10]
+async function processOrder(id: string): Promise<Order> {
+  try {
+    const order = await fetchOrder(id);
+    try {
+      await validateOrder(order);
+    } catch {
+      // Swallowed validation error — BAD [10]
+    }
+    return order;
+  } catch {
+    return null;  // Silent failure [10]
+  }
+}
+
+// VIOLATION: Error type erasure [1]
+function parseConfig(raw: string): Config {
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new Error('Parse failed');  // Lost original error context [1]
+  }
+}
+```
+
+### Implicit Error States [1][2]
+
+```typescript
+// VIOLATION: null/undefined for errors — caller can't distinguish "not found" from "error" [1]
+function findUser(id: string): User | null {
+  return null;
+}
+
+// VIOLATION: Sentinel values as error signal [2]
+function calculateDiscount(userId: string): number {
+  if (!userId) return -1;  // Magic -1 means error — see sources.md [9] for proper approach
+  return computeDiscount(userId);
+}
+
+// VIOLATION: Throwing in async without Result [1]
+async function fetchData(url: string): Promise<Data> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error('Fetch failed');  // Should return Result [1]
+  }
+  return response.json();
+}
+```
+
+---
+
+## Dependency Injection — Extended Violations [3]
+
+### Hidden Dependencies [3]
+
+Fowler's canonical DI article [3] identifies these as the anti-patterns that DI solves.
+
+```typescript
+// VIOLATION: Hidden dependencies via imports [3]
+import { config } from './config';     // Global config
+import { analytics } from './analytics'; // Global analytics
+
+class UserService {
+  createUser(data: UserData) {
+    if (config.features.requireEmailVerification) { /* can't test with different config */ }
+    analytics.track('user_created', data);  // Can't mock in tests [3]
+  }
+}
+
+// VIOLATION: Static method dependencies — can't mock [3]
+class OrderService {
+  processOrder(order: Order) {
+    const tax = TaxCalculator.calculate(order.total);    // Static — untestable [3]
+    const shipping = ShippingService.getRate(order.address); // Static — untestable [3]
+  }
+}
+
+// VIOLATION: Service locator anti-pattern [3]
+class PaymentService {
+  process(payment: Payment) {
+    const gateway = ServiceLocator.resolve<PaymentGateway>('paymentGateway');
+    return gateway.charge(payment);
+  }
+}
+```
+
+### Partial Injection [3]
+
+```typescript
+// VIOLATION: Some dependencies injected, others not — inconsistent [3]
+class ReportService {
+  constructor(private db: Database) {}  // Injected
+
+  generate(reportId: string) {
+    const data = this.db.query(reportId);
+    logger.info('Report generated');   // BAD — global logger [3]
+    if (config.features.pdfExport) {   // BAD — global config [3]
+      // ...
+    }
+  }
+}
+```
+
+---
+
+## Immutability — Extended Violations [7][14]
+
+### Array Mutations [14]
+
+Rich Hickey's "Value of Values" [14] explains why mutation destroys referential transparency.
+
+```typescript
+// VIOLATION: In-place array modifications [14]
+function processItems(items: Item[]): Item[] {
+  items.push({ id: 'new' });   // Mutates input [14]
+  items.splice(0, 1);          // Mutates input [14]
+  items.reverse();             // Mutates in place [14]
+  return items;
+}
+
+// VIOLATION: Sorting without copy [14]
+function getSortedUsers(users: User[]): User[] {
+  return users.sort((a, b) => a.name.localeCompare(b.name));  // Mutates original! [14]
+}
+
+// VIOLATION: forEach with mutations [14]
+function transformItems(items: Item[]): Item[] {
+  items.forEach(item => {
+    item.processed = true;  // Mutation [14]
+  });
+  return items;
+}
+```
+
+### Object Mutations [7][14]
+
+```typescript
+// VIOLATION: Nested object mutation [7]
+function updateAddress(user: User, city: string): User {
+  user.address.city = city;  // Nested mutation [7]
+  return user;
+}
+
+// VIOLATION: Object.assign mutating first argument [14]
+function mergeConfig(base: Config, overrides: Partial<Config>): Config {
+  return Object.assign(base, overrides);  // Mutates base [14]
+}
+
+// VIOLATION: Deleting properties [14]
+function removeField(obj: Record<string, unknown>, field: string) {
+  delete obj[field];  // Mutation [14]
+  return obj;
+}
+```
+
+---
+
+## Pure Functions — Extended Violations [8][11]
+
+### Side Effect Patterns [11]
+
+Bernhardt's "Functional Core, Imperative Shell" [11] identifies these as imperative shell concerns leaking into the functional core.
+
+```typescript
+// VIOLATION: Accessing global state [15]
+let counter = 0;
+function getNextId(): string {
+  return `id-${counter++}`;  // Global state modification [15]
+}
+
+// VIOLATION: Date/time dependency — non-deterministic [8]
+function isExpired(expiry: Date): boolean {
+  return new Date() > expiry;  // Inject clock instead [8]
+}
+
+// VIOLATION: Random values — non-deterministic [8]
+function generateToken(): string {
+  return Math.random().toString(36);  // Inject RNG instead [8]
+}
+```
+
+### Hidden I/O [11]
+
+```typescript
+// VIOLATION: Caching with side effects in pure function [11]
+const cache = new Map();
+function expensiveCalculation(input: string): number {
+  if (cache.has(input)) return cache.get(input);  // Global read [11]
+  const result = compute(input);
+  cache.set(input, result);  // Global write [11]
+  return result;
+}
+```
+
+---
+
+## Type Safety — Extended Violations [4][2][21]
+
+### Type Assertions Abuse [4][21]
+
+Making illegal states representable is the opposite of [4].
+
+```typescript
+// VIOLATION: Unsafe type assertion — no runtime check [4]
+const user = data as User;
+
+// VIOLATION: Non-null assertion — assumes non-null [21]
+const name = user!.profile!.name!;
+
+// VIOLATION: any escape hatch [22]
+function process(data: unknown) {
+  return (data as any).property.nested;  // Bypasses type system [22]
+}
+```
+
+### Incomplete Discrimination [4][21]
+
+```typescript
+// VIOLATION: Default case hiding missing patterns [21]
+function handleEvent(event: Event): void {
+  switch (event.type) {
+    case 'click':
+      handleClick(event);
+      break;
+    default:
+      // Silently ignores new event types — compile-time safety lost [21]
+      break;
+  }
+}
+
+// VIOLATION: if/else instead of exhaustive switch [4]
+function getLabel(status: Status): string {
+  if (status === 'pending') return 'Waiting';
+  if (status === 'active') return 'Running';
+  return 'Unknown';  // New status values silently fall through [4]
+}
+```
+
+---
+
+## Resource Cleanup — Extended Violations [7]
+
+### Connection Leaks [7]
+
+SICP's emphasis on resource management [7] applies equally to OS resources.
+
+```typescript
+// VIOLATION: Connection not released on error [7]
+async function queryDatabase(sql: string) {
+  const conn = await pool.getConnection();
+  const result = await conn.query(sql);  // If this throws, connection leaks [7]
+  conn.release();
+  return result;
+}
+
+// VIOLATION: Stream not closed on error [7]
+function readFile(path: string) {
+  const stream = fs.createReadStream(path);
+  stream.on('data', chunk => process(chunk));
+  // No error handler — stream never closed on error [7]
+}
+```
+
+### Timer Leaks [7]
+
+```typescript
+// VIOLATION: Interval not cleared [7]
+function startPolling() {
+  setInterval(() => {
+    fetchData();
+  }, 1000);
+  // No way to stop polling — resource leak [7]
+}
+```
+
+---
+
+## API Consistency — Extended Violations [1][3]
+
+### Mixed Error Handling [1]
+
+Inconsistency violates Railway Oriented Programming's one-track model [1].
+
+```typescript
+// VIOLATION: Three different error patterns in same class [1]
+class UserRepository {
+  findById(id: string): User | null { ... }       // Pattern 1: null
+
+  getById(id: string): User {
+    const user = this.findById(id);
+    if (!user) throw new NotFoundError();          // Pattern 2: throw [1]
+    return user;
+  }
+
+  findByEmail(email: string): Result<User, Error> { ... }  // Pattern 3: Result
+}
+```
+
+### Mixed Async Patterns [3]
+
+```typescript
+// VIOLATION: Mixing callbacks and promises [3]
+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 [10]
+async function processOrder(order: Order) {
+  saveOrder(order);           // Missing await [10]
+  await sendEmail(order.email);
+  logAnalytics(order);        // Missing await [10]
+}
+```

package/src/assets/skills/test-driven-development/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: test-driven-development
+description: This skill should be used when implementing new features, fixing bugs, or writing new code. Enforces RED-GREEN-REFACTOR.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.ts"
+    - "**/*.tsx"
+    - "**/*.js"
+    - "**/*.jsx"
+    - "**/*.py"
+  exclude:
+    - "node_modules/**"
+    - "dist/**"
+    - "**/*.test.*"
+    - "**/*.spec.*"
+---
+
+# Test-Driven Development
+
+Enforce the RED-GREEN-REFACTOR cycle for all implementation work. Tests define the design. Code satisfies the tests. Refactoring improves the design without changing behavior.
+
+## Iron Law
+
+> **TESTS FIRST, ALWAYS**
+>
+> Write the failing test before the production code. No exceptions. If you catch
+> yourself writing production code without a failing test, stop immediately, delete
+> the production code, write the test, watch it fail, then write the minimum code
+> to make it pass. The test IS the specification.
+
+---
+
+## The Cycle
+
+### Step 1: RED — Write a Failing Test
+
+Write a test that describes the behavior you want. Run it. Watch it fail. The failure message IS your specification.
+
+```
+Describe what the code SHOULD do, not how it does it.
+One behavior per test. One assertion per test (ideally).
+Name tests as sentences: "returns error when email is invalid"
+```
+
+**Checkpoint:** The test MUST fail before proceeding. A test that passes immediately proves nothing.
+
+### Step 2: GREEN — Write Minimum Code to Pass
+
+Write the simplest production code that makes the failing test pass. No more, no less.
+
+```
+Hardcode first if that's simplest. Generalize when the next test forces it.
+Don't write code "you'll need later." Write code the test demands NOW.
+Don't optimize. Don't refactor. Don't clean up. Just pass the test.
+```
+
+**Checkpoint:** All tests pass. If any test fails, fix it before moving on.
+
+### Step 3: REFACTOR — Improve Without Changing Behavior
+
+Now clean up. Extract helpers, rename variables, simplify logic. Tests stay green throughout.
+
+```
+Run tests after every refactoring step.
+If a test breaks during refactor, undo immediately — you changed behavior.
+Apply DRY, extract patterns, improve readability.
+```
+
+**Checkpoint:** All tests still pass. Code is clean. Repeat from Step 1 for next behavior.
+
+---
+
+## Cycle Verification
+
+After each RED-GREEN-REFACTOR cycle, ALL must hold:
+
+- [ ] Test existed BEFORE production code (not concurrent, not after)
+- [ ] Test failed for the RIGHT reason (expected behavior absent, not syntax/import error)
+- [ ] Production code is minimal — no speculative additions beyond what the test demands
+- [ ] ALL tests pass, not just the new one
+- [ ] Refactoring happened in Step 3 (or code is already clean — state explicitly)
+- [ ] No untested production code remains
+
+If any fails: you skipped TDD. Back up and redo the cycle correctly.
+
+---
+
+## Rationalization Prevention
+
+These are the excuses developers use to skip TDD. Recognize and reject them.
+
+| Excuse | Why It Feels Right | Why It's Wrong | Correct Action |
+|--------|-------------------|----------------|----------------|
+| "I'll write tests after" | Need to see the shape first | Tests ARE the shape — they define the interface before implementation exists | Write the test first |
+| "Too simple to test" | It's just a getter/setter | Getters break, defaults change, edge cases hide in "simple" code | Write it — takes 30 seconds |
+| "I'll refactor later" | Just get it working now | "Later" never comes; technical debt compounds silently | Refactor now in Step 3 |
+| "Test is too hard to write" | Setup is complex, mocking is painful | Hard-to-test code = bad design; the test is telling you the interface is wrong | Simplify the interface first |
+| "Need to see the whole picture" | Can't test what I haven't designed yet | TDD IS design; each test reveals the next piece of the interface | Let the test guide the design |
+| "Tests slow me down" | Faster to just write the code | Faster until the first regression; TDD is faster for anything > 50 lines | Trust the cycle |
+| "Framework is hard to set up" | Setup is complex | One-time cost vs recurring regression cost; untested code compounds debt | Set up the framework first — that IS the work |
+| "Need the architecture first" | Can't test without structure | Tests DEFINE the architecture; they reveal what interfaces are needed | Let tests drive the structure |
+| "This is infrastructure, not logic" | Plumbing doesn't need tests | Infrastructure carries data; broken plumbing floods everything downstream | Test the contract, not the internals |
+| "Deadline is tight, no time for tests" | Ship now, test later | Untested code ships bugs; fixing bugs under deadline is slower than TDD | TDD is faster under pressure, not slower |
+
+See `references/rationalization-prevention.md` for extended examples with code.
+
+### Red Flags — STOP Immediately
+
+The rationalization table above catches excuses you make *before starting*. These red flags catch you *mid-work* — thoughts that signal you are about to skip a step.
+
+| Thought | Correction |
+|---------|------------|
+| "Let me write the implementation first, tests after" | Delete the code. Write the test. Watch it fail. Then rewrite. |
+| "I need to see the shape before I can test" | The test IS the shape. It defines the interface before implementation. |
+| "The test setup is too complex for this" | Complex setup = too much coupling. Simplify the design first. |
+| "I'll just spike this and add tests later" | Unless the user said "spike" — you're rationalizing, not prototyping. |
+| "Let me get it working, then lock it with tests" | Those tests verify your implementation, not the requirement. Backwards. |
+| "I know this works, I've written it before" | Past code passed past tests. This code needs its own failing test. |
+| "One more function, then I'll write the test" | STOP. Write the test for what you have now. Increments, not batches. |
+
+### Test-First vs Code-First
+
+**Code-first** (wrong):
+1. Write `parseConfig()` — split lines, filter comments, build map
+2. Write test: `parseConfig("key=val")` passes
+3. Ship. Undiscovered: empty input, malformed lines, multi-value keys, whitespace
+> Test mirrors implementation. Edge cases stay hidden until production.
+
+**Test-first** (correct):
+1. Test: "ignores comment lines" — `parseConfig("# comment\nkey=val")` → `{key: val}`
+2. Test: "handles empty input" — `parseConfig("")` → empty result
+3. Test: "rejects malformed lines" — `parseConfig("no-equals")` → error
+4. Implement `parseConfig()` to satisfy all three
+> Tests define the contract. Implementation forced to handle edges from the start.
+
+The difference: code-first tests verify what you *happened to build*. Test-first tests specify what *should exist*.
+
+### When Stuck
+
+| Blocker | Solution |
+|---------|----------|
+| Don't know what to test first | Test the simplest input/output pair. "Given X, expect Y." Start there. |
+| Test needs complex setup/state | Extract the logic into a pure function. Test that. Integrate after. |
+| Behavior depends on external state (DB, API, clock) | Inject the dependency as a parameter. Pass a fake in tests. |
+| Multiple behaviors tangled together | Decompose. One test = one behavior. If you can't isolate it, the design needs splitting. |
+| Modifying legacy code with no tests | Write a characterization test first — a test that captures the current behavior, even if wrong. Then make your change and see what breaks. |
+
+---
+
+## Process Enforcement
+
+When implementing any feature under ambient IMPLEMENT:
+
+1. **Identify the first behavior** — What is the simplest thing this feature must do?
+2. **Write the test** — Describe that behavior as a failing test
+3. **Run the test** — Confirm it fails (RED)
+4. **Write minimum code** — Just enough to pass (GREEN)
+5. **Refactor** — Clean up while tests stay green (REFACTOR)
+6. **Repeat** — Next behavior, next test, next cycle
+
+### File Organization
+
+- Test file lives next to production file: `user.ts` → `user.test.ts`
+- Follow project's existing test conventions (Jest, Vitest, pytest, etc.)
+- Import the module under test, not internal helpers
+
+### What to Test
+
+| Test | Don't Test |
+|------|------------|
+| Public API behavior | Private implementation details |
+| Error conditions and edge cases | Framework internals |
+| Integration points (boundaries) | Third-party library correctness |
+| State transitions | Getter/setter plumbing (unless non-trivial) |
+
+---
+
+## When TDD Does Not Apply
+
+- **Quick/chat tasks** — Trivial edits, exploration, conversational requests
+- **Non-code tasks** — Documentation, configuration, CI changes
+- **Exploratory prototyping** — User explicitly says "just spike this" or "prototype"
+- **Existing test suite changes** — Modifying tests themselves (devflow:testing skill applies instead)
+
+When skipping TDD, never rationalize. State clearly: "Skipping TDD because: [specific reason from list above]."
+
+---
+
+## Integration with Ambient Mode
+
+- **IMPLEMENT** → TDD enforced. Write the failing test before production code. Skill loaded via Code agent frontmatter.
+- **DEBUG** → TDD applies to the fix: write a test that reproduces the bug first, then fix.
+- **PLAN** → TDD shapes the plan: test strategy section, test-first file ordering, RED-GREEN-REFACTOR cycle awareness.
+- **RESOLVE** → TDD enforced via the Code agent (issue-fix mode). Every fix needs a failing-then-passing regression test first.
+- **PIPELINE** → TDD inherited transitively through `/implement` → the Code agent.

package/src/assets/skills/testing/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: testing
+description: This skill should be used when the user asks to "write tests", "fix failing tests", "improve test coverage", "add integration tests", "debug a flaky test", or reviews test quality. Provides behavior-focused testing patterns, coverage analysis, and detection of brittle test anti-patterns like implementation coupling and non-deterministic assertions.
+user-invocable: false
+allowed-tools: Read, Grep, Glob, AskUserQuestion
+activation:
+  file-patterns:
+    - "**/*.test.*"
+    - "**/*.spec.*"
+    - "**/test/**"
+    - "**/tests/**"
+    - "**/__tests__/**"
+  exclude:
+    - "node_modules/**"
+---
+
+# Testing Patterns
+
+## Iron Law
+
+> **TESTS VALIDATE BEHAVIOR, NOT IMPLEMENTATION** [4][8]
+>
+> A test should fail when behavior breaks, not when implementation changes. Mock at
+> boundaries, not internals. Test the contract, not the code path. If tests are hard to
+> write, the design is wrong — fix the architecture, not the tests. [3][8]
+
+---
+
+## Testing Shapes [6][7][10]
+
+| Shape | Guidance |
+|-------|---------|
+| Pyramid [6] | Many unit → fewer integration → fewest E2E |
+| Trophy [7] | Integration tests give best ROI for UI-heavy code |
+| Google [4] | 70% unit / 20% integration / 10% E2E; avoid E2E excess [12] |
+
+---
+
+## Test Doubles Taxonomy [1][9]
+
+| Type | When to Use | Example |
+|------|------------|---------|
+| **Dummy** | Fill unused parameters | `null`, empty object |
+| **Stub** | Return canned data, no assertions | `getRate: () => 0.1` |
+| **Spy** | Record calls, assert after | `jest.spyOn()` on public methods |
+| **Mock** | Pre-programmed expectations | `expect(fn).toHaveBeenCalledWith(x)` |
+| **Fake** | Working substitute (in-memory DB) | `InMemoryUserRepo` |
+
+"Mock roles, not objects" — mock interfaces you own, never third-party internals [3][9].
+
+---
+
+## Test Design Red Flags
+
+| Red Flag | Symptom | Root Cause | Fix |
+|----------|---------|-----------|-----|
+| Complex setup >10 lines [8] | `beforeEach` with 6+ mocks | Too many dependencies | Split service; use fakes [1][4] |
+| Repetitive try/catch [8] | Same pattern >3 times | API throws, not Result | Migrate to Result types [4] |
+| Nested mock structures [1][3] | `mockDb.orders.create: jest.fn()` | Tight coupling | Extract interface; use fake [9] |
+| Spying on private methods [8] | `jest.spyOn(obj as any, '_method')` | Tests implementation | Assert observable output [4] |
+
+```typescript
+// VIOLATION: Tests private implementation [8]
+jest.spyOn(cart as any, 'updateTotal');
+expect(spy).toHaveBeenCalled();   // Tests HOW
+
+// CORRECT: Tests observable behavior [4]
+cart.addItem({ id: '1', price: 10 });
+expect(cart.getTotal()).toBe(10); // Tests WHAT
+```
+
+---
+
+## Property-Based Testing [5][14]
+
+State invariants; let the framework generate inputs and shrink failures [5]:
+
+```typescript
+// fast-check: property must hold for all valid inputs [14]
+fc.assert(fc.property(fc.string(), (s) => decode(encode(s)) === s));
+```
+
+Use for: parsers/serializers, arithmetic, sorting, state machines [5][13][14].
+
+---
+
+## Flaky Tests [11][18]
+
+| Root Cause | Fix |
+|-----------|-----|
+| Async/timing races | Use fake timers; `await` all async ops [19] |
+| Order dependencies | Each test self-contained; fresh state [4] |
+| Shared mutable state | Reset in `afterEach`; use DI [4] |
+
+Quarantine flaky tests immediately — a suite that sometimes passes is worse than no suite [11].
+
+---
+
+## Coverage & Severity [4][8]
+
+| Severity | Criteria |
+|----------|----------|
+| **CRITICAL** | Tests don't verify behavior; critical paths untested; everything mocked [4] |
+| **HIGH** | Missing error paths; flaky tests [11]; slow (>10s); setup >10 lines [8] |
+| **MEDIUM** | Missing edge cases; weak assertions; unclear AAA structure [17] |
+| **LOW** | Organization; naming clarity |
+
+---
+
+## Test Suite Safety [19]
+
+```typescript
+{ fileParallelism: false, maxWorkers: 1, testTimeout: 10000 }  // vitest / jest
+```
+
+---
+
+## Extended References
+
+| Reference | Contents |
+|-----------|----------|
+| `references/sources.md` | Full bibliography (20 sources) |
+| `references/violations.md` | Extended violations with citations [1][4][8][11] |
+| `references/patterns.md` | Correct patterns with citations [1][2][5][14] |
+| `references/detection.md` | Bash commands for automated detection |
+| `references/report-template.md` | Report format for documenting issues |
+
+---
+
+## Quality Gates [4][8][17]
+
+- [ ] Setup <10 lines; use fakes over mocks for complex dependencies [1]
+- [ ] No spying on private methods or internal state [8]
+- [ ] Tests verify behavior, not implementation details [4]
+- [ ] All branches covered: happy path + errors + edge cases
+- [ ] Test names describe expected behavior [4]
+- [ ] Tests follow Arrange-Act-Assert structure [17]
+- [ ] No real delays — use fake timers [19]
+- [ ] No flaky patterns (race conditions, timing dependencies) [11][18]