jeo-code 0.11.6 → 0.12.0

package/CHANGELOG.md

@@ -9,6 +9,18 @@ The README mirrors the latest 5 entries — regenerate with `bun run changelog:s
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-10-16
+_Karpathy behavioral guardrails become always-on discipline, and skill routing gains an ECC single-harness inventory plus a Jev-style advisory router._
+
+### Added
+- **Bundled `karpathy-guidelines` skill** (`src/prompts/skills/karpathy-guidelines/SKILL.md`, registered in `src/skills/catalog.ts`) — the four `multica-ai/andrej-karpathy-skills` principles (think before coding, simplicity first, surgical changes, goal-driven execution), operationalized for jeo: ambiguity handling points at `deep-interview`, goal-driven verification points at the done-verification gate. Guidance-only, no executor or MCP tool.
+- **Always-on `KARPATHY_DISCIPLINE` prompt block** (`src/agent/engine.ts`, `src/commands/launch.ts`) — appended to `executorSystemPrompt()` and the interactive system prompt alongside `WORKING_DISCIPLINE`. Existing discipline constants are byte-stable; the Karpathy block is additive. The JEO workflow-routing brief now states the guidelines apply to every coding turn without an explicit skill invocation.
+- **ECC + Jev-style skill router** (`src/agent/skill-router.ts`, `docs/ecc-jev-routing.md`) — heuristic advisory `routeSkillsForTask()` (Jev `route-skills` parity: gate 0.30 / fit 0.30, `sharded` vs `shortlist` strategy, top-k 3, stopword-filtered overlap with a decisive explicit-name bonus, fail-open explicit-none) plus `inventorySkillConflicts()` (ECC single-harness rule: one skill identity, one source — duplicate normalized names from distinct paths are reported, never silently mixed). The router only suggests; `$skill` remains the sole execution entrypoint and the model is never switched.
+- **ECC/Jev operation-flow doc** (`docs/ecc-jev-routing.md`) — source analysis of `andrej-karpathy-skills`, ECC, and the Jev control plane, with the jeo-code mapping table and the per-turn flow.
+
+### Verified
+- `bun run typecheck` clean; new `test/karpathy-skill-router.test.ts` (8 tests: skill registration, four-principle prompt wiring, explicit-name routing, gate/fit explicit-none, sharded/shortlist strategy, inventory conflicts) green alongside the skill/prompt/engine suites (228 pass across 17 files).
+
 ## [0.11.6] - 2026-10-16
 _Live Antigravity account model discovery now serves the actual account's available models instead of assuming static availability._
 

package/README.ja.md

@@ -395,10 +395,10 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.0]** (2026-10-16) — Karpathy behavioral guardrails become always-on discipline, and skill routing gains an ECC single-harness inventory plus a Jev-style advisory router.
 - **[0.11.6]** (2026-10-16) — Live Antigravity account model discovery now serves the actual account's available models instead of assuming static availability.
 - **[0.11.5]** (2026-10-04) — Anthropic login now runs Opus 5.5 and Sonnet 5.5 as the selected models: the OAuth client version gate and incompatible fast-mode temperature are fixed, with real request and streaming responses verified.
 - **[0.11.4]** (2026-10-01) — The release pipeline could not actually release: 13 tests failed on Linux CI only, and the stored npm token no longer authenticated. Both are fixed at the root — the suite is order-independent, and publishing no longer depends on a secret that can expire.
-- **[0.11.3]** (2026-10-01) — Remote control grew from one Telegram bot into one shared daemon serving Telegram, Discord, and Slack — and the workflow gates that were meant to block unverified work (`approve`/`team` plan identity, `done` re-checks, the autopilot ratchet) now actually block it.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -397,10 +397,10 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.0]** (2026-10-16) — Karpathy behavioral guardrails become always-on discipline, and skill routing gains an ECC single-harness inventory plus a Jev-style advisory router.
 - **[0.11.6]** (2026-10-16) — Live Antigravity account model discovery now serves the actual account's available models instead of assuming static availability.
 - **[0.11.5]** (2026-10-04) — Anthropic login now runs Opus 5.5 and Sonnet 5.5 as the selected models: the OAuth client version gate and incompatible fast-mode temperature are fixed, with real request and streaming responses verified.
 - **[0.11.4]** (2026-10-01) — The release pipeline could not actually release: 13 tests failed on Linux CI only, and the stored npm token no longer authenticated. Both are fixed at the root — the suite is order-independent, and publishing no longer depends on a secret that can expire.
-- **[0.11.3]** (2026-10-01) — Remote control grew from one Telegram bot into one shared daemon serving Telegram, Discord, and Slack — and the workflow gates that were meant to block unverified work (`approve`/`team` plan identity, `done` re-checks, the autopilot ratchet) now actually block it.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -389,10 +389,10 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.0]** (2026-10-16) — Karpathy behavioral guardrails become always-on discipline, and skill routing gains an ECC single-harness inventory plus a Jev-style advisory router.
 - **[0.11.6]** (2026-10-16) — Live Antigravity account model discovery now serves the actual account's available models instead of assuming static availability.
 - **[0.11.5]** (2026-10-04) — Anthropic login now runs Opus 5.5 and Sonnet 5.5 as the selected models: the OAuth client version gate and incompatible fast-mode temperature are fixed, with real request and streaming responses verified.
 - **[0.11.4]** (2026-10-01) — The release pipeline could not actually release: 13 tests failed on Linux CI only, and the stored npm token no longer authenticated. Both are fixed at the root — the suite is order-independent, and publishing no longer depends on a secret that can expire.
-- **[0.11.3]** (2026-10-01) — Remote control grew from one Telegram bot into one shared daemon serving Telegram, Discord, and Slack — and the workflow gates that were meant to block unverified work (`approve`/`team` plan identity, `done` re-checks, the autopilot ratchet) now actually block it.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -393,10 +393,10 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.0]** (2026-10-16) — Karpathy behavioral guardrails become always-on discipline, and skill routing gains an ECC single-harness inventory plus a Jev-style advisory router.
 - **[0.11.6]** (2026-10-16) — Live Antigravity account model discovery now serves the actual account's available models instead of assuming static availability.
 - **[0.11.5]** (2026-10-04) — Anthropic login now runs Opus 5.5 and Sonnet 5.5 as the selected models: the OAuth client version gate and incompatible fast-mode temperature are fixed, with real request and streaming responses verified.
 - **[0.11.4]** (2026-10-01) — The release pipeline could not actually release: 13 tests failed on Linux CI only, and the stored npm token no longer authenticated. Both are fixed at the root — the suite is order-independent, and publishing no longer depends on a secret that can expire.
-- **[0.11.3]** (2026-10-01) — Remote control grew from one Telegram bot into one shared daemon serving Telegram, Discord, and Slack — and the workflow gates that were meant to block unverified work (`approve`/`team` plan identity, `done` re-checks, the autopilot ratchet) now actually block it.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.11.6",
+  "version": "0.12.0",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
   "main": "src/cli.ts",

package/src/agent/engine.ts

@@ -227,6 +227,20 @@ export const VERIFICATION_DIRECTIVE =
   "Distinguish a passing test from a met requirement: never weaken, skip, or narrow a test to make it pass. " +
   "When you write tests, exercise observable behavior, edge values, branch conditions, invariants, and error handling — never assert defaults or tautologies.";
 
+/** Karpathy behavioral guardrails (multica-ai/andrej-karpathy-skills, MIT):
+ *  think-before-coding, simplicity-first, surgical-changes, goal-driven
+ *  execution — operationalized for jeo's tool loop. Kept SEPARATE from
+ *  WORKING_DISCIPLINE so existing prompt contracts stay byte-stable; callers
+ *  opt in by appending this block. Mirrors the bundled `karpathy-guidelines`
+ *  skill's SKILL.md in compact system-prompt form. */
+export const KARPATHY_DISCIPLINE = [
+  "Karpathy discipline (caution over speed on non-trivial work; use judgment on trivial one-liners):",
+  "- Think before coding: state assumptions explicitly; when multiple interpretations exist, present them instead of picking silently; push back when a simpler approach exists; stop and ask when confused.",
+  "- Simplicity first: minimum code that solves the problem — no unasked features, no single-use abstractions, no speculative flexibility, no impossible-scenario error handling. If 200 lines could be 50, rewrite it.",
+  "- Surgical changes: touch only what the request requires; match existing style; mention unrelated dead code instead of deleting it; remove only the orphans YOUR changes created. Every changed line must trace to the request.",
+  "- Goal-driven execution: turn tasks into verifiable goals (repro test before fix, tests-before/after for refactors, per-step verify checks) and loop until the verification signal passes — a stale pass from before the last edit does not count.",
+].join("\n");
+
 
 export function executorSystemPrompt(
   role = "Executor Agent, a senior software developer",
@@ -238,6 +252,7 @@ export function executorSystemPrompt(
     `Accomplish the user's request by calling tools and verifying your work.\n\n` +
     `${protocol}\n\n` +
     `${WORKING_DISCIPLINE}\n\n` +
