Universal Hooks - Zero-Config Quality Gates for Every Project

> Install once, forget forever. Your code quality is now on autopilot.

What Is This?

A smart hook system that auto-detects your project stack and installs exactly the quality gates you need. No configuration files to edit. No boilerplate to copy. It just works.

Supported Quality Gates

Code Quality

| Gate | What It Checks | Languages | |------|---------------|-----------| | Formatter | Code formatting consistency | All (Prettier, Biome, Black, gofmt) | | Linter | Code quality rules & anti-patterns | JS/TS (ESLint), Python (Ruff), Rust (Clippy), Go (golint) | | Type Check | Type correctness | TypeScript, Python (pyright/mypy) | | Import Sort | Import ordering & cleanup | JS/TS, Python |

Security

| Gate | What It Checks | |------|---------------| | Secrets Detection | API keys, tokens, passwords in code | | Dependency Audit | Known vulnerable dependencies | | License Check | License compliance of dependencies | | Permissions Check | File permission anomalies |

Git Hygiene

| Gate | What It Checks | |------|---------------| | Commit Message | Conventional Commits format | | Branch Name | Team branch naming convention | | File Size | Prevent large file commits | | Binary Files | Prevent unexpected binary commits | | Merge Markers | Detect leftover conflict markers | | Debug Code | Detect console.log, debugger, TODO/FIXME | | AI Markers | Track AI-generated code with markers |

Auto-Detection

When you run "setup git hooks", the skill:

1. Scans project root for config files (package.json, pyproject.toml, Cargo.toml, go.mod, etc.)
2. Detects languages from file extensions and configs
3. Detects tools from devDependencies and config files
4. Generates hook scripts tailored to your stack
5. Installs hooks via .husky/ or .git/hooks/

Detection Examples

Detected: package.json → JavaScript/TypeScript project
  ├─ eslint config found → Enable ESLint hook
  ├─ prettier config found → Enable Prettier hook
  ├─ typescript found → Enable TypeScript check hook
  └─ No conventional commits → Enable commit message hook

Detected: pyproject.toml → Python project
  ├─ ruff config found → Enable Ruff hook
  ├─ mypy config found → Enable type check hook
  └─ No black config → Suggest Biome for formatting

Detected: Cargo.toml → Rust project
  ├─ Enable cargo clippy hook
  ├─ Enable cargo fmt hook
  └─ Enable cargo test hook

Hook Scripts

Pre-Commit Hook

bash
#!/bin/bash
# Auto-generated by Universal Hooks Skill
# Project: my-awesome-project
# Generated: 2026-03-20

set -e

echo "🔍 Running quality gates..."

# === Formatters ===
if command -v prettier &> /dev/null; then
  echo "  ▶ Checking formatting (Prettier)..."
  npx prettier --check "src/**/*.{ts,tsx,js,jsx,json,css,md}" || {
    echo "  ❌ Formatting issues found. Running auto-fix..."
    npx prettier --write "src/**/*.{ts,tsx,js,jsx,json,css,md}"
    echo "  ✅ Formatting fixed. Please review and re-commit."
    exit 1
  }
fi

# === Linters ===
if [ -f ".eslintrc*" ] || [ -f "eslint.config.*" ]; then
  echo "  ▶ Running ESLint..."
  npx eslint src/ --max-warnings 0 || {
    echo "  ❌ ESLint errors found. Fix them before committing."
    exit 1
  }
fi

# === Type Checking ===
if [ -f "tsconfig.json" ]; then
  echo "  ▶ Running TypeScript check..."
  npx tsc --noEmit || {
    echo "  ❌ TypeScript errors found."
    exit 1
  }
fi

# === Security ===
echo "  ▶ Scanning for secrets..."
if command -v trufflehog &> /dev/null; then
  trufflehog --no-update . 2>/dev/null || {
    echo "  ❌ Potential secrets detected! Remove them before committing."
    exit 1
  }
fi

# === AI Code Markers ===
echo "  ▶ Checking AI code markers..."
if grep -r "AI-GENERATED" --include="*.ts" --include="*.tsx" --include="*.py" .; then
  echo "  ⚠️  AI-generated code detected. Ensure it's been reviewed."
fi

# === Debug Code ===
echo "  ▶ Checking for debug code..."
if grep -rn "console\.log\|console\.debug\|debugger\|binding\.pry" --include="*.ts" --include="*.tsx" --include="*.js" src/ 2>/dev/null; then
  echo "  ⚠️  Debug code detected. Remove before committing."
  # Warning only, don't block
fi

# === Conflict Markers ===
if grep -rn "<<<<<<\|>>>>>>\|=======" --include="*.ts" --include="*.tsx" --include="*.py" --include="*.js" src/ 2>/dev/null; then
  echo "  ❌ Merge conflict markers found! Resolve before committing."
  exit 1
fi

# === Large Files ===
MAX_FILE_SIZE=500  # KB
LARGE_FILES=$(find . -type f -size +${MAX_FILE_SIZE}k -not -path "./node_modules/*" -not -path "./.git/*" -not -path "./dist/*" -newer .git/HEAD 2>/dev/null)
if [ -n "$LARGE_FILES" ]; then
  echo "  ⚠️  Large files detected:"
  echo "$LARGE_FILES" | while read file; do
    echo "    - $file ($(du -k "$file" | cut -f1)KB)"
  done
  echo "  Consider using Git LFS for files > ${MAX_FILE_SIZE}KB."
