A domain-neutral adaptive learning engine with schema-driven course packs.
Socratic tutoring ยท mastery tracking ยท multi-subject isolation ยท offline Mind Elixir knowledge maps
Adaptive Learning Coach turns a structured technical subject (programming, mathematics, algorithms & data, and other quantitative disciplines) into an adaptive one-on-one learning path. It separates a domain-neutral engine from schema-driven course packs, so adding a new subject means adding a pack โ never touching engine code.
The coach teaches in Chinese while retaining English technical terms, APIs, identifiers, and code.
- Domain-neutral engine โ zero hard-coded subject facts; every discipline is a validated course pack.
- Prerequisite graph โ a DAG of concepts with stable IDs, stage, objectives, and validator preferences.
- Adaptive mastery (0โ4) โ diagnose, unlock, teach, and re-schedule review per learner.
- Socratic tutoring ladder โ reasoning โ minimal hint โ smaller guiding question โ full answer + variation.
- Active practice โ Easy=1 / Medium=2 / Hard=3 exercises per round, revealed one at a time.
- Deterministic-first validation โ compiler/tests/runtime/static analysis, symbolic & numeric math; rubric fallback with exact evidence labels.
- Multi-subject isolation โ per-pack state under
.adaptive-learning/<pack-id>/, never cross-contaminated. - Offline Mind Elixir maps โ single-file HTML knowledge maps (no CDN, no network) with status colors, search, filters, details, zoom, and PNG export.
- Fail-closed safety โ read-only official packs, no arbitrary pack commands, atomic writes, path/symlink containment.
The engine owns orchestration, schemas, persistence, validators, the generated-pack lifecycle, and one domain-neutral viewer. All subject knowledge lives in course packs.
Adaptive Learning Coach โ domain-neutral engine SKILL.md ยท schemas/ ยท scripts/ ยท references/ ยท assets/ (state-templates + mind-map-viewer) validate-pack ยท validate-state ยท generate-pack ยท generate-map ยท adapters ยท state ยท map-data reads / validates writes / renders course-packs/ โ subject knowledge typescript/ ยท origin: official ยท readOnly: true generated/linear-algebra/ ยท generated ยท calibratable .adaptive-learning/ โ per-learner state <pack-id>/ ยท profile.json ยท progress.json ยท mistakes.md knowledge-map.html (offline Mind Elixir)Engine code contains no subject facts โ packs contain no engine code.
Every subject runs the same ten-step loop.
1 ยท route ่ทฏ็ฑ่ฏทๆฑ 2 ยท pack ๅ็ฐ/็ๆ+ๆ ก้ช 3 ยท state ้็ฆปๅญฆ็ง็ถๆ 4 ยท diagnose ่ฏๆญๅ ไฟฎ 5 ยท select ้่็น 6 ยท teach ๆ่ฏพ 7 ยท practice ็ปไน ยทไธๆฌกไธ้ข 8 ยท assess ้ช่ฏ 9 ยท update ๆดๆฐ่ฏๆฎ 10 ยท render ้็ปๅพ่ฐฑ| Level | Meaning | Unlock |
|---|---|---|
| 0 | Not encountered | โ |
| 1 | Recognizes the concept | โ |
| 2 | Can reproduce with guidance | โ |
| 3 | Can apply independently | unlocks dependents |
| 4 | Can explain, transfer, combine | mastery |
| Difficulty | Count |
|---|---|
| Easy | 1 |
| Medium | 2 |
| Hard | 3 |
Rounds announce the total but reveal one exercise at a time.
1 ยท Ask for reasoning ่ฏท่ฏดๆๆจ็๏ผๆๅบๅณ็ญ็น 2 ยท Minimal hint ๆๅ็ธๅ ณๆฆๅฟต๏ผ็ปๅบๆๅฐๆ็คบ 3 ยท Smaller guided question ๆๆไธไธชๆดๅฐ็ๅผๅฏผ้ฎ้ข 4 ยท Full answer + variation ็ฌฌ 3 ๆฌกๅผๅฏผๅคฑ่ดฅๅ็ปๅฎๆด็ญๆกไธๆจ็๏ผๅนถ็ซๅณๅๅผ้ข| Label | Meaning |
|---|---|
tool-verified |
verified by a deterministic tool (compiler, tests, runtime, symbolic/numeric math, โฆ) |
ๅบไบ่ฏๅๆ ๅๅคๆญ |
judged by rubric + reasoning only (no tool) |
unverified |
not verified |
A rubric result is never reported as tool-verified; a tool error is never recorded as a learner error.
Precedence: review-due > current > mastered > learning > available > locked
adaptive-learning-coach/ # the domain-neutral engine (the skill)
โโโ SKILL.md # workflow (82 lines) + frontmatter
โโโ agents/openai.yaml # Codex/OpenAI skill metadata
โโโ schemas/ # JSON Schema 2020-12 contracts
โ โโโ pack.schema.json
โ โโโ graph.schema.json
โ โโโ profile.schema.json
โ โโโ progress.schema.json
โโโ references/ # progressive-disclosure guides
โ โโโ learning-workflow.md
โ โโโ mastery-and-review.md
โ โโโ exercise-generation.md
โ โโโ pack-authoring.md
โ โโโ adapter-selection.md
โโโ scripts/
โ โโโ validate-pack.mjs
โ โโโ validate-state.mjs
โ โโโ generate-pack.mjs
โ โโโ generate-map.mjs
โ โโโ lib/
โ โโโ pack.mjs # manifest/graph/files validators + allowlist
โ โโโ state.mjs # index/profile/progress validators + paths
โ โโโ adapters.mjs # exercise counts, adapter selection, evidence, calibration
โ โโโ generator.mjs # atomic generated-pack writer
โ โโโ map-data.mjs # graph โ mind-map payload + HTML injection
โโโ assets/
โโโ state-templates/ # index/profile/progress/mistakes templates
โโโ mind-map-viewer/ # TypeScript + Vite + Mind Elixir viewer โ dist/index.html
course-packs/
โโโ typescript/ # official, read-only โ 43 nodes, 5 projects
โโโ generated/linear-algebra/ # generated, calibratable โ 11 nodes, 1 applied project
tests/
โโโ adaptive-learning-coach/ # pack validation, migration, state/adapters,
# generated-pack, map-data, structure, scenarios, forward-results
- Node.js โฅ 22.12 (the skill CLIs are dependency-free; the viewer build uses
npm)
DSH discovers directory-bundle skills (<dir>/SKILL.md with name + description frontmatter) from project and user roots:
| Root | Path |
|---|---|
| project | <repo>/.dsh/skills/ (or <repo>/.agents/skills/) |
| user | ~/.dsh/skills/ (or ~/.agents/skills/) |
From this repository's root:
New-Item -ItemType Directory -Force -Path ".dsh\skills" | Out-Null
New-Item -ItemType SymbolicLink -Path ".dsh\skills\adaptive-learning-coach" -Target "..\adaptive-learning-coach"A symlink (not a copy) keeps the generator's
course-packs/generated/default rooted at the repo. On Windows usecmd /c mklink /Jif symlinks need Developer Mode.
The skill is also Codex-compatible (agents/openai.yaml), installable under ~/.codex/skills/ the same way.
node adaptive-learning-coach/scripts/validate-pack.mjs --pack course-packs/typescript
node adaptive-learning-coach/scripts/validate-pack.mjs --pack course-packs/generated/linear-algebra
node --test tests/adaptive-learning-coach/*.test.mjsnode adaptive-learning-coach/scripts/generate-map.mjs `
--pack course-packs/typescript `
--progress .adaptive-learning/typescript/progress.json `
--template adaptive-learning-coach/assets/mind-map-viewer/dist/index.html `
--out .adaptive-learning/typescript/knowledge-map.html| Script | Purpose |
|---|---|
validate-pack.mjs --pack <root> |
validate a course pack (schema + files + containment), exit 0/1 |
validate-state.mjs --pack --graph --index --profile --progress |
validate learner state + cross-check pack IDs |
generate-pack.mjs --draft <json> --out <dir> |
atomically write a generated pack into course-packs/generated/ |
generate-map.mjs --pack --progress --template --out |
render an offline Mind Elixir map |
generate-map.mjs --landing <json> --out |
render the multi-subject landing page |
node --test tests/adaptive-learning-coach/*.test.mjs # 64 tests
npm test --prefix adaptive-learning-coach/assets/mind-map-viewer # 5 vitest tests
npx tsc --noEmit --prefix adaptive-learning-coach/assets/mind-map-viewer # type check
npm run build --prefix adaptive-learning-coach/assets/mind-map-viewer # single-file dist
Coverage: pack schema/validation, TypeScript pack migration, state & adapter contracts, generated-pack safety, map data/escaping, skill structure & domain-neutrality, plus four forward scenarios (TypeScript, linear algebra, multi-subject, read-only).
- Read-only by default โ official/user-locked packs are never calibrated; calibration only bumps
revisionon generated packs. - No arbitrary code โ packs declare built-in adapter IDs only; any command not mapped to an adapter is rejected.
- Fail closed โ every pack path passes lexical + canonical filesystem containment checks; symlink escape and canonicalization failure reject.
- Preserve on failure โ atomic writes (temp + rename with backup) and state preserved on corruption.
- Offline viewer โ Mind Elixir (not Mermaid), single-file HTML, no CDN requests.
- No subject leakage โ the engine is scanned by a test to contain zero subject-specific tokens.
All planned tasks are complete and review-clean: generic engine skeleton & pack validation โ TypeScript official pack โ state/adapters โ generated linear-algebra pack โ offline Mind Elixir viewer โ generic SKILL.md workflow โ forward scenarios & delivery.
The TypeScript pack is the first official fixture; linear algebra is the first generated fixture proving the engine has no hidden TypeScript coupling.
Contributions welcome. This project follows a strict test-first, review-clean discipline โ run the full test suite before opening a PR.
MIT ยฉ Adaptive Learning Coach contributors