+    `${KARPATHY_DISCIPLINE}\n\n` +
     `${OUTPUT_DISCIPLINE}\n\n` +
     verificationDirective
   );

package/src/agent/skill-router.ts

@@ -0,0 +1,163 @@
+/**
+ * ECC single-harness + Jev-style skill routing for jeo-code.
+ *
+ * Two concerns live here on purpose, mirroring the external operating layer:
+ *
+ * 1. ECC inventory (fail-closed on duplicates): exactly ONE harness path per
+ *    skill identity. A later skill dir's same-named skill OVERRIDES (that is the
+ *    documented `loadSkills` precedence), but two DIFFERENT source paths
+ *    claiming the same normalized name inside ONE resolution pass is a duplicate
+ *    installation — report it instead of silently shadowing.
+ *
+ * 2. Jev `route-skills` heuristic (advisory, always fail-open): scores a task
+ *    against the loaded skill catalog with zero I/O and returns a top-k
+ *    selection plus an advisory routing note. Gate and fit thresholds are both
+ *    `0.30`, matching the Jev control plane. This never installs skills, never
+ *    changes the model, and never throws — an empty/ambiguous task yields an
+ *    explicit none with a reason, not a guess.
+ */
+
+import type { SkillDoc } from "../skills/catalog";
+
+/** Gate below which no skill is selected (explicit none, reason "gate"). */
+export const SKILL_ROUTE_GATE = 0.3;
+/** Fit below which a top candidate is still rejected (explicit none, reason "fits"). */
+export const SKILL_ROUTE_FIT = 0.3;
+/** Max skills compared in one scoring shard (Jev `choiceCap` analogue). */
+export const SKILL_ROUTE_CHOICE_CAP = 6;
+/** Max skills returned. */
+export const SKILL_ROUTE_TOP_K = 3;
+
+export interface SkillRouteCandidate {
+  name: string;
+  score: number;
+  reasons: string[];
+}
+
+export interface SkillRouteSelection {
+  topK: SkillRouteCandidate[];
+  /** "gate" = nothing cleared the gate; "fits" = cleared gate but failed fit; "ok" = advisory selection. */
+  reason: "gate" | "fits" | "ok";
+  /** "sharded" when ceil(catalogSize / choiceCap) <= 4, otherwise "shortlist". */
+  strategy: "sharded" | "shortlist";
+  /** Advisory only — never an install or model instruction. */
+  routing: string;
+}
+
+const TOKEN_RE = /[a-z0-9][a-z0-9._-]*/gi;
+
+/** Closed-class / low-signal words excluded from routing overlap — without
+ *  this, chit-chat ("how are you") spuriously matches every long skill doc. */
+const STOPWORDS = new Set([
+  "the", "are", "you", "your", "and", "for", "with", "that", "this", "have",
+  "has", "had", "what", "when", "where", "which", "how", "why", "who", "whom",
+  "there", "here", "today", "hello", "please", "just", "like", "from", "into",
+  "over", "under", "about", "after", "before", "then", "than", "also", "only",
+  "very", "much", "more", "most", "some", "such", "will", "would", "could",
+  "should", "does", "did", "not", "but", "all",
+]);
+
+function tokens(text: string): Set<string> {
+  const out = new Set<string>();
+  for (const m of text.toLowerCase().matchAll(TOKEN_RE)) {
+    const t = m[0];
+    if (t.length >= 3 && !STOPWORDS.has(t)) out.add(t);
+  }
+  return out;
+}
+
+function skillText(s: SkillDoc): string {
+  return `${s.name} ${s.summary} ${s.whenToUse} ${s.details}`.toLowerCase();
+}
+
+/**
+ * Score one skill against the task: keyword overlap over the skill's own
+ * name/summary/when/details vocabulary. Name-token hits weigh more (explicit
+ * user intent, e.g. "ralplan" in the task). Pure, deterministic.
+ */
+export function scoreSkillForTask(task: string, skill: SkillDoc): { score: number; reasons: string[] } {
+  const taskTokens = tokens(task);
+  if (taskTokens.size === 0) return { score: 0, reasons: [] };
+  const text = skillText(skill);
+  const textTokens = tokens(text);
+  let overlap = 0;
+  const reasons: string[] = [];
+  for (const t of taskTokens) {
+    if (textTokens.has(t)) {
+      overlap++;
+      if (reasons.length < 5) reasons.push(t);
+    }
+  }
+  const nameTokens = tokens(skill.name.replace(/[:/]/g, " "));
+  let nameHits = 0;
+  for (const t of taskTokens) if (nameTokens.has(t)) nameHits++;
+  // Overlap ratio over task vocabulary + a decisive name bonus: an explicit
+  // skill-name mention in the task (e.g. "ralplan") must dominate generic
+  // vocabulary overlap from longer skill docs.
+  const score = overlap / taskTokens.size + Math.min(nameHits * 1.0, 1.5);
+  return { score, reasons };
+}
+
+/**
+ * Jev-style `route-skills`: heuristic top-k skill selection for one task.
+ * Never throws; empty input yields explicit none with reason "gate".
+ */
+export function routeSkillsForTask(task: string, skills: SkillDoc[], topK = SKILL_ROUTE_TOP_K): SkillRouteSelection {
+  const strategy: SkillRouteSelection["strategy"] =
+    Math.ceil(skills.length / SKILL_ROUTE_CHOICE_CAP) <= 4 ? "sharded" : "shortlist";
+  const trimmed = task.trim();
+  if (!trimmed) {
+    return { topK: [], reason: "gate", strategy, routing: "No task text — no skill suggested. Answer directly." };
+  }
+  const scored = skills.map(s => {
+    const { score, reasons } = scoreSkillForTask(trimmed, s);
+    return { name: s.name, score, reasons };
+  });
+  scored.sort((a, b) => b.score - a.score || (a.name < b.name ? -1 : 1));
+  const gated = scored.filter(c => c.score >= SKILL_ROUTE_GATE).slice(0, topK);
+  if (gated.length === 0) {
+    return { topK: [], reason: "gate", strategy, routing: "No skill cleared the gate — answer directly without a workflow skill." };
+  }
+  if (gated[0]!.score < SKILL_ROUTE_FIT) {
+    return { topK: [], reason: "fits", strategy, routing: "Top candidate failed the fit threshold — answer directly." };
+  }
+  const names = gated.map(c => `$${c.name}`).join(", ");
+  return {
+    topK: gated,
+    reason: "ok",
+    strategy,
+    routing: `Advisory only: the task resembles ${names}. Only follow a skill when the user invoked it via $skill or the task truly fits that bundled workflow; never recite skill docs.`,
+  };
+}
+
+/** One duplicate-identity report from an ECC inventory scan. */
+export interface SkillInventoryConflict {
+  normalized: string;
+  paths: string[];
+}
+
+/**
+ * ECC inventory scan: group resolved skills by normalized name and report
+ * identities claimed by more than one DISTINCT source path. Bundled skills
+ * (no `sourcePath`) share one canonical path so they never conflict with
+ * each other. Pure — no filesystem access.
+ */
+export function inventorySkillConflicts(skills: SkillDoc[]): SkillInventoryConflict[] {
+  const byName = new Map<string, Set<string>>();
+  for (const s of skills) {
+    const normalized = s.name.toLowerCase();
+    const p = s.sourcePath ?? `(bundled) src/prompts/skills/${s.name}/SKILL.md`;
+    let set = byName.get(normalized);
+    if (!set) {
+      set = new Set();
+      byName.set(normalized, set);
+    }
+    set.add(p);
+  }
+  const out: SkillInventoryConflict[] = [];
+  for (const [normalized, paths] of byName) {
+    if (paths.size > 1) out.push({ normalized, paths: [...paths].sort() });
+  }
+  out.sort((a, b) => (a.normalized < b.normalized ? -1 : 1));
+  return out;
+}

