ai-guard-plugins 1.1.0

package/plugins/cline/hooks/PreToolUse

@@ -0,0 +1,200 @@
+#!/bin/bash
+# =============================================================================
+# AI Guard Plugin: PreToolUse Hook for Cline
+# Combines: billing-guard (before), dry-guard, cursorrules-enforcer
+#
+# Requires: jq (https://jqlang.github.io/jq/)
+# Contract: reads JSON from stdin, outputs JSON to stdout
+# =============================================================================
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+TOOL=$(echo "$INPUT" | jq -r '.preToolUse.tool // empty' 2>/dev/null || true)
+PARAMS=$(echo "$INPUT" | jq -c '.preToolUse.parameters // {}' 2>/dev/null || echo '{}')
+
+# Default: allow
+allow() { echo '{"cancel":false,"contextModification":"","errorMessage":""}'; exit 0; }
+cancel() { echo "{\"cancel\":true,\"contextModification\":\"\",\"errorMessage\":$(echo "$1" | jq -Rs .)}"; exit 0; }
+warn() { echo "{\"cancel\":false,\"contextModification\":$(echo "$1" | jq -Rs .),\"errorMessage\":\"\"}"; exit 0; }
+
+[ -z "$TOOL" ] && allow
+
+# =============================================================================
+# 1. BILLING GUARD (before) — block commands with billing errors
+# =============================================================================
+if [ "$TOOL" = "execute_command" ]; then
+  COMMAND=$(echo "$PARAMS" | jq -r '.command // empty' 2>/dev/null || true)
+  if [ -n "$COMMAND" ]; then
+    if echo "$COMMAND" | grep -qiE \
+      'payment.method|payment.required|account.is.not.active.*billing|billing.details|quota.exceeded|insufficient.funds|rate.limit.*billing|plan.expired|subscription.inactive'; then
+      cancel "BILLING ERROR detected in command. The API provider requires payment. Fix billing before retrying. Do NOT retry this operation."
+    fi
+  fi
+fi
+
+# =============================================================================
+# 2. CURSORRULES ENFORCER — block code violations
+# =============================================================================
+if [ "$TOOL" = "write_to_file" ] || [ "$TOOL" = "insert_code_block" ] || [ "$TOOL" = "search_and_replace" ]; then
+  FILE_PATH=$(echo "$PARAMS" | jq -r '.path // empty' 2>/dev/null || true)
+  [ -z "$FILE_PATH" ] && allow
+
+  BASENAME=$(basename "$FILE_PATH")
+  LOWER_BASENAME=$(echo "$BASENAME" | tr '[:upper:]' '[:lower:]')
+
+  # Check: documentation files (before extension filter)
+  case "$LOWER_BASENAME" in
+    readme|readme.md|changelog.md|contributing.md)
+      cancel "CURSORRULES VIOLATIONS in ${BASENAME}:\n- DOCUMENTATION: Creating ${BASENAME}. Do not create documentation files unless explicitly requested.\n\nFix these before proceeding."
+      ;;
+  esac
+
+  # Skip non-code extensions
+  EXT="${FILE_PATH##*.}"
+  case "$EXT" in
+    ts|tsx|js|jsx|mts|mjs|cts|cjs) ;;
+    *) ;; # Don't exit — DRY guard may still apply for write_to_file
+  esac
+
+  # Skip excluded paths
+  for skip in node_modules dist .next build .turbo migrations; do
+    [[ "$FILE_PATH" == "$skip/"* || "$FILE_PATH" == *"/$skip/"* ]] && allow
+  done
+
+  # Only run content checks on code files
+  IS_CODE=false
+  case "$EXT" in
+    ts|tsx|js|jsx|mts|mjs|cts|cjs) IS_CODE=true ;;
+  esac
+
+  if [ "$IS_CODE" = true ]; then
+    # Extract content
+    CONTENT=$(echo "$PARAMS" | jq -r '.content // .new_string // empty' 2>/dev/null || true)
+
+    if [ -n "$CONTENT" ]; then
+      VIOLATIONS=""
+
+      # Check: as any / as unknown
+      if echo "$CONTENT" | grep -qE '\bas\s+(any|unknown)\b'; then
+        VIOLATIONS="${VIOLATIONS}\n- TYPE CAST: 'as any' or 'as unknown' found. Use the most specific correct type."
+      fi
+
+      # Check: as Type assertions (exclude import/export aliases like "import { x as Foo }")
+      if echo "$CONTENT" | grep -qE '[^{,]\s+as\s+[A-Z][A-Za-z]+' | grep -vqE '(import|export)\s.*\bas\s'; then
+        VIOLATIONS="${VIOLATIONS}\n- TYPE ASSERTION: 'as Type' found. Avoid type assertions — use type narrowing or generics."
+      fi
+
+      # Check: require()
+      if echo "$CONTENT" | grep -qE '\brequire\s*\('; then
+        VIOLATIONS="${VIOLATIONS}\n- REQUIRE: require() found. Use static imports."
+      fi
+
+      # Check: @ts-ignore / @ts-expect-error
+      if echo "$CONTENT" | grep -qE '@ts-ignore|@ts-expect-error'; then
+        VIOLATIONS="${VIOLATIONS}\n- TS SUPPRESSION: @ts-ignore or @ts-expect-error found. Fix the type error properly."
+      fi
+
+      # Check: TODO / FIXME / HACK / placeholder / later
+      if echo "$CONTENT" | grep -qiE '\bTODO\b|\bFIXME\b|\bHACK\b|\bplaceholder\b|//\s*later\b'; then
+        VIOLATIONS="${VIOLATIONS}\n- PLACEHOLDER: TODO/FIXME/placeholder found. Production-ready code only."
+      fi
+
+      # Check: underscore-prefixed variables/functions
+      if echo "$CONTENT" | grep -qE '(const|let|var|function)\s+_[a-zA-Z]'; then
+        VIOLATIONS="${VIOLATIONS}\n- UNDERSCORE NAMING: Variable/function starting with underscore. Do not use underscore prefixes."
+      fi
+
+      # Check: underscore-prefixed filename
+      if [ "${BASENAME:0:1}" = "_" ]; then
+        VIOLATIONS="${VIOLATIONS}\n- UNDERSCORE FILE: Filename starts with underscore (${BASENAME}). Do not use underscore prefixes."
+      fi
+
+      # Check: index files should only re-export
+      if echo "$BASENAME" | grep -qiE '^index\.(ts|tsx|js|jsx|mts|mjs|cts|cjs)$'; then
+        NON_EXPORT_LINES=$(echo "$CONTENT" | awk '!/^[[:space:]]*(export[[:space:]]+[{*]|export[[:space:]]+type|export[[:space:]]+default|import[[:space:]]|\/\/|\/\*)/ && $0 !~ /^[[:space:]]*$/ {c++} END {print c+0}')
+        if [ "$NON_EXPORT_LINES" -gt 2 ]; then
+          VIOLATIONS="${VIOLATIONS}\n- INDEX LOGIC: Logic found in index file. Index files may only re-export modules."
+        fi
+      else
+        # Check: excessive re-exports in non-index files
+        REEXPORT_COUNT=$(echo "$CONTENT" | grep -cE 'export\s+\{[^}]*\}\s+from\s+' || echo "0")
+        if [ "$REEXPORT_COUNT" -gt 2 ]; then
+          VIOLATIONS="${VIOLATIONS}\n- RE-EXPORTS: Multiple re-exports in non-index file."
+        fi
+      fi
+
+      if [ -n "$VIOLATIONS" ]; then
+        cancel "CURSORRULES VIOLATIONS in ${BASENAME}:$(echo -e "$VIOLATIONS")\n\nFix these before proceeding."
+      fi
+    fi
+  fi
+fi
+
+# =============================================================================
+# 3. DRY GUARD — warn before creating duplicate files
+# =============================================================================
+if [ "$TOOL" = "write_to_file" ]; then
+  FILE_PATH=$(echo "$PARAMS" | jq -r '.path // empty' 2>/dev/null || true)
+  [ -z "$FILE_PATH" ] && allow
+
+  # Only check code files
+  EXT="${FILE_PATH##*.}"
+  case "$EXT" in
+    ts|tsx|js|jsx) ;;
+    *) allow ;;
+  esac
+
+  for skip in node_modules dist .next build .turbo migrations; do
+    [[ "$FILE_PATH" == "$skip/"* || "$FILE_PATH" == *"/$skip/"* ]] && allow
+  done
+
+  # Skip if file already exists (editing, not creating)
+  [ -f "$FILE_PATH" ] && allow
+
+  BASENAME=$(basename "$FILE_PATH")
+  DIRNAME=$(dirname "$FILE_PATH")
+  WARNINGS=""
+
+  # Tokenize filename and search for similar files
+  TOKENS=$(echo "$BASENAME" | sed 's/\.[^.]*$//' | tr '-_.' '\n' | tr '[:upper:]' '[:lower:]' | awk 'length >= 3')
+
+  for token in $TOKENS; do
+    SIMILAR=$(find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) \
+      ! -path "*/node_modules/*" ! -path "*/dist/*" ! -path "*/.next/*" ! -path "*/.turbo/*" \
+      2>/dev/null | grep -Fi -- "$token" | grep -Fv -- "$FILE_PATH" | head -8 || true)
+    if [ -n "$SIMILAR" ]; then
+      COUNT=$(echo "$SIMILAR" | wc -l | tr -d ' ')
+      WARNINGS="${WARNINGS}\nSIMILAR FILES (${COUNT} matching '${token}'):\n${SIMILAR}"
+    fi
+  done
+
+  # Check target directory for existing files
+  if [ -d "$DIRNAME" ]; then
+    EXISTING=$(find "$DIRNAME" -maxdepth 1 -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) 2>/dev/null || true)
+    if [ -n "$EXISTING" ]; then
+      ECOUNT=$(echo "$EXISTING" | wc -l | tr -d ' ')
+      WARNINGS="${WARNINGS}\nTARGET DIR already has ${ECOUNT} file(s):\n$(echo "$EXISTING" | head -15)"
+    fi
+  fi
+
+  # Check for PascalCase symbol collision
+  PASCAL=$(echo "$BASENAME" | sed 's/\.[^.]*$//' | sed -E 's/(^|[-_.])([a-z])/\U\2/g')
+  if [ ${#PASCAL} -ge 3 ]; then
+    for search_dir in src packages lib app; do
+      if [ -d "$search_dir" ]; then
+        COLLISIONS=$(grep -rEl -- "export.*${PASCAL}" "$search_dir" 2>/dev/null | grep -Fv -- "$FILE_PATH" | grep -v node_modules | head -5 || true)
+        if [ -n "$COLLISIONS" ]; then
+          WARNINGS="${WARNINGS}\nSYMBOL COLLISION — '${PASCAL}' already exported from:\n${COLLISIONS}"
+        fi
+      fi
+    done
+  fi
+
+  if [ -n "$WARNINGS" ]; then
+    warn "[DRY-GUARD] Before creating ${BASENAME}:$(echo -e "$WARNINGS")\n\nConsider extending an existing file instead of creating a new one."
+  fi
+fi
+
+allow

package/plugins/cline/hooks/TaskComplete

@@ -0,0 +1,134 @@
+#!/bin/bash
+# =============================================================================
+# AI Guard Plugin: TaskComplete Hook for Cline
+# Simplified: capture-insights (pattern matching + JSONL logging)
+#
+# Requires: jq (https://jqlang.github.io/jq/)
+# Contract: reads JSON from stdin, outputs JSON to stdout
+# =============================================================================
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+TASK_SUMMARY=$(echo "$INPUT" | jq -r '.taskComplete.summary // empty' 2>/dev/null || true)
+
+# Default: allow (never cancel on TaskComplete)
+allow() { echo '{"cancel":false,"contextModification":"","errorMessage":""}'; exit 0; }
+inform() { echo "{\"cancel\":false,\"contextModification\":$(echo "$1" | jq -Rs .),\"errorMessage\":\"\"}"; exit 0; }
+
+[ -z "$TASK_SUMMARY" ] && allow
+
+# =============================================================================
+# Memory file location
+# =============================================================================
+MEMORY_DIR="${HOME}/.cline/memory"
+MEMORY_FILE="${MEMORY_DIR}/insights.jsonl"
+
+mkdir -p "$MEMORY_DIR"
+
+# =============================================================================
+# Pattern checks (from capture-insights.ts)
+# =============================================================================
+MATCHED_IDS=""
+NOW=$(date -u +"%Y-%m-%dT%H:%M")
+PROJECT_NAME=$(basename "${PWD}")
+
+check_pattern() {
+  local id="$1"
+  local pattern="$2"
+  local insight="$3"
+
+  if echo "$TASK_SUMMARY" | grep -qiE "$pattern"; then
+    MATCHED_IDS="${MATCHED_IDS} ${id}"
+
+    if [ -f "$MEMORY_FILE" ] && grep -q "\"id\":\"${id}\"" "$MEMORY_FILE" 2>/dev/null; then
+      # Increment count for existing entry (using jq --arg for safe interpolation)
+      TMPFILE=$(mktemp)
+      while IFS= read -r line; do
+        if echo "$line" | grep -q "\"id\":\"${id}\""; then
+          OLD_COUNT=$(echo "$line" | jq -r '.count')
+          NEW_COUNT=$((OLD_COUNT + 1))
+          OLD_PROJECTS=$(echo "$line" | jq -r '.projects')
+          NEW_PROJECTS="$OLD_PROJECTS"
+          # Exact token match for project name (not substring)
+          if ! printf '%s' "$OLD_PROJECTS" | tr ',' '\n' | grep -Fxq -- "$PROJECT_NAME"; then
+            NEW_PROJECTS="${OLD_PROJECTS},${PROJECT_NAME}"
+          fi
+          echo "$line" | jq -c --argjson count "$NEW_COUNT" --arg last "$NOW" --arg projects "$NEW_PROJECTS" \
+            '.count = $count | .last = $last | .projects = $projects'
+        else
+          echo "$line"
+        fi
+      done < "$MEMORY_FILE" > "$TMPFILE"
+      mv "$TMPFILE" "$MEMORY_FILE"
+    else
+      # Create new entry
+      jq -nc --arg id "$id" --arg insight "$insight" --arg last "$NOW" --arg projects "$PROJECT_NAME" \
+        '{id: $id, insight: $insight, count: 1, last: $last, projects: $projects}' >> "$MEMORY_FILE"
+    fi
+  fi
+}
+
+check_pattern "dry-violation" \
+  "DRY|don.t repeat|already exists|duplicat" \
+  "Check existing files before creating new ones. Extract shared utils when there is clear reuse."
+
+check_pattern "unused-code" \
+  "unused import|unused variable|dead code" \
+  "Biome --fix handles unused imports/variables automatically."
+
+check_pattern "type-safety-bypass" \
+  "as any|ts-ignore|ts-expect-error" \
+  "Never use as any or ts-ignore. Use the most specific correct type."
+
+check_pattern "scope-discipline" \
+  "refactor.*minimal|minimal change|scope creep" \
+  "Make the minimal change needed. Do not refactor while fixing."
+
+check_pattern "circular-dep" \
+  "circular dependency|circular import" \
+  "Restructure module boundaries to break circular dependencies."
+
+check_pattern "re-export" \
+  "re-export|barrel file|index file.*logic" \
+  "Avoid re-exports. Index files may only re-export modules, never logic."
+
+check_pattern "path-resolution" \
+  "process.cwd|project root.*monorepo" \
+  "Never assume process.cwd() equals project root in monorepos."
+
+check_pattern "data-migration" \
+  "migration|schema change|database migrat" \
+  "Verify schema and data integrity after migrations. Make migrations idempotent."
+
+check_pattern "workaround" \
+  "workaround|hack|bandaid|band-aid" \
+  "Document why workaround was needed and plan a proper fix."
+
+check_pattern "performance" \
+  "performance|slow query|optimize|bottleneck" \
+  "Profile before optimizing. Measure, do not guess."
+
+check_pattern "security" \
+  "security|secret|credential|api.key|token leak" \
+  "Review credentials handling. Never commit secrets."
+
+check_pattern "test-mock" \
+  "test.*mock.*implementation|mock.*detail" \
+  "Mock behavior (modules), not implementation details."
+
+if [ -n "$MATCHED_IDS" ]; then
+  ENTRY_COUNT=0
+  [ -f "$MEMORY_FILE" ] && ENTRY_COUNT=$(wc -l < "$MEMORY_FILE" | tr -d ' ')
+
+  # Squeeze to top 15 if over limit
+  if [ "$ENTRY_COUNT" -gt 15 ]; then
+    TMPFILE=$(mktemp)
+    jq -s 'sort_by(-.count) | .[0:15] | .[]' "$MEMORY_FILE" > "$TMPFILE" 2>/dev/null && mv "$TMPFILE" "$MEMORY_FILE" || true
+  fi
+
+  inform "[capture-insights] Patterns detected in session (${PROJECT_NAME}, ${ENTRY_COUNT} total entries). Learning from this session."
+fi
+
+allow

package/plugins/cline/hooks/UserPromptSubmit

@@ -0,0 +1,29 @@
+#!/bin/bash
+# =============================================================================
+# AI Guard Plugin: UserPromptSubmit Hook for Cline
+# Simplified: auto-summarize-input (warns about large inputs)
+#
+# Requires: jq (https://jqlang.github.io/jq/)
+# Contract: reads JSON from stdin, outputs JSON to stdout
+# =============================================================================
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+PROMPT=$(echo "$INPUT" | jq -er '.userPromptSubmit.userPrompt // empty' 2>/dev/null || true)
+
+# Default: allow
+allow() { echo '{"cancel":false,"contextModification":"","errorMessage":""}'; exit 0; }
+warn() { echo "{\"cancel\":false,\"contextModification\":$(echo "$1" | jq -Rs .),\"errorMessage\":\"\"}"; exit 0; }
+
+[ -z "$PROMPT" ] && allow
+
+THRESHOLD=10000
+CHAR_COUNT=${#PROMPT}
+
+if [ "$CHAR_COUNT" -gt "$THRESHOLD" ]; then
+  warn "[auto-summarize] Input is very large (${CHAR_COUNT} chars). Before processing, summarize this input while preserving ALL code snippets, file paths, error messages, and requirements verbatim. Remove ONLY redundancy, repetition, and filler text."
+fi
+
+allow

package/plugins/cursor/rules/auto-lint-fix.mdc

@@ -0,0 +1,21 @@
+---
+description: "Auto-format code with Biome after every file write or edit"
+globs: "**/*.ts,**/*.tsx,**/*.js,**/*.jsx,**/*.mts,**/*.mjs,**/*.cts,**/*.cjs"
+alwaysApply: false
+---
+
+# Auto Lint Fix
+
+After EVERY file write or edit to a TypeScript/JavaScript file, run:
+
+```bash
+"${BIOME_PATH:-biome}" check --fix --unsafe <filepath>
+```
+
+## Rules
+
+- Only run on code files: .ts, .tsx, .js, .jsx, .mts, .mjs, .cts, .cjs
+- Skip files in: node_modules, dist, .next, build, .turbo
+- If `BIOME_PATH` environment variable is set, use that path instead of `biome`
+- If Biome is not installed, skip formatting (do not fail)
+- Do not manually fix formatting issues that Biome handles automatically

package/plugins/cursor/rules/auto-summarize-input.mdc

@@ -0,0 +1,17 @@
+---
+description: "Summarize large inputs to preserve context window tokens"
+alwaysApply: true
+---
+
+# Auto Summarize Input
+
+When receiving input that exceeds 10,000 characters, summarize it before processing.
+
+## Summarization rules
+
+- Preserve ALL code snippets verbatim
+- Preserve ALL file paths verbatim
+- Preserve ALL error messages verbatim
+- Preserve ALL requirements and specifications verbatim
+- Remove ONLY: redundancy, repetition, and filler text
+- Note the original character count and reduction percentage

package/plugins/cursor/rules/billing-guard.mdc

@@ -0,0 +1,26 @@
+---
+description: "Detect and stop on billing/API payment errors to prevent infinite retry loops"
+alwaysApply: true
+---
+
+# Billing Guard
+
+If ANY API call, tool execution, or command output contains text matching these patterns, IMMEDIATELY stop all operations:
+
+- "no payment method" or "add a payment method"
+- "payment required"
+- "account is not active" with "billing"
+- "billing details"
+- "quota exceeded"
+- "insufficient funds"
+- "rate limit" with "billing"
+- "plan expired"
+- "subscription inactive"
+
+## Required behavior
+
+1. STOP all current operations immediately
+2. Do NOT retry the failed operation
+3. Do NOT delegate or spawn sub-tasks
+4. Notify the user that billing needs to be fixed before continuing
+5. Do NOT attempt workarounds or alternative approaches — the billing issue must be resolved first

package/plugins/cursor/rules/capture-insights.mdc

@@ -0,0 +1,32 @@
+---
+description: "Track and learn from recurring coding mistakes across sessions"
+alwaysApply: true
+---
+
+# Capture Insights
+
+Monitor your own outputs and actions for these recurring anti-patterns. When detected, apply the corresponding lesson immediately.
+
+## Tracked patterns
+
+| Pattern | Lesson |
+|---------|--------|
+| DRY violation ("already exists", "duplicate") | Check existing files before creating new ones. Extract shared utils for clear reuse. |
+| Unused code (imports, variables, dead code) | Biome --fix handles unused imports/variables automatically. |
+| Type safety bypass (as any, ts-ignore) | Never use as any or ts-ignore. Use the most specific correct type. |
+| Scope creep (refactoring while fixing) | Make the minimal change needed. Do not refactor while fixing. |
+| Circular dependencies | Restructure module boundaries to break circular dependencies. |
+| Re-export overuse (barrel files with logic) | Index files may only re-export modules, never contain logic. |
+| Path resolution (process.cwd assumptions) | Never assume process.cwd() equals project root in monorepos. |
+| Migration issues | Verify schema and data integrity after migrations. Make migrations idempotent. |
+| Workarounds and hacks | Document why the workaround was needed and plan a proper fix. |
+| Performance guessing | Profile before optimizing. Measure, do not guess. |
+| Security (secrets, credentials, tokens) | Review credentials handling. Never commit secrets. |
+| Test mock overreach | Mock behavior (modules), not implementation details. |
+
+## Required behavior
+
+When you detect one of these patterns in your own work:
+1. Stop and acknowledge the pattern
+2. Apply the corresponding lesson
+3. Correct the action before proceeding

package/plugins/cursor/rules/code-standards.mdc

@@ -0,0 +1,77 @@
+---
+description: "Enforce TypeScript/JavaScript coding standards on every file write and edit"
+globs: "**/*.ts,**/*.tsx,**/*.js,**/*.jsx,**/*.mts,**/*.mjs,**/*.cts,**/*.cjs"
+alwaysApply: false
+---
+
+# Code Standards Enforcer
+
+These rules apply to every code file write and edit. Violations must be fixed before proceeding.
+
+## Type safety
+
+- Never use `as any` or `as unknown`. Use the most specific correct type.
+- Never use `as Type` assertions. Use type narrowing, generics, or satisfies instead.
+- Never use `@ts-ignore` or `@ts-expect-error`. Fix the underlying type error.
+
+```typescript
+// Bad
+const data = response as any;
+const user = getUser() as UserType;
+// @ts-ignore
+brokenCall();
+
+// Good
+const data: ApiResponse = response;
+const user = getUser(); // return type already UserType
+```
+
+## Import style
+
+- Never use `require()`. Use static `import` statements.
+
+```typescript
+// Bad
+const fs = require('fs');
+
+// Good
+import fs from 'node:fs';
+```
+
+## No placeholders
+
+- Never leave `TODO`, `FIXME`, `HACK`, `placeholder`, or `// later` comments. All code must be production-ready.
+
+## Naming
+
+- Never prefix variables or functions with underscore (`_`).
+- Never prefix filenames with underscore.
+
+```typescript
+// Bad
+const _count = 0;
+function _helper() {}
+
+// Good
+const count = 0;
+function helper() {}
+```
+
+## Index files
+
+- Index/barrel files (`index.ts`, `index.js`) may ONLY contain re-exports. No business logic.
+- Non-index files may have at most 2 re-export statements.
+
+```typescript
+// Good index.ts
+export { UserService } from './user-service';
+export { AuthService } from './auth-service';
+
+// Bad index.ts
+export { UserService } from './user-service';
+const cache = new Map(); // logic does not belong here
+```
+
+## Documentation files
+
+- Do not create README.md, CHANGELOG.md, or CONTRIBUTING.md unless explicitly requested.

package/plugins/cursor/rules/dry-guard.mdc

@@ -0,0 +1,31 @@
+---
+description: "Check for duplicate files and symbol collisions before creating new code files"
+globs: "**/*.ts,**/*.tsx,**/*.js,**/*.jsx"
+alwaysApply: false
+---
+
+# DRY Guard
+
+Before creating ANY new code file (.ts, .tsx, .js, .jsx), perform these checks:
+
+## 1. Similar file search
+
+Tokenize the new filename by splitting on `-`, `_`, and `.` (ignore tokens shorter than 3 characters). Search the project for existing files whose names contain any of those tokens.
+
+Skip directories: node_modules, dist, .next, build, .turbo, migrations
+
+## 2. Target directory check
+
+List existing code files in the target directory. If the directory already contains files, consider whether the new file's logic belongs in one of them.
+
+## 3. Symbol collision check
+
+Convert the filename to PascalCase (e.g., `format-date.ts` becomes `FormatDate`). Search `src/`, `packages/`, `lib/`, and `app/` for existing exports matching that name.
+
+## Required behavior
+
+- If similar files are found: review them before creating a new file
+- If the symbol already exists: extend the existing file instead
+- If the target directory has related files: consolidate rather than create
+
+Do NOT create a new file when extending an existing one would be cleaner.