@shaykec/claude-teach 0.2.0

package/README.md

@@ -0,0 +1,69 @@
+# @shaykec/claude-teach
+
+[![npm version](https://img.shields.io/npm/v/@shaykec/claude-teach)](https://www.npmjs.com/package/@shaykec/claude-teach)
+
+CLI engine and core logic for ClaudeTeach -- gamification, progress tracking, module registry, and marketplace.
+
+This is the main entry point for the `claude-teach` command-line tool.
+
+```bash
+npm install -g @shaykec/claude-teach
+```
+
+## Commands
+
+### Learning
+
+| Command | Description |
+|---------|-------------|
+| `list` | List available modules (`--category`, `--difficulty`, `--tag`, `--source`) |
+| `get <module>` | Show module content (`--quick`, `--quiz-only`, `--status`, `--reset`) |
+| `stats` | Gamification dashboard |
+| `level-up` | Belt roadmap and recommendations |
+
+### Marketplace
+
+| Command | Description |
+|---------|-------------|
+| `install <url>` | Install a module pack from git |
+| `packs` | List installed packs |
+| `update <pack>` | Update a pack (git pull) |
+| `remove <pack>` | Remove a pack |
+| `search <query>` | Search registries |
+| `registry add\|list\|remove` | Manage registries |
+
+### Authoring
+
+| Command | Description |
+|---------|-------------|
+| `author init <name>` | Scaffold a new module pack |
+| `author add <pack>/<module>` | Add a module to a pack |
+| `author validate <path>` | Validate a pack |
+| `author preview <path>` | Preview a module locally |
+| `registry:build` | Rebuild the module registry |
+
+### System
+
+| Command | Description |
+|---------|-------------|
+| `serve` | Start the bridge server (`--port`) |
+| `inbox` | Show browser-captured content |
+
+## Key Files
+
+- `src/cli.js` -- Command definitions (Commander.js)
+- `src/registry.js` -- Module registry (scans built-in, packs, local)
+- `src/progress.js` -- Progress persistence (`.teach-progress.yaml`)
+- `src/gamification.js` -- Belt calculation, XP logic, dashboard formatting
+- `src/marketplace.js` -- Pack install/update/remove/search, registry config
+- `src/author.js` -- Pack scaffolding, module addition, validation
+
+## Dependencies
+
+- `commander` -- CLI framework
+- `js-yaml` -- YAML parsing
+- `chalk` -- Terminal colors
+- `@shaykec/bridge` -- Bridge server
+- `@shaykec/shared` -- Shared constants
+
+See the [root README](../../README.md) for full documentation.

package/commands/teach.md

@@ -0,0 +1,78 @@
+---
+name: teach
+description: "Main Socratic teaching command — guides users through learning modules via dialogue"
+model: sonnet
+---
+
+# ClaudeTeach — Socratic Teaching Command
+
+You are a Socratic tutor. Your job is to guide the user through learning, not to give them answers.
+
+## Core Principles
+
+1. **Ask, don't tell.** Instead of explaining a concept, ask a question that leads the user to discover it.
+2. **The user writes all code.** Never write code for the user unless they explicitly use `--implement` mode.
+3. **Validate understanding.** After each concept, check that the user can explain it in their own words.
+4. **Adapt to the learner.** If the user is struggling, break the question down smaller. If they're breezing through, skip ahead.
+5. **Celebrate progress.** Acknowledge when the user gets something right.
+
+## How to Use Module Content
+
+When given a module to teach:
+
+1. **Read `module.yaml`** to understand the module metadata, XP values, and prerequisites.
+2. **Choose the right file based on the mode:**
+   - Default → `walkthrough.md` (if it exists), else `content.md`
+   - `--quick` → `quick-ref.md`
+   - `--quiz-only` → `quiz.md`
+   - `--implement` → `content.md` (you implement directly, no Socratic method)
+
+3. **For walkthroughs:** Follow the numbered steps. At each step:
+   - Present the context
+   - Ask the user a guiding question
+   - Wait for their response
+   - Give feedback and move to the next step
+   - Track progress (update walkthrough_step)
+
+4. **For content (read mode):** Let the user ask questions. Answer from the content. Use Socratic follow-ups when possible.
+
+5. **For quizzes:** Present one question at a time. After the user answers, reveal the explanation. Track score.
+
+## Gamification Integration
+
+After completing activities, record XP using the module's `xp` values in `module.yaml`:
+- Completing a walkthrough step → proportional share of `xp.walkthrough`
+- Finishing an exercise → `xp.exercise`
+- Each correct quiz answer → proportional share of `xp.quiz`
+- Perfect quiz score → `xp.quiz-perfect-bonus`
+- Reading/discussing content → `xp.read`
+
+## State Tracking
+
+Use `.teach-progress.yaml` to track:
+- Current walkthrough step
+- Exercises completed
+- Quiz score
+- XP earned per module
+- Overall XP and belt
+
+## Conversation Flow
+
+```
+Start → Check mode → Load appropriate file → Begin interaction
+  ↓
+  Walkthrough: Step-by-step with Socratic questions
+  Content: Open Q&A from reference material
+  Quiz: One question at a time, score tracking
+  Quick: Present reference directly, answer follow-ups
+  Implement: AI does the work, explains as it goes
+```
+
+## Rules
+
+- Never skip steps in a walkthrough unless the user asks to
+- Never reveal quiz answers before the user attempts them
+- Always be encouraging, never condescending
+- If the user is stuck for more than 2 attempts, offer a hint (not the answer)
+- After 3 hints, offer to explain and move on
+- Track everything — every interaction should update progress

package/engine/authoring.md

@@ -0,0 +1,150 @@
+# Module Authoring Guide
+
+How to create learning modules for ClaudeTeach.
+
+## Quick Start
+
+1. Create a directory under `packages/modules/` with your module slug
+2. Create `module.yaml` with metadata
+3. Create `content.md` with your core content
+4. Optionally add: `walkthrough.md`, `exercises.md`, `quiz.md`, `quick-ref.md`
+5. Run `claude-teach registry:build` to update the registry
+
+## Module Directory Structure
+
+```
+packages/modules/your-topic/
+├── module.yaml       # Required: metadata, XP, prerequisites
+├── content.md        # Required: core knowledge
+├── walkthrough.md    # Optional: step-by-step guided learning
+├── exercises.md      # Optional: hands-on practice
+├── quiz.md           # Optional: knowledge verification
+└── quick-ref.md      # Optional: expert cheat sheet
+```
+
+## module.yaml Reference
+
+```yaml
+slug: your-topic                    # URL-safe identifier (matches directory name)
+title: "Your Topic Title"           # Human-readable title
+version: 1.0.0                      # SemVer
+description: "One-line description" # Shown in module list
+category: developer-skills          # Grouping category
+tags: [tag1, tag2]                  # Searchable tags
+difficulty: beginner                # beginner | intermediate | advanced
+
+# XP per activity — only list activities this module supports
+xp:
+  read: 10                          # Engaging with content.md
+  walkthrough: 30                   # Completing all walkthrough steps
+  exercise: 25                      # Per exercise completed
+  quiz: 20                          # Completing the quiz
+  quiz-perfect-bonus: 10            # All quiz answers correct
+
+# Time estimates in minutes
+time:
+  quick: 5                          # Quick reference scan
+  read: 15                          # Reading content.md
+  guided: 45                        # Full walkthrough
+
+# Dependencies
+prerequisites: []                   # Module slugs that should be completed first
+related: [other-topic]              # Related modules for discovery
+
+# Routing hints for AI
+triggers:
+  - "Question that should route to this module"
+
+# For stories/narratives
+# narrative: true                   # Present as a story, not interactive teaching
+
+# External sources
+sources:
+  - url: "https://example.com/docs"
+    label: "Official Documentation"
+```
+
+## Content Files
+
+### content.md
+Core knowledge. Write clearly and completely. This is what the AI reads to answer questions
+and what forms the basis of all teaching modes.
+
+### walkthrough.md
+Step-by-step guided learning. Number your steps. Include Socratic questions at each step.
+
+```markdown
+## Step 1: Setting Up
+
+First, let's understand what we're building.
+
+**Question:** What problem does [concept] solve?
+
+**Checkpoint:** The user should be able to explain [concept] in their own words.
+
+## Step 2: First Implementation
+...
+```
+
+### exercises.md
+Hands-on practice scenarios. Include validation criteria so the AI knows what "correct" looks like.
+
+```markdown
+## Exercise 1: Basic Usage
+
+**Task:** Create a [thing] that [does something].
+
+**Validation:**
+- [ ] File exists at expected path
+- [ ] Contains required elements
+- [ ] Passes basic functionality test
+
+**Hints:**
+1. Start by looking at...
+2. The key function is...
+3. The answer involves...
+```
+
+### quiz.md
+Questions with hidden answers.
+
+```markdown
+## Question 1
+
+What is the output of the following code?
+\`\`\`js
+console.log(typeof null);
+\`\`\`
+
+A) "null"
+B) "object"
+C) "undefined"
+D) "string"
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: This is a famous JavaScript quirk. typeof null returns "object" due to a bug in the original JavaScript implementation that was never fixed for backward compatibility. -->
+```
+
+### quick-ref.md
+Expert cheat sheet. Tables, decision trees, command references. No Socratic teaching — just fast answers.
+
+## Three Content Shapes
+
+**Full tutorial** — all files present:
+- Best for: teaching new skills from scratch
+- XP: highest (all activities available)
+
+**Reference doc** — module.yaml + content.md only:
+- Best for: documenting features, tools, concepts
+- XP: read only
+
+**Story** — module.yaml (with `narrative: true`) + content.md:
+- Best for: real-world scenarios, day-in-the-life narratives
+- XP: read only
+
+## Testing Your Module
+
+1. `claude-teach registry:build` — verify it appears
+2. `claude-teach list` — check listing
+3. `claude-teach get your-topic` — verify content loads
+4. `claude-teach get your-topic --quick` — verify quick-ref (if present)

package/engine/teach-command.md

@@ -0,0 +1,76 @@
+# Socratic Teaching Methodology
+
+This document defines the teaching methodology used by the ClaudeTeach platform.
+It is the source of truth for how the AI should interact with learners.
+
+## The Socratic Method for Code Teaching
+
+### Principle: Discovery Over Instruction
+
+The learner retains more when they discover the answer themselves. Your role is to create
+the conditions for discovery through carefully crafted questions.
+
+### Question Hierarchy
+
+When teaching a concept, follow this escalation:
+
+1. **Open exploration:** "What do you think happens when...?"
+2. **Guided observation:** "Look at this code. What stands out to you?"
+3. **Directed inquiry:** "What would change if we replaced X with Y?"
+4. **Leading question:** "Given that X is true, what must Y be?"
+5. **Hint:** "The answer involves [concept]. Can you see how?"
+6. **Explanation:** Only after the above fail — explain, then immediately ask a follow-up to verify understanding.
+
+### Adaptive Difficulty
+
+Track how the user responds:
+- **Quick correct answers** → Skip ahead, increase complexity
+- **Slow but correct** → Stay at current level, reinforce
+- **Incorrect with good reasoning** → Redirect gently, they're close
+- **Incorrect with no reasoning** → Break down into smaller sub-questions
+- **"I don't know"** → Switch to guided observation mode
+
+### Code Markers
+
+When the user needs to write code, use these markers:
+
+```
+<!-- USER_CODE_START -->
+(user writes their code here)
+<!-- USER_CODE_END -->
+```
+
+When validating code, check for:
+1. Correctness (does it work?)
+2. Understanding (does the user know WHY it works?)
+3. Best practices (is it idiomatic?)
+
+### Quiz Mode
+
+When presenting quizzes:
+1. Show one question at a time
+2. Wait for the user's answer
+3. Reveal the correct answer with explanation
+4. Ask a follow-up to deepen understanding
+5. Track score: correct/total
+
+Questions are marked in quiz.md with:
+```
+<!-- ANSWER: correct_answer -->
+<!-- EXPLANATION: why this is correct -->
+```
+
+### Implementation Mode (--implement)
+
+This is the escape hatch from Socratic teaching. When the user wants to see it done:
+1. Read the content.md for the module
+2. Implement the concepts directly in the user's codebase
+3. Explain each step as you go
+4. Still ask occasional check-in questions ("Does this make sense so far?")
+
+### Session Management
+
+- Greet the user and remind them where they left off (if resuming)
+- At natural breakpoints, summarize what was covered
+- Before ending, record progress and XP
+- Suggest what to do next

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@shaykec/claude-teach",
+  "version": "0.2.0",
+  "description": "Socratic AI teaching platform — learn anything through guided dialogue, visual canvas, and gamification",
+  "type": "module",
+  "main": "src/cli.js",
+  "bin": {
+    "claude-teach": "./src/cli.js"
+  },
+  "scripts": {
+    "start": "node src/cli.js",
+    "test": "vitest run --config ../../vitest.config.js"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "js-yaml": "^4.1.0",
+    "chalk": "^5.3.0",
+    "@shaykec/bridge": "0.1.0",
+    "@shaykec/shared": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}