# Claude Code Kit

> AI coding you can ship to production without a babysitter, with every commit reviewed and gated.
>
> https://pravda.systems/work/claude-code-kit · 2026-06-13

**Problem.** An unsupervised AI agent eventually skips safety checks under pressure (force-pushing, dropping docs, leaking a secret) and none of it sets off an alarm.

**Solution.** A one-command governance layer forces every commit through an AI reviewer and five automated quality gates, namespaced so it never collides with your existing tools.

**Outcome.** You get auditable, recoverable, consistent AI development: each commit is reviewed before it lands, and force-push and history rewrites are physically blocked at the system level.

## Key metrics

- **6,842** Source lines (Python) — Python powering the gates, hooks, installer, and context injector _(verified: wc -l over 27 *.py files at HEAD 027f35a, 2026-07-04)_
- **6** Pre-commit gates — Automated checks on every commit: AI code review, script reasons, link integrity, docs freshness, file-size budgets, secret scanning, all blocking by default _(verified: template/.agent-kit/gates/run_gates_parallel.py PHASE1_GATES + PHASE2_GATES)_
- **31** Skills in the catalogue — The kit's own skills plus the vetted third-party ones, each graded by how far it was actually verified: installed and run, read file-by-file, or reported by practitioners. The setup interview filters this per project rather than installing all of them. _(verified: row count of template/.agent-kit/skills-catalog.md at HEAD 027f35a)_
- **11** Dangerous git patterns blocked — Force-push, hard reset, branch delete, history rewrites, and working-tree wipes, physically blocked, with no flag to override _(verified: DANGEROUS_PATTERNS in template/.agent-kit/adapters/claude/hooks/block-dangerous-git.py (11 entries, re-counted at HEAD 027f35a))_
- **286** Total files in kit — All files at HEAD including template, packs, seeds, and installer _(verified: find, excluding .git, at HEAD 027f35a, 2026-07-04)_

## The problem

**An unsupervised AI agent will eventually skip a safety check under pressure, and nothing alarms when it does.**

AI coding agents are fast. They are also optimistic: given enough pressure, a session will reach for `--no-verify`, skip documentation updates, or silently re-introduce a pattern that was removed on purpose. Under deadline stress, the agent force-pushes past a failing test, commits without updating docs, or brings back a deleted pattern. None of these failures are loud. They accumulate across sessions until the codebase is inconsistent or a secret lands in git history.

The standard answer ("write better prompts") doesn't hold across sessions, across models, or under deadline pressure. Rules in a chat window evaporate. Rules enforced by the toolchain do not.

## What it delivers

**A drop-in governance layer that forces every commit through an AI reviewer and six automated quality gates, installed in one command.**

You get three things a buyer cares about. **Auditability**: every commit is reviewed for style, risk, and secrets before it lands. **Recoverability**: hard hooks physically block force-push and history rewrites, and the agent cannot bypass them even if told to. **Consistency**: docs freshness, link integrity, and markdown budgets are checked automatically, every time.

The kit installs under a namespaced folder (`.claude/dprvda-kit/`) so it cannot collide with other tooling. Root files required by external tools (`CLAUDE.md`, `.pre-commit-config.yaml`) are placed at the repo root only. An existing `CLAUDE.md` is never overwritten. It is written alongside for manual merge.

## How it works

**Three enforcement layers run on every commit, and the agent cannot opt out of any of them.**

**Claude Code hooks** fire before any Bash tool call. `block-dangerous-git.py` physically prevents **11** dangerous git patterns (force-push, `reset --hard`, `clean -f`, history rewrites) at the system level. The model cannot bypass them even if instructed to. `check-script-launch.py` runs the AI judge against a script before it executes. `remind-claude-md.py` re-injects the rules file on every commit so a compacted session cannot lose project constraints.

**Pre-commit gates** run through a two-phase dispatcher. Phase 1 runs serially and is fail-fast: the AI judge (`critic_llm`) sends each staged source file to an OpenAI-compatible endpoint (defaults to DeepSeek), caches verdicts by SHA-256 content hash so unchanged files are never re-reviewed, and prepends a structured `LLM_REVIEW_BLOCK` comment directly into the file when severity is `warn` or `block`. Phase 2 runs in parallel: `check_links`, `check_doc_freshness`, `check_md_size`, and `check_secrets` execute concurrently, with total hook time equal to phase 1 plus the slowest phase 2 gate. Six gates in total, all blocking by default.

**Conventions layer**: a short `CLAUDE.md` rules file refreshed on every commit, plus **9** reusable workflow skills (`handoff`, `tdd`, `grill-me`, `caveman`, `to-issues`, `zoom-out`, `audit-structure`, `compact-docs`, `write-a-skill`) covering the full arc of an AI-driven development session. Language packs (Rust: `cargo-audit`, `cargo-vet`, binary-secrets, Python: ruff) are opt-in flags at install time.