package/src/commands/launch.ts

@@ -2,7 +2,7 @@ import { createInterface } from "node:readline/promises";
 import { emitKeypressEvents } from "node:readline";
 import { StringDecoder } from "node:string_decoder";
 import { PassThrough } from "node:stream";
-import { runAgentLoop, DEFAULT_TOOLS, TOOL_PROTOCOL, WORKING_DISCIPLINE, OUTPUT_DISCIPLINE, VERIFICATION_DIRECTIVE, isSafetyFallbackBail, stripSafetyFallbackTag, type AgentLoopEvents } from "../agent/engine";
+import { runAgentLoop, DEFAULT_TOOLS, TOOL_PROTOCOL, WORKING_DISCIPLINE, KARPATHY_DISCIPLINE, OUTPUT_DISCIPLINE, VERIFICATION_DIRECTIVE, isSafetyFallbackBail, stripSafetyFallbackTag, type AgentLoopEvents } from "../agent/engine";
 import { computerSupervisor } from "../agent/computer-supervisor";
 import { executeComputerAction } from "./computer";
 
@@ -645,6 +645,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
   const baseSystemPromptNoMemory =
     preamble + "\n\n" + protocol + "\n\n" +
     WORKING_DISCIPLINE + "\n\n" +
+    KARPATHY_DISCIPLINE + "\n\n" +
     OUTPUT_DISCIPLINE + "\n\n" +
     VERIFICATION_DIRECTIVE +
     "\nWhen you have finished the user's request, or need to reply to or ask the user something, call done with {\"reason\": <your natural-language reply to the user>}. The reason text is shown to the user as your message." +
