devflow-kit 0.9.0 → 1.1.0

package/shared/skills/self-review/references/violations.md

@@ -0,0 +1,308 @@
+# Self-Review Violations
+
+Common anti-patterns and code violations organized by the 9 pillars.
+
+---
+
+## Self-Review Process Violations
+
+| Violation | Problem | Fix |
+|-----------|---------|-----|
+| Skipping pillars | Incomplete review | Check all 9 pillars |
+| Ignoring P0/P1 issues | Returning broken code | Fix before returning |
+| Surface-level review | Missing deep issues | Review each pillar thoroughly |
+| No evidence | Unverifiable claims | Reference specific code |
+| Deferring critical fixes | Technical debt | Fix CRITICAL/HIGH immediately |
+
+---
+
+## P0 Pillars (MUST Fix)
+
+### 1. Design Violations
+
+**Question**: Does the implementation fit the architecture?
+
+**Red Flags**:
+```typescript
+// BAD: Direct database access in controller
+class UserController {
+  async getUser(req, res) {
+    const user = await db.query('SELECT * FROM users WHERE id = ?', [req.params.id]);
+  }
+}
+
+// BAD: God class doing everything
+class ApplicationManager {
+  createUser() {}
+  processPayment() {}
+  sendEmail() {}
+  generateReport() {}
+  // 500 more methods...
+}
+
+// BAD: Circular dependencies
+// a.ts imports b.ts, b.ts imports a.ts
+```
+
+**Checklist**:
+- [ ] Follows existing patterns in codebase
+- [ ] Respects layer boundaries (controller/service/repository)
+- [ ] Dependencies injected, not instantiated
+- [ ] Not over-engineering (YAGNI)
+- [ ] Not under-engineering (technical debt)
+- [ ] Interactions with other components are sound
+
+---
+
+### 2. Functionality Violations
+
+**Question**: Does the code work as intended?
+
+**Red Flags**:
+```typescript
+// BAD: Missing null check
+function getDisplayName(user: User) {
+  return user.profile.displayName;  // user.profile could be undefined!
+}
+
+// BAD: Race condition
+let balance = await getBalance();
+if (balance >= amount) {
+  await withdraw(amount);  // Balance could change between check and withdraw!
+}
+
+// BAD: Off-by-one error
+for (let i = 0; i <= array.length; i++) {  // Should be < not <=
+  process(array[i]);
+}
+```
+
+**Checklist**:
+- [ ] Happy path works correctly
+- [ ] Edge cases handled (null, empty, boundary values)
+- [ ] Error cases handled gracefully
+- [ ] No race conditions in concurrent code
+- [ ] No infinite loops or recursion without base case
+- [ ] State mutations are intentional and correct
+
+---
+
+### 3. Security Violations
+
+**Question**: Are there security vulnerabilities?
+
+**Red Flags**:
+```typescript
+// BAD: SQL injection
+const query = `SELECT * FROM users WHERE email = '${email}'`;
+
+// BAD: Command injection
+exec(`ls ${userInput}`);
+
+// BAD: Hardcoded secret
+const API_KEY = 'sk-abc123xyz789';
+
+// BAD: Missing auth check
+app.delete('/api/users/:id', async (req, res) => {
+  await deleteUser(req.params.id);  // No auth!
+});
+```
+
+**Checklist**:
+- [ ] No SQL/NoSQL injection
+- [ ] No command injection
+- [ ] No XSS vulnerabilities
+- [ ] Input validated at boundaries
+- [ ] No hardcoded secrets
+- [ ] Authentication/authorization checked
+- [ ] Sensitive data not logged
+
+---
+
+## P1 Pillars (SHOULD Fix)
+
+### 4. Complexity Violations
+
+**Question**: Can a reader understand this in 5 minutes?
+
+**Red Flags**:
+```typescript
+// BAD: Deep nesting
+if (a) {
+  if (b) {
+    if (c) {
+      if (d) {
+        if (e) {
+          // actual logic buried here
+        }
+      }
+    }
+  }
+}
+
+// BAD: Magic numbers
+setTimeout(callback, 86400000);
+if (status === 3) { }
+```
+
+**Checklist**:
+- [ ] Functions are < 50 lines
+- [ ] Nesting depth < 4 levels
+- [ ] Cyclomatic complexity < 10
+- [ ] No magic numbers/strings
+- [ ] Single responsibility per function
+- [ ] Complex logic has explanatory comments
+
+---
+
+### 5. Error Handling Violations
+
+**Question**: Are errors handled explicitly and consistently?
+
+**Red Flags**:
+```typescript
+// BAD: Swallowed exception
+try {
+  await riskyOperation();
+} catch (e) {
+  // silently ignored!
+}
+
+// BAD: Generic error message
+throw new Error('Something went wrong');
+
+// BAD: Resource leak on error
+const file = await openFile(path);
+await processFile(file);  // If this throws, file never closed!
+await file.close();
+```
+
+**Checklist**:
+- [ ] Errors are caught and handled appropriately
+- [ ] Error messages are helpful (not generic)
+- [ ] No silent failures (swallowed exceptions)
+- [ ] Consistent error handling pattern (Result types or throws)
+- [ ] Resources cleaned up in error paths
+- [ ] Errors logged with context
+
+---
+
+### 6. Tests Violations
+
+**Question**: Is the new functionality tested?
+
+**Red Flags**:
+```typescript
+// BAD: No tests for new function
+export function calculateDiscount(price, type) {
+  // 20 lines of logic with no tests
+}
+
+// BAD: Test that doesn't verify behavior
+it('creates user', async () => {
+  await createUser(data);
+  expect(mockDb.insert).toHaveBeenCalled();  // Only checks mock was called
+});
+
+// BAD: Missing edge case tests
+describe('divide', () => {
+  it('divides numbers', () => {
+    expect(divide(10, 2)).toBe(5);
+  });
+  // No test for divide by zero!
+});
+```
+
+**Checklist**:
+- [ ] New code has corresponding tests
+- [ ] Tests cover happy path
+- [ ] Tests cover error cases
+- [ ] Tests cover edge cases
+- [ ] Tests are not brittle (test behavior, not implementation)
+- [ ] Tests would fail if code breaks
+
+---
+
+## P2 Pillars (FIX if Time Permits)
+
+### 7. Naming Violations
+
+**Question**: Are names clear and descriptive?
+
+**Red Flags**:
+```typescript
+// BAD: Cryptic names
+const d = new Date();
+const r = items.filter(i => i.t > d);
+const x = r.reduce((a, b) => a + b.p, 0);
+
+// BAD: Misleading name
+function getUser(id) {
+  return db.users.findAll();  // Returns ALL users, not one!
+}
+```
+
+**Checklist**:
+- [ ] Variable names describe content
+- [ ] Function names describe action
+- [ ] No single-letter names (except loop indices)
+- [ ] No abbreviations that aren't universal
+- [ ] Consistent naming style (camelCase/snake_case)
+
+---
+
+### 8. Consistency Violations
+
+**Question**: Does this match existing patterns?
+
+**Red Flags**:
+```typescript
+// BAD: Different style than rest of codebase
+// Existing code uses Result types
+function existingFunction(): Result<User, Error> { }
+
+// Your code throws instead
+function yourFunction(): User {
+  throw new Error('...');  // Inconsistent!
+}
+```
+
+**Checklist**:
+- [ ] Follows existing code style
+- [ ] Uses same patterns as surrounding code
+- [ ] Error handling matches project conventions
+- [ ] Import organization matches existing files
+- [ ] No unnecessary divergence from norms
+
+---
+
+### 9. Documentation Violations
+
+**Question**: Will others understand this code?
+
+**Red Flags**:
+```typescript
+// BAD: Missing docs on complex function
+export function calculateProratedBilling(plan, start, end, previous) {
+  // 50 lines of complex billing logic with no explanation
+}
+
+// BAD: Outdated comment
+// Returns user's full name
+function getDisplayName(user) {
+  return user.username;  // Actually returns username!
+}
+```
+
+**Checklist**:
+- [ ] Complex logic has explanatory comments
+- [ ] Public APIs have JSDoc/docstrings
+- [ ] README updated if behavior changes
+- [ ] No outdated comments
+- [ ] Comments explain "why", not "what"
+
+---
+
+## Quick Reference
+
+See [patterns.md](patterns.md) for correct patterns and [report-template.md](report-template.md) for self-review format.