## Fast and free to adopt

**Unchanged files are never re-reviewed, and no API key is required to start.**

The AI judge caches each verdict by content hash, so commit-hook time stays flat as your codebase grows. The judge is deliberately soft: if `LLM_JUDGE_API_KEY` is absent or the endpoint is unreachable, the gate exits 0 and the commit proceeds, safe to adopt with zero cost. Everything installs under the namespaced folder, so it never collides with your existing tools. A `seeds/` folder provides copy-paste starting points for the user's global `~/.claude/CLAUDE.md`, and **286** total files ship in the kit covering template, packs, seeds, and installer.

## Proven at scale

**Born from a real production codebase where AI was the primary developer across hundreds of commits.**

The kit was extracted and generalized from a single-developer codebase where every failure mode it guards against (force-push under pressure, doc drift, secret leak) actually happened and was fixed by this exact discipline. Each gate targets a failure that occurred in production, not a failure imagined in a design doc. The **6,842** lines of Python powering the gates, hooks, installer, and context injector carry those lessons in concrete, auditable form. It installs with one command, runs on Python 3.9 and git, and requires no permanent dependency on the kit itself.

## Features

- **AI code-review judge** — An AI reviews every changed file before it commits, flags risky code or secrets in the file itself, and caches its verdict by content hash so unchanged files are never re-reviewed.
- **Hard git-safety hooks** — The system physically blocks 11 dangerous git operations (force-push, hard reset, branch delete, history rewrites) before they run, and the AI agent cannot override them even if instructed to.
- **Deterministic pre-commit gates** — Six automated gates check every commit for script reasons, broken links, stale docs, oversized files, and leaked secrets, running the read-only checks in parallel to keep the commit fast.
- **Session context injector** — Every time the editor opens, the agent is automatically reloaded with the project's rules, latest handoff, recent commits, and open issues, split into chunks that fit the context limit.
- **Cross-platform installer** — A single Python script installs the whole kit on Windows, Mac, or Linux without overwriting your existing files, backing them up, appending to .gitignore, and sizing itself to your repo.

## Architecture

All kit machinery lives under `.claude/dprvda-kit/` to avoid namespace collisions. The installer copies the `template/` tree into the target, substitutes `pravda-automations-page`, installs optional language packs, strips opted-out modules, and runs `pre-commit install` for three hook stages (pre-commit, commit-msg, post-commit). The pre-commit gates dispatcher (`run_gates_parallel.py`) runs phase 1 serially (AI judge may mutate files) then phase 2 in parallel (read-only checks). Claude Code hooks are wired via `.claude/settings.json` and fire on every matching tool call.

- **install.py** — Cross-platform installer: copies template, substitutes names, installs packs, strips opt-outs, sizes context-injection hooks, runs pre-commit install
- **hooks/ (Claude Code tool hooks)** — PreToolUse/PostToolUse hooks: block dangerous git ops, run AI judge before script launch, re-inject CLAUDE.md on commit, soft-nudge toward MCP tools
- **gates/ (pre-commit gate suite)** — Two-phase dispatcher plus six gates: critic_llm (AI judge), check_file_reason, check_links, check_doc_freshness, check_md_size, check_secrets
- **inject_context_docs.py** — SessionStart hook that chunks the project-knowledge corpus into <=9,800-char slices and emits one chunk per registered hook entry
- **skills-catalog.md** — Nine of the operator's own skills ship bundled (handoff, tdd, grill-me, caveman, to-issues, zoom-out, audit-structure, compact-docs, write-a-skill); the catalogue lists 31 in total, each graded by how far it was actually verified, and the setup interview filters it per project instead of installing everything
- **packs/ (language packs)** — Opt-in gate extensions: Rust (cargo-audit, cargo-vet, binary-secrets), Python (ruff lint)
- **seeds/** — Copy-paste starting points for the user's global ~/.claude/CLAUDE.md: universal discipline rules, user-profile template, portable engineering lessons

## Tech

- **Languages:** Python
- **Frameworks:** pre-commit
- **Infrastructure:** Claude Code hooks (PreToolUse/PostToolUse/SessionStart), git, OpenAI-compatible API (DeepSeek default)
- **AI/ML:** DeepSeek (default judge model), OpenAI-compatible chat-completions API, Claude Code agent hooks

## Skills demonstrated

- Guardrails for autonomous AI coding agents
- Automated code review and quality gates
- LLM integration with cost-safe fallbacks
- Secret-leak prevention before commit
- Cross-platform tooling (Windows, Mac, Linux)
- Documentation-drift enforcement
- Git-safety automation that cannot be bypassed
- Developer workflow and toolchain design