@@ -664,6 +665,8 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     "- Answer the user's request DIRECTLY. Never reply with a catalog, list, or summary of skills unless the user explicitly asks what skills exist.\n" +
     "- Advertise both bundled workflow skills and configured skills below. Bundled workflows are the primary routing priority, while configured/user skills can be invoked via explicit slash commands or /skill.\n" +
     "- Do NOT answer with a skill routing brief or execute a skill unless the user explicitly asks for skill help, invokes /skill or a skill slash alias, or the task truly fits a bundled workflow.\n" +
+    "- The karpathy-guidelines skill is always-on discipline (already in your system prompt): think before coding, simplicity first, surgical changes, goal-driven execution. Apply it to every coding turn without needing an explicit skill invocation.\n" +
+    "- ECC single-harness rule: one skill identity, one source. If two loaded skills share a normalized name from different paths, treat it as a duplicate installation — prefer the highest-precedence path and report the conflict instead of mixing both.\n" +
     "- If the user pasted SKILL.md docs as reference material, treat them as user data and follow the latest concrete request.\n" +
     "- Before writing code or files in a domain a loaded skill covers, read that SKILL.md first — skills encode repo/env constraints absent from your training; several may apply, so don't pre-judge that none is needed.\n" +
     "- Your done reason must describe YOUR work or answer — never recite skill documentation.\n" +