package/shared/skills/test-driven-development/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: test-driven-development
+description: >-
+  Enforce RED-GREEN-REFACTOR cycle during implementation. Write failing tests before
+  production code. Distinct from test-patterns (which reviews test quality) — this
+  skill enforces the TDD workflow during code generation.
+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.
+
+---
+
+## 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 |
+
+See `references/rationalization-prevention.md` for extended examples with code.
+
+---
+
+## Process Enforcement
+
+When implementing any feature under ambient BUILD/STANDARD:
+
+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 depth** — Ambient classified as QUICK (chat, exploration, trivial edits)
+- **Non-code tasks** — Documentation, configuration, CI changes
+- **Exploratory prototyping** — User explicitly says "just spike this" or "prototype"
+- **Existing test suite changes** — Modifying tests themselves (test-patterns skill applies instead)
+
+When skipping TDD, never rationalize. State clearly: "Skipping TDD because: [specific reason from list above]."
+
+---
+
+## Integration with Ambient Mode
+
+- **BUILD/STANDARD** → TDD enforced. Every new function/method gets test-first treatment.
+- **BUILD/QUICK** → TDD skipped (trivial single-file edit).
+- **BUILD/ESCALATE** → TDD mentioned in nudge toward `/implement`.
+- **DEBUG/STANDARD** → TDD applies to the fix: write a test that reproduces the bug first, then fix.

