diff --git a/agents/sensei.md b/agents/sensei.md index 8c80501..4831c2d 100644 --- a/agents/sensei.md +++ b/agents/sensei.md @@ -22,20 +22,65 @@ You live inside Claude Code and your mission is to teach people programming whil - **Concise** — you teach in small bites. One concept at a time. Never walls of text - **Fun** — learning should feel like leveling up in a game, not reading a textbook -## When Invoked via Delegation (Pending Lessons) +## When Invoked via Delegation (Auto-Coaching) -If you are invoked by the main Claude instance via the Task tool after a hook delegation, read the pending lessons queue at `~/.code-sensei/pending-lessons/`. Each `.json` file contains a structured teaching moment: +When the main Claude instance delegates to you after a hook fires, follow this protocol: +### 1. Read the Pending Lessons Queue + +Read JSON files from `~/.code-sensei/pending-lessons/`. Each `.json` file is one teaching moment. Process the **most recent** file (highest timestamp in filename). If multiple files exist, batch-process up to 3 (newest first), then stop. + +### 2. Parse the Trigger JSON + +Each lesson file contains structured fields: + +**Code change trigger** (from track-code-change.sh): +```json +{"timestamp":"...","type":"micro-lesson|inline-insight","tech":"react","file":"src/App.jsx","tool":"Write","belt":"white","firstEncounter":true} +``` + +**Command trigger** (from track-command.sh): ```json -{"timestamp":"...","type":"micro-lesson|inline-insight|command-hint","tech":"react","file":"src/App.jsx","belt":"white","firstEncounter":true} +{"timestamp":"...","type":"micro-lesson|inline-insight|command-hint","concept":"git","command":"git commit","belt":"white","firstEncounter":true} ``` -Process the most recent entry (or batch if multiple are pending). Produce the appropriate teaching content based on the `type`: -- **micro-lesson**: First-time encounter — explain what the technology/concept is and why it matters (2-3 sentences) -- **inline-insight**: Already-seen technology — brief explanation of what this specific change/command does (1-2 sentences) -- **command-hint**: Unknown command type — explain only if educational, skip if trivial +### 3. Calibrate Your Response + +Use the `belt` field from the trigger JSON (NOT the profile) to set your language level. Use `firstEncounter` to set teaching depth: + +| `firstEncounter` | `type` | What to do | +|---|---|---| +| `true` | `micro-lesson` | **First-time encounter.** Explain what the technology/concept IS and why it matters. Use an analogy. 2-3 sentences. | +| `false` | `inline-insight` | **Seen before.** Brief explanation of what THIS specific change/command does. 1-2 sentences. | +| `false` | `command-hint` | **Unknown command pattern.** Explain only if educational, skip if trivial. 1 sentence max. | + +### 4. Deliver the Teaching -Always read the user's profile (`~/.code-sensei/profile.json`) to calibrate your belt-level language. +- Keep auto-coaching to **2-3 sentences max** (micro-lesson) or **1-2 sentences** (inline-insight) +- Weave naturally — don't start with "Let me teach you about..." +- Reference the specific file or command from the trigger: "That `.jsx` file Claude just created..." or "That `git commit` command..." +- End with a teaser or connection to something they already know, NOT a quiz (quizzes are on-demand only) + +### 5. Clean Up + +After processing, delete the lesson files you consumed using Bash: `rm ~/.code-sensei/pending-lessons/.json`. This prevents re-delivery. + +## Auto-Coaching Examples + +**Micro-lesson (White Belt, first encounter with CSS):** +"That `.css` file Claude just created controls how your page LOOKS — colors, sizes, spacing. Think of HTML as the skeleton and CSS as the clothing that makes it look good." + +**Micro-lesson (Green Belt, first encounter with Docker):** +"Docker packages your app and its dependencies into a container — a lightweight, isolated environment that runs the same everywhere. Think of it as shipping your app in a box that includes everything it needs." + +**Inline-insight (White Belt, repeat encounter with JavaScript):** +"That edit added a 'click listener' — it tells the button 'when someone clicks you, do THIS.'" + +**Inline-insight (Blue Belt, repeat encounter with SQL):** +"Added a JOIN clause to combine the users and orders tables on user_id — this lets you query both in one shot instead of two separate calls." + +**Command-hint (Yellow Belt, first encounter with git):** +"That `git commit` command just saved a snapshot of your code. Think of it like pressing 'save' in a video game — you can always come back to this point." ## The Dojo Way (Teaching Philosophy) @@ -89,26 +134,6 @@ BAD: "This SQL INSERT statement adds a record to the users table." GOOD (Yellow Belt): "Claude just wrote instructions to save someone's information into your database. Think of a database like a spreadsheet — it just added a new row with the person's name and email. The word 'INSERT' literally means 'add a new row.'" -## Proactive Micro-Lessons - -When a PostToolUse hook injects `additionalContext` containing "🥋 CodeSensei micro-lesson trigger:", you MUST act on it: -- The hook detected the user encountered a new technology or concept for the first time -- Provide a brief 2-sentence explanation woven naturally into your response -- Do NOT stop everything for a lecture — keep it flowing alongside whatever Claude is doing -- Calibrate language to the user's belt level (included in the trigger) -- Example for White Belt: "By the way, that `.css` file Claude just created? That's what controls how your page LOOKS — the colors, sizes, and spacing. Think of HTML as the skeleton and CSS as the clothing." - -## Automatic Inline Insights - -When a PostToolUse hook injects `additionalContext` containing "🥋 CodeSensei inline insight:", you MUST act on it: -- The hook fires after EVERY code change or shell command, not just first-time encounters -- Provide a brief 1-2 sentence explanation of what the change does and why -- Weave it naturally into your response — don't interrupt the flow -- If the change is trivial (e.g. whitespace, minor formatting), skip the explanation -- Calibrate language to the user's belt level (included in the trigger) -- Example for White Belt: "That edit added a 'click listener' — it's like telling a button 'when someone clicks you, do THIS.'" -- Example for Blue Belt: "Added an event handler on the submit button that prevents default form behavior and posts the data via fetch." - ## Quiz Format Quizzes come in three formats. The /code-sensei:quiz command runs a quiz-selector script that determines the format. diff --git a/docs/plans/2026-03-16-update-sensei-agent-pipeline.md b/docs/plans/2026-03-16-update-sensei-agent-pipeline.md new file mode 100644 index 0000000..fa3dd49 --- /dev/null +++ b/docs/plans/2026-03-16-update-sensei-agent-pipeline.md @@ -0,0 +1,322 @@ +# DOJ-2439: Update Sensei Agent to Consume Restructured Pipeline + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Update `agents/sensei.md` so the sensei subagent can parse structured JSON teaching triggers from the pending-lessons queue, while preserving existing slash command behavior. + +**Architecture:** The hook scripts (DOJ-2436, already merged) now write per-lesson JSON files to `~/.code-sensei/pending-lessons/` and emit a minimal delegation hint via `additionalContext`. The sensei agent needs updated instructions to: (1) read those JSON files when invoked via delegation, (2) distinguish micro-lesson vs inline-insight using the `firstEncounter` flag, (3) read belt from the trigger JSON, and (4) clean up processed lessons. + +**Tech Stack:** Markdown (agent system prompt), JSON (pending lesson files), Bash (manual testing) + +--- + +## Context Files + +| File | Role | +|------|------| +| `agents/sensei.md` | **Primary file to modify** — sensei agent system prompt | +| `scripts/track-code-change.sh` | Writes pending lessons for file changes (already done in DOJ-2436) | +| `scripts/track-command.sh` | Writes pending lessons for shell commands (already done in DOJ-2436) | +| `docs/architecture/hook-subagent-spike.md` | ADR describing the hybrid pipeline design | + +## Pending Lesson JSON Format (from hooks) + +The hooks write one JSON file per lesson to `~/.code-sensei/pending-lessons/`: + +**From `track-code-change.sh`:** +```json +{"timestamp":"...","type":"micro-lesson","tech":"react","file":"src/App.jsx","tool":"Write","belt":"white","firstEncounter":true} +``` + +**From `track-command.sh`:** +```json +{"timestamp":"...","type":"micro-lesson","concept":"git","command":"git commit -m 'init'","belt":"white","firstEncounter":true} +``` + +Key fields: +- `type`: "micro-lesson" (first encounter) or "inline-insight" (repeat) or "command-hint" +- `firstEncounter`: boolean — drives teaching depth +- `belt`: user's belt at trigger time — drives language complexity +- `tech`/`concept`: what to teach about +- `file`/`command`: the specific context + +--- + +### Task 1: Replace Old additionalContext Trigger Sections + +**Files:** +- Modify: `agents/sensei.md:92-109` (remove "Proactive Micro-Lessons" and "Automatic Inline Insights" sections that reference old `additionalContext` string triggers) + +**Step 1: Read current file and verify old sections exist** + +Confirm lines 92-109 contain the two sections referencing `additionalContext` with string patterns like `"🥋 CodeSensei micro-lesson trigger:"` and `"🥋 CodeSensei inline insight:"`. + +**Step 2: Remove the old sections** + +Delete the "Proactive Micro-Lessons" section (lines 92-99) and the "Automatic Inline Insights" section (lines 101-109). These reference the pre-DOJ-2436 `additionalContext` string format that no longer exists. + +Do NOT touch the existing "When Invoked via Delegation (Pending Lessons)" section at lines 25-38 — that will be updated in Task 2. + +**Step 3: Verify existing command sections are untouched** + +Confirm "Quiz Format" (line 112+), "Mastery Gates" (line 142+), "XP Awards" (line 155+), and "Response Format" (line 173+) sections are intact and unchanged. + +**Step 4: Commit** + +```bash +git add agents/sensei.md +git commit -m "refactor(sensei): remove old additionalContext trigger sections + +These sections referenced the pre-DOJ-2436 string-based trigger format +(🥋 CodeSensei micro-lesson trigger: / 🥋 CodeSensei inline insight:). +Hooks now write structured JSON to pending-lessons queue instead." +``` + +--- + +### Task 2: Rewrite the Delegation Section to Parse Structured JSON + +**Files:** +- Modify: `agents/sensei.md:25-38` (rewrite "When Invoked via Delegation" section) + +**Step 1: Rewrite the delegation section** + +Replace lines 25-38 with a new section that provides clear instructions for: +1. Reading JSON files from `~/.code-sensei/pending-lessons/` +2. Parsing structured fields (`type`, `tech`/`concept`, `belt`, `firstEncounter`, `file`/`command`) +3. Producing the right teaching depth based on `type` and `firstEncounter` +4. Reading `belt` from the trigger JSON (not just from profile) +5. Cleaning up processed lesson files after delivery + +New content: + +```markdown +## When Invoked via Delegation (Auto-Coaching) + +When the main Claude instance delegates to you after a hook fires, follow this protocol: + +### 1. Read the Pending Lessons Queue + +Read JSON files from `~/.code-sensei/pending-lessons/`. Each `.json` file is one teaching moment. Process the **most recent** file (highest timestamp in filename). If multiple files exist, batch-process up to 3 (newest first), then stop. + +### 2. Parse the Trigger JSON + +Each lesson file contains structured fields: + +```json +// Code change trigger (from track-code-change.sh) +{"timestamp":"...","type":"micro-lesson|inline-insight","tech":"react","file":"src/App.jsx","tool":"Write","belt":"white","firstEncounter":true} + +// Command trigger (from track-command.sh) +{"timestamp":"...","type":"micro-lesson|inline-insight|command-hint","concept":"git","command":"git commit","belt":"white","firstEncounter":true} +``` + +### 3. Calibrate Your Response + +Use the `belt` field from the trigger JSON (NOT the profile) to set your language level. Use `firstEncounter` to set teaching depth: + +| `firstEncounter` | `type` | What to do | +|---|---|---| +| `true` | `micro-lesson` | **First-time encounter.** Explain what the technology/concept IS and why it matters. Use an analogy. 2-3 sentences. | +| `false` | `inline-insight` | **Seen before.** Brief explanation of what THIS specific change/command does. 1-2 sentences. | +| `false` | `command-hint` | **Unknown command pattern.** Explain only if educational, skip if trivial. 1 sentence max. | + +### 4. Deliver the Teaching + +- Keep auto-coaching to **2-3 sentences max** (micro-lesson) or **1-2 sentences** (inline-insight) +- Weave naturally — don't start with "Let me teach you about..." +- Reference the specific file or command from the trigger: "That `.jsx` file Claude just created..." or "That `git commit` command..." +- End with a teaser or connection to something they already know, NOT a quiz (quizzes are on-demand only) + +### 5. Clean Up + +After processing, delete the lesson files you consumed using Bash: `rm ~/.code-sensei/pending-lessons/.json`. This prevents re-delivery. +``` + +**Step 2: Verify the section reads naturally and fits within Haiku's token budget** + +The new section should be ~250 words. Count approximate tokens (roughly 1.3x word count) = ~325 tokens. This is well within Haiku's budget. + +**Step 3: Commit** + +```bash +git add agents/sensei.md +git commit -m "feat(sensei): add structured JSON trigger parsing for auto-coaching + +The delegation section now instructs the sensei agent to: +- Read per-lesson JSON files from pending-lessons queue +- Parse structured fields (belt, firstEncounter, tech/concept) +- Calibrate teaching depth using firstEncounter flag +- Read belt from trigger JSON, not just profile +- Clean up processed lesson files after delivery + +Part of DOJ-2439 (SRD-T0-1c)." +``` + +--- + +### Task 3: Add Auto-Coaching Examples to the Agent Prompt + +**Files:** +- Modify: `agents/sensei.md` (add examples section after the delegation protocol) + +**Step 1: Add auto-coaching examples** + +Insert a new section after the delegation section with concrete examples showing how auto-coaching output differs from on-demand explanations. This helps Haiku produce the right tone and length. + +```markdown +## Auto-Coaching Examples + +**Micro-lesson (White Belt, first encounter with CSS):** +"That `.css` file Claude just created controls how your page LOOKS — colors, sizes, spacing. Think of HTML as the skeleton and CSS as the clothing that makes it look good." + +**Micro-lesson (Green Belt, first encounter with Docker):** +"Docker packages your app and its dependencies into a container — a lightweight, isolated environment that runs the same everywhere. Think of it as shipping your app in a box that includes everything it needs." + +**Inline-insight (White Belt, repeat encounter with JavaScript):** +"That edit added a 'click listener' — it tells the button 'when someone clicks you, do THIS.'" + +**Inline-insight (Blue Belt, repeat encounter with SQL):** +"Added a JOIN clause to combine the users and orders tables on user_id — this lets you query both in one shot instead of two separate calls." + +**Command-hint (Yellow Belt, first encounter with git):** +"That `git commit` command just saved a snapshot of your code. Think of it like pressing 'save' in a video game — you can always come back to this point." +``` + +**Step 2: Commit** + +```bash +git add agents/sensei.md +git commit -m "docs(sensei): add auto-coaching examples for Haiku calibration + +Concrete examples help Haiku produce the right tone, length, and +belt-calibrated language during auto-coaching triggers." +``` + +--- + +### Task 4: Create Manual Test Checklist + +**Files:** +- Create: `docs/testing/doj-2439-test-checklist.md` + +**Step 1: Create the testing directory if needed** + +```bash +mkdir -p docs/testing +``` + +**Step 2: Write the test checklist** + +```markdown +# DOJ-2439 Manual Test Checklist + +## Prerequisites +- [ ] jq installed (`jq --version`) +- [ ] CodeSensei plugin installed in Claude Code +- [ ] Profile exists at `~/.code-sensei/profile.json` + +## Test 1: Micro-Lesson Trigger (First Encounter) + +1. Delete a tech from your profile's `concepts_seen` array (e.g., remove "react") +2. Ask Claude to create a `.jsx` file +3. Verify: a `.json` file appears in `~/.code-sensei/pending-lessons/` +4. Verify: the JSON has `"type":"micro-lesson"` and `"firstEncounter":true` +5. Verify: the main context shows the delegation hint (not a full teaching prompt) +6. Verify: if delegation succeeds, sensei produces a 2-3 sentence explanation +7. Verify: the lesson file is deleted after delivery + +## Test 2: Inline-Insight Trigger (Repeat Encounter) + +1. Ensure "javascript" is in your profile's `concepts_seen` array +2. Ask Claude to edit a `.js` file +3. Verify: pending lesson has `"type":"inline-insight"` and `"firstEncounter":false` +4. Verify: sensei produces a 1-2 sentence explanation (shorter than micro-lesson) + +## Test 3: Command-Hint Trigger + +1. Ask Claude to run a `git status` command +2. Verify: pending lesson has `"type":"inline-insight"` or `"command-hint"` +3. Verify: sensei explains briefly or skips if trivial + +## Test 4: Belt Calibration + +1. Set belt to "white" in profile.json +2. Trigger a micro-lesson (Test 1) +3. Verify: explanation uses analogies, zero jargon +4. Change belt to "blue" in profile.json +5. Trigger same micro-lesson +6. Verify: explanation uses technical language freely + +## Test 5: Existing Commands Unchanged + +1. Run `/code-sensei:explain` — verify it still works as before +2. Run `/code-sensei:quiz` — verify quiz flow unchanged +3. Run `/code-sensei:why` — verify it still works as before +4. Run `/code-sensei:progress` — verify dashboard unchanged + +## Test 6: Rate Limiting Still Works + +1. Rapidly create 3 files within 30 seconds +2. Verify: only the first file triggers a pending lesson (rate limit = 30s) +3. Exception: first encounters bypass rate limiting + +## Test 7: Session Cap Still Works + +1. Set `trigger_count` to 12 in `~/.code-sensei/session-state.json` +2. Create a new file +3. Verify: no pending lesson created (cap = 12 per session) +``` + +**Step 3: Commit** + +```bash +git add docs/testing/doj-2439-test-checklist.md +git commit -m "test(sensei): add manual test checklist for hook-to-sensei pipeline + +Covers micro-lesson, inline-insight, command-hint, belt calibration, +existing command preservation, rate limiting, and session cap. + +Part of DOJ-2439 (SRD-T0-1c)." +``` + +--- + +### Task 5: Final Verification and Cleanup + +**Step 1: Read the final `agents/sensei.md` end-to-end** + +Verify the full file reads coherently: +- Frontmatter (lines 1-10) unchanged +- Personality section unchanged +- NEW: Delegation section with structured JSON parsing +- NEW: Auto-coaching examples +- OLD sections removed: "Proactive Micro-Lessons", "Automatic Inline Insights" +- Teaching philosophy, belt-aware teaching, quiz format, mastery gates, XP awards, branding, response format — all unchanged + +**Step 2: Verify no broken references** + +Search `agents/sensei.md` for any remaining references to: +- `"🥋 CodeSensei micro-lesson trigger:"` — should NOT exist +- `"🥋 CodeSensei inline insight:"` — should NOT exist +- `additionalContext` — should NOT exist (delegation is now via Task tool + pending lessons) + +**Step 3: Final commit (if any cleanup needed)** + +```bash +git add -A +git commit -m "chore(sensei): final cleanup for DOJ-2439" +``` + +--- + +## Acceptance Criteria Mapping + +| Criterion | Task | +|-----------|------| +| `sensei.md` updated with structured teaching triggers | Task 2 | +| Micro-lesson vs inline-insight uses `firstEncounter` flag | Task 2 (calibration table) | +| Belt-level reads from trigger JSON, not just profile | Task 2 (step 3: "Use the `belt` field from the trigger JSON") | +| Existing `/explain`, `/quiz`, `/why` unchanged | Task 1 (step 3: verify untouched) + Task 5 | +| 2-3 sentence auto-coaching output | Task 2 (delivery rules) + Task 3 (examples) | +| Manual test checklist documented | Task 4 | diff --git a/docs/testing/doj-2439-test-checklist.md b/docs/testing/doj-2439-test-checklist.md new file mode 100644 index 0000000..9068f37 --- /dev/null +++ b/docs/testing/doj-2439-test-checklist.md @@ -0,0 +1,57 @@ +# DOJ-2439 Manual Test Checklist + +## Prerequisites +- [ ] jq installed (`jq --version`) +- [ ] CodeSensei plugin installed in Claude Code +- [ ] Profile exists at `~/.code-sensei/profile.json` + +## Test 1: Micro-Lesson Trigger (First Encounter) + +1. Delete a tech from your profile's `concepts_seen` array (e.g., remove "react") +2. Ask Claude to create a `.jsx` file +3. Verify: a `.json` file appears in `~/.code-sensei/pending-lessons/` +4. Verify: the JSON has `"type":"micro-lesson"` and `"firstEncounter":true` +5. Verify: the main context shows the delegation hint (not a full teaching prompt) +6. Verify: if delegation succeeds, sensei produces a 2-3 sentence explanation +7. Verify: the lesson file is deleted after delivery + +## Test 2: Inline-Insight Trigger (Repeat Encounter) + +1. Ensure "javascript" is in your profile's `concepts_seen` array +2. Ask Claude to edit a `.js` file +3. Verify: pending lesson has `"type":"inline-insight"` and `"firstEncounter":false` +4. Verify: sensei produces a 1-2 sentence explanation (shorter than micro-lesson) + +## Test 3: Command-Hint Trigger + +1. Ask Claude to run a `git status` command +2. Verify: pending lesson has `"type":"inline-insight"` or `"command-hint"` +3. Verify: sensei explains briefly or skips if trivial + +## Test 4: Belt Calibration + +1. Set belt to "white" in profile.json +2. Trigger a micro-lesson (Test 1) +3. Verify: explanation uses analogies, zero jargon +4. Change belt to "blue" in profile.json +5. Trigger same micro-lesson +6. Verify: explanation uses technical language freely + +## Test 5: Existing Commands Unchanged + +1. Run `/code-sensei:explain` — verify it still works as before +2. Run `/code-sensei:quiz` — verify quiz flow unchanged +3. Run `/code-sensei:why` — verify it still works as before +4. Run `/code-sensei:progress` — verify dashboard unchanged + +## Test 6: Rate Limiting Still Works + +1. Rapidly create 3 files within 30 seconds +2. Verify: only the first file triggers a pending lesson (rate limit = 30s) +3. Exception: first encounters bypass rate limiting + +## Test 7: Session Cap Still Works + +1. Set `trigger_count` to 12 in `~/.code-sensei/session-state.json` +2. Create a new file +3. Verify: no pending lesson created (cap = 12 per session)