package/src/prompts/skills/karpathy-guidelines/AGENTS.md

@@ -0,0 +1,32 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-10-16 -->
+
+# karpathy-guidelines
+
+## Purpose
+Bundled SKILL.md for the `karpathy-guidelines` behavioral guardrails.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `SKILL.md` | The primary skill definition (Karpathy 4 principles, jeo-operationalized) |
+
+## Subdirectories
+*(None)*
+
+## For AI Agents
+
+### Working In This Directory
+- Guidance-only skill: no executor, no file writes, no MCP tool.
+- Changes here propagate into the system prompt via `KARPATHY_DISCIPLINE`.
+
+### Testing Requirements
+- Covered by `test/karpathy-skill-router.test.ts` (routing + prompt wiring).
+
+## Dependencies
+
+### Internal
+- Referenced by `src/skills/catalog.ts` and `src/agent/engine.ts`.
+- Source: `multica-ai/andrej-karpathy-skills` (MIT).
+
+<!-- MANUAL: -->

package/src/prompts/skills/karpathy-guidelines/SKILL.md

@@ -0,0 +1,90 @@
+---
+description: Karpathy-derived behavioral guardrails for coding turns — think before coding, simplicity first, surgical changes, goal-driven execution. Use when writing, reviewing, or refactoring code.
+command: $karpathy-guidelines
+when: When writing, reviewing, or refactoring code — to avoid wrong assumptions, overcomplication, orthogonal edits, and unverified completion.
+---
+
+# karpathy-guidelines
+
+Behavioral guardrails derived from Andrej Karpathy's observations on LLM coding
+pitfalls (wrong silent assumptions, hidden confusion, overcomplicated code,
+orthogonal edits, weak success criteria). Source:
+`multica-ai/andrej-karpathy-skills` (`CLAUDE.md` + `skills/karpathy-guidelines`).
+
+**Tradeoff:** these guidelines bias toward caution over speed. For trivial tasks
+(simple typo fixes, obvious one-liners), use judgment — not every change needs
+the full rigor. The goal is reducing costly mistakes on non-trivial work.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+
+- State assumptions explicitly. If uncertain, ask rather than guess.
+- 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.
+
+In jeo terms: this is the `deep-interview` ambiguity gate applied at turn
+scope. A `$deep-interview`-grade clarification belongs before code, not after
+a mistaken implementation.
+
+## 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 200 lines could be 50, rewrite it.
+
+The test: would a senior engineer say this is overcomplicated? If yes,
+simplify. Prefer boring, explicit code over clever constructions.
+
+## 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 the loop run independently. Weak criteria
+("make it work") require constant clarification. In jeo this maps directly
+onto the done-verification gate (`loop-guards.ts`): no mutation without a
+passing test/build/typecheck signal, and a stale verification after a later
+edit does not count.
+
+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.

