feat: move learning into the implementation loop

.claude-plugin/plugin.json

@@ -1,14 +1,16 @@
 {
   "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"
   },
   "repository": "https://github.com/MinitJain/know-your-code",
   "license": "MIT",
   "keywords": [
     "learning",
+    "ai-coding",
+    "developer-tools",
     "git",
     "hooks",
     "education"

.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"],

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 `<date> skip <sha>` 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.

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,31 +90,37 @@ 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**
 
 ```bash
 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
 

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\"" }]
+      }
     ]
   }
 }

hooks/learning-loop.sh

@@ -0,0 +1,40 @@
+#!/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
+[ -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.
+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 <<EOF
+know-your-code (in-flow checkpoint, level: $level):
+A meaningful tracked diff just changed. Before continuing, give the user a brief
+checkpoint in 2–4 sentences: what behavior changed, why this approach was used,
+and one important edge case or risk. Do not quiz them for routine work. If this
+change introduces a consequential decision, pause and run the decision checkpoint
+from the know-your-code skill instead.
+EOF