feat(skill): integrate Karpathy behavioral guidelines into every CLAUDE.md (#25)

CHANGELOG.md

@@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Karpathy Guidelines skill** (`skill/karpathy-guidelines/SKILL.md`): a behavioral-guardrail skill installed alongside ClaudeForge that applies to every coding, review, and refactoring task. Covers four principles — Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution — adapted with attribution from the MIT-licensed [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) repository.
+- **Automatic embedding into every CLAUDE.md**: `skill/template_selector.py` and `skill/generator.py` now insert a `## Behavioral Guidelines` section into every generated and enhanced CLAUDE.md, so the principles ship with every project that runs `/enhance-claude-md`.
+- **Installer support for the new skill**: `install.sh` and `install.ps1` now copy the skill to `~/.claude/skills/karpathy-guidelines/` (or the project-level equivalent) and include it in the uninstall instructions.
+- **Slash command documentation**: `command/enhance-claude-md.md` documents the always-on Behavioral Guidelines section as a required part of the workflow.
+
 ---
 
 ## [2.0.0] - 2026-01-08

CLAUDE.md

@@ -6,11 +6,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-**ClaudeForge** is a comprehensive toolkit for automated CLAUDE.md creation, enhancement, and maintenance for Claude Code projects. The repository consists of three integrated components:
+**ClaudeForge** is a comprehensive toolkit for automated CLAUDE.md creation, enhancement, and maintenance for Claude Code projects. The repository consists of four integrated components:
 
 1. **Skill** (`claudeforge-skill`) - Core Python modules for analysis, generation, and validation
 2. **Slash Command** (`/enhance-claude-md`) - Interactive multi-phase discovery workflow
 3. **Guardian Agent** (`claude-md-guardian`) - Background maintenance agent
+4. **Karpathy Guidelines Skill** (`karpathy-guidelines`) - Behavioral guardrails embedded into every generated CLAUDE.md and installed as a standalone skill, adapted with attribution from the MIT-licensed [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) repository
 
 ---
 

README.md

@@ -49,6 +49,9 @@ Interactive interface with multi-phase discovery workflow
 ### 3. **Guardian Agent** (`claude-md-guardian`)
 Background agent for automatic CLAUDE.md maintenance and synchronization
 
+### 4. **Karpathy Guidelines Skill** (`karpathy-guidelines`)
+Behavioral guardrails — Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution — installed as a standalone skill and automatically embedded into every CLAUDE.md generated or enhanced by `/enhance-claude-md`. Adapted with attribution from the MIT-licensed [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) repository, inspired by Andrej Karpathy's observations on common LLM coding failure modes.
+
 ---
 
 ## 🚀 Quick Start

command/enhance-claude-md.md

@@ -82,6 +82,14 @@ The skill provides:
 - 🔧 **Enhancement**: Adds missing sections and improves existing files
 - 📦 **Modular Architecture**: Supports context-specific files (backend/, frontend/, database/)
 
+### Always-On: Karpathy Behavioral Guidelines
+
+Every generated or enhanced CLAUDE.md MUST include a `## Behavioral Guidelines` section summarising the four Karpathy principles (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) with a link to the installed `karpathy-guidelines` skill.
+
+The `claude-md-enhancer` skill inserts this section automatically — both in `template_selector.customize_template()` for new files and in `generator.merge_with_existing()` for enhanced files. Do not strip it during enhancement; if it is missing from an existing CLAUDE.md, treat that as a required addition.
+
+The full skill is installed at `~/.claude/skills/karpathy-guidelines/SKILL.md` (or `./.claude/skills/karpathy-guidelines/SKILL.md` for project-level installs).
+
 ### Option B: Agent Invocation (Recommended for Maintenance)
 
 For ongoing maintenance and automatic updates throughout your project lifecycle, I can invoke the `claude-md-guardian` agent instead:

install.ps1

@@ -177,6 +177,7 @@ while (-not $validChoice) {
 Write-Host ""
 Write-Info "Installation will create:"
 Write-Host "  • Skill:    $skillsDir\claudeforge-skill\"
+Write-Host "  • Skill:    $skillsDir\karpathy-guidelines\"
 Write-Host "  • Command:  $commandsDir\enhance-claude-md\"
 Write-Host "  • Agent:    $agentsDir\claude-md-guardian.md"
 Write-Host ""
@@ -211,6 +212,25 @@ if (Test-Path $skillPath) {
 Copy-Item -Path "skill" -Destination $skillPath -Recurse -Force
 Write-Success "Skill installed → $skillPath\"
 
+# Install karpathy-guidelines as a separate top-level skill so it is
+# discoverable as its own skill and applies to every project (not only
+# during /enhance-claude-md runs).
+Write-Info "Installing karpathy-guidelines skill..."
+$karpathyPath = "$skillsDir\karpathy-guidelines"
+if (Test-Path $karpathyPath) {
+    Write-Warning "Existing karpathy-guidelines skill found. Creating backup..."
+    $backupName = "karpathy-guidelines.backup.$(Get-Date -Format 'yyyyMMdd_HHmmss')"
+    Move-Item -Path $karpathyPath -Destination "$skillsDir\$backupName" -Force
+    Write-Success "Backup created"
+}
+Copy-Item -Path "skill\karpathy-guidelines" -Destination $karpathyPath -Recurse -Force
+# Remove the nested duplicate inside claudeforge-skill so the skill exists once.
+$nestedKarpathy = "$skillPath\karpathy-guidelines"
+if (Test-Path $nestedKarpathy) {
+    Remove-Item -Path $nestedKarpathy -Recurse -Force
+}
+Write-Success "Karpathy guidelines installed → $karpathyPath\"
+
 # Install slash command
 Write-Info "Installing /enhance-claude-md command..."
 $commandPath = "$commandsDir\enhance-claude-md"
@@ -342,10 +362,12 @@ Write-Info "To uninstall, run:"
 Write-Host ""
 if ($scope -eq "user-level") {
     Write-Host "  Remove-Item -Recurse -Force ~\.claude\skills\claudeforge-skill"
+    Write-Host "  Remove-Item -Recurse -Force ~\.claude\skills\karpathy-guidelines"
     Write-Host "  Remove-Item -Recurse -Force ~\.claude\commands\enhance-claude-md"
     Write-Host "  Remove-Item -Force ~\.claude\agents\claude-md-guardian.md"
 } else {
     Write-Host "  Remove-Item -Recurse -Force .\.claude\skills\claudeforge-skill"
+    Write-Host "  Remove-Item -Recurse -Force .\.claude\skills\karpathy-guidelines"
     Write-Host "  Remove-Item -Recurse -Force .\.claude\commands\enhance-claude-md"
     Write-Host "  Remove-Item -Force .\.claude\agents\claude-md-guardian.md"
 }

install.sh

@@ -158,6 +158,7 @@ done
 echo ""
 print_info "Installation will create:"
 echo "  • Skill:    $SKILLS_DIR/claudeforge-skill/"
+echo "  • Skill:    $SKILLS_DIR/karpathy-guidelines/"
 echo "  • Command:  $COMMANDS_DIR/enhance-claude-md/"
 echo "  • Agent:    $AGENTS_DIR/claude-md-guardian.md"
 echo ""
@@ -188,6 +189,20 @@ fi
 cp -r skill "$SKILLS_DIR/claudeforge-skill"
 print_success "Skill installed → $SKILLS_DIR/claudeforge-skill/"
 
+# Install karpathy-guidelines as a separate top-level skill so it is
+# discoverable as its own skill (and applies to every project, not only
+# during /enhance-claude-md runs).
+print_info "Installing karpathy-guidelines skill..."
+if [ -d "$SKILLS_DIR/karpathy-guidelines" ]; then
+    print_warning "Existing karpathy-guidelines skill found. Creating backup..."
+    mv "$SKILLS_DIR/karpathy-guidelines" "$SKILLS_DIR/karpathy-guidelines.backup.$(date +%Y%m%d_%H%M%S)"
+    print_success "Backup created"
+fi
+cp -r skill/karpathy-guidelines "$SKILLS_DIR/karpathy-guidelines"
+# Remove the nested duplicate so the karpathy skill exists once.
+rm -rf "$SKILLS_DIR/claudeforge-skill/karpathy-guidelines"
+print_success "Karpathy guidelines installed → $SKILLS_DIR/karpathy-guidelines/"
+
 # Install slash command
 print_info "Installing /enhance-claude-md command..."
 if [ -d "$COMMANDS_DIR/enhance-claude-md" ]; then
@@ -303,10 +318,12 @@ print_info "To uninstall, run:"
 echo ""
 if [ "$SCOPE" == "user-level" ]; then
     echo "  rm -rf ~/.claude/skills/claudeforge-skill"
+    echo "  rm -rf ~/.claude/skills/karpathy-guidelines"
     echo "  rm -rf ~/.claude/commands/enhance-claude-md"
     echo "  rm -f ~/.claude/agents/claude-md-guardian.md"
 else
     echo "  rm -rf ./.claude/skills/claudeforge-skill"
+    echo "  rm -rf ./.claude/skills/karpathy-guidelines"
     echo "  rm -rf ./.claude/commands/enhance-claude-md"
     echo "  rm -f ./.claude/agents/claude-md-guardian.md"
 fi

skill/generator.py

@@ -61,6 +61,12 @@ class ContentGenerator:
         lines.extend(principles)
         lines.append("")
 
+        # Behavioral Guidelines (Karpathy principles - applied to every project)
+        lines.append("## Behavioral Guidelines")
+        lines.append("")
+        lines.extend(self._generate_karpathy_guidelines())
+        lines.append("")
+
         # Tech Stack (summary only)
         if self.project_context.get('tech_stack'):
             lines.append("## Tech Stack")
@@ -388,6 +394,13 @@ class ContentGenerator:
                 lines.append("")
                 lines.append(new_section)
 
+        # Always ensure the Karpathy behavioral guidelines section is present
+        if "Behavioral Guidelines" not in existing_sections:
+            lines.append("")
+            lines.append("## Behavioral Guidelines")
+            lines.append("")
+            lines.extend(self._generate_karpathy_guidelines())
+
         return '\n'.join(lines)
 
     def _extract_existing_sections(self, content: str) -> List[str]:
@@ -448,6 +461,33 @@ class ContentGenerator:
 
         return principles
 
+    def _generate_karpathy_guidelines(self) -> List[str]:
+        """Emit the embedded Karpathy guidelines section.
+
+        Distilled summary applied to every generated CLAUDE.md. The full skill
+        text lives in the ``karpathy-guidelines`` skill installed alongside
+        ClaudeForge.
+        """
+        return [
+            "Behavioral guardrails applied to every coding, review, and refactoring task.",
+            "Full skill: `~/.claude/skills/karpathy-guidelines/SKILL.md`.",
+            "",
+            "1. **Think before coding.** State load-bearing assumptions; if a request "
+            "has multiple reasonable interpretations, surface them instead of picking "
+            "silently. Stop and ask when something is genuinely unclear.",
+            "2. **Simplicity first.** Write the minimum code that solves the stated "
+            "problem. No speculative abstractions, no unrequested configuration, no "
+            "error handling for conditions that cannot occur. If the first draft is "
+            "much larger than necessary, rewrite before shipping.",
+            "3. **Surgical changes.** Touch only what the task requires. Do not "
+            "opportunistically reformat or refactor adjacent code, and match the "
+            "surrounding style. Every changed line should trace directly to the "
+            "user's request.",
+            "4. **Goal-driven execution.** Convert vague requests into verifiable "
+            "success criteria before coding (e.g. failing test first), and state a "
+            "step-by-step plan with per-step verification for multi-step work.",
+        ]
+
     def _generate_tech_stack_summary(self) -> List[str]:
         """Generate tech stack summary."""
         lines = []

skill/karpathy-guidelines/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: karpathy-guidelines
+description: Behavioral guardrails for LLM-assisted coding. Use when writing, reviewing, or refactoring code in any project to avoid overcomplication, keep changes surgical, surface assumptions early, and execute against verifiable success criteria.
+license: MIT
+permissions:
+  allow:
+    - Read
+    - Glob
+    - Grep
+---
+
+# Karpathy Guidelines for LLM Coding
+
+Behavioral guardrails for code generation in Claude Code projects, distilled from observations on common LLM coding failure modes. Apply these to every editing, reviewing, and refactoring task.
+
+> Attribution: adapted from the MIT-licensed `karpathy-guidelines` skill by Forrest Chang
+> (https://github.com/forrestchang/andrej-karpathy-skills), inspired by Andrej Karpathy's
+> commentary on where LLM-generated code typically goes wrong.
+> ClaudeForge integrates these principles so every project initialised or enhanced through
+> `/enhance-claude-md` ships with them in its CLAUDE.md.
+
+---
+
+## When to Apply
+
+Apply on every non-trivial task: writing new code, editing existing code, code review, refactoring, and bug fixing. They are intentionally conservative — bias toward caution over speed.
+
+---
+
+## 1. Think Before Coding
+
+Surface what is uncertain. Do not paper over confusion with plausible-sounding code.
+
+- State assumptions before implementing; if any are load-bearing and you are not sure, ask.
+- If the request admits more than one reasonable interpretation, list them rather than silently picking one.
+- If a simpler approach exists than the one the user proposed, say so and explain the tradeoff.
+- When something is genuinely unclear, stop. Identify what is unclear in concrete terms, then ask.
+
+---
+
+## 2. Simplicity First
+
+Write the minimum code that solves the stated problem. Nothing speculative.
+
+- Do not add features that were not requested.
+- Do not introduce abstractions when there is only one call site.
+- Do not add configuration knobs or extension points on speculation.
+- Do not add error handling for conditions that cannot occur in this code path.
+- If the first draft is 200 lines and a 50-line version would do, rewrite it before shipping.
+
+Self-check: a senior engineer skimming this diff — would they say it is overcomplicated for what was asked? If yes, simplify.
+
+---
+
+## 3. Surgical Changes
+
+Touch only what the task requires. Do not opportunistically refactor.
+
+- Do not "improve" adjacent code, comments, or formatting that the task did not require touching.
+- Do not refactor code that is working, even when you would have written it differently.
+- Match the surrounding code's style and conventions, even when they differ from your defaults.
+- If you notice unrelated dead code or bugs, surface them in the response — do not silently delete or fix them.
+
+When your own changes leave orphans:
+
+- Remove imports, variables, and helpers that your edits made unreachable.
+- Do not remove pre-existing dead code unless explicitly asked.
+
+Diff test: every changed line should be traceable to the user's request. If a line is not, drop it.
+
+---
+
+## 4. Goal-Driven Execution
+
+Turn the task into a verifiable goal, then iterate until the verification passes.
+
+- Convert vague requests into checkable success criteria before coding:
+  - "Add validation" → write the failing tests for invalid inputs first, then make them pass.
+  - "Fix the bug" → write a test that reproduces the bug, then make it pass.
+  - "Refactor X" → confirm the existing tests pass, refactor, confirm they still pass.
+- For multi-step tasks, state the plan inline with verification per step:
+
+```
+1. <step> → verify: <how you will check>
+2. <step> → verify: <how you will check>
+3. <step> → verify: <how you will check>
+```
+
+Strong success criteria let you loop without supervision. Vague ones ("make it work") force the user back into the loop.
+
+---
+
+## Integration with ClaudeForge
+
+- The slash command `/enhance-claude-md` injects a `## Behavioral Guidelines` section into every generated or enhanced `CLAUDE.md`, summarising these four principles with a link back to this skill.
+- The `claude-md-guardian` agent preserves the section across automated maintenance updates.
+- `skill/generator.py` and `skill/template_selector.py` insert the section unconditionally — these principles are not opt-in.
+
+## Effectiveness Indicators
+
+The guidelines are working when diffs trend smaller, rewrites caused by overcomplication drop, and clarifying questions arrive before implementation rather than after a failed attempt.

skill/template_selector.py

@@ -352,6 +352,12 @@ class TemplateSelector:
         lines.extend(self._generate_core_principles(template))
         lines.append("")
 
+        # Add behavioral guidelines (Karpathy principles) - applied to every project
+        lines.append("## Behavioral Guidelines")
+        lines.append("")
+        lines.extend(self._generate_karpathy_guidelines())
+        lines.append("")
+
         # Add tech stack section
         if self.tech_stack:
             lines.append("## Tech Stack")
@@ -437,6 +443,33 @@ class TemplateSelector:
 
         return lines
 
+    def _generate_karpathy_guidelines(self) -> List[str]:
+        """Emit the embedded Karpathy guidelines section.
+
+        Distilled summary intended for every generated CLAUDE.md. Full skill
+        text lives in the ``karpathy-guidelines`` skill installed alongside
+        ClaudeForge.
+        """
+        return [
+            "Behavioral guardrails applied to every coding, review, and refactoring task.",
+            "Full skill: `~/.claude/skills/karpathy-guidelines/SKILL.md`.",
+            "",
+            "1. **Think before coding.** State load-bearing assumptions; if a request "
+            "has multiple reasonable interpretations, surface them instead of picking "
+            "silently. Stop and ask when something is genuinely unclear.",
+            "2. **Simplicity first.** Write the minimum code that solves the stated "
+            "problem. No speculative abstractions, no unrequested configuration, no "
+            "error handling for conditions that cannot occur. If the first draft is "
+            "much larger than necessary, rewrite before shipping.",
+            "3. **Surgical changes.** Touch only what the task requires. Do not "
+            "opportunistically reformat or refactor adjacent code, and match the "
+            "surrounding style. Every changed line should trace directly to the "
+            "user's request.",
+            "4. **Goal-driven execution.** Convert vague requests into verifiable "
+            "success criteria before coding (e.g. failing test first), and state a "
+            "step-by-step plan with per-step verification for multi-step work.",
+        ]
+
     def _generate_workflow_section(self) -> List[str]:
         """Generate workflow section based on specified workflows."""
         lines = []