feat(engineering): add karpathy-coder — active coding discipline enforcer

.claude-plugin/marketplace.json

@@ -660,6 +660,26 @@
         "cross-tool"
       ],
       "category": "knowledge"
+    },
+    {
+      "name": "karpathy-coder",
+      "source": "./engineering/karpathy-coder",
+      "description": "Active coding discipline enforcer based on Karpathy's 4 principles: surface assumptions, simplify, make surgical changes, define verifiable goals. Ships 4 Python tools (complexity_checker, diff_surgeon, assumption_linter, goal_verifier), a review agent, /karpathy-check command, and pre-commit hook. All stdlib-only.",
+      "version": "2.3.0",
+      "author": {
+        "name": "Alireza Rezvani"
+      },
+      "keywords": [
+        "code-quality",
+        "karpathy",
+        "simplicity",
+        "surgical-changes",
+        "complexity",
+        "anti-patterns",
+        "review",
+        "discipline"
+      ],
+      "category": "development"
     }
   ]
 }

.codex/skills-index.json

@@ -3,7 +3,7 @@
   "name": "claude-code-skills",
   "description": "Production-ready skill packages for AI agents - Marketing, Engineering, Product, C-Level, PM, and RA/QM",
   "repository": "https://github.com/alirezarezvani/claude-skills",
