diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index c8868bb..6973c0e 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "know-your-code", - "version": "0.4.0", + "version": "0.4.1", "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 index a4c8c86..33f9f09 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "know-your-code", - "version": "0.4.0", + "version": "0.4.1", "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", diff --git a/CHANGELOG.md b/CHANGELOG.md index 67bbde1..3507cf1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## 0.4.1 — 2026-11-06 + +- Docs: the Claude Code command is `/know-your-code:kyc ...` (plugin commands are namespaced; plain `/kyc` never existed). Saying "kyc pair" also works. +- Skill pre-approves `Read` on its own plugin folder while the skill is active, and re-invokes itself in later turns, so loading `pair.md`, levels and workflows doesn't prompt in default permission mode. + ## 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. diff --git a/README.md b/README.md index 35c6a06..cab6e1a 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ I wanted a permanent solution, because just asking Claude to "quiz me on this co ![know-your-code teaches while building, makes you guess the bug first, then quizzes you before push](assets/demo.gif) +▶ [Watch the 33-second demo with sound](assets/demo.mp4) + ### Install **Claude Code** (send these as two separate prompts): @@ -47,11 +49,11 @@ 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. +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: +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 | |---|---|---| @@ -63,17 +65,17 @@ No stops for boilerplate or formatting. Say "skip this checkpoint" or "pause pai ### Commands -In Claude Code these are slash commands. In other agents, just say them ("kyc hard"). +In Claude Code, type `/know-your-code:kyc ` (`/know` then Tab completes it), or just say it: "kyc pair". In other agents, just say it. | Command | Does | |---|---| -| `/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) | +| `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 @@ -109,7 +111,7 @@ Copy `AGENTS.md` and the `skills/know-your-code/` directory into your project. W ### Why not just use Learning mode? -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. +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/assets/demo.gif b/assets/demo.gif index f0d2dc0..29f9314 100644 Binary files a/assets/demo.gif and b/assets/demo.gif differ diff --git a/assets/demo.mp4 b/assets/demo.mp4 new file mode 100644 index 0000000..86d685e Binary files /dev/null and b/assets/demo.mp4 differ diff --git a/hooks/gate.sh b/hooks/gate.sh index 58ba0ae..5d1ae8f 100755 --- a/hooks/gate.sh +++ b/hooks/gate.sh @@ -34,7 +34,7 @@ kyc="$root/.kyc" [ -f "$kyc/passed-$head" ] && exit 0 -# /kyc off: one skip for this exact commit, consumed on use, logged. +# kyc off: one skip for this exact commit, consumed on use, logged. if [ -f "$kyc/skip-$head" ]; then rm -f "$kyc/skip-$head" echo "$(date -u +%FT%TZ) skip $head" >>"$kyc/log" @@ -48,7 +48,7 @@ Do not retry the push. Use the know-your-code skill if you have it. Otherwise: ask the user 3 questions about this diff (what changed, why this way, what breaks), wait for their own answers, never answer for them, explain anything they get wrong. Only after they pass: mkdir -p \"$kyc\" && touch \"$kyc/passed-$head\", then push again. -To skip once (logged), the user runs /kyc off (or says \"kyc off\" in other agents)" +To skip once (logged), the user runs /know-your-code:kyc off in Claude Code, or says \"kyc off\" in any agent" if [ "$event" = beforeShellExecution ] || [ -n "$cursor_input" ]; then jq -n --arg m "$msg" '{permission:"deny",user_message:"know-your-code: explain before you ship",agent_message:$m}' diff --git a/hooks/nudge.sh b/hooks/nudge.sh index 2c19322..93491bf 100755 --- a/hooks/nudge.sh +++ b/hooks/nudge.sh @@ -7,7 +7,7 @@ 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: ' 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." ;; + on) echo "know-your-code (pair): pair mode is on. If this prompt starts a new task, append '## Task: ' to .kyc/journal-$branch.md. Open a checkpoint only if one clearly applies (debug > design > prediction), max 3 per task, one at a time. Invoke the know-your-code skill and follow its pair.md." ;; 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: ' to .kyc/journal-$branch.md." ;; esac diff --git a/skills/know-your-code/SKILL.md b/skills/know-your-code/SKILL.md index 713fc23..b57829f 100644 --- a/skills/know-your-code/SKILL.md +++ b/skills/know-your-code/SKILL.md @@ -1,6 +1,7 @@ --- name: know-your-code -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. +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 /know-your-code:kyc or says "kyc ...", or when know-your-code context mentions teach mode, pair mode or a plan. +allowed-tools: Read(~/.claude/plugins/cache/know-your-code/**) --- # know-your-code @@ -21,11 +22,13 @@ When it is on, for a non-trivial coding task use the smallest applicable workflo 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. +In Claude Code, open the files this skill links to (`pair.md`, `levels/`, `workflows/`, `templates/`) with the Read tool, not `cat`. Read on this plugin's folder is pre-approved only while this skill is active, which ends at the next user message: in a later turn, invoke the know-your-code skill again before reading them, so the user gets no permission prompt. Other agents: use your normal file-reading tool. + ## 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. +- `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. - `pair`: `on` | `paused`. Pair mode, see [pair.md](pair.md). @@ -35,7 +38,7 @@ Do not claim that the user demonstrated a concept merely because the agent expla First time you create `.kyc/`, also write `.kyc/.gitignore` containing `*` so it never gets committed. -## Quiz flow (gate blocked a push, or `/kyc`) +## Quiz flow (gate blocked a push, or `kyc`) 1. Find the diff being shipped: ```bash @@ -65,7 +68,7 @@ The pass file is only a commit-specific shipping record. It is not evidence that ## Commands -In Claude Code these are `/kyc ...`. In other agents the user just says "kyc easy", "kyc off" and so on. +In Claude Code these are `/know-your-code:kyc ...` (plain `/kyc` does not exist), or the user just says "kyc pair". In other agents the user just says them. When you mention a command to the user in Claude Code, write it as `/know-your-code:kyc ...`. - `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. @@ -84,7 +87,7 @@ In Claude Code these are `/kyc ...`. In other agents the user just says "kyc eas ## 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 `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).