From 6636bce74b90b90e9dda6d0b0d83dbc6cae6ce4e Mon Sep 17 00:00:00 2001 From: TechBrewBoss Date: Mon, 4 May 2026 07:55:05 -0500 Subject: [PATCH] Add opt-in Karpathy guidelines skill (#909) * Add opt-in Karpathy guidelines skill * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/plugins/bundled/index.ts | 9 +- .../bundled/karpathyGuidelines.test.ts | 41 ++++++++ src/plugins/bundled/karpathyGuidelines.ts | 96 +++++++++++++++++++ 3 files changed, 142 insertions(+), 4 deletions(-) create mode 100644 src/plugins/bundled/karpathyGuidelines.test.ts create mode 100644 src/plugins/bundled/karpathyGuidelines.ts diff --git a/src/plugins/bundled/index.ts b/src/plugins/bundled/index.ts index 85dda6519..c27876ceb 100644 --- a/src/plugins/bundled/index.ts +++ b/src/plugins/bundled/index.ts @@ -10,14 +10,15 @@ * claude-in-chrome), use src/skills/bundled/ instead. * * To add a new built-in plugin: - * 1. Import registerBuiltinPlugin from '../builtinPlugins.js' - * 2. Call registerBuiltinPlugin() with the plugin definition here + * 1. Import its registerXPlugin() helper from the plugin module here + * 2. Call that helper from initBuiltinPlugins() */ +import { registerKarpathyGuidelinesPlugin } from './karpathyGuidelines.js' + /** * Initialize built-in plugins. Called during CLI startup. */ export function initBuiltinPlugins(): void { - // No built-in plugins registered yet — this is the scaffolding for - // migrating bundled skills that should be user-toggleable. + registerKarpathyGuidelinesPlugin() } diff --git a/src/plugins/bundled/karpathyGuidelines.test.ts b/src/plugins/bundled/karpathyGuidelines.test.ts new file mode 100644 index 000000000..f271e4c33 --- /dev/null +++ b/src/plugins/bundled/karpathyGuidelines.test.ts @@ -0,0 +1,41 @@ +import { afterEach, expect, test } from 'bun:test' + +import { + clearBuiltinPlugins, + getBuiltinPluginDefinition, +} from '../builtinPlugins.js' +import { registerKarpathyGuidelinesPlugin } from './karpathyGuidelines.js' + +afterEach(() => { + clearBuiltinPlugins() +}) + +test('karpathy guidelines registers as an opt-in built-in plugin', () => { + registerKarpathyGuidelinesPlugin() + + const plugin = getBuiltinPluginDefinition('karpathy-guidelines') + + expect(plugin).toBeDefined() + expect(plugin?.defaultEnabled).toBe(false) + expect(plugin?.skills?.map(skill => skill.name)).toEqual([ + 'karpathy-guidelines', + ]) +}) + +test('karpathy guidelines skill includes optional user focus', async () => { + registerKarpathyGuidelinesPlugin() + + const skill = getBuiltinPluginDefinition('karpathy-guidelines')?.skills?.[0] + expect(skill).toBeDefined() + + const blocks = await skill!.getPromptForCommand( + 'prefer tests over snapshots', + {} as never, + ) + const text = (blocks[0] as { text: string }).text + + expect(text).toContain('# CLAUDE.md') + expect(text).toContain('These guidelines are working if') + expect(text).toContain('## User Focus') + expect(text).toContain('prefer tests over snapshots') +}) diff --git a/src/plugins/bundled/karpathyGuidelines.ts b/src/plugins/bundled/karpathyGuidelines.ts new file mode 100644 index 000000000..e8e8106a1 --- /dev/null +++ b/src/plugins/bundled/karpathyGuidelines.ts @@ -0,0 +1,96 @@ +import { registerBuiltinPlugin } from '../builtinPlugins.js' + +const KARPATHY_GUIDELINES_PROMPT = `# CLAUDE.md + +Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed. + +**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. + +## 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +Before implementing: +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them - don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +## 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +## 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it - don't delete it. + +When your changes create orphans: +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked. + +The test: Every changed line should trace directly to the user's request. + +## 4. Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: +- "Add validation" -> "Write tests for invalid inputs, then make them pass" +- "Fix the bug" -> "Write a test that reproduces it, then make it pass" +- "Refactor X" -> "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan: +\`\`\` +1. [Step] -> verify: [check] +2. [Step] -> verify: [check] +3. [Step] -> verify: [check] +\`\`\` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. + +--- + +**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes. +` + +export function registerKarpathyGuidelinesPlugin(): void { + registerBuiltinPlugin({ + name: 'karpathy-guidelines', + description: + 'Optional coding guidelines that favor simple, surgical, verifiable changes.', + version: '1.0.0', + defaultEnabled: false, + skills: [ + { + name: 'karpathy-guidelines', + description: + 'Apply coding guidelines that reduce common LLM implementation mistakes.', + whenToUse: + 'Use when writing, reviewing, or refactoring code, especially when a task could become overcomplicated or needs careful verification.', + userInvocable: true, + async getPromptForCommand(args) { + const focus = args.trim() + const prompt = focus + ? `${KARPATHY_GUIDELINES_PROMPT}\n\n## User Focus\n\n${focus}\n` + : KARPATHY_GUIDELINES_PROMPT + + return [{ type: 'text', text: prompt }] + }, + }, + ], + }) +}