fi

echo "✅ All quality gates passed!"

Commit Message Hook

bash
#!/bin/bash
# Enforces Conventional Commits format

COMMIT_MSG_FILE=$1
COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")

# Conventional Commits pattern:
# type(scope): description
# Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
PATTERN='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?:\s.+'

if ! echo "$COMMIT_MSG" | grep -qE "$PATTERN"; then
  echo "❌ Invalid commit message format!"
  echo ""
  echo "Expected: type(scope): description"
  echo ""
  echo "Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert"
  echo ""
  echo "Examples:"
  echo "  feat(auth): add JWT token refresh"
  echo "  fix(api): handle null response from user endpoint"
  echo "  docs: update README installation guide"
  echo "  refactor(utils): extract date formatter to separate module"
  echo ""
  echo "Your message: $COMMIT_MSG"
  exit 1
fi

# Check body line length (72 chars max)
BODY=$(echo "$COMMIT_MSG" | sed '1d' | sed '/^$/d' | head -1)
if [ -n "$BODY" ] && [ ${#BODY} -gt 72 ]; then
  echo "⚠️  Commit body line too long (${#BODY} > 72 chars). Consider wrapping."
fi

echo "✅ Commit message format valid."

Pre-Push Hook

bash
#!/bin/bash
# Runs before pushing to remote

set -e

echo "🚀 Pre-push checks..."

# === Run Tests ===
if [ -f "package.json" ]; then
  if jq -e '.scripts.test' package.json > /dev/null 2>&1; then
    echo "  ▶ Running tests..."
    npm test -- --passWithNoTests || {
      echo "  ❌ Tests failed. Fix before pushing."
      exit 1
    }
  fi
fi

# === Check Branch Name ===
BRANCH=$(git branch --show-current)
PROTECTED_BRANCHES=("main" "master" "develop" "staging")
if [[ " ${PROTECTED_BRANCHES[*]} " =~ " ${BRANCH} " ]]; then
  echo "  ❌ Direct push to '$BRANCH' is not allowed. Use a feature branch and PR."
  exit 1
fi

# === Dependency Audit ===
if [ -f "package.json" ]; then
  echo "  ▶ Running dependency audit..."
  npm audit --audit-level=high || {
    echo "  ❌ High severity vulnerabilities found. Run 'npm audit fix' first."
    exit 1
  }
fi

echo "✅ Pre-push checks passed! Pushing to origin/$BRANCH..."

AI Code Markers

When the AI agent generates code, it should add markers for traceability:

typescript
// AI-GENERATED: This function was generated by an AI coding assistant
// Reviewed-by: <developer-name> on 2026-03-20
// Confidence: high
export function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

The pre-commit hook checks for unreviewed AI-generated code:

bash
# Check for AI markers that haven't been reviewed
if grep -r "AI-GENERATED" src/ | grep -v "Reviewed-by"; then
  echo "⚠️  Unreviewed AI-generated code found. Please review and add 'Reviewed-by' marker."
fi

GitHub Actions Templates

CI Quality Gate

yaml
name: Quality Gates
on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Type Check
        run: npx tsc --noEmit
      
      - name: Lint
        run: npx eslint src/ --max-warnings 0
      
      - name: Format Check
        run: npx prettier --check .
      
      - name: Test
        run: npm test -- --coverage
      
      - name: Security Audit
        run: npm audit --audit-level=high
      
      - name: Check AI Code Reviews
        run: |
          UNREVIEWED=$(grep -r "AI-GENERATED" src/ | grep -v "Reviewed-by" | wc -l)
          if [ "$UNREVIEWED" -gt 0 ]; then
            echo "::warning::$UNREVIEWED AI-generated files need review"
          fi

Quick Start Commands

| Command | Description | |---------|-------------| | "setup git hooks" | Auto-detect stack and install all hooks | | "setup pre-commit only" | Install only pre-commit hook | | "setup commit convention" | Install only commit message hook | | "setup CI pipeline" | Generate GitHub Actions config | | "check hooks status" | Show currently active hooks | | "update hooks" | Re-run detection and update hooks |

Stack Support Matrix

| Stack | Formatter | Linter | Type Check | Test | Security | |-------|-----------|--------|------------|------|----------| | React/Next.js | Prettier | ESLint | tsc | Jest/Vitest | npm audit | | Vue/Nuxt | Prettier | ESLint | tsc | Vitest | npm audit | | Python/Django | Black/Biome | Ruff | mypy/pyright | pytest | pip audit | | Go | gofmt | golint | - | go test | govulncheck | | Rust | rustfmt | Clippy | - | cargo test | cargo audit | | Java/Spring | google-java-format | Checkstyle | javac | JUnit | OWASP Dep-Check |

Integration Notes

This skill works with any AI coding agent that supports the SKILL.md standard:

• Claude Code, Codex CLI, Cursor, Windsurf, GitHub Copilot
• CodeBuddy, OpenClaw, and any compatible agent
• Hooks are plain bash scripts for maximum portability
• GitHub Actions templates are ready-to-use YAML files