From 83a207c8d6dd237b0f22ff26d5a11efe90838add Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:15:58 +0530 Subject: [PATCH 01/12] docs: reposition product around in-flow learning --- README.md | 98 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 59 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 72ece15..5a7649d 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ ## know-your-code -I'm a software engineering student. Every few months a new frontier model lands, faster and more powerful than the last. AI moves faster than a student can understand, and I stopped understanding my own code, especially when it's complex or new to me. +Build at AI speed without becoming a stranger to your own code. -I don't think I'm alone in that. +know-your-code is a learning layer for AI coding agents. It keeps implementation moving, but surfaces the important decisions, tradeoffs, and risks while the work is happening—not only after a giant diff is finished. -So I built a Claude Code plugin that makes sure you learn something every time you ship: before you push, you explain what changed and why. +> AI writes the code. You stay in the loop. -![know-your-code blocks a git push until you explain the diff](assets/demo.gif) +![know-your-code shows an in-flow learning checkpoint](assets/demo.gif) ### Install @@ -15,6 +15,7 @@ So I built a Claude Code plugin that makes sure you learn something every time y ``` /plugin marketplace add MinitJain/know-your-code ``` + ``` /plugin install know-your-code@know-your-code ``` @@ -23,51 +24,64 @@ Needs `git` and `jq` on your PATH. More agents: see [Other agents](#other-agents ### How it works -You code like you always do. When you try to `git push` or open a PR, the gate stops you: +The learning loop has three speeds: -``` -❯ push this +1. **Passive checkpoint** — after a meaningful code change, the agent gives a short summary: what changed, why, and one risk. No response is required. +2. **Decision checkpoint** — before a consequential choice, you choose between approaches or ask for more context. +3. **Ship checkpoint** — before `git push` or `gh pr create`, the existing diff review makes sure you can explain what you are shipping. -⛔ know-your-code: explain before you ship - 3 files changed · +142 −18 +The system is deliberately selective. It does not quiz every tool call or interrupt routine work. - Q1. Why does retryFetch() back off instead of retrying instantly? - Q2. What happens if the Redis call in queue.ts throws? ``` +❯ add password reset + +KYC · decision checkpoint +Where should reset tokens live? + +a) A separate table — easier to revoke and audit +b) A signed token — fewer database reads, harder to invalidate -Answer in your own words. Get it right, you ship. Get it wrong, you learn why, then you ship. +Choose a direction, or ask for more context. + +...agent implements the feature... + +KYC · passive checkpoint +Implemented the request flow. Tokens are hashed, expire after 15 minutes, +and are invalidated after use. Remaining risk: account-enumeration through +reset-request errors. +``` ### Levels -| Level | When | What | +| Level | During implementation | Before push | |---|---|---| -| `easy` | Before push | Multiple choice with hints. Pick, then say why in one line. | -| `medium` | Before push | Open questions on what changed, why, and what breaks. **Default.** | -| `hard` | Before coding **and** before push | Pick between tradeoffs, plan the build, then check the build against your plan. | +| `easy` | Short summaries; decisions include plain-language options | Three multiple-choice questions with hints | +| `medium` | Summaries plus one open question for important decisions. **Default.** | Three focused questions: what, why, and what breaks | +| `hard` | Compare approaches, write a 5–10 line plan, then check meaningful changes against it | Explain plan/build drift and one failure mode | -Start easy. Graduate to hard. +Start with `easy`. Use `hard` when you are learning a new area or shipping a risky feature. ### Commands -In Claude Code these are slash commands. In other agents, just say them ("kyc hard"). +In Claude Code these are slash commands. In other agents, just say them (for example, "kyc hard"). | Command | Does | |---|---| -| `/kyc` | Quiz me on the current diff now | -| `/kyc explain` | Walk me through what changed and why | -| `/kyc easy` · `medium` · `hard` | Set difficulty | -| `/kyc off` | Skip the gate once (logged) | +| `/kyc` | Run a checkpoint on the current work | +| `/kyc explain` | Walk through what changed, why, data flow, and risks | +| `/kyc easy` · `medium` · `hard` | Set the learning intensity | +| `/kyc off` | Skip the ship checkpoint once (logged) | ### Other agents -The quiz is an [Agent Skill](https://agentskills.io) (`skills/know-your-code/SKILL.md`), so any agent that reads skills can run it. The gate is a hook, so it only works where the agent has hooks. +The learning loop is an [Agent Skill](https://agentskills.io) (`skills/know-your-code/SKILL.md`). Hooks add passive checkpoints where the agent supports post-tool hooks; `AGENTS.md` provides the same behavior as a soft rule everywhere else. -| Agent | Gate (blocks push) | Quiz skill | Hard-mode plan nudge | Status | -|---|---|---|---|---| -| Claude Code | ✅ `PreToolUse` | ✅ | ✅ | tested | -| Codex | ✅ `PreToolUse` | ✅ | ✅ | untested | -| Cursor | ✅ `beforeShellExecution` | via `AGENTS.md` | ❌ (Cursor prompt hooks can't add context) | untested | -| Others (Windsurf, Cline, …) | ❌ | via `AGENTS.md` | ❌ | soft rule only | +| Agent | Ship gate | In-flow checkpoints | Status | +|---|---|---|---| +| Claude Code | ✅ `PreToolUse` | ✅ `PostToolUse` | supported | +| Codex | ✅ `PreToolUse` | ✅ `PostToolUse` | supported | +| Cursor | ✅ `beforeShellExecution` | via `AGENTS.md` | soft in-flow support | +| Others | via `AGENTS.md` | via `AGENTS.md` | soft rule | **Codex** @@ -76,7 +90,7 @@ codex plugin marketplace add MinitJain/know-your-code codex plugin add know-your-code@know-your-code ``` -Then run `codex`, open `/hooks`, review and trust the hooks, and start a new thread. Codex skips hooks it hasn't trusted. +Then run `codex`, open `/hooks`, review and trust the hooks, and start a new thread. **Cursor** @@ -84,23 +98,29 @@ Then run `codex`, open `/hooks`, review and trust the hooks, and start a new thr git clone https://github.com/MinitJain/know-your-code ~/.know-your-code ``` -Copy `hooks/cursor-hooks.json` to `~/.cursor/hooks.json` (or merge its `beforeShellExecution` entry into yours) and replace `KYC_DIR` with the absolute clone path, e.g. `/Users/you/.know-your-code`. Copy `AGENTS.md` into your project so the agent knows how to run the quiz. +Copy `hooks/cursor-hooks.json` to `~/.cursor/hooks.json` and replace `KYC_DIR` with the absolute clone path. Copy `AGENTS.md` into your project so the agent follows the in-flow protocol. **Anything else** -Copy `AGENTS.md` into your project. Without hooks nothing stops the push, so the agent follows the rule on its own. +Copy `AGENTS.md` into your project. Without hooks, checkpoints are still part of the agent instructions, but the ship gate cannot block the shell. -### Why not just use Learning mode? +### Product principles -Claude Code's Learning mode nudges. It doesn't stop you. Other tools make you write every line by hand. know-your-code stays out of your way while you build, and only stands between you and shipping. +- Maximize understanding per interruption. +- Explain important decisions before implementation, not every line after it. +- Keep routine work fast. +- Ask the developer to reason; never pretend the agent's explanation is theirs. +- Fail open if the learning layer is unavailable. +- Keep the final ship checkpoint as a safety net, not the whole product. ### How the gate works -- State lives in `.kyc/` at your repo root (self-gitignored). -- A pass is tied to the exact commit. New commit, new quiz. -- Needs `jq`. If `jq` is missing the gate fails open and warns. -- Catches `git push` and `gh pr create`, also inside chains like `git add . && git push`. Not caught: shell aliases (`gp`) and commands wrapped in `sh -c '...'`. -- It is an honor system: you can always delete the hook. The point is the habit, not the lock. +- State lives in `.kyc/` at the repo root (self-gitignored). +- A pass is tied to the exact commit. New commit, new ship checkpoint. +- The in-flow hook only prompts when the working diff changes; it stores a hash in `.kyc/` so repeated tool calls stay quiet. +- Needs `jq`. If `jq` is missing, the hook fails open and warns. +- Catches `git push` and `gh pr create`, including chains like `git add . && git push`. +- It is an honor system: you can always use `/kyc off`. The point is the habit, not the lock. ### Develop From 557969ecbaae39253509f1cec782a5db34081667 Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:16:00 +0530 Subject: [PATCH 02/12] docs: make in-flow learning the default agent protocol --- AGENTS.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 103c11a..0eba36f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,9 +1,14 @@ # know-your-code -Before you run `git push` or `gh pr create`, the user must explain what changed and why. +The goal is to help the user build at AI speed while understanding important implementation decisions. -1. Check for `.kyc/passed-$(git rev-parse HEAD)` at the repo root. If it exists, push. -2. If `.kyc/skip-$(git rev-parse HEAD)` exists, delete it, append ` skip ` to `.kyc/log`, and push. -3. Otherwise follow [`skills/know-your-code/SKILL.md`](skills/know-your-code/SKILL.md): quiz the user on the diff, wait for their own answers, never answer for them, and only then create the pass file. +During implementation, keep the user in the loop: -Agents with hooks (Claude Code, Codex, Cursor) enforce this with `hooks/gate.sh`. Everywhere else this file is the only guard, so follow it. +1. Before a consequential decision, explain the decision, give 2–3 options with tradeoffs, and let the user choose or ask for more context. +2. After a meaningful code change, give a short checkpoint covering what changed, why this approach was used, and one risk. Do not interrupt routine edits. +3. If implementation diverges from the stated approach, call it out and ask whether the new direction is understood. +4. Before `git push` or `gh pr create`, follow [`skills/know-your-code/SKILL.md`](skills/know-your-code/SKILL.md) for the final ship checkpoint. + +When hooks are available, `hooks/gate.sh` enforces the ship checkpoint and `hooks/learning-loop.sh` nudges the agent after meaningful diff changes. + +The user must answer in their own words. Never create a pass file without their answer. If they need to ship immediately, ask them to use `kyc off`; the skip is logged and applies once. From 4d613c837da8ea86ac40408d5dbd1a7cecb575dc Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:16:04 +0530 Subject: [PATCH 03/12] feat: add in-flow learning loop to core skill --- skills/know-your-code/SKILL.md | 124 +++++++++++++++++++-------------- 1 file changed, 71 insertions(+), 53 deletions(-) diff --git a/skills/know-your-code/SKILL.md b/skills/know-your-code/SKILL.md index cb40b13..5ab0c3f 100644 --- a/skills/know-your-code/SKILL.md +++ b/skills/know-your-code/SKILL.md @@ -1,65 +1,83 @@ --- name: know-your-code -description: Quiz the user on their diff before git push or gh pr create, and in hard mode make them plan before coding. Use when the know-your-code gate blocks a push, when the user runs /kyc, or when hard-mode context asks for a plan. +description: Keep users productive while they learn important implementation decisions during AI-assisted coding, then verify understanding before shipping. --- # know-your-code -The user vibe codes freely. Before shipping, they must show they understand what changed and why. You are a patient tutor, not a gatekeeper who enjoys saying no. - -## State (all in `/.kyc/`) - -- `level`: `easy` | `medium` | `hard`. Missing = `medium`. -- `passed-`: user passed for this commit. The gate allows push. -- `skip-`: one-time skip from `/kyc off`. The gate consumes and logs it. -- `plan-.md`: hard-mode plan, written before coding. -- `log`: one line per pass/skip. - -First time you create `.kyc/`, also write `.kyc/.gitignore` containing `*` so it never gets committed. - -## Quiz flow (gate blocked a push, or `/kyc`) - -1. Find the diff being shipped: - ```bash - base=$(git merge-base HEAD @{u} 2>/dev/null || git merge-base HEAD origin/HEAD 2>/dev/null \ - || git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD origin/master 2>/dev/null) - git diff "$base"...HEAD - ``` - - If `base` is empty (no remote yet), or the diff is huge or clearly includes unrelated history (e.g. the branch was cut from another feature branch), show `git log --oneline -15` and ask the user which commit their work starts from. Never quiz from the repo's first commit. - - Uncommitted changes are not part of the push. Mention them, don't quiz them. -2. Read the diff and the code around it. Ask about the parts that matter: logic, error handling, data flow, security. Never ask about formatting, renames, or lockfiles. -3. Read the level file (`levels/.md` next to this file) and follow it. -4. Show the header: `⛔ know-your-code: explain before you ship` + `N files changed · +A −D`. -5. Wait for the user's answers. Do not answer for them. Do not hint unless the level allows it. -6. Grade honestly: - - Right (core idea correct, wording can be rough): say what they got right in one line, add anything they missed. - - Wrong or "I don't know": explain the real answer briefly, then ask ONE follow-up that checks they now get it. Correct follow-up = pass. -7. On pass: - ```bash - mkdir -p .kyc && [ -f .kyc/.gitignore ] || echo '*' > .kyc/.gitignore - touch .kyc/passed-$(git rev-parse HEAD) - echo "$(date -u +%FT%TZ) pass $(git rev-parse HEAD) $(cat .kyc/level 2>/dev/null || echo medium)" >> .kyc/log - ``` - Then retry the original push/PR command. +You are a patient tutor embedded in the implementation loop, not a gatekeeper who waits until the end. -## Commands +## The learning loop + +Use the lightest interaction that creates understanding: + +### 1. Passive checkpoint + +After a meaningful implementation chunk, briefly say: + +- **Changed:** what behavior or data flow changed +- **Why:** why this approach was used +- **Risk:** one edge case, failure mode, or security concern + +Keep it to 2–4 sentences. Do not ask the user to respond for routine changes. + +### 2. Decision checkpoint + +Pause before consequential choices such as API shape, schema, authentication, concurrency, state management, caching, or error behavior. + +1. State the decision in plain language. +2. Give 2–3 viable approaches. +3. Explain the tradeoffs: complexity, performance, failure modes, and reversibility. +4. Ask the user to choose, explain their preference, or request more context. +5. Continue once the direction is clear. + +Do not create a checkpoint for formatting, renames, lockfiles, trivial refactors, or routine test fixes. + +### 3. Plan checkpoint -In Claude Code these are `/kyc ...`. In other agents the user just says "kyc easy", "kyc off" and so on. +At `hard` level, before a real feature: + +1. Give 2–3 approaches without deciding for the user. +2. Ask them to choose and say why. +3. Ask for a 5–10 line plan covering files, data flow, edge cases, and tests. +4. Challenge one weak spot. +5. Save the plan to `.kyc/plan-.md`. + +Skip this for typos, configuration changes, and questions. + +### 4. Ship checkpoint + +Before `git push` or `gh pr create`: + +1. Find the diff being shipped and ignore unrelated history. +2. Ask exactly the number and type of questions defined by the selected level. +3. Ask about important behavior, reasoning, failure modes, and security—not formatting. +4. Wait for the user's own answers. Never answer for them. +5. If an answer is wrong, explain briefly and ask one follow-up. +6. On pass, create `.kyc/passed-` and retry the original command. + +The ship checkpoint is the final safety net. It should not be the user's first exposure to the reasoning. + +## Levels + +The level is stored in `.kyc/level`; missing means `medium`. + +- **easy:** Use short passive summaries. At decision checkpoints, prefer plain-language multiple choice. At ship time, ask 3 multiple-choice questions with hints, then one sentence explaining why the change was needed. +- **medium:** Use passive summaries by default. At decision checkpoints, ask one open question about the tradeoff when the decision matters. At ship time, ask exactly 3 open questions: what changed, why this approach, and what breaks. +- **hard:** Use all medium behavior. Require the plan checkpoint for real features. At ship time, compare the saved plan with the build, explain drift, and ask one failure-mode question. + +## Commands -- `kyc` → run the quiz flow on the current diff now. -- `kyc explain` → walk the user through the diff: what changed, why, data flow, risks. Plain words, grouped by file. No quiz, no pass file. -- `kyc easy` | `medium` | `hard` → `mkdir -p .kyc && ([ -f .kyc/.gitignore ] || echo '*' > .kyc/.gitignore) && echo > .kyc/level`. Confirm in one line what that level does. -- `kyc off` → ask for a one-line reason, then: - ```bash - mkdir -p .kyc && ([ -f .kyc/.gitignore ] || echo '*' > .kyc/.gitignore) - touch .kyc/skip-$(git rev-parse HEAD) - echo "$(date -u +%FT%TZ) off $(git rev-parse HEAD) " >> .kyc/log - ``` - Tell them the next push of this commit goes through once, and it's logged. +- `kyc` — run the learning loop on the current work now. +- `kyc explain` — explain the current changes by file: behavior, reason, data flow, and risks. Do not create a pass file. +- `kyc easy` | `medium` | `hard` — set the level. +- `kyc off` — ask for a one-line reason, consume a one-time skip for the current HEAD, and log it. ## Rules -- Never create `passed-*` without the user answering. That defeats the whole tool. If the user says "just push", point them to `/kyc off`. -- Never edit the user's code during the quiz. -- New commit = new HEAD = new quiz. Keep it short if the new diff is tiny (one question). -- Keep it fast: whole quiz should take the user under 3 minutes. +- Optimize for understanding per interruption. +- Keep routine implementation moving. +- Never create `passed-*` without the user's answer. +- New commit means a new ship checkpoint. +- Never edit user code during a ship checkpoint. +- If the hook is unavailable, follow this protocol from the skill. From d5e62ba65045eb7c01691ed674249386b02b65ad Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:16:25 +0530 Subject: [PATCH 04/12] docs: refine README motivation and productivity promise From 4a3f7541e2f4861246cc3f49e801c56ee67e56d7 Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:17:23 +0530 Subject: [PATCH 05/12] docs: redefine easy level for in-flow learning --- skills/know-your-code/levels/easy.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/skills/know-your-code/levels/easy.md b/skills/know-your-code/levels/easy.md index a7b1398..be7e21d 100644 --- a/skills/know-your-code/levels/easy.md +++ b/skills/know-your-code/levels/easy.md @@ -1,15 +1,14 @@ # Easy -1. Ask 3 multiple-choice questions on the diff. 4 options each, one correct. Make wrong options plausible, not silly. -2. After each pick: wrong → give a hint and let them pick again. Second miss → explain the answer. -3. Then ask one open line: "In one sentence, why did this change need to happen?" -4. Pass = all 3 MCQs resolved + a sensible one-line why. - -Format: -``` -Q1. What does retryFetch() do when the request fails? - a) Throws immediately - b) Retries with growing delay - c) Retries forever with no delay - d) Logs and returns null -``` +During implementation: + +- Give short passive checkpoints after meaningful changes. +- At important decisions, use 2–3 plain-language options with brief tradeoffs. +- Do not require an answer for routine implementation. + +Before shipping: + +1. Ask 3 multiple-choice questions about the important behavior in the diff. +2. After each pick: wrong → give a hint and let the user pick again. Second miss → explain. +3. Ask: "In one sentence, why did this change need to happen?" +4. Pass = all 3 questions resolved plus a sensible one-line why. From 672633297b6f5861f1d676e46fe70097a44d13c6 Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:17:27 +0530 Subject: [PATCH 06/12] docs: redefine medium level for in-flow learning --- skills/know-your-code/levels/medium.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/skills/know-your-code/levels/medium.md b/skills/know-your-code/levels/medium.md index 477519e..0fca509 100644 --- a/skills/know-your-code/levels/medium.md +++ b/skills/know-your-code/levels/medium.md @@ -1,9 +1,13 @@ # Medium (default) -Ask exactly 3 open questions, each tied to a specific file/function in the diff: +During implementation: -1. **What** — what does this code do now that it didn't before? -2. **Why** — why this approach? (why back off, why this data structure, why here) -3. **What breaks** — what happens on failure, bad input, or concurrency? What would break if this line were removed? +- Give a 2–4 sentence passive checkpoint after a meaningful implementation chunk. +- Before a consequential choice, ask one open question about the tradeoff. +- Do not interrupt formatting, renames, lockfiles, or routine test fixes. -No hints up front. Pass = core idea right on all 3 (follow-ups allowed per SKILL.md). +Before shipping, ask exactly 3 open questions tied to the important parts of the diff: + +1. **What** — what does the code do now that it did not before? +2. **Why** — why this approach instead of another? +3. **What breaks** — what happens on failure, bad input, concurrency, or security-sensitive input? From bd1a7da5d2a1cd452f333331d065815441b26acf Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:17:34 +0530 Subject: [PATCH 07/12] docs: redefine hard level around plan and build checkpoints --- skills/know-your-code/levels/hard.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/skills/know-your-code/levels/hard.md b/skills/know-your-code/levels/hard.md index c879a8f..09af4fb 100644 --- a/skills/know-your-code/levels/hard.md +++ b/skills/know-your-code/levels/hard.md @@ -1,21 +1,20 @@ # Hard -Two checkpoints. +## During implementation -## A. Before coding (PLAN) — only for real features, not typos/config/questions +Use the full in-flow protocol: -1. Before writing code, give the user 2–3 real approaches with tradeoffs (complexity, perf, failure modes). Don't say which you prefer yet. -2. Ask them to pick one and say why. -3. Ask them to write the plan: files to touch, data flow, edge cases, how they'll test it. 5–10 lines, their words. -4. Challenge weak spots once. Then save their plan verbatim to `.kyc/plan-.md` (branch with `/` → `-`). -5. Only now build. +1. Before a real feature, compare 2–3 approaches and ask the user to choose. +2. Require a 5–10 line plan in the user's words. +3. After each meaningful chunk, compare the implementation with the plan. +4. Challenge one weak spot when the build changes direction. -## B. Before push (PLAN vs BUILD) +Skip the plan for typos, configuration changes, questions, and trivial refactors. + +## Before shipping 1. Read `.kyc/plan-.md` and the diff. -2. Ask: - - Where does the build differ from the plan, and why? - - Which edge case from the plan is handled where? Any that aren't? - - One "what breaks" question as in medium. -3. No plan file? Fall back to medium + one tradeoff question ("what other approach could this have used, and why not?"). -4. Pass = they can explain every drift from the plan. +2. Ask where the build differs from the plan and why. +3. Ask which planned edge case is handled where, and which is not. +4. Ask one "what breaks" question. +5. Pass only when the user can explain important drift from the plan. From 2fd3f5c35f1e1213b3ceb760339ab0aae514ba62 Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:17:37 +0530 Subject: [PATCH 08/12] feat: add post-tool learning checkpoints --- hooks/hooks.json | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/hooks/hooks.json b/hooks/hooks.json index 340019d..43a40ce 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -10,6 +10,12 @@ { "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/hard-plan.sh\"" }] } + ], + "PostToolUse": [ + { + "matcher": "Bash", + "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/learning-loop.sh\"" }] + } ] } } From 944c4dabc1e5ec7f888fdc64d09b102c66d44eef Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:17:45 +0530 Subject: [PATCH 09/12] feat: nudge agent with in-flow learning checkpoints --- hooks/learning-loop.sh | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 hooks/learning-loop.sh diff --git a/hooks/learning-loop.sh b/hooks/learning-loop.sh new file mode 100644 index 0000000..270d0be --- /dev/null +++ b/hooks/learning-loop.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +# In-flow learning nudge. Runs after Bash tool calls and only speaks when the +# working diff has changed. The agent supplies the actual explanation. +# Exit 0 always: learning must never block implementation. + +input=$(cat) +command -v jq >/dev/null || exit 0 + +cwd=$(jq -r '.cwd // empty' <<<"$input") +cd "${cwd:-.}" 2>/dev/null || exit 0 +root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0 +kyc="$root/.kyc" +mkdir -p "$kyc" 2>/dev/null || exit 0 + +# Hash staged and unstaged diffs. Untracked files are intentionally excluded +# because they can be large; the ship gate still catches them. +hash=$( { + git diff --no-ext-diff + git diff --cached --no-ext-diff +} 2>/dev/null | shasum -a 256 | awk '{print $1}') +[ -n "$hash" ] || exit 0 + +last=$(cat "$kyc/.last-diff-hash" 2>/dev/null || true) +[ "$hash" = "$last" ] && exit 0 +printf '%s' "$hash" >"$kyc/.last-diff-hash" + +level=$(cat "$kyc/level" 2>/dev/null || echo medium) +cat < Date: Thu, 5 Nov 2026 19:18:22 +0530 Subject: [PATCH 10/12] docs: update Codex plugin positioning --- .codex-plugin/plugin.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index ded1910..0072261 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,18 +1,18 @@ { "name": "know-your-code", "version": "0.2.0", - "description": "Vibe code freely, but explain what changed and why before you git push or open a PR.", + "description": "Build at AI speed while understanding the important decisions, tradeoffs, and risks in your code.", "author": { "name": "Minit Jain", "url": "https://github.com/MinitJain" }, "homepage": "https://github.com/MinitJain/know-your-code", "repository": "https://github.com/MinitJain/know-your-code", "license": "MIT", - "keywords": ["learning", "git", "hooks", "education"], + "keywords": ["learning", "ai-coding", "developer-tools", "git", "hooks", "education"], "skills": "./skills/", "hooks": "./hooks/hooks.json", "interface": { "displayName": "know-your-code", - "shortDescription": "Explain your diff before you push", - "longDescription": "Blocks git push and gh pr create until you answer questions about what changed and why. Three levels: easy, medium, hard.", + "shortDescription": "Learn while you build with AI", + "longDescription": "Keeps implementation moving with selective in-flow checkpoints, then verifies understanding before git push or gh pr create.", "developerName": "Minit Jain", "category": "Productivity", "capabilities": ["Instructions", "Lifecycle hooks"], From 1f07a47cbb8d6dc1815a424f464bfb8578dcca31 Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:18:25 +0530 Subject: [PATCH 11/12] docs: update Claude plugin positioning --- .claude-plugin/plugin.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index ee9ca57..aa2e570 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "know-your-code", "version": "0.2.0", - "description": "Vibe code freely, but explain what changed and why before you git push or open a PR.", + "description": "Build at AI speed while understanding the important decisions, tradeoffs, and risks in your code.", "author": { "name": "Minit Jain" }, @@ -9,6 +9,8 @@ "license": "MIT", "keywords": [ "learning", + "ai-coding", + "developer-tools", "git", "hooks", "education" From 15ebc3b71ab56abc51beea869c975e0bbaab1cbc Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:19:18 +0530 Subject: [PATCH 12/12] fix: keep in-flow hook quiet on clean repos --- hooks/learning-loop.sh | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/hooks/learning-loop.sh b/hooks/learning-loop.sh index 270d0be..11bada6 100644 --- a/hooks/learning-loop.sh +++ b/hooks/learning-loop.sh @@ -11,6 +11,11 @@ cd "${cwd:-.}" 2>/dev/null || exit 0 root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0 kyc="$root/.kyc" mkdir -p "$kyc" 2>/dev/null || exit 0 +[ -f "$kyc/.gitignore" ] || printf '* +' >"$kyc/.gitignore" + +# Do not speak on clean or routine tool calls. +git diff --quiet --no-ext-diff && git diff --cached --quiet --no-ext-diff && exit 0 # Hash staged and unstaged diffs. Untracked files are intentionally excluded # because they can be large; the ship gate still catches them.