From 3b8f7e9ab9d0d734016c44f1c9d0f31b1f3e3a20 Mon Sep 17 00:00:00 2001 From: MINIT Date: Tue, 3 Nov 2026 13:39:34 +0530 Subject: [PATCH 1/9] feat: make know-your-code teaching first --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 4 +- .github/workflows/test.yml | 2 + .gitignore | 1 + AGENTS.md | 2 + CHANGELOG.md | 12 +++ README.md | 22 ++++- commands/kyc.md | 2 +- hooks/hard-plan.sh | 9 -- hooks/hooks.json | 2 +- hooks/nudge.sh | 17 ++++ skills/know-your-code/SKILL.md | 41 +++++++-- skills/know-your-code/pair.md | 84 +++++++++++++++++++ .../templates/decision-record.md | 8 ++ .../templates/implementation-blueprint.md | 20 +++++ .../templates/learning-report.md | 16 ++++ skills/know-your-code/workflows/context.md | 12 +++ .../workflows/explore-codebase.md | 11 +++ .../workflows/implementation-planning.md | 14 ++++ .../workflows/knowledge-transfer.md | 11 +++ .../workflows/learning-during-build.md | 13 +++ .../workflows/understand-task.md | 12 +++ .../know-your-code/workflows/verification.md | 11 +++ tests/gate.test.sh | 10 ++- tests/teaching.test.sh | 27 ++++++ 25 files changed, 340 insertions(+), 25 deletions(-) create mode 100644 .gitignore delete mode 100755 hooks/hard-plan.sh create mode 100755 hooks/nudge.sh create mode 100644 skills/know-your-code/pair.md create mode 100644 skills/know-your-code/templates/decision-record.md create mode 100644 skills/know-your-code/templates/implementation-blueprint.md create mode 100644 skills/know-your-code/templates/learning-report.md create mode 100644 skills/know-your-code/workflows/context.md create mode 100644 skills/know-your-code/workflows/explore-codebase.md create mode 100644 skills/know-your-code/workflows/implementation-planning.md create mode 100644 skills/know-your-code/workflows/knowledge-transfer.md create mode 100644 skills/know-your-code/workflows/learning-during-build.md create mode 100644 skills/know-your-code/workflows/understand-task.md create mode 100644 skills/know-your-code/workflows/verification.md create mode 100644 tests/teaching.test.sh diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index ee9ca57..c8868bb 100644 --- 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 index ded1910..a4c8c86 100644 --- 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 index 0b295cb..3991126 100644 --- 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 new file mode 100644 index 0000000..e43b0f9 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.DS_Store diff --git a/AGENTS.md b/AGENTS.md index 103c11a..f1e4b91 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,8 @@ Before you run `git push` or `gh pr create`, the user must explain what changed and why. +For coding work, 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 end with a knowledge-transfer summary. 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 ` 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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 3e4d862..a38f60e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## 0.4.0 — 2026-11-03 + +- Teaching-first workflow: understand the repository before coding, learn during meaningful increments, verify with evidence, and finish with knowledge transfer. +- Progressive-disclosure workflows and templates for codebase exploration, plans, verification, persistent learning context and transfer reports. + +## 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-.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 index 72ece15..9df4c3e 100644 --- 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. +### Teaching-first build flow + +The skill now teaches during the build, not only at shipping time. For a non-trivial task it 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. Local learning context lives in the ignored `.kyc/` directory: `profile.md`, `concepts.md`, `decisions.md`, and optional plans. + +### 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-.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,14 +71,16 @@ 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 profile` | Read or update my local learning context | | `/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 skill | Teaching workflow / reminder | Status | |---|---|---|---|---| | Claude Code | ✅ `PreToolUse` | ✅ | ✅ | tested | | Codex | ✅ `PreToolUse` | ✅ | ✅ | untested | @@ -92,7 +110,7 @@ Copy `AGENTS.md` into your project. Without hooks nothing stops the push, so the ### 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 index 5a5da22..42d15fa 100644 --- 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 deleted file mode 100755 index 59e023b..0000000 --- a/hooks/hard-plan.sh +++ /dev/null @@ -1,9 +0,0 @@ -#!/usr/bin/env bash -# Hard level only: remind Claude to run the plan step before writing feature code. -# stdout on exit 0 is added to Claude's context. -cwd=$(jq -r '.cwd // empty' 2>/dev/null) || exit 0 -root=$(git -C "${cwd:-.}" rev-parse --show-toplevel 2>/dev/null) || exit 0 -[ "$(cat "$root/.kyc/level" 2>/dev/null)" = hard ] || exit 0 -branch=$(git -C "$root" rev-parse --abbrev-ref HEAD | tr / -) -[ -f "$root/.kyc/plan-$branch.md" ] && exit 0 -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." diff --git a/hooks/hooks.json b/hooks/hooks.json index 340019d..17bb37c 100644 --- 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 new file mode 100755 index 0000000..86aa573 --- /dev/null +++ b/hooks/nudge.sh @@ -0,0 +1,17 @@ +#!/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: ' 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: ' to .kyc/journal-$branch.md." ;; +esac + +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 index cb40b13..35573bd 100644 --- a/skills/know-your-code/SKILL.md +++ b/skills/know-your-code/SKILL.md @@ -1,12 +1,24 @@ --- 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 when the know-your-code gate blocks a push, when the user runs /kyc, or when know-your-code context mentions pair mode, learning, verification 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. +## Teaching-first workflow + +For any non-trivial coding task, use the smallest applicable workflow in [workflows/](workflows/): + +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**: 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 `/.kyc/`) - `level`: `easy` | `medium` | `hard`. Missing = `medium`. @@ -14,9 +26,17 @@ The user vibe codes freely. Before shipping, they must show they understand what - `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). +- `journal-.md`: pair-mode checkpoint journal. +- `profile.md`: user goals, preferences and evidence-backed learning notes. +- `concepts.md`: concept-level status: `unfamiliar`, `introduced`, `practiced` or `demonstrated`. +- `decisions.md`: durable decisions, alternatives, reasons and outcomes. +- `plans/`: optional task blueprints and verification notes. First time you create `.kyc/`, also write `.kyc/.gitignore` containing `*` so it never gets committed. +Initialize or update the context files using [context.md](workflows/context.md). Keep entries short, factual and task-specific. Never record secrets, and never upgrade a concept to `demonstrated` without evidence. + ## Quiz flow (gate blocked a push, or `/kyc`) 1. Find the diff being shipped: @@ -27,14 +47,15 @@ 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/.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-.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/.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) @@ -42,12 +63,15 @@ First time you create `.kyc/`, also write `.kyc/.gitignore` containing `*` so it ``` 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 profile` → read or update `.kyc/profile.md`, `.kyc/concepts.md` and `.kyc/decisions.md` using [context.md](workflows/context.md). - `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 @@ -56,10 +80,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) " >> .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. diff --git a/skills/know-your-code/pair.md b/skills/know-your-code/pair.md new file mode 100644 index 0000000..d4b9a48 --- /dev/null +++ b/skills/know-your-code/pair.md @@ -0,0 +1,84 @@ +# Pair mode + +Opt-in. On only when `.kyc/pair` contains `on` (set by `kyc pair`). + +You keep building. At the few moments that matter, the user reasons first, then you argue, then you build. This is a teaching conversation, not an approval system. + +## State + +- `.kyc/pair`: `on` | `paused`. Missing = off. +- `.kyc/journal-.md` (branch with `/` → `-`): append-only. Each task starts with a `## Task: ` heading. + +When the user asks for a new feature, fix or change: +1. Append `## Task: ` to the journal. +2. If `.kyc/pair` is `paused`, set it back to `on`. + +Checkpoints used = entries under the latest `## Task:` heading. **Max 3 per task. Only one open at a time.** + +## When to open a checkpoint + +In priority order: + +1. **Debug**: an error, failing test, unexpected output, or reported bug. First priority. +2. **Design**: 2–3 real approaches with different tradeoffs, failure modes or future cost (API shape, data model, concurrency, trust boundary, migration). +3. **Prediction**: before a test, build, migration or risky command whose result tells us something. + +Never for: formatting, boilerplate, following local conventions, harmless reads, cheap-to-undo choices. If nothing clearly qualifies, keep building. + +## How a checkpoint runs + +1. Show the evidence and say in one line why this moment matters. +2. Ask the user to go first: + - Debug: "What's your leading hypothesis, and what would prove it over the next most likely cause?" Do not propose a fix yet. + - Design: lay out the options and tradeoffs. "Which would you pick, and why?" + - Prediction: "What do you expect to happen, and why?" Do not run it yet. +3. After they answer, send ONE message with: + - the strongest counterargument, counterexample or alternative (specific, respectful); + - your recommendation, if it differs or adds something. +4. Wait. They may push back once, or say "go". Don't demand agreement. Max 2 user turns per checkpoint. +5. Build or run. Then append the journal entry. + +## Journal entries + +One per checkpoint. Only the fields for its type: + +```markdown +### debug +- symptom: `/api/save` returns 500 on empty body +- hypothesis: req.json() throws before the url check +- actual cause: same, JSON parse error on empty body +- hypothesis correct: yes + +### design +- options: queue per user · single queue + user key · cron batch +- user choice: single queue + user key, fewer Redis connections +- counter: one slow user blocks others without concurrency limits +- final: single queue + concurrency 4 + +### prediction +- command: `npm test -- queue` +- prediction: 2 failures, both in retry tests +- actual: 1 failure, retry delay off by one +- prediction correct: no + +### skipped +- debug: user said "skip this checkpoint", knew the fix +``` + +`pause pair mode` → append `### paused` with one line, set `.kyc/pair` to `paused`. No more checkpoints until the next task. +`skip this checkpoint` → append `### skipped`. It counts toward the 3. +Never shame a skip. Never skip silently. + +## Hard level: user writes the core + +At `hard`, after a design checkpoint and before you implement: if one function carries the feature's central invariant or decision, ask the user to write that function. You handle the wiring, boilerplate and repetitive edits. Review their function together before continuing. No line counts. If no function carries a real decision, skip this. + +## Push quiz from the journal + +When the gate blocks a push and `.kyc/journal-.md` exists, pick up to 3 entries, in this order: + +1. prediction or hypothesis marked `no` +2. design where `final` differs from the user's choice +3. most recent + +Check each against the actual diff. The journal is evidence, not truth: if the code no longer matches the entry, ask about that. Example: "You chose a single queue for fewer connections. Does the diff still do that?" No journal or nothing relevant → normal diff quiz. diff --git a/skills/know-your-code/templates/decision-record.md b/skills/know-your-code/templates/decision-record.md new file mode 100644 index 0000000..9041aff --- /dev/null +++ b/skills/know-your-code/templates/decision-record.md @@ -0,0 +1,8 @@ +## YYYY-MM-DD — task + +- Decision: +- Alternatives: +- Why: +- Counterargument: +- Outcome: +- Follow-up: diff --git a/skills/know-your-code/templates/implementation-blueprint.md b/skills/know-your-code/templates/implementation-blueprint.md new file mode 100644 index 0000000..431ca46 --- /dev/null +++ b/skills/know-your-code/templates/implementation-blueprint.md @@ -0,0 +1,20 @@ +# Implementation blueprint + +## Outcome + +## Current path + +`entry point → transformation → side effect` + +## Invariant + +## Increments and checks + +1. Change — Check: +2. Change — Check: + +## Alternatives and tradeoffs + +## Assumptions / open questions + +## Rollback or failure boundary diff --git a/skills/know-your-code/templates/learning-report.md b/skills/know-your-code/templates/learning-report.md new file mode 100644 index 0000000..6190a84 --- /dev/null +++ b/skills/know-your-code/templates/learning-report.md @@ -0,0 +1,16 @@ +# Learning report + +## What changed + +## Decisions and tradeoffs + +## Concepts + +| Concept | Status | Evidence | Next practice | +|---|---|---|---| + +## Verification + +## Risks and follow-up + +## Rebuild exercise diff --git a/skills/know-your-code/workflows/context.md b/skills/know-your-code/workflows/context.md new file mode 100644 index 0000000..3f0b543 --- /dev/null +++ b/skills/know-your-code/workflows/context.md @@ -0,0 +1,12 @@ +# Persistent learning context + +Create `.kyc/` and its `.gitignore` before writing context. The ignore file must contain `*`; these notes are local learning state, not project source. + +Use these files: + +- `profile.md`: goals, preferred explanation depth, and evidence-backed preferences. Do not infer expertise from a single correct answer. +- `concepts.md`: one row per concept with status, evidence and a next practice. Status can only move `unfamiliar → introduced → practiced → demonstrated`; it can move back when later evidence shows a gap. +- `decisions.md`: date/task, decision, alternatives considered, reason, counterargument, outcome and follow-up. Record outcomes, not just the agent's recommendation. +- `plans/.md`: optional blueprint, assumptions, affected files and verification plan. Use a safe descriptive name, not user input pasted into a shell command. + +When the user explicitly says they already know a concept, treat that as a preference to reduce explanation, not as `demonstrated` evidence. Ask for a smaller prediction or explanation instead of repeating a lesson. Never store secrets, tokens, personal data or full command output unnecessarily. diff --git a/skills/know-your-code/workflows/explore-codebase.md b/skills/know-your-code/workflows/explore-codebase.md new file mode 100644 index 0000000..3c8de07 --- /dev/null +++ b/skills/know-your-code/workflows/explore-codebase.md @@ -0,0 +1,11 @@ +# Repository exploration + +Explore in this order, stopping when the question is answered: + +1. Read the repository instructions and package/build manifests. +2. Check `git status`, branch context and recent history so edits do not confuse existing work. +3. Locate the user-facing entry point, the owner of the behavior, its data boundary and its tests. Prefer focused search over reading every file. +4. Read the smallest complete slice of the current execution path, including error paths and configuration. +5. Search for existing patterns before inventing a new abstraction. + +Report the resulting map in plain language: entry point → transformation → side effect, plus the tests that protect it. If the repository is too unfamiliar to proceed safely, say what is missing and inspect one level deeper. diff --git a/skills/know-your-code/workflows/implementation-planning.md b/skills/know-your-code/workflows/implementation-planning.md new file mode 100644 index 0000000..6fb4a89 --- /dev/null +++ b/skills/know-your-code/workflows/implementation-planning.md @@ -0,0 +1,14 @@ +# Lightweight implementation plan + +Use [templates/implementation-blueprint.md](../templates/implementation-blueprint.md) when a task spans more than one responsibility. + +The plan should name: + +- the behavior and invariant being added or preserved; +- the smallest ordered increments and files/symbols each touches; +- alternatives rejected and why; +- assumptions that need confirmation; +- a verification command or observation for every risky increment; +- the rollback or failure boundary. + +The plan is a guide, not a promise to preserve a bad design. Update it when evidence changes the approach and record the decision in `.kyc/decisions.md`. diff --git a/skills/know-your-code/workflows/knowledge-transfer.md b/skills/know-your-code/workflows/knowledge-transfer.md new file mode 100644 index 0000000..72dba6c --- /dev/null +++ b/skills/know-your-code/workflows/knowledge-transfer.md @@ -0,0 +1,11 @@ +# Stage D — Transfer knowledge + +End non-trivial work with a short report: + +- what changed and the execution path it affects; +- the important design decisions, alternatives and tradeoffs; +- concepts introduced or practiced, with evidence-backed statuses; +- checks run and what they prove or leave unverified; +- remaining risks, follow-ups and one small rebuild/explain exercise for the user. + +If pair mode was active, include the journal outcomes and any skipped or paused checkpoints. Do not claim independence from a successful build alone. diff --git a/skills/know-your-code/workflows/learning-during-build.md b/skills/know-your-code/workflows/learning-during-build.md new file mode 100644 index 0000000..2c3d946 --- /dev/null +++ b/skills/know-your-code/workflows/learning-during-build.md @@ -0,0 +1,13 @@ +# Stage B — Understandable Execution + +Build in coherent increments. Before each increment, tell the user what responsibility is changing, what data/control flow matters, and what will demonstrate it. Then implement the increment autonomously and show the relevant evidence. + +Teach immediately before an unfamiliar concept is used, not in a long preliminary lecture. Explain only the concept's role here, its important constraint, and one nearby example. Mark it `introduced` or `practiced` in `.kyc/concepts.md` only when the evidence supports that status. + +Use occasional hand-backs, not constant narration: + +- ask for a prediction before a test, migration, command or observable side effect; +- ask for the invariant or failure mechanism when a bug or security boundary is central; +- ask the user to choose among materially different designs when the choice changes behavior, cost, or future maintenance. + +Do not hand back naming, formatting, routine plumbing, or choices already established by the repository. If the user cannot answer, teach briefly, let them retry, and continue without treating uncertainty as failure. Pair mode adds explicit checkpoints and a journal; ordinary mode does not require a pause at every increment. diff --git a/skills/know-your-code/workflows/understand-task.md b/skills/know-your-code/workflows/understand-task.md new file mode 100644 index 0000000..8af63cf --- /dev/null +++ b/skills/know-your-code/workflows/understand-task.md @@ -0,0 +1,12 @@ +# Stage A — Understand before coding + +Use this for a feature, bug fix, refactor or unfamiliar integration. Skip or compress it for a typo, formatting-only change or an explicitly scoped one-line edit. + +1. Restate the requested outcome and the observable acceptance condition. +2. Inspect the repository shape, relevant instructions, current branch/status and existing tests before proposing files. +3. Trace the current behavior from entry point to side effect. Name the files and symbols that own each responsibility. +4. Identify dependencies, integration points, security/reliability concerns and at least one unfamiliar concept. Check the local context files before teaching something already practiced. +5. State assumptions and alternatives. If an assumption could change the design, ask the user; otherwise label it and proceed. +6. Give a short blueprint: files to change, data/control flow, smallest increments and how each increment will be checked. + +Do not dump a directory listing or explain framework boilerplate. Show the user the few facts that determine the design. diff --git a/skills/know-your-code/workflows/verification.md b/skills/know-your-code/workflows/verification.md new file mode 100644 index 0000000..1298617 --- /dev/null +++ b/skills/know-your-code/workflows/verification.md @@ -0,0 +1,11 @@ +# Stage C — Verify and debug + +For each meaningful increment: + +1. State the expected result before running the check when the result teaches something. +2. Run the narrowest relevant test, type check, linter or focused command first. +3. Compare actual and expected output. Distinguish a product failure, a test failure, an environment failure and an inconclusive check. +4. If it fails, show the symptom and ask for the user's first hypothesis in pair mode; otherwise briefly explain the likely cause and investigate before changing code. +5. Add or update a regression check when the behavior is durable. Finish with the full appropriate suite and inspect the diff. + +Never call a green command proof of behavior it does not exercise. Record meaningful predictions and outcomes in the pair journal or `.kyc/decisions.md`. diff --git a/tests/gate.test.sh b/tests/gate.test.sh index 32e1d7d..3061f7d 100755 --- a/tests/gate.test.sh +++ b/tests/gate.test.sh @@ -60,13 +60,19 @@ out=$(jq -n --arg d "$repo" '{command:"git push",cwd:$d}' | bash "$gate" 2>/dev/ 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.sh: hard-level plan reminder + pair-mode reminder +hp="$(dirname "$gate")/nudge.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; } +echo on > "$repo/.kyc/pair" +nudge | grep -q "pair mode is on" && echo "ok pair reminder when on" || { echo "FAIL pair reminder when on"; fail=1; } +echo paused > "$repo/.kyc/pair" +nudge | grep -q "paused for the current task" && echo "ok pair reminder when paused" || { echo "FAIL pair reminder when paused"; fail=1; } +rm "$repo/.kyc/pair" +[ -z "$(nudge)" ] && echo "ok no pair reminder when off" || { echo "FAIL no pair reminder when off"; fail=1; } exit $fail diff --git a/tests/teaching.test.sh b/tests/teaching.test.sh new file mode 100644 index 0000000..da87b7a --- /dev/null +++ b/tests/teaching.test.sh @@ -0,0 +1,27 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +cd "$ROOT" + +for file in \ + skills/know-your-code/workflows/understand-task.md \ + skills/know-your-code/workflows/explore-codebase.md \ + skills/know-your-code/workflows/implementation-planning.md \ + skills/know-your-code/workflows/learning-during-build.md \ + skills/know-your-code/workflows/verification.md \ + skills/know-your-code/workflows/knowledge-transfer.md \ + skills/know-your-code/workflows/context.md \ + skills/know-your-code/templates/implementation-blueprint.md \ + skills/know-your-code/templates/learning-report.md \ + skills/know-your-code/templates/decision-record.md +do + test -s "$file" +done + +rg -q 'passed-.*without.*user|Never create.*pass file' skills/know-your-code/SKILL.md +rg -q 'unfamiliar.*introduced.*practiced.*demonstrated' skills/know-your-code/SKILL.md skills/know-your-code/workflows/context.md +rg -q 'pair mode.*opt-in|Pair mode is opt-in' README.md AGENTS.md skills/know-your-code/pair.md +rg -q 'journal.*diff|journal is evidence' README.md skills/know-your-code/pair.md + +echo 'teaching workflow tests: ok' From d945fcc5023cb860ef82664c72779c948032edc6 Mon Sep 17 00:00:00 2001 From: MINIT Date: Tue, 3 Nov 2026 13:44:24 +0530 Subject: [PATCH 2/9] fix: use portable grep in teaching test --- tests/teaching.test.sh | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/teaching.test.sh b/tests/teaching.test.sh index da87b7a..14cf558 100644 --- a/tests/teaching.test.sh +++ b/tests/teaching.test.sh @@ -19,9 +19,9 @@ do test -s "$file" done -rg -q 'passed-.*without.*user|Never create.*pass file' skills/know-your-code/SKILL.md -rg -q 'unfamiliar.*introduced.*practiced.*demonstrated' skills/know-your-code/SKILL.md skills/know-your-code/workflows/context.md -rg -q 'pair mode.*opt-in|Pair mode is opt-in' README.md AGENTS.md skills/know-your-code/pair.md -rg -q 'journal.*diff|journal is evidence' README.md skills/know-your-code/pair.md +grep -Eq 'passed-.*without.*user|Never create.*pass file' skills/know-your-code/SKILL.md +grep -Eq 'unfamiliar.*introduced.*practiced.*demonstrated' skills/know-your-code/SKILL.md skills/know-your-code/workflows/context.md +grep -Eq 'pair mode.*opt-in|Pair mode is opt-in' README.md AGENTS.md skills/know-your-code/pair.md +grep -Eq 'journal.*diff|journal is evidence' README.md skills/know-your-code/pair.md echo 'teaching workflow tests: ok' From 57d18cfe7c1f472659e35d663160ea4eb0177894 Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:23:27 +0530 Subject: [PATCH 3/9] fix: activate teaching workflow for coding tasks --- skills/know-your-code/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/know-your-code/SKILL.md b/skills/know-your-code/SKILL.md index 35573bd..b60dfff 100644 --- a/skills/know-your-code/SKILL.md +++ b/skills/know-your-code/SKILL.md @@ -1,6 +1,6 @@ --- 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 when the know-your-code gate blocks a push, when the user runs /kyc, or when know-your-code context mentions pair mode, learning, verification 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 any non-trivial coding task, including features, bug fixes and refactors, when the know-your-code gate blocks a push, when the user runs /kyc, or when know-your-code context mentions pair mode, learning, verification or a plan. --- # know-your-code @@ -9,13 +9,13 @@ The user vibe codes freely. Before shipping, they must show they understand what ## Teaching-first workflow -For any non-trivial coding task, use the smallest applicable workflow in [workflows/](workflows/): +For any non-trivial coding task, use the smallest applicable workflow in [workflows/](workflows/). The default mode is 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**: 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). +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. From 5238123529fb571ef86ccf2350771510a99889ab Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:23:42 +0530 Subject: [PATCH 4/9] docs: clarify fallback installation and product motivation --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9df4c3e..e0d47e8 100644 --- a/README.md +++ b/README.md @@ -102,11 +102,11 @@ 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? From f64b85ff3a885917d8b3121cf85508547fca5de8 Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:24:38 +0530 Subject: [PATCH 5/9] docs: make fallback teaching guidance self-contained --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f1e4b91..b72cc5d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,10 +2,10 @@ Before you run `git push` or `gh pr create`, the user must explain what changed and why. -For coding work, 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 end with a knowledge-transfer summary. 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. +For coding work, 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 ` 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. +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 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. From 7e14c5de7660e036f8360f5a584b47d37544aee0 Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:25:42 +0530 Subject: [PATCH 6/9] test: cover nudge behavior and workflow activation From 823d35e8fb46d8201fc2828b85b732341995b0e7 Mon Sep 17 00:00:00 2001 From: MINIT Date: Thu, 5 Nov 2026 19:26:04 +0530 Subject: [PATCH 7/9] test: cover nudge behavior and workflow activation --- tests/teaching.test.sh | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/tests/teaching.test.sh b/tests/teaching.test.sh index 14cf558..d6160c2 100644 --- a/tests/teaching.test.sh +++ b/tests/teaching.test.sh @@ -24,4 +24,36 @@ grep -Eq 'unfamiliar.*introduced.*practiced.*demonstrated' skills/know-your-code grep -Eq 'pair mode.*opt-in|Pair mode is opt-in' README.md AGENTS.md skills/know-your-code/pair.md grep -Eq 'journal.*diff|journal is evidence' README.md skills/know-your-code/pair.md +grep -Eq 'Use for any non-trivial coding task' skills/know-your-code/SKILL.md +grep -Eq 'default mode is lightweight' skills/know-your-code/SKILL.md +grep -Eq 'fallback.*compact' AGENTS.md + +if command -v jq >/dev/null 2>&1; then + teaching_tmp=$(mktemp -d) + trap 'rm -rf "$teaching_tmp"' EXIT + git -C "$teaching_tmp" init -q + git -C "$teaching_tmp" config user.email test@example.com + git -C "$teaching_tmp" config user.name test + printf 'initial\n' >"$teaching_tmp/app.txt" + git -C "$teaching_tmp" add app.txt + git -C "$teaching_tmp" commit -qm initial + git -C "$teaching_tmp" branch -M main + mkdir -p "$teaching_tmp/.kyc" + printf 'on\n' >"$teaching_tmp/.kyc/pair" + + pair_output=$(printf '{"cwd":"%s"}' "$teaching_tmp" | bash "$ROOT/hooks/nudge.sh") + grep -q 'pair mode is on' <<<"$pair_output" + + rm -f "$teaching_tmp/.kyc/pair" + printf 'hard\n' >"$teaching_tmp/.kyc/level" + hard_output=$(printf '{"cwd":"%s"}' "$teaching_tmp" | bash "$ROOT/hooks/nudge.sh") + grep -q 'no plan for branch' <<<"$hard_output" + + printf 'plan\n' >"$teaching_tmp/.kyc/plan-main.md" + quiet_output=$(printf '{"cwd":"%s"}' "$teaching_tmp" | bash "$ROOT/hooks/nudge.sh") + test -z "$quiet_output" +else + echo 'jq unavailable; skipping nudge behavior checks' +fi + echo 'teaching workflow tests: ok' From 845c2f7bfddd8ab252b95e47c11f76793bf8affb Mon Sep 17 00:00:00 2001 From: Minit Jain Date: Thu, 5 Nov 2026 19:42:29 +0530 Subject: [PATCH 8/9] fix: make teach mode opt-in, cut unused state, fix CI Review of PR #3: - Teaching flow only runs after /kyc teach (.kyc/teach); default stays out of the way until the push gate, as the README promises - Drop concepts.md, decisions.md, plans/ and decision-record template: nothing read them, and decisions duplicated the journal - nudge.sh reminds while teach mode is on - teaching.test.sh: replace prose greps (the CI failure) with a check that every skill link resolves - Hand-back questions must not contain or follow with the answer - Workflow headings numbered to match SKILL.md --- AGENTS.md | 4 +- CHANGELOG.md | 5 +- README.md | 7 +- hooks/nudge.sh | 2 + skills/know-your-code/SKILL.md | 19 +++--- .../templates/decision-record.md | 8 --- .../templates/learning-report.md | 4 +- skills/know-your-code/workflows/context.md | 16 ++--- .../workflows/explore-codebase.md | 2 +- .../workflows/implementation-planning.md | 4 +- .../workflows/knowledge-transfer.md | 4 +- .../workflows/learning-during-build.md | 6 +- .../workflows/understand-task.md | 4 +- .../know-your-code/workflows/verification.md | 4 +- tests/gate.test.sh | 3 + tests/teaching.test.sh | 67 +++---------------- 16 files changed, 54 insertions(+), 105 deletions(-) delete mode 100644 skills/know-your-code/templates/decision-record.md diff --git a/AGENTS.md b/AGENTS.md index b72cc5d..760e22d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,10 +2,10 @@ Before you run `git push` or `gh pr create`, the user must explain what changed and why. -For coding work, 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. +If `.kyc/teach` contains `on` (the user ran `kyc teach`), 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 ` 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. If 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. +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 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 index a38f60e..9b6a794 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,8 +2,9 @@ ## 0.4.0 — 2026-11-03 -- Teaching-first workflow: understand the repository before coding, learn during meaningful increments, verify with evidence, and finish with knowledge transfer. -- Progressive-disclosure workflows and templates for codebase exploration, plans, verification, persistent learning context and transfer reports. +- Teach mode (`/kyc teach`, opt-in): 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 diff --git a/README.md b/README.md index e0d47e8..482cb13 100644 --- a/README.md +++ b/README.md @@ -47,9 +47,9 @@ Answer in your own words. Get it right, you ship. Get it wrong, you learn why, t Start easy. Graduate to hard. -### Teaching-first build flow +### Teach mode -The skill now teaches during the build, not only at shipping time. For a non-trivial task it 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. Local learning context lives in the ignored `.kyc/` directory: `profile.md`, `concepts.md`, `decisions.md`, and optional plans. +Off by default. Turn it on with `/kyc teach`. For a non-trivial task Claude then 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 @@ -71,7 +71,8 @@ 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 profile` | Read or update my local learning context | +| `/kyc teach` · `teach off` | Turn teach mode on or off | +| `/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) | diff --git a/hooks/nudge.sh b/hooks/nudge.sh index 86aa573..5226426 100755 --- a/hooks/nudge.sh +++ b/hooks/nudge.sh @@ -11,6 +11,8 @@ case "$(cat "$kyc/pair" 2>/dev/null)" in 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 +[ "$(cat "$kyc/teach" 2>/dev/null)" = on ] && 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 diff --git a/skills/know-your-code/SKILL.md b/skills/know-your-code/SKILL.md index b60dfff..370648b 100644 --- a/skills/know-your-code/SKILL.md +++ b/skills/know-your-code/SKILL.md @@ -1,15 +1,17 @@ --- 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 any non-trivial coding task, including features, bug fixes and refactors, when the know-your-code gate blocks a push, when the user runs /kyc, or when know-your-code context mentions pair mode, learning, verification 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 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. -## Teaching-first workflow +## Teach mode -For any non-trivial coding task, use the smallest applicable workflow in [workflows/](workflows/). The default mode is 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: +Opt-in. On only when `.kyc/teach` contains `on` (set by `kyc teach`). 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). @@ -28,15 +30,11 @@ Do not claim that the user demonstrated a concept merely because the agent expla - `log`: one line per pass/skip. - `pair`: `on` | `paused`. Pair mode, see [pair.md](pair.md). - `journal-.md`: pair-mode checkpoint journal. -- `profile.md`: user goals, preferences and evidence-backed learning notes. -- `concepts.md`: concept-level status: `unfamiliar`, `introduced`, `practiced` or `demonstrated`. -- `decisions.md`: durable decisions, alternatives, reasons and outcomes. -- `plans/`: optional task blueprints and verification notes. +- `teach`: `on` or missing. 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. -Initialize or update the context files using [context.md](workflows/context.md). Keep entries short, factual and task-specific. Never record secrets, and never upgrade a concept to `demonstrated` without evidence. - ## Quiz flow (gate blocked a push, or `/kyc`) 1. Find the diff being shipped: @@ -71,7 +69,8 @@ In Claude Code these are `/kyc ...`. In other agents the user just says "kyc eas - `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 profile` → read or update `.kyc/profile.md`, `.kyc/concepts.md` and `.kyc/decisions.md` using [context.md](workflows/context.md). +- `kyc teach` → `mkdir -p .kyc && ([ -f .kyc/.gitignore ] || echo '*' > .kyc/.gitignore) && echo on > .kyc/teach`. `kyc teach off` → `rm -f .kyc/teach`. +- `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 > .kyc/level`. Confirm in one line what that level does. - `kyc off` → ask for a one-line reason, then: ```bash diff --git a/skills/know-your-code/templates/decision-record.md b/skills/know-your-code/templates/decision-record.md deleted file mode 100644 index 9041aff..0000000 --- a/skills/know-your-code/templates/decision-record.md +++ /dev/null @@ -1,8 +0,0 @@ -## YYYY-MM-DD — task - -- Decision: -- Alternatives: -- Why: -- Counterargument: -- Outcome: -- Follow-up: diff --git a/skills/know-your-code/templates/learning-report.md b/skills/know-your-code/templates/learning-report.md index 6190a84..a069e71 100644 --- a/skills/know-your-code/templates/learning-report.md +++ b/skills/know-your-code/templates/learning-report.md @@ -6,8 +6,8 @@ ## Concepts -| Concept | Status | Evidence | Next practice | -|---|---|---|---| +| Concept | Evidence | Next practice | +|---|---|---| ## Verification diff --git a/skills/know-your-code/workflows/context.md b/skills/know-your-code/workflows/context.md index 3f0b543..3f61b66 100644 --- a/skills/know-your-code/workflows/context.md +++ b/skills/know-your-code/workflows/context.md @@ -1,12 +1,8 @@ -# Persistent learning context +# Learning profile -Create `.kyc/` and its `.gitignore` before writing context. The ignore file must contain `*`; these notes are local learning state, not project source. +`.kyc/profile.md` holds the user's goals, preferred explanation depth, and evidence-backed notes ("predicted the retry backoff correctly", "unsure about SQL joins"). Create `.kyc/` and its `.gitignore` (containing `*`) first; this is local learning state, not project source. -Use these files: - -- `profile.md`: goals, preferred explanation depth, and evidence-backed preferences. Do not infer expertise from a single correct answer. -- `concepts.md`: one row per concept with status, evidence and a next practice. Status can only move `unfamiliar → introduced → practiced → demonstrated`; it can move back when later evidence shows a gap. -- `decisions.md`: date/task, decision, alternatives considered, reason, counterargument, outcome and follow-up. Record outcomes, not just the agent's recommendation. -- `plans/.md`: optional blueprint, assumptions, affected files and verification plan. Use a safe descriptive name, not user input pasted into a shell command. - -When the user explicitly says they already know a concept, treat that as a preference to reduce explanation, not as `demonstrated` evidence. Ask for a smaller prediction or explanation instead of repeating a lesson. Never store secrets, tokens, personal data or full command output unnecessarily. +- Read it before teaching, so you skip what the user already knows and slow down where they struggled. +- Update it only from evidence: a correct prediction, a checkpoint answer, code the user wrote, or a successful explanation. One correct answer is not expertise. +- "I already know this" is a preference to explain less, not evidence. Ask for a small prediction instead of a lecture. +- Keep it short. Never store secrets, tokens, personal data or command output. diff --git a/skills/know-your-code/workflows/explore-codebase.md b/skills/know-your-code/workflows/explore-codebase.md index 3c8de07..3943206 100644 --- a/skills/know-your-code/workflows/explore-codebase.md +++ b/skills/know-your-code/workflows/explore-codebase.md @@ -1,4 +1,4 @@ -# Repository exploration +# 1b. Explore the codebase Explore in this order, stopping when the question is answered: diff --git a/skills/know-your-code/workflows/implementation-planning.md b/skills/know-your-code/workflows/implementation-planning.md index 6fb4a89..3e92a96 100644 --- a/skills/know-your-code/workflows/implementation-planning.md +++ b/skills/know-your-code/workflows/implementation-planning.md @@ -1,4 +1,4 @@ -# Lightweight implementation plan +# 2. Plan Use [templates/implementation-blueprint.md](../templates/implementation-blueprint.md) when a task spans more than one responsibility. @@ -11,4 +11,4 @@ The plan should name: - a verification command or observation for every risky increment; - the rollback or failure boundary. -The plan is a guide, not a promise to preserve a bad design. Update it when evidence changes the approach and record the decision in `.kyc/decisions.md`. +The plan is a guide, not a promise to preserve a bad design. Update it when evidence changes the approach; in pair mode the change goes in the journal. diff --git a/skills/know-your-code/workflows/knowledge-transfer.md b/skills/know-your-code/workflows/knowledge-transfer.md index 72dba6c..52cdf26 100644 --- a/skills/know-your-code/workflows/knowledge-transfer.md +++ b/skills/know-your-code/workflows/knowledge-transfer.md @@ -1,10 +1,10 @@ -# Stage D — Transfer knowledge +# 5. Transfer knowledge End non-trivial work with a short report: - what changed and the execution path it affects; - the important design decisions, alternatives and tradeoffs; -- concepts introduced or practiced, with evidence-backed statuses; +- concepts the user practiced, and the evidence (a prediction, an answer, code they wrote); - checks run and what they prove or leave unverified; - remaining risks, follow-ups and one small rebuild/explain exercise for the user. diff --git a/skills/know-your-code/workflows/learning-during-build.md b/skills/know-your-code/workflows/learning-during-build.md index 2c3d946..d158768 100644 --- a/skills/know-your-code/workflows/learning-during-build.md +++ b/skills/know-your-code/workflows/learning-during-build.md @@ -1,8 +1,8 @@ -# Stage B — Understandable Execution +# 3. Learn while building Build in coherent increments. Before each increment, tell the user what responsibility is changing, what data/control flow matters, and what will demonstrate it. Then implement the increment autonomously and show the relevant evidence. -Teach immediately before an unfamiliar concept is used, not in a long preliminary lecture. Explain only the concept's role here, its important constraint, and one nearby example. Mark it `introduced` or `practiced` in `.kyc/concepts.md` only when the evidence supports that status. +Teach immediately before an unfamiliar concept is used, not in a long preliminary lecture. Explain only the concept's role here, its important constraint, and one nearby example. Use occasional hand-backs, not constant narration: @@ -10,4 +10,6 @@ Use occasional hand-backs, not constant narration: - ask for the invariant or failure mechanism when a bug or security boundary is central; - ask the user to choose among materially different designs when the choice changes behavior, cost, or future maintenance. +When you hand back a question, stop and wait for the answer. Never put the answer in the same message, and never inside the question ("why is it 2?" gives it away; ask "what does it return?"). + Do not hand back naming, formatting, routine plumbing, or choices already established by the repository. If the user cannot answer, teach briefly, let them retry, and continue without treating uncertainty as failure. Pair mode adds explicit checkpoints and a journal; ordinary mode does not require a pause at every increment. diff --git a/skills/know-your-code/workflows/understand-task.md b/skills/know-your-code/workflows/understand-task.md index 8af63cf..80d2f2f 100644 --- a/skills/know-your-code/workflows/understand-task.md +++ b/skills/know-your-code/workflows/understand-task.md @@ -1,11 +1,11 @@ -# Stage A — Understand before coding +# 1. Understand before coding Use this for a feature, bug fix, refactor or unfamiliar integration. Skip or compress it for a typo, formatting-only change or an explicitly scoped one-line edit. 1. Restate the requested outcome and the observable acceptance condition. 2. Inspect the repository shape, relevant instructions, current branch/status and existing tests before proposing files. 3. Trace the current behavior from entry point to side effect. Name the files and symbols that own each responsibility. -4. Identify dependencies, integration points, security/reliability concerns and at least one unfamiliar concept. Check the local context files before teaching something already practiced. +4. Identify dependencies, integration points, security/reliability concerns and at least one unfamiliar concept. Check `.kyc/profile.md` before teaching something the user already knows. 5. State assumptions and alternatives. If an assumption could change the design, ask the user; otherwise label it and proceed. 6. Give a short blueprint: files to change, data/control flow, smallest increments and how each increment will be checked. diff --git a/skills/know-your-code/workflows/verification.md b/skills/know-your-code/workflows/verification.md index 1298617..55382c0 100644 --- a/skills/know-your-code/workflows/verification.md +++ b/skills/know-your-code/workflows/verification.md @@ -1,4 +1,4 @@ -# Stage C — Verify and debug +# 4. Verify and debug For each meaningful increment: @@ -8,4 +8,4 @@ For each meaningful increment: 4. If it fails, show the symptom and ask for the user's first hypothesis in pair mode; otherwise briefly explain the likely cause and investigate before changing code. 5. Add or update a regression check when the behavior is durable. Finish with the full appropriate suite and inspect the diff. -Never call a green command proof of behavior it does not exercise. Record meaningful predictions and outcomes in the pair journal or `.kyc/decisions.md`. +Never call a green command proof of behavior it does not exercise. In pair mode, record predictions and outcomes in the journal. diff --git a/tests/gate.test.sh b/tests/gate.test.sh index 3061f7d..ddd43a9 100755 --- a/tests/gate.test.sh +++ b/tests/gate.test.sh @@ -73,6 +73,9 @@ nudge | grep -q "pair mode is on" && echo "ok pair reminder when on" || { echo echo paused > "$repo/.kyc/pair" nudge | grep -q "paused for the current task" && echo "ok pair reminder when paused" || { echo "FAIL pair reminder when paused"; fail=1; } rm "$repo/.kyc/pair" +echo on > "$repo/.kyc/teach" +nudge | grep -q "teach mode is on" && echo "ok teach reminder when on" || { echo "FAIL teach reminder when on"; fail=1; } +rm "$repo/.kyc/teach" [ -z "$(nudge)" ] && echo "ok no pair reminder when off" || { echo "FAIL no pair reminder when off"; fail=1; } exit $fail diff --git a/tests/teaching.test.sh b/tests/teaching.test.sh index d6160c2..9a11d79 100644 --- a/tests/teaching.test.sh +++ b/tests/teaching.test.sh @@ -1,59 +1,12 @@ #!/usr/bin/env bash -set -euo pipefail - -ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) -cd "$ROOT" - -for file in \ - skills/know-your-code/workflows/understand-task.md \ - skills/know-your-code/workflows/explore-codebase.md \ - skills/know-your-code/workflows/implementation-planning.md \ - skills/know-your-code/workflows/learning-during-build.md \ - skills/know-your-code/workflows/verification.md \ - skills/know-your-code/workflows/knowledge-transfer.md \ - skills/know-your-code/workflows/context.md \ - skills/know-your-code/templates/implementation-blueprint.md \ - skills/know-your-code/templates/learning-report.md \ - skills/know-your-code/templates/decision-record.md -do - test -s "$file" +# Every relative .md link inside the skill and AGENTS.md must point at a file that exists. +cd "$(dirname "$0")/.." || exit 1 +fail=0 +for f in AGENTS.md skills/know-your-code/*.md skills/know-your-code/*/*.md; do + dir=$(dirname "$f") + while read -r link; do + [ -e "$dir/$link" ] || { echo "FAIL $f -> $link"; fail=1; } + done < <(grep -oE '\]\([^)#:]+\)' "$f" | sed -E 's/^\]\(//; s/\)$//') done - -grep -Eq 'passed-.*without.*user|Never create.*pass file' skills/know-your-code/SKILL.md -grep -Eq 'unfamiliar.*introduced.*practiced.*demonstrated' skills/know-your-code/SKILL.md skills/know-your-code/workflows/context.md -grep -Eq 'pair mode.*opt-in|Pair mode is opt-in' README.md AGENTS.md skills/know-your-code/pair.md -grep -Eq 'journal.*diff|journal is evidence' README.md skills/know-your-code/pair.md - -grep -Eq 'Use for any non-trivial coding task' skills/know-your-code/SKILL.md -grep -Eq 'default mode is lightweight' skills/know-your-code/SKILL.md -grep -Eq 'fallback.*compact' AGENTS.md - -if command -v jq >/dev/null 2>&1; then - teaching_tmp=$(mktemp -d) - trap 'rm -rf "$teaching_tmp"' EXIT - git -C "$teaching_tmp" init -q - git -C "$teaching_tmp" config user.email test@example.com - git -C "$teaching_tmp" config user.name test - printf 'initial\n' >"$teaching_tmp/app.txt" - git -C "$teaching_tmp" add app.txt - git -C "$teaching_tmp" commit -qm initial - git -C "$teaching_tmp" branch -M main - mkdir -p "$teaching_tmp/.kyc" - printf 'on\n' >"$teaching_tmp/.kyc/pair" - - pair_output=$(printf '{"cwd":"%s"}' "$teaching_tmp" | bash "$ROOT/hooks/nudge.sh") - grep -q 'pair mode is on' <<<"$pair_output" - - rm -f "$teaching_tmp/.kyc/pair" - printf 'hard\n' >"$teaching_tmp/.kyc/level" - hard_output=$(printf '{"cwd":"%s"}' "$teaching_tmp" | bash "$ROOT/hooks/nudge.sh") - grep -q 'no plan for branch' <<<"$hard_output" - - printf 'plan\n' >"$teaching_tmp/.kyc/plan-main.md" - quiet_output=$(printf '{"cwd":"%s"}' "$teaching_tmp" | bash "$ROOT/hooks/nudge.sh") - test -z "$quiet_output" -else - echo 'jq unavailable; skipping nudge behavior checks' -fi - -echo 'teaching workflow tests: ok' +[ $fail = 0 ] && echo "ok all skill links resolve" +exit $fail From 9d46f951d5db8c590c08be1e8422eb4b14fd467f Mon Sep 17 00:00:00 2001 From: Minit Jain Date: Thu, 5 Nov 2026 20:27:08 +0530 Subject: [PATCH 9/9] feat: teach mode on by default; apply CodeRabbit review - Teach mode is on unless .kyc/teach says off (/kyc teach off); pair mode stays opt-in - Skill description triggers on non-trivial coding tasks so the workflow actually loads (CodeRabbit) - README support table: split teach workflow from hook reminders, Cursor/others get the workflow via AGENTS.md + skill folder (CodeRabbit) - Tests: commit.gpgsign=false on temp commits so global signing can't break them (CodeRabbit); teach-on-by-default test --- AGENTS.md | 4 ++-- CHANGELOG.md | 2 +- README.md | 10 +++++----- hooks/nudge.sh | 2 +- skills/know-your-code/SKILL.md | 8 ++++---- tests/gate.test.sh | 11 +++++------ 6 files changed, 18 insertions(+), 19 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 760e22d..a1d91da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,10 +2,10 @@ Before you run `git push` or `gh pr create`, the user must explain what changed and why. -If `.kyc/teach` contains `on` (the user ran `kyc teach`), 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. +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 ` 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. If teach mode is on 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. +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 index 9b6a794..67bbde1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## 0.4.0 — 2026-11-03 -- Teach mode (`/kyc teach`, opt-in): understand the repository before coding, learn during meaningful increments, verify with evidence, finish with knowledge transfer. +- 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. diff --git a/README.md b/README.md index 482cb13..0371e06 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ Start easy. Graduate to hard. ### Teach mode -Off by default. Turn it on with `/kyc teach`. For a non-trivial task Claude then 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 @@ -71,7 +71,7 @@ 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` · `teach off` | Turn teach mode on or off | +| `/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 | @@ -81,12 +81,12 @@ In Claude Code these are slash commands. In other agents, just say them ("kyc ha 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 | Teaching workflow / reminder | 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** diff --git a/hooks/nudge.sh b/hooks/nudge.sh index 5226426..2c19322 100755 --- a/hooks/nudge.sh +++ b/hooks/nudge.sh @@ -11,7 +11,7 @@ case "$(cat "$kyc/pair" 2>/dev/null)" in 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 -[ "$(cat "$kyc/teach" 2>/dev/null)" = on ] && 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." +[ "$(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." diff --git a/skills/know-your-code/SKILL.md b/skills/know-your-code/SKILL.md index 370648b..713fc23 100644 --- a/skills/know-your-code/SKILL.md +++ b/skills/know-your-code/SKILL.md @@ -1,6 +1,6 @@ --- 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 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 /kyc, or when know-your-code context mentions teach mode, pair mode or a plan. --- # know-your-code @@ -9,7 +9,7 @@ The user vibe codes freely. Before shipping, they must show they understand what ## Teach mode -Opt-in. On only when `.kyc/teach` contains `on` (set by `kyc teach`). When it is off, build normally and stay out of the way until the push gate. +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: @@ -30,7 +30,7 @@ Do not claim that the user demonstrated a concept merely because the agent expla - `log`: one line per pass/skip. - `pair`: `on` | `paused`. Pair mode, see [pair.md](pair.md). - `journal-.md`: pair-mode checkpoint journal. -- `teach`: `on` or missing. Teach mode. +- `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. @@ -69,7 +69,7 @@ In Claude Code these are `/kyc ...`. In other agents the user just says "kyc eas - `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` → `mkdir -p .kyc && ([ -f .kyc/.gitignore ] || echo '*' > .kyc/.gitignore) && echo on > .kyc/teach`. `kyc teach off` → `rm -f .kyc/teach`. +- `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 > .kyc/level`. Confirm in one line what that level does. - `kyc off` → ask for a one-line reason, then: diff --git a/tests/gate.test.sh b/tests/gate.test.sh index ddd43a9..740a28c 100755 --- a/tests/gate.test.sh +++ b/tests/gate.test.sh @@ -6,7 +6,7 @@ fail=0 repo=$(mktemp -d) trap 'rm -rf "$repo"' EXIT git -C "$repo" init -q -git -C "$repo" -c user.name=t -c user.email=t@t commit -q --allow-empty -m init +git -C "$repo" -c user.name=t -c user.email=t@t -c commit.gpgsign=false commit -q --allow-empty -m init head() { git -C "$repo" rev-parse HEAD; } run() { # run -> exit code of gate @@ -43,7 +43,7 @@ grep -q 'mkdir -p ".*" && touch ".*passed-' <<<"$msg" && echo "ok block guidan mkdir -p "$repo/.kyc" && touch "$repo/.kyc/passed-$(head)" expect 0 "$repo" "git push" "passed HEAD allowed" -git -C "$repo" -c user.name=t -c user.email=t@t commit -q --allow-empty -m next +git -C "$repo" -c user.name=t -c user.email=t@t -c commit.gpgsign=false commit -q --allow-empty -m next expect 2 "$repo" "git push" "new commit needs new pass" touch "$repo/.kyc/skip-$(head)" @@ -52,7 +52,7 @@ 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 +git -C "$repo" -c user.name=t -c user.email=t@t -c commit.gpgsign=false 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=$? @@ -63,6 +63,8 @@ out=$(jq -n --arg d "$repo" '{hook_event_name:"beforeShellExecution",command:"ls # nudge.sh: hard-level plan reminder + pair-mode reminder hp="$(dirname "$gate")/nudge.sh" nudge() { jq -n --arg d "$repo" '{prompt:"add login",cwd:$d}' | bash "$hp"; } +nudge | grep -q "teach mode is on" && echo "ok teach reminder by default" || { echo "FAIL teach reminder by default"; fail=1; } +echo off > "$repo/.kyc/teach" [ -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; } @@ -73,9 +75,6 @@ nudge | grep -q "pair mode is on" && echo "ok pair reminder when on" || { echo echo paused > "$repo/.kyc/pair" nudge | grep -q "paused for the current task" && echo "ok pair reminder when paused" || { echo "FAIL pair reminder when paused"; fail=1; } rm "$repo/.kyc/pair" -echo on > "$repo/.kyc/teach" -nudge | grep -q "teach mode is on" && echo "ok teach reminder when on" || { echo "FAIL teach reminder when on"; fail=1; } -rm "$repo/.kyc/teach" [ -z "$(nudge)" ] && echo "ok no pair reminder when off" || { echo "FAIL no pair reminder when off"; fail=1; } exit $fail