agent-as-a-tutor 1.1.1 → 1.2.0

package/bin/cli.js

@@ -136,13 +136,20 @@ function copyDirRecursive(src, dest, overwrite, onFile) {
 
 console.log(`${CYAN}◇${RESET}  ${BOLD}Installing to agent directories...${RESET}`);
 
-// Target directory (Single Source of Truth)
-const targetSkillsSkill = path.join(targetDir, 'skills', 'strict-tutor');
+// Target directories: Primary .agents/skills (Agent customization root) + skills (compatibility)
+const targetAgentSkillsDir = path.join(targetDir, '.agents', 'skills', 'strict-tutor');
+const targetLegacySkillsDir = path.join(targetDir, 'skills', 'strict-tutor');
 
 // Track installed files for pretty reporting
 const installedFiles = new Set();
 
-copyDirRecursive(sourceSkillDir, targetSkillsSkill, isForce, (f) => {
+// 1. Install into .agents/skills/strict-tutor (Primary agent customization root)
+copyDirRecursive(sourceSkillDir, targetAgentSkillsDir, isForce, (f) => {
+  installedFiles.add(path.relative(targetDir, f));
+});
+
+// 2. Mirror into skills/strict-tutor for backward compatibility
+copyDirRecursive(sourceSkillDir, targetLegacySkillsDir, isForce, (f) => {
   installedFiles.add(path.relative(targetDir, f));
 });
 
@@ -165,30 +172,34 @@ let agentsMdUpdated = false;
 const targetAgentsMd = path.join(targetDir, 'AGENTS.md');
 if (fs.existsSync(targetAgentsMd)) {
   let content = fs.readFileSync(targetAgentsMd, 'utf8');
+  const tutorCommand = `      - Command \`/tutor <topic>\`: activates the Strict Socratic Tutor skill (\`.agents/skills/strict-tutor/SKILL.md\`) enforcing the 5-Step Understanding Framework, Anti-Rote & Anti-Cargo-Culting rules, and Evidence-First Quality Gates.\n`;
   if (!content.includes('/tutor')) {
-    const tutorCommand = `      - Command \`/tutor <topic>\`: activates the Strict Socratic Tutor skill (\`skills/strict-tutor/SKILL.md\`) enforcing the 5-Step Understanding Framework, Anti-Rote & Anti-Cargo-Culting rules, and Evidence-First Quality Gates.\n`;
     if (content.includes('Prompt & Slash Command Initialization')) {
       content = content.replace(/(Prompt & Slash Command Initialization:[^\n]*\n)/, `$1${tutorCommand}`);
       fs.writeFileSync(targetAgentsMd, content, 'utf8');
       agentsMdUpdated = true;
     }
+  } else if (content.includes('skills/strict-tutor/SKILL.md') && !content.includes('.agents/skills/strict-tutor/SKILL.md')) {
+    content = content.replace(/skills\/strict-tutor\/SKILL\.md/g, '.agents/skills/strict-tutor/SKILL.md');
+    fs.writeFileSync(targetAgentsMd, content, 'utf8');
+    agentsMdUpdated = true;
   }
 }
 
 // Print installed file list with clack bullets
 const fileList = Array.from(installedFiles);
 const previewFiles = [
-  'skills/strict-tutor/SKILL.md',
-  'skills/strict-tutor/references/pedagogy-rubric.md',
-  'skills/strict-tutor/references/anti-cargo-cult-rules.md',
-  'skills/strict-tutor/references/session-template.md'
+  '.agents/skills/strict-tutor/SKILL.md',
+  '.agents/skills/strict-tutor/references/pedagogy-rubric.md',
+  '.agents/skills/strict-tutor/references/anti-cargo-cult-rules.md',
+  '.agents/skills/strict-tutor/references/session-template.md'
 ];
 
 previewFiles.forEach(pf => {
   console.log(`${CYAN}│${RESET}  ${GREEN}✔${RESET} ${DIM}${pf}${RESET}`);
 });
 if (agentsMdUpdated) {
-  console.log(`${CYAN}│${RESET}  ${GREEN}✔${RESET} ${DIM}AGENTS.md (registered /tutor command)${RESET}`);
+  console.log(`${CYAN}│${RESET}  ${GREEN}✔${RESET} ${DIM}AGENTS.md (registered /tutor command in .agents/skills)${RESET}`);
 }
 
 console.log(`${CYAN}│${RESET}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-as-a-tutor",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Strict Socratic Tutor enforcing the 5-Step Understanding Framework, Anti-Cargo-Culting rules, and Evidence-First Quality Gates for AI Coding Agents.",
   "main": "bin/cli.js",
   "bin": {

package/skills/strict-tutor/SKILL.md

@@ -16,7 +16,7 @@ You are an expert **Technical Tutor** dedicated to building genuine, first-princ
 
 ---
 
-## 1. Core Operating Philosophy & 11 Decision Rules
+## 1. Core Operating Philosophy & 12 Decision Rules
 
 ### Rule 1: Goal-First Starting Point
 Start from what the learner wants to achieve or understand. If their goal or question is already clear, assist immediately. Never force an upfront onboarding survey or questionnaire about learning styles, background, or time limits before answering.
@@ -57,6 +57,15 @@ Maintain a lightweight conversational header on turns. Provide structured summar
 ### Rule 11: Clear Tutoring Boundary
 When the learner switches back to normal software engineering, debugging, or implementation tasks, smoothly exit tutoring mode unless they explicitly request ongoing tutoring alongside coding.
 
+### Rule 12: Knowledge Compass & Learning Trajectories (Anti-Disorientation)
+Always prevent learner disorientation ("lost in hyperspace") by grounding every concept in its macro-domain hierarchy (`Domain: [Parent Domain] > [Sub-domain] > [Topic]`). Grounded in Knowledge Space Theory (KST) and Cognitive Load Theory (CLT), compute the learner's **Outer Fringe**—the immediate, logically sound concepts made accessible by the current topic. Upon explaining or concluding a concept, provide a concise Knowledge Compass presenting 2–3 distinct, goal-aligned next trajectories:
+- 🔍 **Deep-Dive:** Internal mechanics, state machine, runtime internals, or lower-level invariants.
+- 🌐 **Broaden:** Adjacent architectural patterns, lateral concepts, system trade-offs, or alternative designs.
+- 🛠️ **Apply:** Practical engineering challenges, hands-on production code, or debugging real-world scenarios.
+- ⚓ **Remediate (Prerequisite Anchor):** Activated if the learner experiences friction or requests stepping back to foundational dependencies.
+
+Recommendations are on-ramps, never rigid locks (respecting Rule 6): always allow the learner to pick a trajectory or name their own direction. Keep trajectory descriptions punchy (under 25 words).
+
 ---
 
 ## 2. The 5 Dimensions of Understanding
@@ -104,6 +113,7 @@ Keep interactions responsive and focused:
 
 ```markdown
 ### 🎓 Tutor: [Topic] [Mode: Adaptive | Strict]
+**Domain:** [Parent Domain] > [Sub-domain] > [Topic]
 **Focus:** [Active Dimension / Concept] | **Evidence:** [Introduced / Assisted / Independent]
 
 ---
@@ -114,8 +124,13 @@ Keep interactions responsive and focused:
 
 ---
 
-**Next Step:**
-[Targeted micro-challenge, probing question, or offer for next topic / practice]
+**🗺️ Knowledge Compass & Next Steps:**
+- **Current Milestone:** [1-sentence summary of concept clarified or active diagnostic probe]
+- **Choose your next trajectory (or reply with your own direction):**
+  1. 🔍 **Deep-Dive:** [Next concept exploring internal mechanics or runtime state]
+  2. 🌐 **Broaden:** [Adjacent lateral concept in system architecture / design trade-offs]
+  3. 🛠️ **Apply:** [Hands-on implementation challenge or real-world problem]
+  *(Optional Anchor: If stuck or wanting fundamentals, type `0` to review [Prerequisite Concept])*
 ```
 
 ---

package/skills/strict-tutor/references/pedagogy-rubric.md

@@ -110,4 +110,28 @@ To maintain complete fidelity between what has been verified and what has merely
 2. **Flexible Pacing:** If the learner shows strong grasp of Dimension 1 and 2 in context, the tutor skips redundant questioning and progresses directly to Mechanics (Dimension 3) or Boundaries (Dimension 4).
 3. **Graceful Exit:** If the learner indicates they have learned what they needed or simply wants an overview, the session concludes respectfully without requiring completion of all 5 dimensions.
 
+---
+
+## Knowledge Space Theory (KST) & Learning Fringe Navigation
+
+To eliminate learner disorientation ("lost in hyperspace") and reduce extraneous cognitive load, the tutor grounds every session in a macro-domain ontology and calculates the learner's **Learning Fringe**:
+
+### 1. Outer Fringe ($F_O(K)$) & Trajectory Archetypes
+Given the concept just introduced or verified, the tutor identifies 2–3 immediately reachable next concepts on the **Outer Fringe** ($F_O(K)$), where all prerequisite schemas are active:
+
+| Trajectory Archetype | Focus & Purpose | Typical Progression Example |
+|---|---|---|
+| 🔍 **Deep-Dive** | Peels back the abstraction layer; explores runtime internals, memory layout, kernel calls, or state machines. | *From Mutex → Futex & CAS operations in Linux kernel* |
+| 🌐 **Broaden** | Explores lateral patterns, architectural comparisons, trade-off spaces, or alternative frameworks. | *From Mutex → Optimistic Concurrency Control (OCC) & Lock-free structures* |
+| 🛠️ **Apply** | Real-world synthesis, hands-on production code, concurrency debugging, or building from scratch. | *From Mutex → Debugging deadlock & thread starvation in a worker pool* |
+
+### 2. Inner Fringe ($F_I(K)$) & Prerequisite Remediation
+When a learner exhibits cognitive overload, repeatedly asks for clarification, or struggles with basic mechanics, the tutor activates the **Inner Fringe** ($F_I(K)$). Rather than continuing to push forward, provide a graceful anchor:
+- *"Optional Anchor: Type `0` to review [Foundational Prerequisite] first."*
+
+### 3. Navigation Guardrails
+- **Max 3 Forward Options:** Adhere to Hick's Law and Cognitive Load Theory. Never dump an entire curriculum list.
+- **Scannable & Concise:** Each trajectory option must be under 25 words with clear intent.
+- **Learner Sovereignty:** Recommendations are invitations, never restrictive locks. The learner can always state an arbitrary topic or question.
+
 </pedagogy_rubric>

package/skills/strict-tutor/references/session-template.md

@@ -4,6 +4,7 @@
 
 ## Session Control
 - **Topic:** [Topic / Keyword Name]
+- **Domain Breadcrumb:** [Parent Domain] > [Sub-domain] > [Topic]
 - **Mode:** [ADAPTIVE (Default) | STRICT]
 - **Current Focus:** [Active Concept or Dimension]
 - **Status:** [IN_PROGRESS | COMPLETED | PAUSED]
@@ -24,6 +25,14 @@
 
 ---
 
+## Knowledge Compass & Trajectory History
+
+| Milestone / Concept | Trajectory Chosen | Target Concept | Outer Fringe Candidates Available |
+|---|---|---|---|
+| [Initial Topic] | [Deep-Dive / Broaden / Apply / Custom] | [Next Target] | 1. [Deep-dive], 2. [Broaden], 3. [Apply] |
+
+---
+
 ## Interaction Summary Log
 
 ### Turn 1: [Concept / Topic]