Setup Pre-Commit Hooks

Invocation Position

This is an infrastructure skill, not a normal feature-delivery stage.

Use /setup-pre-commit when a project needs commit-time formatting, linting, type checking, and test hooks.

Do not use it as part of the default feature pipeline. It prepares the repo so later /execute and /pre-merge steps have stronger feedback loops.

What This Sets Up

• Lefthook for git hook management (fast, zero-dependency, config-as-code)
• Formatting + linting on staged files (Biome preferred; Prettier, ESLint, or others supported)
• Typecheck and test scripts in the pre-commit hook

Steps

1. Detect Package Manager

Check for pnpm-lock.yaml (pnpm), package-lock.json (npm), yarn.lock (yarn), bun.lockb (bun). Use whichever is present. Default to npm if unclear.

Store the detected package manager — it's used for all install and run commands below.

2. Detect Existing Formatter/Linter

Before installing anything, check what's already in the project:

# Check package.json for existing tools
cat package.json | grep -E "biome|prettier|eslint|oxlint|dprint" 2>/dev/null
# Check for config files
ls biome.json biome.jsonc .prettierrc .prettierrc.* prettier.config.* .eslintrc* eslint.config.* 2>/dev/null

If an existing formatter/linter is detected: use it. Don't install a competing tool.

If nothing is detected: recommend Biome (single tool for formatting + linting, fast, zero-config defaults) and confirm with the user before installing.

Ask: "No formatter/linter detected. I'd recommend Biome — it handles both formatting and linting in one tool, is very fast, and works out of the box. Want to go with Biome, or would you prefer Prettier, ESLint, or something else?"

3. Install Dependencies

Install as devDependencies using the detected package manager:

Lefthook (always):

# pnpm
pnpm add -D lefthook

# npm
npm install -D lefthook

# yarn
yarn add -D lefthook

# bun
bun add -D lefthook

Formatter/linter (based on detection or user choice):

4. Initialize Lefthook

npx lefthook install

This creates the git hook symlinks. No .husky/ directory, no prepare script needed — Lefthook manages hooks directly via lefthook.yml.

Add a prepare script to package.json so hooks are installed automatically for anyone who clones the repo:

{
  "scripts": {
    "prepare": "lefthook install"
  }
}

5. Create lefthook.yml

Create lefthook.yml at the repo root. The configuration depends on which formatter/linter was detected or chosen.

With Biome (preferred):

pre-commit:
  parallel: true
  commands:
    format-and-lint:
      glob: "*.{js,ts,jsx,tsx,json,css}"
      run: npx @biomejs/biome check --write --staged {staged_files}
      stage_fixed: true
    typecheck:
      run: {package_manager} run typecheck
    test:
      run: {package_manager} run test

With Prettier:

pre-commit:
  parallel: true
  commands:
    format:
      glob: "*.{js,ts,jsx,tsx,json,css,md,yml,yaml}"
      run: npx prettier --write {staged_files}
      stage_fixed: true
    typecheck:
      run: {package_manager} run typecheck
    test:
      run: {package_manager} run test

With ESLint:

pre-commit:
  parallel: true
  commands:
    lint:
      glob: "*.{js,ts,jsx,tsx}"
      run: npx eslint --fix {staged_files}
      stage_fixed: true
    typecheck:
      run: {package_manager} run typecheck
    test:
      run: {package_manager} run test

With Prettier + ESLint:

pre-commit:
  parallel: true
  commands:
    format:
      glob: "*.{js,ts,jsx,tsx,json,css,md,yml,yaml}"
      run: npx prettier --write {staged_files}
      stage_fixed: true
    lint:
      glob: "*.{js,ts,jsx,tsx}"
      run: npx eslint --fix {staged_files}
      stage_fixed: true
    typecheck:
      run: {package_manager} run typecheck
    test:
      run: {package_manager} run test

Adapt the config:

• Replace {package_manager} with the detected package manager (pnpm, npm, yarn, bun)
• If the repo has no typecheck script in package.json, omit that command and tell the user
• If the repo has no test script in package.json, omit that command and tell the user
• Adjust glob patterns to match the project's file types

6. Create Formatter Config (if missing)

Only create if no config exists and the user chose to install a new tool.

Biome (`biome.json`):

{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "formatter": {
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  }
}

Prettier (`.prettierrc`):

{
  "useTabs": false,
  "tabWidth": 2,
  "printWidth": 80,
  "singleQuote": false,
  "trailingComma": "es5",
  "semi": true,
  "arrowParens": "always"
}

7. Verify

• [ ] lefthook.yml exists at repo root
• [ ] prepare script in package.json is "lefthook install"
• [ ] Formatter/linter config exists
• [ ] Run npx lefthook run pre-commit to verify hooks work
• [ ] No .husky/ directory exists (if migrating from Husky, remove it)

8. Clean Up Husky (if migrating)

If the project previously used Husky:

# Remove Husky artifacts
rm -rf .husky
# Remove Husky from dependencies
{package_manager} remove husky lint-staged
# Remove .lintstagedrc if it exists and is no longer needed
rm -f .lintstagedrc .lintstagedrc.* lint-staged.config.*

Update the prepare script in package.json from "husky" to "lefthook install".

9. Commit

Stage all changed/created files and commit with message:

chore: add pre-commit hooks (lefthook + biome) (or substitute the actual formatter name)

This will run through the new pre-commit hooks — a good smoke test that everything works.

Why Lefthook over Husky

• No node_modules dependency at hook runtime — Lefthook hooks run directly, no npx lint-staged wrapper
• Config as code — lefthook.yml is declarative and version-controlled; Husky uses shell scripts in .husky/
• Parallel execution — runs formatting, typecheck, and tests in parallel by default
• `{staged_files}` built-in — no need for lint-staged as a separate dependency; Lefthook handles staged file filtering natively
• `stage_fixed: true` — automatically re-stages files after formatting fixes, no extra tooling
• Glob filtering — only runs tools on matching file types, no wasted cycles

Why Biome as Default

• Single tool — replaces both Prettier (formatting) and ESLint (linting)
• Fast — written in Rust, 10-100x faster than Prettier + ESLint
• Zero config — works out of the box with sensible defaults
• Compatible — 97% Prettier-compatible formatting, growing ESLint rule coverage
• One config file — biome.json instead of .prettierrc + .eslintrc + conflicting rules

Handoff

• Expected input: a repo that needs commit-time quality gates
• Produces: working git hooks and tool configuration for commit-time checks
• Supports downstream: /execute and /pre-merge by making basic verification more automatic
• What comes next: return to normal feature work with stronger local feedback loops