package/shared/skills/test-driven-development/references/rationalization-prevention.md

@@ -0,0 +1,111 @@
+# TDD Rationalization Prevention — Extended Examples
+
+Detailed code examples showing how each rationalization leads to worse outcomes.
+
+## "I'll write tests after"
+
+### What happens:
+
+```typescript
+// Developer writes production code first
+function calculateDiscount(price: number, tier: string): number {
+  if (tier === 'gold') return price * 0.8;
+  if (tier === 'silver') return price * 0.9;
+  return price;
+}
+
+// Then "writes tests after" — but only for the happy path they remember
+test('gold tier gets 20% off', () => {
+  expect(calculateDiscount(100, 'gold')).toBe(80);
+});
+// Missing: negative prices, unknown tiers, zero prices, NaN handling
+```
+
+### What TDD would have caught:
+
+```typescript
+// Test first — forces you to think about the contract
+test('returns error for negative price', () => {
+  expect(calculateDiscount(-100, 'gold')).toEqual({ ok: false, error: 'NEGATIVE_PRICE' });
+});
+// Now the interface includes error handling from the start
+```
+
+## "Too simple to test"
+
+### What happens:
+
+```typescript
+// "It's just a config getter, no test needed"
+function getMaxRetries(): number {
+  return parseInt(process.env.MAX_RETRIES || '3');
+}
+// 6 months later: someone sets MAX_RETRIES="three" and prod crashes with NaN retries
+```
+
+### What TDD would have caught:
+
+```typescript
+test('returns default when env var is not a number', () => {
+  process.env.MAX_RETRIES = 'three';
+  expect(getMaxRetries()).toBe(3); // Forces validation logic
+});
+```
+
+## "Test is too hard to write"
+
+### What happens:
+
+```typescript
+// "I can't test this easily because it needs database + email + filesystem"
+async function processOrder(orderId: string) {
+  const db = new Database();
+  const order = await db.find(orderId);
+  await sendEmail(order.customerEmail, 'Your order is processing');
+  await fs.writeFile(`/invoices/${orderId}.pdf`, generateInvoice(order));
+  await db.update(orderId, { status: 'processing' });
+}
+// Result: untestable monolith, test would need real DB + email + filesystem
+```
+
+### What TDD forces:
+
+```typescript
+// Hard-to-test = bad design. TDD forces dependency injection:
+async function processOrder(
+  orderId: string,
+  deps: { db: OrderRepository; emailer: Emailer; invoices: InvoiceStore }
+): Promise<Result<void, OrderError>> {
+  // Now trivially testable with mocks
+}
+```
+
+## "I'll refactor later"
+
+### What happens:
+
+```typescript
+// Sprint 1: "just get it working"
+function handleRequest(req: any) {
+  if (req.type === 'create') { /* 50 lines */ }
+  else if (req.type === 'update') { /* 50 lines */ }
+  else if (req.type === 'delete') { /* 30 lines */ }
+  // Sprint 2-10: more conditions added, function grows to 500 lines
+  // "Refactor later" never comes because nobody wants to touch it
+}
+```
+
+### What TDD enforces:
+
+Step 3 (REFACTOR) happens every cycle. The function never grows beyond what's clean because you clean it every 5-10 minutes.
+
+## "Tests slow me down"
+
+### The math:
+
+| Approach | Time to write | Time to first bug | Time to fix bug | Total (1 month) |
+|----------|:---:|:---:|:---:|:---:|
+| No TDD | 2h | 4h | 3h (no repro test) | 9h+ |
+| TDD | 3h | Caught in test | 15min (test pinpoints) | 3h 15min |
+
+TDD is slower for the first 30 minutes. It's faster for everything after that.