diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..d9d9f22 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,12 @@ +{ + "name": "know-your-code", + "interface": { "displayName": "know-your-code" }, + "plugins": [ + { + "name": "know-your-code", + "source": { "source": "url", "url": "https://github.com/MinitJain/know-your-code.git", "ref": "main" }, + "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, + "category": "Productivity" + } + ] +} diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 94593b5..912681b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,6 +1,9 @@ { "name": "know-your-code", - "owner": { "name": "Minit Jain" }, + "description": "Explain your diff before you push: a learning gate for AI-assisted coding.", + "owner": { + "name": "Minit Jain" + }, "plugins": [ { "name": "know-your-code", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index bd02da2..ee9ca57 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,9 +1,17 @@ { "name": "know-your-code", - "version": "0.1.0", + "version": "0.2.0", "description": "Vibe code freely, but explain what changed and why before you git push or open a PR.", - "author": { "name": "Minit Jain" }, + "author": { + "name": "Minit Jain" + }, "repository": "https://github.com/MinitJain/know-your-code", "license": "MIT", - "keywords": ["learning", "git", "hooks", "education"] + "keywords": [ + "learning", + "git", + "hooks", + "education" + ], + "icon": "./assets/icon.png" } diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json new file mode 100644 index 0000000..ded1910 --- /dev/null +++ b/.codex-plugin/plugin.json @@ -0,0 +1,25 @@ +{ + "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.", + "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"], + "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.", + "developerName": "Minit Jain", + "category": "Productivity", + "capabilities": ["Instructions", "Lifecycle hooks"], + "websiteURL": "https://github.com/MinitJain/know-your-code", + "defaultPrompt": ["kyc", "kyc explain", "kyc hard"], + "brandColor": "#3b82f6", + "composerIcon": "./assets/icon.png", + "logo": "./assets/icon.png" + } +} diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..0b295cb --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,21 @@ +name: test + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: JSON manifests are valid + run: for f in .claude-plugin/*.json .codex-plugin/plugin.json .agents/plugins/marketplace.json hooks/*.json; do jq empty "$f" || exit 1; done + - name: Versions match + 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 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..103c11a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,9 @@ +# know-your-code + +Before you run `git push` or `gh pr create`, the user must explain what changed and why. + +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. + +Agents with hooks (Claude Code, Codex, Cursor) enforce this with `hooks/gate.sh`. Everywhere else this file is the only guard, so follow it. diff --git a/CHANGELOG.md b/CHANGELOG.md index b67b11e..3e4d862 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## 0.2.0 — 2026-11-02 + +- Codex plugin (`.codex-plugin/plugin.json`, `.agents/plugins/marketplace.json`). Same hooks as Claude Code. +- Cursor support: `hooks/cursor-hooks.json`; the gate reads Cursor's `beforeShellExecution` input and answers with a JSON deny. +- `AGENTS.md` fallback for agents without hooks. +- Gate block message carries the quiz rules, so agents without the skill still run a fair quiz. +- `/kyc` logic moved into `SKILL.md` so every agent gets the commands. +- README: demo GIF, fixed install line (`know-your-code@know-your-code`), agent support table. +- Icon, GitHub Actions test workflow. +- Gate catches more push forms: subshells, absolute paths, `sudo`, `env`, `command`, `time`, VAR=x prefixes, quoted `git -C` args; ignores `echo git push`. Portable regex (no `\x27`). +- Quiz diff base: upstream, then origin default branch; asks the user instead of quizzing from the first commit. + ## 0.1.0 — 2026-11-02 - PreToolUse gate blocks `git push` / `gh pr create` until `.kyc/passed-` exists. diff --git a/README.md b/README.md index 1aa4cf4..3d45a43 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,20 @@ I don't think I'm alone in that. So I built a Claude Code plugin with guardrails: before you push, you explain what changed and why. Code stays fast. You keep learning. +![know-your-code blocks a git push until you explain the diff](assets/demo.gif) + ### Install +**Claude Code** (send these as two separate prompts): + ``` /plugin marketplace add MinitJain/know-your-code -/plugin install know-your-code ``` +``` +/plugin install know-your-code@know-your-code +``` + +Needs `git` and `jq` on your PATH. More agents: see [Other agents](#other-agents). ### How it works @@ -41,6 +49,8 @@ Start easy. Graduate to hard. ### Commands +In Claude Code these are slash commands. In other agents, just say them ("kyc hard"). + | Command | Does | |---|---| | `/kyc` | Quiz me on the current diff now | @@ -48,6 +58,38 @@ Start easy. Graduate to hard. | `/kyc easy` · `medium` · `hard` | Set difficulty | | `/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 | +|---|---|---|---|---| +| 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 | + +**Codex** + +```bash +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. + +**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. + +**Anything else** + +Copy `AGENTS.md` into your project. Without hooks nothing stops the push, so the agent follows the rule on its own. + ### 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. @@ -57,6 +99,7 @@ Claude Code's Learning mode nudges. It doesn't stop you. Other tools make you wr - 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. ### Develop @@ -64,6 +107,7 @@ Claude Code's Learning mode nudges. It doesn't stop you. Other tools make you wr ``` claude --plugin-dir ~/know-your-code bash tests/gate.test.sh +claude plugin validate . ``` ### License diff --git a/assets/demo.gif b/assets/demo.gif new file mode 100644 index 0000000..6cb9a1d Binary files /dev/null and b/assets/demo.gif differ diff --git a/assets/icon.png b/assets/icon.png new file mode 100644 index 0000000..a40daef Binary files /dev/null and b/assets/icon.png differ diff --git a/commands/kyc.md b/commands/kyc.md index dd04dad..5a5da22 100644 --- a/commands/kyc.md +++ b/commands/kyc.md @@ -3,16 +3,6 @@ description: Quiz, explain, set level, or skip the know-your-code gate argument-hint: "[explain | easy | medium | hard | off]" --- -Use the know-your-code skill. Argument: `$ARGUMENTS` +Use the know-your-code skill and follow its "Commands" section for: `kyc $ARGUMENTS` -- empty → run the quiz flow on the current diff now. -- `explain` → walk the user through the diff: what changed, why, data flow, risks. Plain words, grouped by file. No quiz, no pass file. -- `easy` | `medium` | `hard` → `mkdir -p .kyc && ([ -f .kyc/.gitignore ] || echo '*' > .kyc/.gitignore) && echo > .kyc/level`. Confirm in one line what that level does. -- `off` → ask the user 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. -- anything else → show the usage line from argument-hint. +Empty argument = run the quiz now. Unknown argument = show the usage line from argument-hint. diff --git a/hooks/cursor-hooks.json b/hooks/cursor-hooks.json new file mode 100644 index 0000000..407caa1 --- /dev/null +++ b/hooks/cursor-hooks.json @@ -0,0 +1,12 @@ +{ + "version": 1, + "hooks": { + "beforeShellExecution": [ + { + "command": "bash \"KYC_DIR/hooks/gate.sh\"", + "matcher": "git|gh ", + "timeout": 15 + } + ] + } +} diff --git a/hooks/gate.sh b/hooks/gate.sh index 3190c63..58ba0ae 100755 --- a/hooks/gate.sh +++ b/hooks/gate.sh @@ -1,19 +1,29 @@ #!/usr/bin/env bash -# know-your-code gate: PreToolUse hook on Bash. -# Blocks `git push` / `gh pr create` until the user has explained the current HEAD. -# Exit 0 = allow, exit 2 = block (stderr goes back to Claude). +# know-your-code gate. Blocks `git push` / `gh pr create` until the user has explained the current HEAD. +# Claude Code + Codex: PreToolUse on Bash, command in .tool_input.command. +# Cursor: beforeShellExecution, command in top-level .command, wants JSON on stdout. +# Exit 0 = allow, exit 2 = block (reason on stderr). input=$(cat) # Fail open: a learning tool must never brick someone's shell. command -v jq >/dev/null || { echo "know-your-code: jq missing, gate disabled" >&2; exit 0; } -cmd=$(jq -r '.tool_input.command // empty' <<<"$input") +cmd=$(jq -r '.tool_input.command // .command // empty' <<<"$input") cwd=$(jq -r '.cwd // empty' <<<"$input") - -# Match push/PR anywhere in a chain (`git add . && git push`), allowing global -# flags like `git -C dir push`, but not `git commit -m "push"`. -if ! grep -Eq '(^|[;&|( ])git( +-[^ ]+( +[^- ][^ ]*)?)* +push( |$)|(^|[;&|( ])gh +pr +create( |$)' <<<"$cmd"; then +event=$(jq -r '.hook_event_name // empty' <<<"$input") +cursor_input=$(jq -r '.command // empty' <<<"$input") + +# Match push/PR at a shell-command boundary (`git add . && git push`), allowing +# wrappers (sudo, env, command, exec, nohup, time), VAR=x prefixes, a path to the +# binary and quoted global-option args, but not text like `echo git push`. +# shortcut: `sh -c 'git push'` and shell aliases are not caught; needs a real shell parser. +q="'" # literal quote: `\x27` in an ERE is not portable across grep implementations +pre='(^|[;&|(){}])[[:space:]]*((sudo|env|command|exec|nohup|time)([[:space:]]+-[^[:space:]]+)*[[:space:]]+|[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+)*(/?[[:alnum:]_.-]+/)*' +end='([[:space:]]|$|[;&|(){}])' +git_push="${pre}git([[:space:]]+-[^[:space:]]+([[:space:]]+(\"[^\"]*\"|${q}[^${q}]*${q}|[^[:space:]]+))?)*[[:space:]]+push${end}" +gh_pr="${pre}gh[[:space:]]+pr[[:space:]]+create${end}" +if ! grep -Eq "$git_push|$gh_pr" <<<"$cmd"; then exit 0 fi @@ -32,10 +42,16 @@ if [ -f "$kyc/skip-$head" ]; then fi level=$(cat "$kyc/level" 2>/dev/null || echo medium) -cat >&2 <&2 exit 2 diff --git a/hooks/hooks.json b/hooks/hooks.json index c685796..340019d 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -3,12 +3,12 @@ "PreToolUse": [ { "matcher": "Bash", - "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/gate.sh" }] + "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/gate.sh\"" }] } ], "UserPromptSubmit": [ { - "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/hard-plan.sh" }] + "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/hard-plan.sh\"" }] } ] } diff --git a/skills/know-your-code/SKILL.md b/skills/know-your-code/SKILL.md index d3af50a..cb40b13 100644 --- a/skills/know-your-code/SKILL.md +++ b/skills/know-your-code/SKILL.md @@ -20,8 +20,12 @@ First time you create `.kyc/`, also write `.kyc/.gitignore` containing `*` so it ## Quiz flow (gate blocked a push, or `/kyc`) 1. Find the diff being shipped: - - upstream exists: `git diff @{u}...HEAD` - - else: `git diff $(git merge-base HEAD origin/HEAD 2>/dev/null || git rev-list --max-parents=0 HEAD)...HEAD` + ```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. @@ -38,6 +42,21 @@ First time you create `.kyc/`, also write `.kyc/.gitignore` containing `*` so it ``` Then retry the original push/PR command. +## 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 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. + ## Rules - Never create `passed-*` without the user answering. That defeats the whole tool. If the user says "just push", point them to `/kyc off`. diff --git a/tests/gate.test.sh b/tests/gate.test.sh index 228dc9d..32e1d7d 100755 --- a/tests/gate.test.sh +++ b/tests/gate.test.sh @@ -25,9 +25,21 @@ expect 2 "$repo" "git push" "git push blocked" expect 2 "$repo" "git push -u origin main" "git push with args blocked" expect 2 "$repo" "git add . && git push" "chained push blocked" expect 2 "$repo" "git -C . push" "push with global flag blocked" +expect 2 "$repo" "git -C '/tmp/a b' push" "push with quoted global arg blocked" +expect 2 "$repo" "(git push)" "push in subshell blocked" +expect 2 "$repo" "/usr/bin/git push" "absolute git push blocked" +expect 2 "$repo" "sudo git push" "sudo git push blocked" expect 2 "$repo" "gh pr create --fill" "gh pr create blocked" +expect 2 "$repo" "env -i git push" "env -i git push blocked" +expect 2 "$repo" "command git push" "command git push blocked" +expect 2 "$repo" "GIT_TRACE=1 time git push" "VAR=x time git push blocked" +expect 0 "$repo" "echo git push" "push text in echo allowed" +expect 0 "$repo" 'git commit -m "git push later"' "git push inside commit msg allowed" expect 0 "$(mktemp -d)" "git push" "outside git repo allowed" +msg=$(jq -n --arg d "$repo" '{tool_input:{command:"git push"},cwd:$d}' | bash "$gate" 2>&1 >/dev/null) +grep -q 'mkdir -p ".*" && touch ".*passed-' <<<"$msg" && echo "ok block guidance quotes state path" || { echo "FAIL block guidance quotes state path"; fail=1; } + mkdir -p "$repo/.kyc" && touch "$repo/.kyc/passed-$(head)" expect 0 "$repo" "git push" "passed HEAD allowed" @@ -39,4 +51,22 @@ expect 0 "$repo" "git push" "skip allows once" expect 2 "$repo" "git push" "skip consumed" grep -q "skip $(head)" "$repo/.kyc/log" && echo "ok skip logged" || { echo "FAIL skip logged"; fail=1; } +# Cursor beforeShellExecution: top-level command, JSON deny on stdout +git -C "$repo" -c user.name=t -c user.email=t@t commit -q --allow-empty -m cursor +out=$(jq -n --arg d "$repo" '{hook_event_name:"beforeShellExecution",command:"git push",cwd:$d}' | bash "$gate" 2>/dev/null); code=$? +[ "$code" = 2 ] && [ "$(jq -r .permission <<<"$out")" = deny ] && echo "ok cursor push denied with JSON" || { echo "FAIL cursor push denied with JSON (code $code, out: $out)"; fail=1; } +out=$(jq -n --arg d "$repo" '{command:"git push",cwd:$d}' | bash "$gate" 2>/dev/null); code=$? +[ "$code" = 2 ] && [ "$(jq -r .permission <<<"$out")" = deny ] && echo "ok cursor wire input denied with JSON" || { echo "FAIL cursor wire input denied with JSON (code $code, out: $out)"; fail=1; } +out=$(jq -n --arg d "$repo" '{hook_event_name:"beforeShellExecution",command:"ls",cwd:$d}' | bash "$gate" 2>/dev/null); code=$? +[ "$code" = 0 ] && [ -z "$out" ] && echo "ok cursor non-push allowed" || { echo "FAIL cursor non-push allowed"; fail=1; } + +# hard-plan.sh: nudge only on hard level with no plan for the branch +hp="$(dirname "$gate")/hard-plan.sh" +nudge() { jq -n --arg d "$repo" '{prompt:"add login",cwd:$d}' | bash "$hp"; } +[ -z "$(nudge)" ] && echo "ok no nudge on medium" || { echo "FAIL no nudge on medium"; fail=1; } +echo hard > "$repo/.kyc/level" +nudge | grep -q "know-your-code (hard)" && echo "ok nudge on hard without plan" || { echo "FAIL nudge on hard without plan"; fail=1; } +touch "$repo/.kyc/plan-$(git -C "$repo" rev-parse --abbrev-ref HEAD | tr / -).md" +[ -z "$(nudge)" ] && echo "ok no nudge once plan exists" || { echo "FAIL no nudge once plan exists"; fail=1; } + exit $fail