Git Hooks & Quality Gates

ContextKit provides framework-aware quality checks via Git hooks. No external dependencies like Husky required — works in any git repo, not just Node.js projects.

Why Quality Gates?

Quality gates are automated checkpoints that enforce standards before code reaches the repository. They catch what human review misses under time pressure — and what AI assistants can get wrong even with good context.

In traditional development

Code review catches bugs — but review quality drops as teams scale, timelines tighten, and reviewers grow fatigued. Quality gates automate the baseline so review can focus on logic and design, not formatting and test coverage.

In the age of AI

AI writes code fast — sometimes faster than anyone reviews it. It can generate plausible-looking code that doesn't type-check, skips tests, or violates project conventions. Quality gates are the mechanical layer that enforces standards regardless of how the code was written.

Where quality gates fit in the ContextKit workflow

1. Context (MD-first specs + standards) — reduces AI hallucination upstream, before a line of code is written
2. Squad workflow (PO → Architect → Dev → Test → Review) — structures what gets built and how
3. Quality gates (pre-push hook) — enforces standards mechanically at the git layer, no exceptions

Specs and squad reduce the chance of bad code being written. Quality gates catch it if it slips through anyway. They're the last line of defense — and the only one that's automatic.

Overview

Hook	What it does
pre-push	Auto-detects your framework and runs quality checks before pushing
commit-msg	Enforces Conventional Commits format

No dependencies required

ContextKit uses git config core.hooksPath to point Git at .contextkit/hooks/. No npm packages, no Husky, no lint-staged. Works with any language.

How It Works

1During install

ck install copies hook scripts from the ContextKit repo into .contextkit/hooks/ in your project, then runs git config core.hooksPath .contextkit/hooks to point Git at them.

2For Node.js projects

A prepare script is added to package.json so hooks activate automatically for all developers after npm install.

"scripts": {
  "prepare": "git config core.hooksPath .contextkit/hooks"
}

3For non-Node projects

Each developer runs bash .contextkit/hooks/setup-hooks.sh once, or adds the git config command to their build tool's setup task.

Pre-push Quality Gates

The pre-push hook auto-detects your project framework and runs the appropriate quality checks. All gates are skipped silently when tools aren't installed.

Framework	Checks
Node.js	TypeScript, ESLint, Prettier, build, test, e2e tests — each check only runs when that tool or script is present in `package.json`; auto-detects npm/yarn/pnpm/bun
Python	ruff/flake8, mypy, black/ruff format, pytest
Rust	cargo check, clippy, cargo test
Go	go vet, golangci-lint, go test
PHP	PHPStan, PHPUnit
Ruby	RuboCop, RSpec/rake test
Java	Maven verify / Gradle check
Kotlin	ktlint, Gradle test
Swift	SwiftLint, swift test
.NET / C#	dotnet build, dotnet test

Silent skipping

If a tool isn't installed (e.g., no ESLint in your project), that gate is skipped silently — it won't block your push. Only installed tools are checked.

When a gate fails

  [3] Tests
  npm test
  FAIL src/checkout.test.js
  ...

  ❌ Quality Gates FAILED — push blocked.

The push is blocked and the failing gate is shown. Fix the issue and push again, or use git push --no-verify to bypass for emergencies.

Commit Message Hook

When enabled, the commit-msg hook enforces Conventional Commits format:

<type>(<scope>): <description>

Types: feat, fix, improve, docs, refactor, test, chore

Auto-skipped: merge commits, reverts, fixups, and squash commits are never validated.

Minimum length: subject line must be at least 10 characters.

Examples

feat(auth): add login pagefix: resolve null pointer in checkoutimprove(perf): reduce bundle sizedocs: update API referencetest(cart): add edge case coverage

Team Setup

One developer enables hooks during ck install. For Node.js projects, the prepare script ensures hooks work for everyone automatically.

Node.js projects

The prepare script in package.json runs automatically after npm install, so hooks activate for all developers without any extra steps.

Other projects (Python, Rust, Go, etc.)

Add this to your project's setup instructions or Makefile:

git config core.hooksPath .contextkit/hooks

Configuration

Skip hooks during install

ck install --no-hooks

Skip hooks for a single push

git push --no-verify

Uninstall hooks

git config --unset core.hooksPath

Troubleshooting

Hooks not running after clone (non-Node projects)

For non-Node projects there's no prepare script to auto-configure hooks after clone. Each developer needs to run this once:

git config core.hooksPath .contextkit/hooks

Add this to your project's Makefile, justfile, or onboarding docs so new team members don't miss it.

When to use `git push --no-verify`

--no-verify bypasses all hooks for a single push. Use it sparingly — it's an escape hatch, not a workflow:

Emergency fix where a flaky test is blocking a critical deploy
Pushing a WIP branch you know isn't ready for full checks
Debugging the hook itself

Don't use it to avoid fixing a legitimate failure — that defeats the purpose of quality gates.

A tool is installed but its gate is still skipped

Gates are skipped silently when the tool isn't found in the expected location. Common causes:

Node.js gates (TypeScript, ESLint, Prettier): the hook checks package.json for the dependency — if it's installed globally but not listed in dependencies or devDependencies, the gate is skipped
Build/test gates: the hook checks for a matching script key in package.json#scripts — if the script is named differently (e.g. unit-test instead of test), the gate won't run
All gates: if the tool isn't on $PATH when git runs the hook, it won't be found — check that your shell profile exports the right paths

CI Squad

Platform Examples

Was this helpful?

Help us improve the documentation by sharing your feedback.