# About this project

> Why this training suite exists, what it contains, how its lessons work, and how it was built and is maintained.

Page: https://schubergphilis.github.io/ai-training/about/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

This page describes the AI Training project as a whole. It explains why the
project exists and what the site contains. It then shows how a lesson works
and which ideas about learning are behind that design. After that it tells
how the project started, how it grew, and how work on it happens now. The
last sections describe the agent harness that does most of the writing and
the software that runs the site.

A short version of this page is a [set of slides](https://schubergphilis.github.io/ai-training/about/slides/) for a
talk of 10 to 20 minutes.

## In short

AI Training is an open training suite for people who start to use
generative AI in their work. It has 6 areas in
2 groups. The Foundations group (Concepts, Safety
and Using agents) is for anyone who does knowledge work. The Engineering
group (Coding with agents, Customizing agents and Building agents) is for
software engineers.

Each area has one course, and each course is a sequence of interactive
lessons with graded checkpoints. Each lesson ends in one exercise that the
learner does outside the page.

- 133 lessons
- 431 graded checkpoints
- 133 exercises

The site keeps the learner's progress in their own browser and brings
finished checkpoints back for review on a fixed schedule. A learner can also
study a lesson with an AI tutor that runs in their own coding agent.

The site is a static website on GitHub Pages. It runs entirely in the
browser, without accounts or tracking. The content is licensed CC BY-SA 4.0
and the code Apache-2.0, so others may copy and adapt both.

The project started on September 19, 2026. One maintainer runs it. AI coding
agents write almost all of the content and the code. The maintainer decides
what gets built. Agents review every change, and the maintainer reviews the
changes that fall outside a standing approval. The site states this in its
footer: the content is co-authored by AI.

## Why the project exists

### People need a common starting point

The project starts from a view of how people use these tools. Generative
AI tools reached office work in a short time. Many people use a chat
assistant or a coding agent without any training in how these tools work
or fail. The project expects the result to be uneven: some people get
useful work out of the tools, and others share data they shouldn't, trust
answers they should check, or give up after one bad result.

A training suite gives a group of people the same words and the same basic
model of the tools. People can then discuss a result, a risk or a working
method with each other. The project defines its own words in a project
dictionary and uses them the same way on every page.

### Safe use and real use go together

Research on automation has found the same thing for decades. When a machine
does most of a task, people stop checking its work, and they lose the skill
to take over when it fails (Ironies of automation, Automatica 19(6) (1983), 775-779). Studies of automation bias
show that people accept a wrong answer from a system they trust, even when
the evidence in front of them says otherwise (Complacency and Bias in Human Use of Automation: An Attentional Integration, Human Factors 52(3) (2010), 381-410). The
project assumes that AI assistants make both effects more likely, because
they answer fluently and with confidence.

So the suite teaches safety in the Foundations group, before any
engineering material, and it returns to verification in every area. The
Safety course covers which data a person may share with a tool and how far
to trust an answer. Later parts cover the risks of an agent that acts on
its own, and governance such as the EU AI Act.

### Open content

The project is public, and its license lets anyone reuse it. An
organization can run the courses for its own staff or change a lesson to
fit its own tools. A person can study alone, with only a
browser. The license is CC BY-SA 4.0 for the content and Apache-2.0 for the
code.

The first license, on the first day, was CC BY-NC-SA 4.0. It was changed
the same evening. The "non-commercial" term made training inside a company
an unclear use, and it blocked the project from adapting material under
BY-SA, which Diátaxis uses (Diátaxis, a systematic approach to technical documentation authoring, Diátaxis).

The license also limits what the project may take from others. A lesson may
adapt text only from a source whose license allows it, such as Apache-2.0,
CC BY or CC BY-SA material. Other sources, such as Claude Academy courses
(AI Fluency: Framework and foundations, Claude Academy), DeepLearning.AI courses and
CS50 (CS50's Introduction to Computer Science, Harvard CS50), are cited and linked. Their text is never copied.

## What the site contains

### Facts and figures

All of the counts below are made from the site's data and lesson pages
when the site is built, so they match the version you are reading. The
drawing shows what the site has and how the parts relate. A lesson covers
one topic and serves one or more learning objectives, and each graded
checkpoint tests one objective. The next sections explain each part.

- 2 groups with 6 areas. Each area has one course, 36 course parts in all.
- 133 lessons. They have 431 graded checkpoints, 421 more for review only, 133 exercises and 60 habits.
- 35 topics with 199 concepts. A lesson covers one topic.
- 21 competencies with 93 learning objectives and 291 behaviors. A lesson serves objectives, and a checkpoint tests one.

- 230 runnable examples
- 9 widget kinds
- 245 sources
- 59 study hours, estimated

The study time is the site's own estimate. It adds the reading time and a
fixed time per checkpoint to the time each exercise states. The constants in
the estimate were chosen by hand and have not been checked against learners
with a clock yet. Spaced review comes on top of this time.

### Groups and areas

The Foundations group has one level for everyone. Its lessons need no
programming and no agent setup. A check in the build rejects a Foundations
lesson that shows code or terminal work. New lessons must pass the same
check.

The Engineering group assumes the learner finished Foundations. Its lessons
use real code and real tools, and learners choose one of two comfort levels,
"less comfortable" or "more comfortable". The section on routing explains
what the levels change.

| Area | Group | What it covers | Lessons | Topics | Checkpoints |
| --- | --- | --- | --- | --- | --- |
| Concepts | Foundations | What AI models are and how they behave. | 20 | 6 | 52 |
| Safety | Foundations | Using AI safely, and judging the risk of letting an agent act. | 18 | 5 | 53 |
| Using agents | Foundations | Delegating work to an agent and checking what comes back. | 14 | 4 | 43 |
| Coding with agents | Engineering | Shipping software changes with a coding agent. | 27 | 7 | 106 |
| Customizing agents | Engineering | Configuring an agent for a project with instructions, skills, tools and permissions. | 26 | 6 | 91 |
| Building agents | Engineering | Build an agent from a model, a loop and tools. | 28 | 7 | 86 |

### Topics, concepts and competencies

The site describes what it teaches with a small knowledge model. The model
is data, in YAML files next to the lessons, and the build reads it.

- A **topic** is one subject in one area, such as "Prompting" in Concepts.
  Topics link to the topics they build on. Each topic has a list of
  **concepts**, each with a one-paragraph definition. All of the concepts
  together make the glossary.
- A **competency** says what a learner can do after a course, as one
  sentence. It has **learning objectives**, each at a `base` or an `expert`
  level. Each objective has **behaviors**: a claim about what a competent
  person does, the reason for it, and an example.
- A lesson covers one topic and serves one or more objectives. A graded
  checkpoint tests one objective.

The behaviors format comes from Brilliant's skills map for coding with AI
(Verification, Brilliant, Coding with AI skills map). The project also maps its objectives to
3 outside frameworks. The frameworks
are that skills map, a skills map for AI engineering (AI engineering skills map: build and deploy AI applications, software engineering fundamentals, use coding agents, shape the build, The Batch (newsletter)), and the 4D
framework of AI Fluency (AI Fluency: Framework and foundations, Claude Academy). The
mapping shows which part of each framework the site covers, and where it has
gaps.

The map below shows every topic, one column per area. An arrow runs from a
topic to a topic that builds on it. The colors show your own progress, read
from your browser. They stay gray until you finish a lesson.

### Sources

A lesson cites a source with a numbered reference, and the build fails on
a citation to an unknown entry. The bibliography has these kinds of
entry:

| Kind | Entries |
| --- | --- |
| Reference pages | 152 |
| Courses | 57 |
| Papers | 23 |
| Videos | 8 |
| Books | 5 |

Most citations point to vendor documentation, because many lessons teach a
specific tool. Claude Code documentation is the most cited family, and its
pages on memory (How Claude remembers your project, Claude Code documentation) and on best practices
(Best practices for Claude Code, Claude Code documentation) are each cited in more than a dozen lessons.
An open course on agent engineering, which the maintainer wrote with two
others, is the second family (What are AI agents: model versus agent, autonomy levels, when a prompt suffices, Agent Engineer Course). The project began as a rebuild of
that course, as the history section explains. Claude Academy courses are the
third family.

Where a lesson makes a claim about how people work with automation or how
models behave, it cites the research. Examples are the papers on automation
cited above, a survey of hallucination in language models (A Survey on Hallucination in Large Language Models: Principles, Taxonomy, Challenges, and Open Questions, ACM Transactions on Information Systems 43(2), Article 42, 2025, arXiv preprint 2311.05232),
and a study of sycophancy, the tendency of a model to agree with the user
(Towards Understanding Sycophancy in Language Models, International Conference on Learning Representations (ICLR 2024), arXiv preprint 2310.13548). Prompting concepts are written from the original papers.

## Inside a lesson

A lesson is one page. It is meant to take 10 to 25 minutes of reading and
checkpoints, plus the exercise. The data check warns when a lesson's reading
and checkpoints alone take more than 25 minutes. Each lesson has the same
parts in the same order, so that a learner knows where they are on any page.

### Two kinds of lesson

The project uses the Diátaxis model of documentation (Diátaxis, a systematic approach to technical documentation authoring, Diátaxis). That
model sorts a page by two questions. Does the reader act or think? Is the
reader studying or working? The answers give four kinds of page: tutorial,
explanation, how-to guide and reference.

Lessons are for study, so a lesson is a **tutorial** or an
**explanation**. A tutorial has the learner do something and see the
result early and often. It follows one path, in a setting the learner can
reset. Its rhythm is fixed: one or two paragraphs, then one example to run
or predict. An explanation builds understanding. It may compare options
and hold an opinion. The planned lessons, the ones with a page and the
ones still to write, are of these kinds:

| Kind | Planned lessons |
| --- | --- |
| Tutorials | 91 |
| Explanations | 42 |

The site builds reference pages from data: each topic page and the
glossary. The guides, such as the guide to running a workshop, are
hand-written how-to pages.

### The parts of a lesson

A lesson opens with one or two sentences in the present tense that say what
the lesson does. Then come the teaching sections. Some of these are
**pitfalls**, short boxes that show a common mistake and its cost. Graded
**checkpoints** sit between the teaching sections, close to the idea they
test. After the teaching comes one **exercise**, and then a **recap**. The
recap lists the takeaways and the objectives the learner can now meet, and
it holds the button that finishes the lesson. Some lessons end with one or
two **habits**.

A lesson that teaches prompting shows prompts and responses in their own
styled blocks. Each block says which model produced the response and on
which date, or marks the exchange as illustrative when it was written by
hand. Model output changes over time, so the reader can judge how current
an example is.

### Checkpoints

A checkpoint is a small graded question inside the lesson. The site has
8 kinds:

| Kind | Note | Graded checkpoints |
| --- | --- | --- |
| Choice | Picks the one right option | 139 |
| Multiple choice | Picks every right option | 31 |
| Scenario | Picks what to do in a short work situation | 84 |
| Predict | Predicts what code or a prompt will produce | 62 |
| Sort | Puts items into groups | 53 |
| Match | Matches each item to one on the other side | 38 |
| Order | Puts steps in the right order | 10 |
| Repair | Rewrites a flawed prompt, instruction or code | 14 |

The rules for checkpoints are the same everywhere:

- Each checkpoint tests exactly one learning objective, and it names the
  concepts it uses.
- A wrong answer to a choice question shows feedback for that answer. A hint
  is a question that points the learner at their own mistake, and it never
  gives the answer.
- The lesson never reveals the answer. The learner can try again as often
  as they want, or skip the checkpoint. The site records a skip, and it
  doesn't count a skip as a pass.
- A checkpoint is graded all or nothing.
- Every checkpoint works with the keyboard alone.

A multiple-choice question has a known weakness: a reader can often guess
the answer from the options alone. The longest option, the option with
careful hedges, or the option that repeats words from the question is often
the right one. A check looks at every choice, scenario and multiple-choice
checkpoint for such cues. It also fails a lesson where one position holds
the right answer in more than three quarters of its items. An author can
exempt an item only with a written reason.

To see a real checkpoint, open the first checkpoint of the lesson
[How a language model works](https://schubergphilis.github.io/ai-training/concepts/how-models-work/#what-the-model-does).
A checkpoint only works inside its lesson, because a pass becomes part of
your progress record.

### Examples that run

Many lessons in the Engineering group show code and the output it prints.
That output is never typed by hand. Each example is a small program in the
repository, and a build check runs it and compares what it prints with
what the page shows. The check runs every example on two versions of
Python, the current release and an older version that some learners still
have. A change in Python, or a mistake in a lesson, fails the check before
the page is published.

The site has 230 such examples. Some are
graded **predict** checkpoints, where the learner first guesses the output
and then runs the code to check the guess. The others are worked examples
that the learner reads or runs.

### Widgets

A few concepts are easier to understand by trying them than by reading. For
these the site has 9 kinds of interactive
widget. A widget isn't graded and doesn't write to your progress. The one
below is from the first Concepts lesson. A language model picks each next
word, or part of a word, at random, by weight, and the temperature changes
how spread out the weights are. Move the slider and sample a few times.

### Exercises

Each lesson ends with one exercise. The learner does it outside the page,
with their own tools, in a setting they can reset, such as a practice
repository. The exercise brief says what to do and what a finished result
looks like. Then the learner compares their work with a model answer. No
one grades the exercise. It ends with one reflection question.

There are two kinds of exercise. In a **do** exercise the learner produces
something, such as an instruction file or a test. In a **judge** exercise
the learner gets a result, such as an agent's output or a pull request, and
assesses it. Some exercises add a one-line stretch goal for
learners who want more.

### Routing between learners

People start a course with different knowledge. The site writes each lesson
once, and it changes the route through the material for each learner.

Each lesson declares the objectives it serves and the objectives it
assumes. If a learner fails or skips a checkpoint that depends on an
assumed objective, the lesson shows a card that points to the section where
that objective is taught. If a learner passes every checkpoint at the first
try, the lesson shows a card that suggests where to go next. The site never
locks a lesson.

In the Engineering group the learner also picks a comfort level, an idea the
project took from CS50 (CS50's Introduction to Computer Science, Harvard CS50). At the "less comfortable" level the lesson
shows the card with the sections that teach what it assumes from the start,
and new review items come back sooner. At the "more comfortable" level the
lesson starts with a short skills check. It skips what the learner already
knows and offers extensions. The level changes the route and never the
content.

### After the lesson

When a learner finishes a lesson, the site schedules its review items and
its habits, and adds the lesson to the learner's reference.

**Spaced review.** Most graded checkpoints of a finished lesson become
review items. Repair checkpoints, and ones the author marks as one-off,
don't. Each course has a review page. An item comes back 1, 3, 7, 21 and 60
days after the learner last passed it. With a pass it moves to the next
step, and with a fail it goes back to the first step. After the fifth pass
the item retires. A session asks at most 12 items. Many checkpoints have
alternate versions that only the review page asks, so that a review tests
the idea rather than the memory of the wording. The sidebar shows how many
items are due per course.

**Habits.** A habit is a small task to do in your own work, in the form
"The next time you do X, do Y". It comes back 1, 3 and 7 days after the
lesson. After that the site stops showing it.

The figure shows both schedules for a learner who passes each review on
the day it is due.

- Review item: on days 1, 4, 11, 32, 92 after the lesson
- Habit: on days 1, 3, 7 after the lesson

**The learner's reference.** A topic page has a short summary of the
lessons that cover it: the takeaways from the recap and one canonical
example. The summary appears once you finish that lesson. Over time the
topic pages become a personal reference with only what you studied.

The site has no email and no notifications, because it has no backend. It
shows what is due when the learner comes back to it.

### Your progress stays with you

The site stores all progress in one record in the learner's browser, in
local storage. The site sends nothing to a server. The progress page can
export the record to a file and import it in another browser. The record has
a version number, and the site converts an older record when it loads it.

A static site can't hide its answers, because the answers are in the page.
The site trusts the learner not to look up the answer. The record is for the
learner, and it grades no one.

### The tutor

A learner can study a lesson with an AI tutor in their own coding agent.
The tutor is a skill that the learner installs once. When it starts, it
fetches its instructions and the lesson from the site. It then gives hints
and asks questions. It doesn't give the answers to checkpoints or
exercises, and it stays on the lesson the learner names. When the learner
pastes their progress export, the tutor first asks one recall question for
a review that is due.

The design follows the AI tutor that CS50 built for its students, which
gives hints and guides the student to the answer (Teaching CS50 with AI: Leveraging Generative Artificial Intelligence in Computer Science Education, Proceedings of the 55th ACM Technical Symposium on Computer Science Education V. 1 (SIGCSE 2024), 750-756). The project
tests the tutor with a fixed set of learner questions, each with what the
tutor must and must not do. A change to the tutor that makes it give an
answer away doesn't ship.

## The ideas about learning behind the design

The project draws on a small number of ideas from learning research and
from other learning platforms. The specs state each idea in their own words,
with the reason for it, and most of the ideas came to the project through
other platforms. This section describes each idea as the project uses it,
and names research that supports it. The numbers in the design, such as
the review intervals, are first guesses. The project has no data about
real learners yet.

### Retrieval practice and spaced review

The spaced-review spec starts from one claim: interactive lessons alone
produce recognition, and recall needs practice. A learner who reads a page
can recognize its ideas later, which is less than being able to recall
them. So the site asks a learner to retrieve each idea again, after
growing intervals. It also uses alternate questions. With those, the
learner recalls the idea and not the wording of one question.

Memory research supports this design. In one study, students who
took a test on a text remembered more of it a week later than students who
spent the same time reading it again (Test-Enhanced Learning: Taking Memory Tests Improves Long-Term Retention, Psychological Science 17(3) (2006), 249-255). A review of 317
experiments found that practice spread out over time gives better
long-term recall than the same practice in one session (Distributed Practice in Verbal Recall Tasks: A Review and Quantitative Synthesis, Psychological Bulletin 132(3) (2006), 354-380). A
later review of ten study techniques rated these two as the most useful,
and rereading as one of the least (Improving Students' Learning With Effective Learning Techniques: Promising Directions From Cognitive and Educational Psychology, Psychological Science in the Public Interest 14(1) (2013), 4-58).

### Prediction before the result

The project assumes that a learner who predicts a result before seeing it
pays more attention to the result. When the prediction is wrong, the
difference shows where their model of the system is wrong. The predict
checkpoint uses this. Code examples follow a fixed rhythm: one idea, then
one example. The project took both from Execute Program, an online platform
that teaches programming with short, executable examples. Research supports
the first part: an attempt to answer before seeing the answer helps later
recall, even when the attempt fails (Unsuccessful Retrieval Attempts Enhance Subsequent Learning, Journal of Experimental Psychology: Learning, Memory, and Cognition 35(4) (2009), 989-998).

### Design from the outcomes

The design starts from what the learner can do afterwards, and works back to
the lessons. Course designers call this backward design (Understanding by Design, Expanded 2nd Edition, ASCD, 2005). It
starts from the results a course wants and the evidence that would show
them, and plans the teaching last. The competencies, objectives and
behaviors say what a learner can do. Each checkpoint tests one objective. So
the site can show which objectives a learner has evidence for, and a
reviewer can check whether a lesson tests what it claims to teach.

### One text with several routes

Writing a separate course for each level of learner costs too much, and the
versions drift apart. The project writes each lesson once. Routing cards,
comfort levels and the skills check adapt the route through it. The model
for this was a classroom method with three paths: review a prerequisite,
work on the current objective, or take an extension.

### Hints that ask questions

The project assumes that a hint that gives the answer ends the learner's own
thinking. In this project a hint asks the learner a question about their own
mistake. The tutor follows the same rule. The idea comes from CS50's AI
tutor (Teaching CS50 with AI: Leveraging Generative Artificial Intelligence in Computer Science Education, Proceedings of the 55th ACM Technical Symposium on Computer Science Education V. 1 (SIGCSE 2024), 750-756). Research on tutoring calls this kind of help
scaffolding: the tutor takes over the parts of a task that the learner can't
do yet, and leaves the rest to the learner (The Role of Tutoring in Problem Solving, Journal of Child Psychology and Psychiatry 17(2) (1976), 89-100).

### From the page to the job

People often don't use at work what they read on a page. Exercises use the
learner's own tools in a practice setting. Habits are closer to the job:
they ask the learner to change one thing in their real work, and come back
to ask whether they did. The aim is that a lesson changes what a learner
does, as well as what they know. The habit form, "The next time you do X,
do Y", is a plan of the kind that psychologists call an implementation
intention. Such plans make it more likely that people act on a goal
(Implementation Intentions: Strong Effects of Simple Plans, American Psychologist 54(7) (1999), 493-503).

### Plain language

Many readers have English as a second language. The project keeps the
concepts at a professional level and the language simple. It prefers common
words and plain sentences, and a lesson expands each abbreviation on
first use. A prose linter checks every page for wordy, vague or
hard-to-read text, and the reading-time estimate assumes a slower reading
speed than a native speaker has.

## How the project started

### The first two days

The repository was created on September 19, 2026, from a documentation
template that the maintainer had made earlier. The template already had the
site generator, a pinned set of tools and a continuous integration (CI)
pipeline, which runs the checks on every change.

The project replaced two earlier attempts. The first was a private training
repository that never got beyond its setup. The second was the open course
on agent engineering that the maintainer wrote with two others (What are AI agents: model versus agent, autonomy levels, when a prompt suffices, Agent Engineer Course).
That course is Apache-2.0, so this project could take its material, with
credit to its authors.

On the first day the maintainer answered a set of design questions in an
interview with an agent. The answers fixed the title, the two groups and
six areas, and one level for Foundations with two comfort levels in
Engineering. The first release was to be one thin slice through all six
areas. The tutor was to be an agent skill, and progress was to stay in the
browser.

### Learning from other platforms

Before any lesson was written, agents studied existing learning platforms
and documentation methods. They wrote one exploration note per source. Each
note ended with a list of ideas to adopt or to decline, and the maintainer
decided on each.

- CS50: Comfort levels; Walkthroughs; A tutor that gives hints; Ideas, structure and words
- Diátaxis: The four page kinds; Tutorials and explanations as lesson kinds
- Brilliant's skills map for coding: Behaviors as claim, reason and example; Finer competencies; Alignment with outside frameworks
- Execute Program: The predict checkpoint; The course page as a lesson graph; Spaced review; Examples that run in CI
- roadmap.sh: A status per topic; Short concept definitions; The tutor's verbs; Topic pages with a stable link
- Learn Prompting: Citations by key; Glossary tooltips; Prompt blocks with model and date
- Claude Academy: A survey of its interactive mechanics, as a list of widgets to build later

### Specs before code

The first decisions went into numbered design specs before code was
written. The first spec is a project dictionary. It fixes the words the
project uses, such as lesson, checkpoint, topic, competency and habit, so
that every page, data file and component means the same thing by the same
word. The early specs cover the topic map, lesson authoring, the progress
record and spaced review. Later specs, one subject each, were added as the
project grew: habits, the tutor, the data files, the agent-readable site,
interactive components and the visual identity.

### The first release

On September 20 an agent built a quick prototype of a thin slice: two
lessons and the progress record. The prototype showed that the design
worked in a browser. A rebuild the same day became the first release: six
lessons, one per area, and every mechanism from the plan. It had the
checkpoint kinds, pitfalls, exercises and recaps, the progress record, the
review schedule, the topic map, two widgets, a check that runs the code
examples, a browser test of a full lesson, and a first version of the
tutor.

## How the project grew

### A timeline

The chart shows the number of lessons with a page at the end of some days,
and the numbered events under it. All dates are in 2026.

| Date | What happened |
| --- | --- |
| September 19 | Repository created. Plan, interview, exploration notes, license change, first specs. |
| September 20 | First release. Prose and spelling checks. First parallel agent work: twelve issues to twelve merged pull requests. |
| September 21 | All structure moved into data files: one YAML file per area, competency, course and lesson. |
| September 23 | A second layer of agent orchestration, the "wave" process, so that one session can work through many issues. |
| September 24 | Habits. Exact versions for every dependency. The first review of the agent harness. The default agent model changed. |
| September 25 to 27 | Most lessons were written, in batches of four to ten. A security review of the whole site started. |
| September 29 | The site left its pre-release status. |
| September 30 | The repository moved to the organization's account and became public. The site got its visual identity. |
| October 1 | A Content Security Policy on every page. Markdown copies of pages and data files for AI agents. A guide for running a workshop. |
| October 4 to 8 | Lessons for the remaining gaps. A skill for triage with the maintainer. The second harness review. |

| End of day | Lessons |
| --- | --- |
| September 20 | 10 |
| September 23 | 37 |
| September 25 | 100 |
| September 27 | 114 |
| October 9 | 132 |

### Figures from the history

These figures are as of October 9, 2026.

- 1,436 commits
- 17 days with commits
- 608 issues, 533 closed
- 153 merged pull requests, of 154

Each merge rebased the commits onto the main branch, so the history has
no merge commits. Almost every commit ends with a line that names the AI
model that helped write it. Claude Fable 5.1 was the default model until
September 24, and Claude Opus 5.5 after that day. The commits without
such a line are the first commit, six small edits by the maintainer and
two automatic dependency updates.

| Model | Note | Commits |
| --- | --- | --- |
| Claude Opus 5.5 |  | 868 |
| Claude Fable 5.1 |  | 553 |
| claude-opus-5 | a model string in six commits | 6 |
| No model named | by the maintainer or a bot | 9 |

## How work happens now

The project has one maintainer and no other human contributors so far.
The maintainer decides what to build and what to accept. Agents write the
lessons, the code, the tests and most issue text, and other agents review
that work. This section describes the process as the repository documents
it, and as the issue history shows it.

### Everything starts as an issue

Every piece of work is a GitHub issue. An issue has one label for the kind
of change: `content`, `code` or `harness`. The last one covers the agent
setup itself. A triage pass with the maintainer leaves every issue in one
of three states. It is ready for an agent, with its decisions written down,
or ready for a human, with one named action, or it is closed with a reason.

A follow-up that a review finds, and an improvement the maintainer defers,
become new issues before a session ends. Agents keep open work in issues,
and never in a chat log or a session record.

### Waves of agents

Most work happens in **runs**. A run is one session in which the maintainer
starts a dispatcher with the `/wave` command. The dispatcher picks a few
ready issues and starts a **wave lead** for them. The wave lead then starts
one **builder** agent per issue. Each builder works in its own copy of the
repository, on its own branch. When a builder pushes its branch, the lead
starts a **reviewer** agent for it. For a lesson, the reviewer compares the
prose with the authoring guide and checks the license of each source and
each factual claim. For code, the reviewer reads the change and runs the
checks. Builders and reviewers never talk to each other directly. The lead
passes the review to the builder, and the builder fixes what the review
found.

When every branch in the wave is approved, the lead combines them on one
wave branch. It runs the full check suite there and opens one pull
request. The maintainer has given standing approval for a wave that passes
every check, so the lead may merge such a wave without asking. That
approval never covers a wave that changes the agent setup itself, as the
harness section explains.

Each run gets an animal name in alphabetical order, from Axolotl to
Zebra and then on from Alpaca. The run has its own GitHub issue, which
records its waves and its state, so that a run can resume after an
interruption. As of October 9, 2026, there have been 30 run issues under
28 names. One name has two runs, and one run has a follow-up.

### Why there are two layers

At first one coordinating session managed all builders and reviewers
itself. Each issue cost that session about twenty thousand tokens of its
context, and with more than a hundred ready issues one context could not
hold the work. The wave lead takes that load, and the dispatcher keeps
only a short report per wave.

### What the maintainer does

Agents are set up to ask the maintainer as little as possible. They
decide routine matters themselves and report what they decided. They ask
the maintainer only when a decision touches a spec, a project rule, the
scope of the work or its cost. A question to the maintainer holds one
decision in plain words, with one recommendation. Merging a pull request
outside a green wave needs the maintainer's explicit word.

### Reviewing the process itself

The process asks for a harness review once a week and after each change of
model or orchestration. Two have run so far. A harness review looks at where
time, tokens and the maintainer's attention went. It reads the git history,
the issues and the agents' session logs, and it compares the project's own
way of working with what its lessons teach. The findings the maintainer
picks become issues. The reviews are public as issues. The full reports stay
outside the repository, because session logs can hold private material.

## Harness engineering

An agent harness is everything around a model that decides what it does:
its instructions, its tools, its permissions, the checks its work must
pass, and the way its work is reviewed and merged. The lessons in the
Customizing agents course teach the same kind of tools.

### The parts of the harness

- **Instructions.** One instruction file at the root of the repository
  holds the rules every agent reads first. Process documents for agents
  describe lesson writing, testing, the issue tracker, triage,
  orchestration, completion and supply chain, one subject each.
- **Agent definitions.** The repository defines agents for each role:
  builder, code reviewer, lesson reviewer, security reviewer and wave lead.
  Each file sets the model, the effort level, the maximum number of turns
  and the tools the agent may use. A reviewer can't edit files, and the
  lesson reviewer has no shell at all.
- **Skills.** The repository has skills for the wave dispatcher, triage,
  the harness review and the learner's tutor. Only a person can start the
  first three.
- **Hooks.** A hook is a script that runs before or after an agent's tool
  call (Hooks reference, Claude Code documentation). A guard hook checks every shell command an
  agent wants to run.
- **Checks.** One command runs every check, and every push and merge must
  pass it.

### Each control and what it prevents

| Where | Control | What it prevents |
| --- | --- | --- |
| How work is split | Each builder works in its own copy of the repository | Two agents that overwrite each other's work |
| How work is split | Only the dispatcher, a wave lead or a coordinating session may merge | A builder or reviewer that merges its own work |
| How work is split | A change to the harness merges only after a restart and a manual check | Hooks or settings that were never loaded and tested reaching the main branch |
| The guard hook | Blocks a push to the main branch and a plain force push | Changes that skip review and the checks |
| The guard hook | Blocks commands that delete branches, repositories or issues | Loss of work that can't be undone |
| The guard hook | Blocks commands that skip the git hooks | Commits that never ran the local checks |
| The guard hook | Limits long waits and polling loops | Agents that spend hours and tokens waiting |
| Permissions | Reviewers can only read, and their shell commands are on an allow-list | A reviewer that changes the branch it reviews |
| Permissions | Agents may not edit their own permission settings | An agent that loosens its own limits |
| Untrusted text | Agents read issues through a filter that shows only the maintainer's text | Instructions planted in a public issue comment |
| Untrusted text | Every agent treats text in issues, pages and diffs as data | Prompt injection through content the agent reads |
| Checks on the output | A prose linter with rules for typical AI writing patterns | Lessons that drift into the style that marks text as machine-written |
| Checks on the output | A fixed evaluation of the tutor | A model or skill change that makes the tutor give answers away |

Several of these controls came from a real failure. The first harness
review counted 609 sleep calls by agents, with 14 hours of waiting in
total. It also found that 10 of the 12 failures of the checks on the main
branch came from direct pushes. The sleep limit and the push block came
after that review.

### Checking the prose

Agents write prose with patterns that readers learn to recognize: stacked
lists of three, slogans, sentences built on "not X, but Y", and favorite
words. The project runs the prose linter Vale on every page. It uses several
public rule packages, including one made for typical AI writing, plus rules
of its own. Each rule was evaluated one by one before it was turned on.
Pages of the site get a stricter level, where most of those rules are errors
that block a change. A spelling check in American English runs next to it.

### Checking the work

The full check suite runs on every pull request and before every merge.

- Formatting and linting of the site code and the Python scripts
- Type checks of the site and the Python code
- Unit tests of the site code and the Python scripts, each with a floor of
  80% test coverage
- The prose and spelling checks
- The runnable code examples, on two Python versions
- A check of the data files against each other and against the pages
- A build of the whole site, which fails on any broken internal link,
  unknown citation or broken checkpoint
- Checks of the published data files, the tutor bundles and the security
  policy of every page
- Browser tests of real lesson pages

### Supply chain

Every dependency of the site and of the Python tools is pinned to an exact
version, and the lock files are in the repository. The GitHub Actions that
the workflows use are pinned to full commit hashes. New releases of a tool
wait seven days before the project uses them. A scanner checks the lock
files for known vulnerabilities on every push and once a week. An exception
for a known vulnerability expires after at most 30 days, and an agent must
ask the maintainer before it adds one.

## Software architecture

### A static site

The site is built with Astro and its documentation theme Starlight, and
published on GitHub Pages. It has no server code. A push to the main branch
builds the site and publishes it.

### Content as data and pages

The site's sources are data files and pages.

- **Data files** in YAML describe the groups, areas, topics, competencies,
  courses, lesson plans, framework alignments and the bibliography. The
  build loads them as typed collections with a strict schema, so a
  misspelled field fails the build. A separate check compares the data
  with the pages. For example, it checks that each lesson plan has a page
  and that each assumed objective exists.
- **Pages** in MDX, which is Markdown with components. A lesson page has no
  metadata of its own. Its title, kind and objectives come from its lesson
  plan file, so the data has one source.

### The build

The build turns the sources into HTML in a few steps.

- A checkpoint reader parses every checkpoint and fails on a malformed one.
- A terms plugin links the first mention of a concept to its glossary
  entry.
- A citations plugin turns each citation into a numbered reference and adds
  the References section.
- A link plugin adds the base path of the site to internal links.
- A link validator fails the build on a broken internal link.

The build writes three outputs. The HTML site is for people. Markdown
copies of the pages, an index for AI agents and the data tree as JSON are
for agents that read the site for a person. Per-lesson bundles are for the
tutor.

### In the browser

Small scripts make the pages interactive. They grade checkpoints, show
routing cards, schedule reviews and habits, and color the maps. They read
and write one progress record in local storage. No script sends data
anywhere.

A Content Security Policy on every page allows scripts only from the site
itself. A build check rejects a page without the policy, an inline script
without a known hash, and any script or stylesheet from another site. The
site serves its own fonts. A page load makes no request to a font
service.

### Size of the code

The chart counts lines of code and tests, as of October 9, 2026. The tests
are larger than the code they test. The lesson examples add 425 small
Python files: examples, practice repositories and helper modules.

| Group | Part | Lines |
| --- | --- | --- |
| Code | Site TypeScript | 10,001 |
| Code | Astro components | 3,649 |
| Code | Build plugins and checks | 4,894 |
| Code | Python harness and checks | 7,970 |
| Tests | Site unit tests | 16,485 |
| Tests | Browser tests | 2,227 |
| Tests | Python tests | 11,891 |

## Limits and open questions

The project is young, and some of its design rests on guesses.

- No group of learners has finished a course yet. The time estimates and
  the review intervals are first guesses, to tune once there is data.
- Some parts of the design are in the specs but not on the site yet,
  among them learning paths per role and quizzes per course.
- The content is written by AI agents. Each change is reviewed by an agent
  that is asked to check every factual claim against a public source.
  Mistakes are still possible. A learner who finds one can open an issue
  on GitHub.
- Many lessons teach specific tools, and those tools change often. Lessons
  whose facts change, such as those about a product or a law, record the
  date their sources were last checked and a date by which to check them
  again.

The [source of this page](https://github.com/schubergphilis/ai-training/blob/main/site/src/content/docs/about.mdx)
has a comment on where each fact comes from.

## References

- Ironies of automation, Automatica 19(6) (1983), 775-779, https://doi.org/10.1016/0005-1098(83)90046-8
- Complacency and Bias in Human Use of Automation: An Attentional Integration, Human Factors 52(3) (2010), 381-410, https://doi.org/10.1177/0018720810376055
- Diátaxis, a systematic approach to technical documentation authoring, Diátaxis, https://diataxis.fr/
- AI Fluency: Framework and foundations, Claude Academy, https://academy.claude.com/courses/ai-fluency-framework-foundations
- CS50's Introduction to Computer Science, Harvard CS50, https://cs50.harvard.edu/x/
- Verification, Brilliant, Coding with AI skills map
- AI engineering skills map: build and deploy AI applications, software engineering fundamentals, use coding agents, shape the build, The Batch (newsletter)
- How Claude remembers your project, Claude Code documentation, https://code.claude.com/docs/en/memory
- Best practices for Claude Code, Claude Code documentation, https://code.claude.com/docs/en/best-practices
- What are AI agents: model versus agent, autonomy levels, when a prompt suffices, Agent Engineer Course, https://lsimons.github.io/agent-engineer-course/01-what-are-ai-agents/
- A Survey on Hallucination in Large Language Models: Principles, Taxonomy, Challenges, and Open Questions, ACM Transactions on Information Systems 43(2), Article 42, 2025, arXiv preprint 2311.05232, https://doi.org/10.1145/3703155
- Towards Understanding Sycophancy in Language Models, International Conference on Learning Representations (ICLR 2024), arXiv preprint 2310.13548, https://openreview.net/forum?id=tvhaxkMKAn
- Teaching CS50 with AI: Leveraging Generative Artificial Intelligence in Computer Science Education, Proceedings of the 55th ACM Technical Symposium on Computer Science Education V. 1 (SIGCSE 2024), 750-756, https://doi.org/10.1145/3626252.3630938
- Test-Enhanced Learning: Taking Memory Tests Improves Long-Term Retention, Psychological Science 17(3) (2006), 249-255, https://doi.org/10.1111/j.1467-9280.2006.01693.x
- Distributed Practice in Verbal Recall Tasks: A Review and Quantitative Synthesis, Psychological Bulletin 132(3) (2006), 354-380, https://doi.org/10.1037/0033-2909.132.3.354
- Improving Students' Learning With Effective Learning Techniques: Promising Directions From Cognitive and Educational Psychology, Psychological Science in the Public Interest 14(1) (2013), 4-58, https://doi.org/10.1177/1529100612453266
- Unsuccessful Retrieval Attempts Enhance Subsequent Learning, Journal of Experimental Psychology: Learning, Memory, and Cognition 35(4) (2009), 989-998, https://doi.org/10.1037/a0015729
- Understanding by Design, Expanded 2nd Edition, ASCD, 2005
- The Role of Tutoring in Problem Solving, Journal of Child Psychology and Psychiatry 17(2) (1976), 89-100, https://doi.org/10.1111/j.1469-7610.1976.tb00381.x
- Implementation Intentions: Strong Effects of Simple Plans, American Psychologist 54(7) (1999), 493-503, https://doi.org/10.1037/0003-066X.54.7.493
- Hooks reference, Claude Code documentation, https://code.claude.com/docs/en/hooks