Skip to content

Commit 4bd6170

Browse files
dbejarano820claude
dbejarano820
and
claude
committed
docs: add implementation plan for DOJ-2439
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent af60e4b commit 4bd6170

File tree

1 file changed

+322
-0
lines changed

1 file changed

+322
-0
lines changed

‎docs/plans/2026-03-16-update-sensei-agent-pipeline.md‎

Lines changed: 322 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,322 @@
1+
# DOJ-2439: Update Sensei Agent to Consume Restructured Pipeline
2+
3+
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
4+
5+
**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.
6+
7+
**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.
8+
9+
**Tech Stack:** Markdown (agent system prompt), JSON (pending lesson files), Bash (manual testing)
10+
11+
---
12+
13+
## Context Files
14+
15+
| File | Role |
16+
|------|------|
17+
| `agents/sensei.md` | **Primary file to modify** — sensei agent system prompt |
18+
| `scripts/track-code-change.sh` | Writes pending lessons for file changes (already done in DOJ-2436) |
19+
| `scripts/track-command.sh` | Writes pending lessons for shell commands (already done in DOJ-2436) |
20+
| `docs/architecture/hook-subagent-spike.md` | ADR describing the hybrid pipeline design |
21+
22+
## Pending Lesson JSON Format (from hooks)
23+
24+
The hooks write one JSON file per lesson to `~/.code-sensei/pending-lessons/`:
25+
26+
**From `track-code-change.sh`:**
27+
```json
28+
{"timestamp":"...","type":"micro-lesson","tech":"react","file":"src/App.jsx","tool":"Write","belt":"white","firstEncounter":true}
29+
```
30+
31+
**From `track-command.sh`:**
32+
```json
33+
{"timestamp":"...","type":"micro-lesson","concept":"git","command":"git commit -m 'init'","belt":"white","firstEncounter":true}
34+
```
35+
36+
Key fields:
37+
- `type`: "micro-lesson" (first encounter) or "inline-insight" (repeat) or "command-hint"
38+
- `firstEncounter`: boolean — drives teaching depth
39+
- `belt`: user's belt at trigger time — drives language complexity
40+
- `tech`/`concept`: what to teach about
41+
- `file`/`command`: the specific context
42+
43+
---
44+
45+
### Task 1: Replace Old additionalContext Trigger Sections
46+
47+
**Files:**
48+
- Modify: `agents/sensei.md:92-109` (remove "Proactive Micro-Lessons" and "Automatic Inline Insights" sections that reference old `additionalContext` string triggers)
49+
50+
**Step 1: Read current file and verify old sections exist**
51+
52+
Confirm lines 92-109 contain the two sections referencing `additionalContext` with string patterns like `"🥋 CodeSensei micro-lesson trigger:"` and `"🥋 CodeSensei inline insight:"`.
53+
54+
**Step 2: Remove the old sections**
55+
56+
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.
57+
58+
Do NOT touch the existing "When Invoked via Delegation (Pending Lessons)" section at lines 25-38 — that will be updated in Task 2.
59+
60+
**Step 3: Verify existing command sections are untouched**
61+
62+
Confirm "Quiz Format" (line 112+), "Mastery Gates" (line 142+), "XP Awards" (line 155+), and "Response Format" (line 173+) sections are intact and unchanged.
63+
64+
**Step 4: Commit**
65+
66+
```bash
67+
git add agents/sensei.md
68+
git commit -m "refactor(sensei): remove old additionalContext trigger sections
69+
70+
These sections referenced the pre-DOJ-2436 string-based trigger format
71+
(🥋 CodeSensei micro-lesson trigger: / 🥋 CodeSensei inline insight:).
72+
Hooks now write structured JSON to pending-lessons queue instead."
73+
```
74+
75+
---
76+
77+
### Task 2: Rewrite the Delegation Section to Parse Structured JSON
78+
79+
**Files:**
80+
- Modify: `agents/sensei.md:25-38` (rewrite "When Invoked via Delegation" section)
81+
82+
**Step 1: Rewrite the delegation section**
83+
84+
Replace lines 25-38 with a new section that provides clear instructions for:
85+
1. Reading JSON files from `~/.code-sensei/pending-lessons/`
86+
2. Parsing structured fields (`type`, `tech`/`concept`, `belt`, `firstEncounter`, `file`/`command`)
87+
3. Producing the right teaching depth based on `type` and `firstEncounter`
88+
4. Reading `belt` from the trigger JSON (not just from profile)
89+
5. Cleaning up processed lesson files after delivery
90+
91+
New content:
92+
93+
```markdown
94+
## When Invoked via Delegation (Auto-Coaching)
95+
96+
When the main Claude instance delegates to you after a hook fires, follow this protocol:
97+
98+
### 1. Read the Pending Lessons Queue
99+
100+
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.
101+
102+
### 2. Parse the Trigger JSON
103+
104+
Each lesson file contains structured fields:
105+
106+
```json
107+
// Code change trigger (from track-code-change.sh)
108+
{"timestamp":"...","type":"micro-lesson|inline-insight","tech":"react","file":"src/App.jsx","tool":"Write","belt":"white","firstEncounter":true}
109+
110+
// Command trigger (from track-command.sh)
111+
{"timestamp":"...","type":"micro-lesson|inline-insight|command-hint","concept":"git","command":"git commit","belt":"white","firstEncounter":true}
112+
```
113+
114+
### 3. Calibrate Your Response
115+
116+
Use the `belt` field from the trigger JSON (NOT the profile) to set your language level. Use `firstEncounter` to set teaching depth:
117+
118+
| `firstEncounter` | `type` | What to do |
119+
|---|---|---|
120+
| `true` | `micro-lesson` | **First-time encounter.** Explain what the technology/concept IS and why it matters. Use an analogy. 2-3 sentences. |
121+
| `false` | `inline-insight` | **Seen before.** Brief explanation of what THIS specific change/command does. 1-2 sentences. |
122+
| `false` | `command-hint` | **Unknown command pattern.** Explain only if educational, skip if trivial. 1 sentence max. |
123+
124+
### 4. Deliver the Teaching
125+
126+
- Keep auto-coaching to **2-3 sentences max** (micro-lesson) or **1-2 sentences** (inline-insight)
127+
- Weave naturally — don't start with "Let me teach you about..."
128+
- Reference the specific file or command from the trigger: "That `.jsx` file Claude just created..." or "That `git commit` command..."
129+
- End with a teaser or connection to something they already know, NOT a quiz (quizzes are on-demand only)
130+
131+
### 5. Clean Up
132+
133+
After processing, delete the lesson files you consumed using Bash: `rm ~/.code-sensei/pending-lessons/<filename>.json`. This prevents re-delivery.
134+
```
135+
136+
**Step 2: Verify the section reads naturally and fits within Haiku's token budget**
137+
138+
The new section should be ~250 words. Count approximate tokens (roughly 1.3x word count) = ~325 tokens. This is well within Haiku's budget.
139+
140+
**Step 3: Commit**
141+
142+
```bash
143+
git add agents/sensei.md
144+
git commit -m "feat(sensei): add structured JSON trigger parsing for auto-coaching
145+
146+
The delegation section now instructs the sensei agent to:
147+
- Read per-lesson JSON files from pending-lessons queue
148+
- Parse structured fields (belt, firstEncounter, tech/concept)
149+
- Calibrate teaching depth using firstEncounter flag
150+
- Read belt from trigger JSON, not just profile
151+
- Clean up processed lesson files after delivery
152+
153+
Part of DOJ-2439 (SRD-T0-1c)."
154+
```
155+
156+
---
157+
158+
### Task 3: Add Auto-Coaching Examples to the Agent Prompt
159+
160+
**Files:**
161+
- Modify: `agents/sensei.md` (add examples section after the delegation protocol)
162+
163+
**Step 1: Add auto-coaching examples**
164+
165+
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.
166+
167+
```markdown
168+
## Auto-Coaching Examples
169+
170+
**Micro-lesson (White Belt, first encounter with CSS):**
171+
"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."
172+
173+
**Micro-lesson (Green Belt, first encounter with Docker):**
174+
"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."
175+
176+
**Inline-insight (White Belt, repeat encounter with JavaScript):**
177+
"That edit added a 'click listener' — it tells the button 'when someone clicks you, do THIS.'"
178+
179+
**Inline-insight (Blue Belt, repeat encounter with SQL):**
180+
"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."
181+
182+
**Command-hint (Yellow Belt, first encounter with git):**
183+
"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."
184+
```
185+
186+
**Step 2: Commit**
187+
188+
```bash
189+
git add agents/sensei.md
190+
git commit -m "docs(sensei): add auto-coaching examples for Haiku calibration
191+
192+
Concrete examples help Haiku produce the right tone, length, and
193+
belt-calibrated language during auto-coaching triggers."
194+
```
195+
196+
---
197+
198+
### Task 4: Create Manual Test Checklist
199+
200+
**Files:**
201+
- Create: `docs/testing/doj-2439-test-checklist.md`
202+
203+
**Step 1: Create the testing directory if needed**
204+
205+
```bash
206+
mkdir -p docs/testing
207+
```
208+
209+
**Step 2: Write the test checklist**
210+
211+
```markdown
212+
# DOJ-2439 Manual Test Checklist
213+
214+
## Prerequisites
215+
- [ ] jq installed (`jq --version`)
216+
- [ ] CodeSensei plugin installed in Claude Code
217+
- [ ] Profile exists at `~/.code-sensei/profile.json`
218+
219+
## Test 1: Micro-Lesson Trigger (First Encounter)
220+
221+
1. Delete a tech from your profile's `concepts_seen` array (e.g., remove "react")
222+
2. Ask Claude to create a `.jsx` file
223+
3. Verify: a `.json` file appears in `~/.code-sensei/pending-lessons/`
224+
4. Verify: the JSON has `"type":"micro-lesson"` and `"firstEncounter":true`
225+
5. Verify: the main context shows the delegation hint (not a full teaching prompt)
226+
6. Verify: if delegation succeeds, sensei produces a 2-3 sentence explanation
227+
7. Verify: the lesson file is deleted after delivery
228+
229+
## Test 2: Inline-Insight Trigger (Repeat Encounter)
230+
231+
1. Ensure "javascript" is in your profile's `concepts_seen` array
232+
2. Ask Claude to edit a `.js` file
233+
3. Verify: pending lesson has `"type":"inline-insight"` and `"firstEncounter":false`
234+
4. Verify: sensei produces a 1-2 sentence explanation (shorter than micro-lesson)
235+
236+
## Test 3: Command-Hint Trigger
237+
238+
1. Ask Claude to run a `git status` command
239+
2. Verify: pending lesson has `"type":"inline-insight"` or `"command-hint"`
240+
3. Verify: sensei explains briefly or skips if trivial
241+
242+
## Test 4: Belt Calibration
243+
244+
1. Set belt to "white" in profile.json
245+
2. Trigger a micro-lesson (Test 1)
246+
3. Verify: explanation uses analogies, zero jargon
247+
4. Change belt to "blue" in profile.json
248+
5. Trigger same micro-lesson
249+
6. Verify: explanation uses technical language freely
250+
251+
## Test 5: Existing Commands Unchanged
252+
253+
1. Run `/code-sensei:explain` — verify it still works as before
254+
2. Run `/code-sensei:quiz` — verify quiz flow unchanged
255+
3. Run `/code-sensei:why` — verify it still works as before
256+
4. Run `/code-sensei:progress` — verify dashboard unchanged
257+
258+
## Test 6: Rate Limiting Still Works
259+
260+
1. Rapidly create 3 files within 30 seconds
261+
2. Verify: only the first file triggers a pending lesson (rate limit = 30s)
262+
3. Exception: first encounters bypass rate limiting
263+
264+
## Test 7: Session Cap Still Works
265+
266+
1. Set `trigger_count` to 12 in `~/.code-sensei/session-state.json`
267+
2. Create a new file
268+
3. Verify: no pending lesson created (cap = 12 per session)
269+
```
270+
271+
**Step 3: Commit**
272+
273+
```bash
274+
git add docs/testing/doj-2439-test-checklist.md
275+
git commit -m "test(sensei): add manual test checklist for hook-to-sensei pipeline
276+
277+
Covers micro-lesson, inline-insight, command-hint, belt calibration,
278+
existing command preservation, rate limiting, and session cap.
279+
280+
Part of DOJ-2439 (SRD-T0-1c)."
281+
```
282+
283+
---
284+
285+
### Task 5: Final Verification and Cleanup
286+
287+
**Step 1: Read the final `agents/sensei.md` end-to-end**
288+
289+
Verify the full file reads coherently:
290+
- Frontmatter (lines 1-10) unchanged
291+
- Personality section unchanged
292+
- NEW: Delegation section with structured JSON parsing
293+
- NEW: Auto-coaching examples
294+
- OLD sections removed: "Proactive Micro-Lessons", "Automatic Inline Insights"
295+
- Teaching philosophy, belt-aware teaching, quiz format, mastery gates, XP awards, branding, response format — all unchanged
296+
297+
**Step 2: Verify no broken references**
298+
299+
Search `agents/sensei.md` for any remaining references to:
300+
- `"🥋 CodeSensei micro-lesson trigger:"` — should NOT exist
301+
- `"🥋 CodeSensei inline insight:"` — should NOT exist
302+
- `additionalContext` — should NOT exist (delegation is now via Task tool + pending lessons)
303+
304+
**Step 3: Final commit (if any cleanup needed)**
305+
306+
```bash
307+
git add -A
308+
git commit -m "chore(sensei): final cleanup for DOJ-2439"
309+
```
310+
311+
---
312+
313+
## Acceptance Criteria Mapping
314+
315+
| Criterion | Task |
316+
|-----------|------|
317+
| `sensei.md` updated with structured teaching triggers | Task 2 |
318+
| Micro-lesson vs inline-insight uses `firstEncounter` flag | Task 2 (calibration table) |
319+
| Belt-level reads from trigger JSON, not just profile | Task 2 (step 3: "Use the `belt` field from the trigger JSON") |
320+
| Existing `/explain`, `/quiz`, `/why` unchanged | Task 1 (step 3: verify untouched) + Task 5 |
321+
| 2-3 sentence auto-coaching output | Task 2 (delivery rules) + Task 3 (examples) |
322+
| Manual test checklist documented | Task 4 |

0 commit comments

Comments
 (0)