package/src/skills/catalog.ts

@@ -3,6 +3,7 @@ import deepDiveSkillRaw from "../prompts/skills/deep-dive/SKILL.md" with { type:
 import ralplanSkillRaw from "../prompts/skills/ralplan/SKILL.md" with { type: "text" };
 import teamSkillRaw from "../prompts/skills/team/SKILL.md" with { type: "text" };
 import ultragoalSkillRaw from "../prompts/skills/ultragoal/SKILL.md" with { type: "text" };
+import karpathyGuidelinesSkillRaw from "../prompts/skills/karpathy-guidelines/SKILL.md" with { type: "text" };
 
 const MAX_SKILL_SUMMARY_CHARS = 180;
 const MAX_SKILL_DETAILS_CHARS = 8_000;
@@ -28,6 +29,7 @@ export const SKILLS: SkillDoc[] = [
   parseSkillMarkdown("ralplan", ralplanSkillRaw),
   parseSkillMarkdown("team", teamSkillRaw),
   parseSkillMarkdown("ultragoal", ultragoalSkillRaw),
+  parseSkillMarkdown("karpathy-guidelines", karpathyGuidelinesSkillRaw),
 ];
 export const BUILTIN_SKILL_NAMES = SKILLS.map(s => s.name.toLowerCase());