Problem Statement
The engine core has no learning path. A repo-wide search for tutorial|getting started|onboard|kata|exercise returns two hits: a doc comment at src/engine/examples/BasicCoreUsage/src/main.cpp:2 and an unrelated line in CODE_OF_CONDUCT.md. docs/ holds an ADR template, a Doxyfile and six images. The wiki that would fill the gap is stale (still uses the removed ES:: prefix). Newcomers learn from one 166-line example and nine test files.
Proposed Solution
A progressive, rustlings/ziglings-style exercise track for src/engine/ only: small programs that fail until fixed, run one at a time in a fixed order, with graded hints, a watch loop that auto-advances, and terminal progress tracking.
Constraints
- Learners never clone this repository.
- A review agent checks the tutorials the way a human learner would.
- Learners may know nothing — not C++, not ECS, not build systems.
- The tool watches exercise files and advances on its own.
- An assisting AI asks questions; it does not hand out answers.
- The AI is not necessarily Claude.
Delivery
xmake 3.1.0 ships a plugin manager, so the track installs like cargo install rustlings:
xmake plugin --install github:EngineSquared/learn
xmake learn init my-engine-learning
cd my-engine-learning && xmake learn
No clone, no engine build from source (the engine arrives as the enginesquared xrepo package), no registry step. A template was rejected as the primary path: xmake create -t resolves templates only from global/addon/builtin directories, so new chapters and API-drift fixes could never reach a learner who had already generated their project. A template still ships as a fallback that points at the plugin.
Content
MVP is 14 exercises across four chapters — 00-setup, 01-cpp-you-need, 02-first-loop, 03-systems. The first two chapters contain no engine code at all; they exist because of constraint 3. Four exercise kinds: compile, output, test, and predict (the learner writes the expected output before seeing it — scheduler interleaving is where mental models break).
Guardrails
- An explain-back gate: an exercise stays pending until the learner answers a comprehension question, so code they did not understand does not advance them. Offline, no model, works no matter who or what wrote the code.
- A vendor-neutral tutor contract in TUTOR.md, referenced from AGENTS.md (read by ~30 agents) and imported by CLAUDE.md. It specifies a five-stage question ladder and forbids writing the current exercise's solution.
- For Claude Code specifically, a PreToolUse hook denies edits under exercises/ in tutor mode.
Repositories
- EngineSquared/learn — new, holds the plugin, the curriculum, the book and the QA harness.
- EngineSquared/xrepo — a core_only package config and the fallback template.
- this repository — an ADR and a README link.
Tasks below are filed here for now and will be transferred to EngineSquared/learn once it exists.
Tasks
Unblocking work — nothing else starts until these land.
The runner
The curriculum — #627 is the reference every later exercise copies.
- feat(learn): chapter 00, setup and your first error #627 — feat(learn): chapter 00, setup and your first error
- feat(learn): chapter 01, the C++ you need #628 — feat(learn): chapter 01, the C++ you need
- feat(learn): chapter 02, the first loop #629 — feat(learn): chapter 02, the first loop
- feat(learn): chapter 03, systems #630 — feat(learn): chapter 03, systems
- docs(learn): book chapters, glossary and learner README #631 — docs(learn): book chapters, glossary and learner README
Quality
The AI path
Adoption
Critical path: xrepo#1 → #618 → #619 → #620 → #621 → #622 → #624 → #627 → #628-#630 → #634.
#623, #625, #632 and #633 can run in parallel once #621 and #622 are in.
Issues #627 to #630 are the ones to hand out once #627 has landed as the worked reference — each is self-contained and needs curriculum judgement rather than plumbing.
Additional Context
Full design, research and verification steps: ADR docs/decisions/01-learning-track.md (#637).
Problem Statement
The engine core has no learning path. A repo-wide search for tutorial|getting started|onboard|kata|exercise returns two hits: a doc comment at src/engine/examples/BasicCoreUsage/src/main.cpp:2 and an unrelated line in CODE_OF_CONDUCT.md. docs/ holds an ADR template, a Doxyfile and six images. The wiki that would fill the gap is stale (still uses the removed ES:: prefix). Newcomers learn from one 166-line example and nine test files.
Proposed Solution
A progressive, rustlings/ziglings-style exercise track for src/engine/ only: small programs that fail until fixed, run one at a time in a fixed order, with graded hints, a watch loop that auto-advances, and terminal progress tracking.
Constraints
Delivery
xmake 3.1.0 ships a plugin manager, so the track installs like cargo install rustlings:
No clone, no engine build from source (the engine arrives as the enginesquared xrepo package), no registry step. A template was rejected as the primary path: xmake create -t resolves templates only from global/addon/builtin directories, so new chapters and API-drift fixes could never reach a learner who had already generated their project. A template still ships as a fallback that points at the plugin.
Content
MVP is 14 exercises across four chapters — 00-setup, 01-cpp-you-need, 02-first-loop, 03-systems. The first two chapters contain no engine code at all; they exist because of constraint 3. Four exercise kinds: compile, output, test, and predict (the learner writes the expected output before seeing it — scheduler interleaving is where mental models break).
Guardrails
Repositories
Tasks below are filed here for now and will be transferred to EngineSquared/learn once it exists.
Tasks
Unblocking work — nothing else starts until these land.
The runner
The curriculum — #627 is the reference every later exercise copies.
Quality
The AI path
Adoption
Critical path: xrepo#1 → #618 → #619 → #620 → #621 → #622 → #624 → #627 → #628-#630 → #634.
#623, #625, #632 and #633 can run in parallel once #621 and #622 are in.
Issues #627 to #630 are the ones to hand out once #627 has landed as the worked reference — each is self-contained and needs curriculum judgement rather than plumbing.
Additional Context
Full design, research and verification steps: ADR docs/decisions/01-learning-track.md (#637).