-  "total_skills": 197,
+  "total_skills": 198,
   "skills": [
     {
       "name": "contract-and-proposal-writer",
@@ -551,6 +551,12 @@
       "category": "engineering-advanced",
       "description": "This skill should be used when the user asks to \"design interview processes\", \"create hiring pipelines\", \"calibrate interview loops\", \"generate interview questions\", \"design competency matrices\", \"analyze interviewer bias\", \"create scoring rubrics\", \"build question banks\", or \"optimize hiring systems\". Use for designing role-specific interview loops, competency assessments, and hiring calibration systems."
     },
+    {
+      "name": "karpathy-coder",
+      "source": "../../engineering/karpathy-coder",
+      "category": "engineering-advanced",
+      "description": "Use when writing, reviewing, or committing code to enforce Karpathy's 4 coding principles \u2014 surface assumptions before coding, keep it simple, make surgical changes, define verifiable goals. Triggers on \"review my diff\", \"check complexity\", \"am I overcomplicating this\", \"karpathy check\", \"before I commit\", or any code quality concern where the LLM might be overcoding."
+    },
     {
       "name": "llm-cost-optimizer",
       "source": "../../engineering/llm-cost-optimizer",
@@ -1205,7 +1211,7 @@
       "description": "Software engineering and technical skills"
     },
     "engineering-advanced": {
-      "count": 45,
+      "count": 46,
       "source": "../../engineering",
       "description": "Advanced engineering skills - agents, RAG, MCP, CI/CD, databases, observability"
     },

.codex/skills/karpathy-coder

@@ -0,0 +1 @@
+../../engineering/karpathy-coder

.gemini/skills-index.json

@@ -1,7 +1,7 @@
 {
   "version": "1.0.0",
   "name": "gemini-cli-skills",
-  "total_skills": 294,
+  "total_skills": 297,
   "skills": [
     {
       "name": "README",
@@ -58,6 +58,11 @@
       "category": "agent",
       "description": "Growth Strategist agent for revenue operations, sales engineering, customer success, and business development. Orchestrates business-growth skills. Spawn when users need pipeline analysis, churn prevention, expansion scoring, sales demos, or proposal writing."
     },
+    {
+      "name": "cs-karpathy-reviewer",
+      "category": "agent",
+      "description": "Reviews staged git changes against Karpathy's 4 coding principles. Runs complexity_checker on changed files, diff_surgeon on the diff, and produces a verdict with specific fix recommendations. Spawn before committing, when the user says \"karpathy check\", \"review my diff\", or when the /karpathy-check command is invoked."
+    },
     {
       "name": "cs-product-analyst",
       "category": "agent",
@@ -373,6 +378,11 @@
       "category": "command",
       "description": "Google Workspace CLI operations: setup diagnostics, security audit, recipe discovery, and output analysis. Usage: /google-workspace <setup|audit|recipe|analyze> [options]"
     },
+    {
+      "name": "karpathy-check",
+      "category": "command",
+      "description": "Run Karpathy's 4-principle review on staged changes or the last commit. Checks complexity, diff noise, hidden assumptions, and goal verification. Usage /karpathy-check [--last-commit]"
+    },
     {
       "name": "okr",
       "category": "command",
@@ -863,6 +873,11 @@
       "category": "engineering-advanced",
       "description": "This skill should be used when the user asks to \"design interview processes\", \"create hiring pipelines\", \"calibrate interview loops\", \"generate interview questions\", \"design competency matrices\", \"analyze interviewer bias\", \"create scoring rubrics\", \"build question banks\", or \"optimize hiring systems\". Use for designing role-specific interview loops, competency assessments, and hiring calibration systems."
     },
+    {
+      "name": "karpathy-coder",
+      "category": "engineering-advanced",
+      "description": "Use when writing, reviewing, or committing code to enforce Karpathy's 4 coding principles \u2014 surface assumptions before coding, keep it simple, make surgical changes, define verifiable goals. Triggers on \"review my diff\", \"check complexity\", \"am I overcomplicating this\", \"karpathy check\", \"before I commit\", or any code quality concern where the LLM might be overcoding."
+    },
     {
       "name": "llm-cost-optimizer",
       "category": "engineering-advanced",
@@ -1476,7 +1491,7 @@
   ],
   "categories": {
     "agent": {
-      "count": 28,
+      "count": 29,
       "description": "Agent resources"
     },
     "business-growth": {
@@ -1488,15 +1503,15 @@
       "description": "C-level resources"
     },
     "command": {
-      "count": 28,
+      "count": 29,
       "description": "Command resources"
     },
     "engineering": {
       "count": 51,
       "description": "Engineering resources"
     },
     "engineering-advanced": {
-      "count": 59,
+      "count": 60,
       "description": "Engineering-advanced resources"
     },
     "finance": {

.gemini/skills/cs-karpathy-reviewer/SKILL.md

@@ -0,0 +1 @@
+../../../agents/engineering/cs-karpathy-reviewer.md

.gemini/skills/karpathy-check/SKILL.md

@@ -0,0 +1 @@
+../../../commands/karpathy-check.md

.gemini/skills/karpathy-coder/SKILL.md

@@ -0,0 +1 @@
+../../../engineering/karpathy-coder/SKILL.md

agents/engineering/cs-karpathy-reviewer.md

@@ -0,0 +1,81 @@
+---
+name: cs-karpathy-reviewer
+description: Reviews staged git changes against Karpathy's 4 coding principles. Runs complexity_checker on changed files, diff_surgeon on the diff, and produces a verdict with specific fix recommendations. Spawn before committing, when the user says "karpathy check", "review my diff", or when the /karpathy-check command is invoked.
+skills: engineering/karpathy-coder
+domain: engineering
+model: sonnet
+tools: [Read, Bash, Grep, Glob]
+context: fork
+---
+
+# karpathy-reviewer
+
+## Role
+
+You review code changes against Karpathy's 4 principles. You are opinionated and specific — don't just say "looks fine", point to exact lines and explain which principle they violate.
+
+## Workflow
+
+### 1. Get the diff
+
+```bash
+git diff --staged
+```
+
+If nothing staged, use `git diff HEAD~1..HEAD` (last commit).
+
+### 2. Run the automated tools
+
+```bash
+# Principle #2 — Simplicity check on changed files
+python <plugin>/scripts/complexity_checker.py <changed-files> --json
+
+# Principle #3 — Surgical changes check
+python <plugin>/scripts/diff_surgeon.py --json
+```
+
+### 3. Manual review against each principle
+
+**Principle #1 (Think Before Coding):** Were any assumptions made without explicit mention? Did the implementation pick one interpretation of an ambiguous requirement without surfacing alternatives?
+
+**Principle #2 (Simplicity First):** Are there abstractions that serve only one caller? Classes that could be functions? Error handling for impossible scenarios? Features nobody asked for?
+
+**Principle #3 (Surgical Changes):** Does every changed line trace directly to the task? Any comment changes, style drift, drive-by refactors, or "improvements" to adjacent code?
+
+**Principle #4 (Goal-Driven Execution):** Is there evidence the work was verified? Test additions/modifications? Clear success criteria? Or did the implementation just "look right" without testing?
+
+### 4. Produce a report
+
+```markdown
+## Karpathy Review — <date>
+
+### Tool Results
+- Complexity: <score>/100 (<N> findings)
+- Diff Noise: <ratio>% (<verdict>)
+
+### Principle-by-Principle
+
+#### #1 Think Before Coding
+- [PASS/WARN] <specific observation or "no hidden assumptions detected">
+
+#### #2 Simplicity First
+- [PASS/WARN] <specific observation>
+
+#### #3 Surgical Changes
+- [PASS/WARN] <specific lines cited>
+
+#### #4 Goal-Driven Execution
+- [PASS/WARN] <test coverage or verification evidence>
+
+### Verdict: <PASS / PASS WITH WARNINGS / NEEDS WORK>
+
+### Specific fixes (if any)
+1. <file:line — what to change and why>
+```
+
+## Rules
+
+- **Cite specific lines.** "The diff has noise" is useless. "Line 42: comment changed in untouched function" is actionable.
+- **Don't re-run the user's task.** You review, not implement.
+- **Be proportional.** A typo fix doesn't need the same rigor as a 200-line feature.
+- **Run the tools.** Don't skip automated checks — your manual review supplements them.

commands/karpathy-check.md

@@ -0,0 +1,46 @@
+---
+name: karpathy-check
+description: Run Karpathy's 4-principle review on staged changes or the last commit. Checks complexity, diff noise, hidden assumptions, and goal verification. Usage /karpathy-check [--last-commit]
+---
+
+# /karpathy-check
+
+Review your staged changes (or last commit) against Karpathy's 4 coding principles.
+
+## Usage
+
+```
+/karpathy-check                 # review staged changes
+/karpathy-check --last-commit   # review the most recent commit
+```
+
+## What it runs
+
+1. **Principle #2 (Simplicity):** `scripts/complexity_checker.py` on all changed files — detects over-engineering, premature abstractions, deep nesting, long functions
+2. **Principle #3 (Surgical):** `scripts/diff_surgeon.py` on the diff — detects comment-only changes, whitespace noise, style drift, drive-by refactors
+3. **Principles #1 + #4 (Think + Goals):** The `karpathy-reviewer` agent reads the diff and applies human-judgment checks — hidden assumptions, missing verification
+
+## Output
+
+A structured report with per-principle verdicts and specific line-level fix recommendations.
+
+## When to run
+
+- Before committing (catches noise and overcomplication early)
+- After completing a feature (sanity check before PR)
+- When you suspect the LLM overcoded something
+
+## Sub-agent
+
+Dispatches the `karpathy-reviewer` agent. See `agents/karpathy-reviewer.md`.
+
+## Scripts
+
+- `engineering/karpathy-coder/scripts/complexity_checker.py`
+- `engineering/karpathy-coder/scripts/diff_surgeon.py`
+- `engineering/karpathy-coder/scripts/assumption_linter.py`
+- `engineering/karpathy-coder/scripts/goal_verifier.py`
+
+## Skill Reference
+
+→ `engineering/karpathy-coder/SKILL.md`

engineering/karpathy-coder/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "karpathy-coder",
+  "description": "Active coding discipline enforcer based on Karpathy's 4 principles: surface assumptions, keep it simple, make surgical changes, define verifiable goals. Ships 4 Python tools (complexity_checker, diff_surgeon, assumption_linter, goal_verifier), a review agent, /karpathy-check slash command, and a pre-commit hook. All tools stdlib-only.",
+  "version": "2.3.0",
+  "author": {
+    "name": "Alireza Rezvani",
+    "url": "https://alirezarezvani.com"
+  },
+  "homepage": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/karpathy-coder",
+  "repository": "https://github.com/alirezarezvani/claude-skills",
+  "license": "MIT",
+  "skills": "./"
+}

engineering/karpathy-coder/README.md

@@ -0,0 +1,104 @@
+# karpathy-coder
+
+> **Active coding discipline enforcer** based on [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls.
+
+Not just guidelines — ships Python tools that **detect** violations, a review agent, a slash command, and a pre-commit hook.
+
+## The 4 principles
+
+| # | Principle | What it prevents | Tool that checks it |
+|---|---|---|---|
+| 1 | **Think Before Coding** | Hidden assumptions, silent choices | `assumption_linter.py` |
+| 2 | **Simplicity First** | Over-engineering, premature abstractions | `complexity_checker.py` |
+| 3 | **Surgical Changes** | Diff noise, drive-by refactors | `diff_surgeon.py` |
+| 4 | **Goal-Driven Execution** | Vague plans, missing verification | `goal_verifier.py` |
+
+## Quick start
+
+```bash
+# Install as Claude Code plugin
+/plugin marketplace add alirezarezvani/claude-skills
+/plugin install karpathy-coder@claude-code-skills
+
+# Run before committing
+/karpathy-check
+
+# Or use individual tools from the shell
+python scripts/complexity_checker.py src/ --threshold strict
+python scripts/diff_surgeon.py --diff HEAD~1..HEAD
+echo "I'll just export all user data" | python scripts/assumption_linter.py -
+python scripts/goal_verifier.py plan.md
+```
+
+## What's in the box
+
+| Piece | Count | Detail |
+|---|---|---|
+| SKILL.md | 1 | The 4 principles with `context: fork` for skill chaining |
+| Python tools | 4 | `complexity_checker`, `diff_surgeon`, `assumption_linter`, `goal_verifier` — all stdlib-only |
+| Sub-agent | 1 | `karpathy-reviewer` — runs all 4 principles against a diff |
+| Slash command | 1 | `/karpathy-check` — one-command pre-commit review |
+| Pre-commit hook | 1 | `karpathy-gate.sh` — non-blocking awareness gate |
+| Reference docs | 3 | Full Karpathy context, 10+ anti-pattern examples, 4-level enforcement guide |
+
+## The tools
+
+### complexity_checker.py (Principle #2)
+
+Detects over-engineering: cyclomatic complexity, class density, nesting depth, function length, premature ABC/Protocol usage, import coupling.
+
+```bash
+python scripts/complexity_checker.py src/auth/ --threshold strict --json
+# → score 72/100, 3 findings: nesting depth 6, function 'validate' 62 lines, 2 classes in 80 lines
+```
+
+Three threshold levels: `strict` (new code), `medium` (default), `relaxed` (legacy).
+
+### diff_surgeon.py (Principle #3)
+
+Analyzes a git diff and flags lines that don't trace to the stated goal: comment-only changes, whitespace noise, style drift (quote swaps), drive-by refactors, docstring additions to unchanged functions.
+
+```bash
+python scripts/diff_surgeon.py                    # staged changes
+python scripts/diff_surgeon.py --diff HEAD~3..HEAD # last 3 commits
+# → Noise ratio: 23% (NOISY), 7 comment-only changes, 2 quote-style swaps
+```
+
+### assumption_linter.py (Principle #1)
+
+Reads a plan or proposal and flags hidden assumptions: "just" (hides complexity), "obviously" (unstated assumption), "should work" (hopeful, not verified), vague action verbs, unscoped user references, missing format specifications.
+
+```bash
+echo "I'll just add a function to export all user data" | python scripts/assumption_linter.py -
+# → 3 findings: assumption-just, missing-format, scope-absolute
+```
+
+### goal_verifier.py (Principle #4)
+
+Scores each step of a plan for verification quality (0-3 per step). Flags vague criteria ("should work"), checks for final end-to-end verification, and recommends concrete checks.
+
+```bash
+python scripts/goal_verifier.py implementation-plan.md --json
+# → 6 steps, 8/18 (44%), WEAK — 3 steps have no verification
+```
+
+## Enforcement levels
+
+1. **Passive** — install plugin, principles load as context (~60% compliance)
+2. **Active review** — run `/karpathy-check` before commits (~85%)
+3. **Pre-commit hook** — wire `karpathy-gate.sh` via Husky (~95%)
+4. **CI gate** — add tools to GitHub Actions PR checks (~99%)
+
+See `references/enforcement-patterns.md` for setup instructions at each level.
+
+## Cross-tool compatibility
+
+The tools are pure Python stdlib. The principles work in any AGENTS.md-aware CLI (Codex, Cursor, Antigravity, OpenCode, Gemini CLI).
+
+## Attribution
+
+Derived from [Andrej Karpathy's X post](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls. The principles are Karpathy's observations; the tooling, enforcement patterns, and anti-pattern gallery are original.
+
+## License
+
+MIT.