MinitJain · Nov 5, 2026 · Nov 3, 2026 · Nov 3, 2026 · Nov 5, 2026 · Nov 5, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "know-your-code",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Vibe code freely, but explain what changed and why before you git push or open a PR.",
   "author": {
     "name": "Minit Jain"

diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "know-your-code",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Vibe code freely, but explain what changed and why before you git push or open a PR.",
   "author": { "name": "Minit Jain", "url": "https://github.com/MinitJain" },
   "homepage": "https://github.com/MinitJain/know-your-code",
@@ -12,7 +12,7 @@
   "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.",
+    "longDescription": "Teaches you to understand, build, verify and explain changes, then blocks git push and gh pr create until you answer questions about what changed and why. Three levels: easy, medium, hard.",
     "developerName": "Minit Jain",
     "category": "Productivity",
     "capabilities": ["Instructions", "Lifecycle hooks"],

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -19,3 +19,5 @@ jobs:
         run: test "$(jq -r .version .claude-plugin/plugin.json)" = "$(jq -r .version .codex-plugin/plugin.json)"
       - name: Gate tests
         run: bash tests/gate.test.sh
+      - name: Teaching workflow tests
+        run: bash tests/teaching.test.sh
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+.DS_Store
diff --git a/AGENTS.md b/AGENTS.md
@@ -2,8 +2,10 @@
 
 Before you run `git push` or `gh pr create`, the user must explain what changed and why.
 
+Unless `.kyc/teach` contains `off` (the user ran `kyc teach off`), act as a teaching-first senior engineer: understand the task and relevant code before editing, make a lightweight plan, explain unfamiliar concepts at the moment they matter, verify in meaningful increments, and offer a knowledge-transfer summary for complex work. Keep routine implementation moving; pause only for decisions that materially affect behavior, cost, safety or future maintenance. Load only the relevant workflow from [`skills/know-your-code/workflows/`](skills/know-your-code/workflows/). Pair mode is opt-in; do not turn ordinary work into a quiz.
+
 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.
 
-Agents with hooks (Claude Code, Codex, Cursor) enforce this with `hooks/gate.sh`. Everywhere else this file is the only guard, so follow it.
+Agents with hooks (Claude Code, Codex, Cursor) enforce this with `hooks/gate.sh`. Everywhere else this file is the only guard, so follow it. If teach mode is on (the default) and the linked skill/workflow files are not installed, use this compact fallback: understand the requested outcome and relevant code, state a short plan, ask only about consequential tradeoffs, verify each meaningful increment, and give a brief handoff for complex work. Never claim the user understands something they did not explain or demonstrate.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.0 — 2026-11-03
+
+- Teach mode (on by default, `/kyc teach off` to turn off): understand the repository before coding, learn during meaningful increments, verify with evidence, finish with knowledge transfer.
+- Workflows and templates for codebase exploration, plans, verification and transfer reports, loaded only when needed.
+- `/kyc profile`: local learning profile in `.kyc/profile.md`, updated only from evidence.
+
+## 0.3.0 — 2026-11-03
+
+- Pair mode (`/kyc pair`): while building, the user reasons first at debug, design and prediction checkpoints. Max 3 per task, one at a time. Logged to `.kyc/journal-<branch>.md`.
+- Push quiz asks about journal entries first (wrong predictions, overridden choices), checked against the diff.
+- Hard level: user writes the function that carries the feature's central decision.
+- `hooks/hard-plan.sh` → `hooks/nudge.sh`: also reminds the agent while pair mode is on or paused.
+
 ## 0.2.0 — 2026-11-02
 
 - Codex plugin (`.codex-plugin/plugin.json`, `.agents/plugins/marketplace.json`). Same hooks as Claude Code.

diff --git a/README.md b/README.md
@@ -47,6 +47,22 @@ Answer in your own words. Get it right, you ship. Get it wrong, you learn why, t
 
 Start easy. Graduate to hard.
 
+### Teach mode
+
+On by default; `/kyc teach off` turns it off. For a non-trivial task Claude first maps the relevant code and assumptions, proposes a small plan, explains unfamiliar concepts when they become relevant, verifies meaningful increments, and ends with a knowledge-transfer summary. It stays autonomous between those moments and does not interrupt for boilerplate. It reads `.kyc/profile.md` (edit with `/kyc profile`) so it skips what you already know. Teach mode explains; pair mode (below) makes you answer first. Use either, both, or neither.
+
+### Pair mode
+
+A quiz at push time comes after the thinking. Pair mode moves some of it into the build. Turn it on with `/kyc pair`. At most 3 times per task, one at a time, Claude stops and makes you go first:
+
+| Moment | You | Then Claude |
+|---|---|---|
+| Bug | Give your best guess at the cause | Argues against it once, then checks |
+| Design choice | Pick from 2–3 options and say why | Argues against it once, recommends, builds |
+| Before a test or build | Predict what happens | Runs it, compares |
+
+No stops for boilerplate or formatting. Say "skip this checkpoint" or "pause pair mode" any time; it's logged. Each stop goes into `.kyc/journal-<branch>.md`, and the push quiz asks about your own calls first ("you predicted 2 failures, there was 1, why?"). On `hard`, you also write the one function that carries the feature's core decision.
+
 ### Commands
 
 In Claude Code these are slash commands. In other agents, just say them ("kyc hard").
@@ -55,19 +71,22 @@ In Claude Code these are slash commands. In other agents, just say them ("kyc ha
 |---|---|
 | `/kyc` | Quiz me on the current diff now |
 | `/kyc explain` | Walk me through what changed and why |
+| `/kyc teach off` · `teach` | Turn teach mode off, or back on |
+| `/kyc profile` | Read or update my learning profile |
 | `/kyc easy` · `medium` · `hard` | Set difficulty |
+| `/kyc pair` · `pair off` | Turn pair mode on or off |
 | `/kyc off` | Skip the gate 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.
 
-| Agent | Gate (blocks push) | Quiz skill | Hard-mode plan nudge | Status |
+| Agent | Gate (blocks push) | Quiz + teach workflow | Prompt reminders (hook) | 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 |
+| Cursor | ✅ `beforeShellExecution` | via `AGENTS.md` + skill folder | ❌ (Cursor prompt hooks can't add context) | untested |
+| Others (Windsurf, Cline, …) | ❌ | via `AGENTS.md` + skill folder | ❌ | soft rule only |
 
 **Codex**
 
@@ -84,15 +103,15 @@ 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` (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` and the `skills/know-your-code/` directory into your project so the agent can access the teaching workflows and final quiz.
 
 **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` and the `skills/know-your-code/` directory into your project. Without hooks nothing stops the push, so the agent follows the teaching protocol and final quiz as a soft rule.
 
 ### Why not just use Learning mode?
 
-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.
+Claude Code's Learning output style can mark gaps with `TODO(human)`, but it does not provide this repository-specific understand → build → verify → transfer workflow or connect learning evidence to the shipping quiz. know-your-code complements it: use the style for useful handoffs, and use `/kyc pair` when you want explicit checkpoints.
 
 ### How the gate works
 

diff --git a/commands/kyc.md b/commands/kyc.md
@@ -1,6 +1,6 @@
 ---
 description: Quiz, explain, set level, or skip the know-your-code gate
-argument-hint: "[explain | easy | medium | hard | off]"
+argument-hint: "[explain | profile | easy | medium | hard | pair | pair off | off]"
 ---
 
 Use the know-your-code skill and follow its "Commands" section for: `kyc $ARGUMENTS`

diff --git a/hooks/hard-plan.sh b/hooks/hard-plan.sh
diff --git a/hooks/hooks.json b/hooks/hooks.json
@@ -8,7 +8,7 @@
     ],
     "UserPromptSubmit": [
       {
-        "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/hard-plan.sh\"" }]
+        "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/nudge.sh\"" }]
       }
     ]
   }

diff --git a/hooks/nudge.sh b/hooks/nudge.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# UserPromptSubmit: add know-your-code context. stdout on exit 0 is added to the agent's context.
+# Pair mode on/paused → checkpoint reminder. Hard level without a plan → plan reminder. Else silent.
+cwd=$(jq -r '.cwd // empty' 2>/dev/null) || exit 0
+root=$(git -C "${cwd:-.}" rev-parse --show-toplevel 2>/dev/null) || exit 0
+branch=$(git -C "$root" rev-parse --abbrev-ref HEAD 2>/dev/null | tr / -)
+kyc="$root/.kyc"
+
+case "$(cat "$kyc/pair" 2>/dev/null)" in
+  on) echo "know-your-code (pair): pair mode is on. If this prompt starts a new task, append '## Task: <name>' to .kyc/journal-$branch.md. Open a checkpoint only if one clearly applies (debug > design > prediction), max 3 per task, one at a time. Follow pair.md in the know-your-code skill." ;;
+  paused) echo "know-your-code (pair): paused for the current task. If this prompt starts a new task, set .kyc/pair to 'on' and append '## Task: <name>' to .kyc/journal-$branch.md." ;;
+esac
+
+[ "$(cat "$kyc/teach" 2>/dev/null)" = off ] || echo "know-your-code (teach): teach mode is on. For a non-trivial coding task, follow the Teach mode workflow in the know-your-code skill: understand, plan, learn while building, verify, transfer. Read .kyc/profile.md first. Skip for questions, typos, config tweaks."
+
+if [ "$(cat "$kyc/level" 2>/dev/null)" = hard ] && [ ! -f "$kyc/plan-$branch.md" ]; then
+  echo "know-your-code (hard): no plan for branch '$branch'. If this prompt asks for a real feature, run the hard-level PLAN step from the know-your-code skill BEFORE writing code. Skip for questions, typos, config tweaks."
+fi
+exit 0
diff --git a/skills/know-your-code/SKILL.md b/skills/know-your-code/SKILL.md
@@ -1,19 +1,37 @@
 ---
 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: Teach the user to understand, build, verify and explain changes; quiz their diff before git push or gh pr create; in pair mode, make them reason first at debug, design and prediction checkpoints while building. Use for non-trivial coding tasks (features, bug fixes, refactors) while teach mode is on, which is the default; when the know-your-code gate blocks a push, when the user runs /kyc, or when know-your-code context mentions teach mode, pair mode or a plan.
 ---
 
 # 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.
 
+## Teach mode
+
+On by default. Off only when `.kyc/teach` contains `off` (set by `kyc teach off`). When it is off, build normally and stay out of the way until the push gate.
+
+When it is on, for a non-trivial coding task use the smallest applicable workflow in [workflows/](workflows/). Keep it lightweight: do not wait for the user during routine implementation. Give a compact understanding summary and plan, pause only when a decision materially affects behavior, cost, safety or future maintenance, and make the transfer report optional unless the task is complex or the user asks for it:
+
+1. **Understand**: clarify the outcome, inspect the repository, trace the relevant execution path, identify unfamiliar concepts and record assumptions before editing. Use [understand-task.md](workflows/understand-task.md) and [explore-codebase.md](workflows/explore-codebase.md).
+2. **Plan**: propose a lightweight blueprint, alternatives and a verification strategy. Do not turn this into a ceremony for a one-line change. Use [implementation-planning.md](workflows/implementation-planning.md).
+3. **Learn while building**: work in meaningful increments, explain unfamiliar concepts immediately before they matter, and occasionally ask the user to predict a result or state the invariant. Keep the agent autonomous between those moments. Use [learning-during-build.md](workflows/learning-during-build.md).
+4. **Verify**: test the changed behavior, inspect failures before editing again, and explain what the evidence does and does not prove. Use [verification.md](workflows/verification.md).
+5. **Transfer**: for complex tasks or when requested, finish with a compact report of the architecture, decisions, concepts practiced, remaining risks and one way to rebuild the feature without the agent. Use [knowledge-transfer.md](workflows/knowledge-transfer.md).
+
+Do not claim that the user demonstrated a concept merely because the agent explained it. Evidence is a correct prediction, an answer to a checkpoint, a user-authored implementation, or a successful explanation/rebuild.
+
 ## State (all in `<repo root>/.kyc/`)
 
 - `level`: `easy` | `medium` | `hard`. Missing = `medium`.
 - `passed-<HEAD sha>`: user passed for this commit. The gate allows push.
 - `skip-<HEAD sha>`: one-time skip from `/kyc off`. The gate consumes and logs it.
 - `plan-<branch>.md`: hard-mode plan, written before coding.
 - `log`: one line per pass/skip.
+- `pair`: `on` | `paused`. Pair mode, see [pair.md](pair.md).
+- `journal-<branch>.md`: pair-mode checkpoint journal.
+- `teach`: `off`, or missing = on. Teach mode.
+- `profile.md`: user goals, preferred explanation depth, evidence-backed notes. See [context.md](workflows/context.md).
 
 First time you create `.kyc/`, also write `.kyc/.gitignore` containing `*` so it never gets committed.
 
@@ -27,27 +45,32 @@ First time you create `.kyc/`, also write `.kyc/.gitignore` containing `*` so it
    ```
    - 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/<level>.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:
+2. If `.kyc/journal-<branch>.md` exists, pick questions with the "Push quiz from the journal" rule in [pair.md](pair.md) first. Fill the rest from the diff.
+3. 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.
+4. Read the level file (`levels/<level>.md` next to this file) and follow it.
+5. Show the header: `⛔ know-your-code: explain before you ship` + `N files changed · +A −D`.
+6. Wait for the user's answers. Do not answer for them. Do not hint unless the level allows it.
+7. 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:
+8. 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.
 
+The pass file is only a commit-specific shipping record. It is not evidence that the user understands every concept in the repository.
+
 ## Commands
 
 In Claude Code these are `/kyc ...`. In other agents the user just says "kyc easy", "kyc off" and so on.
 
 - `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 teach off` → `mkdir -p .kyc && ([ -f .kyc/.gitignore ] || echo '*' > .kyc/.gitignore) && echo off > .kyc/teach`. `kyc teach` → `rm -f .kyc/teach` (back to the default, on).
+- `kyc profile` → read or update `.kyc/profile.md` using [context.md](workflows/context.md).
 - `kyc easy` | `medium` | `hard` → `mkdir -p .kyc && ([ -f .kyc/.gitignore ] || echo '*' > .kyc/.gitignore) && echo <level> > .kyc/level`. Confirm in one line what that level does.
 - `kyc off` → ask for a one-line reason, then:
   ```bash
@@ -56,10 +79,13 @@ In Claude Code these are `/kyc ...`. In other agents the user just says "kyc eas
   echo "$(date -u +%FT%TZ) off $(git rev-parse HEAD) <reason>" >> .kyc/log
   ```
   Tell them the next push of this commit goes through once, and it's logged.
+- `kyc pair` → `mkdir -p .kyc && ([ -f .kyc/.gitignore ] || echo '*' > .kyc/.gitignore) && echo on > .kyc/pair`. Then follow [pair.md](pair.md) while building.
+- `kyc pair off` → `rm -f .kyc/pair`. The journal stays.
 
 ## 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 create or edit a pass file, journal answer, concept status or decision on the user's behalf to simulate participation. You may draft a blank template and record an explicitly chosen skip.
 - 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.
-Original file line number
+Diff line change
@@ Expand Up / @@ -8,7 +8,7 @@ @@
         ],
         "UserPromptSubmit": [
           {
-            "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/hard-plan.sh\"" }]
+            "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/nudge.sh\"" }]
           }
         ]
       }
@@ Expand Down @@