---
name: gitstq/universal-hooks
source: https://app.decimal.ai/s/gitstq-universal-hooks@1/SKILL.md
source_sha256: fd9aa5532a3d
---

# 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