How Tamago was built and checked: the agents and their rules, who it’s for, what the model does, and how the work is tested.
01 — Agent Stories
Tamago was built by a small team of AI agents. Each has one job, written down the same way.
The is a little more definition around the interactions or decisions made by an agent to help the user go in a desired direction or reach goals.
As [who], when [trigger], I want [goal], so that [outcome].
It may: [the actions and tools it gets]
It must never: [hard rules]
It decides: [what’s left to the model’s judgment]
It stops when: [what counts as done, plus limits]
I’ll know it works when: [the test and the number]
| Story element | The Planner’s agent story |
|---|---|
| As / when / I want / so that | As the person orchestrating the build, when I think out loud in voice notes, I want them turned into specs and labeled instructions, so that each agent gets one clear task. |
| It may |
|
| It must never |
|
| It decides |
|
| It stops when |
|
| I’ll know it works when |
|
| Story element | The Builder’s agent story |
|---|---|
| As / when / I want / so that | As the person orchestrating the build, when I hand over a spec or a batch of notes, I want working code and course content, tested and live, so that I can judge the result instead of supervising the work. |
| It may |
|
| It must never |
|
| It decides |
|
| It stops when |
|
| I’ll know it works when |
|
| Story element | The Judge’s agent story |
|---|---|
| As / when / I want / so that | As the person orchestrating the build, when a builder finishes a course part or a screen, I want an independent review, so that the builder isn’t grading its own work. |
| It may |
|
| It must never |
|
| It decides |
|
| It stops when |
|
| I’ll know it works when |
|
| Story element | The Debugger’s agent story |
|---|---|
| As / when / I want / so that | As the person orchestrating the build, when something breaks on a real device, I want one fresh session on that one bug, so that the fix comes with a cause and a test. |
| It may |
|
| It must never |
|
| It decides |
|
| It stops when |
|
| I’ll know it works when |
|
Tamago’s team is agents, not a pipeline. Each one plans its own steps inside written rules.
The rules live in one file that every session reads first, so every change to them is tracked.
02 — Product Definition
This section defines the product: who it helps, who it hands to teachers and real exams, and where it stops.
03 — Model Scope
The lessons are fixed, checked content. The model steps in only where a live answer helps: conversation, explanations and notes on writing.
In and Out of Model’s Scope
| Category | Do | Avoid |
|---|---|---|
| Facts | Definitions and verb forms from Wiktionary | Model memory |
| Vocabulary | Words the learner has met | Words past their level |
| Corrections | Two or three, after the conversation | Interrupting to correct |
| Speaking | Listen, record, compare | Grading pronunciation |
| Asking for help | Repeat, slow down, spell, explain, in the language | Switching to English |
| Feedback | One word and the right answer | Praise screens, streak pressure |
| Progress | Honest numbers | Predicting an exam result |
The pattern across every row: the model sets up the practice and reports honestly.
It never does the learning for the learner, and it never invents the facts.
04 — Behavioral Spec
Everything that tells the agents and the product how to behave. About 13,000 words of English, no code.
| Part | File | Words | What it does |
|---|---|---|---|
| Working Mode and Stop Rules | CLAUDE.md |
110 | When the builder works alone and when it stops for me. |
| Team | CLAUDE.md |
297 | Who does what: planner, builders, judge, debugger. |
| Push and Testing Rules | CLAUDE.md |
1,215 | Pull before every push, the fast tier, the full suite on GitHub after. |
| Content Rules | CLAUDE.md |
708 | Checked sources first, facts from Wiktionary, the review before any swap. |
| Craft Rubric | _source/craft-review.md |
746 | Nine criteria the judge scores each screen against. |
| Autonomous Build Rules | _source/autonomous-build.md |
568 | How an unattended overnight run starts, reports and stops. |
| Learning Methods | _source/learning-methods.md |
2,856 | The teaching research the course design has to answer to. |
| Question Types | _source/question-types.md |
1,366 | Every question type and what it asks of the learner. |
| Feature List | _source/tamago-feature-list.md |
2,709 | What the product does, feature by feature. |
| Model Story | _source/model-story.md |
1,657 | What the model is for, and where it stops. |
| Conversation Partner Prompt | server/converse.mjs |
541 | Runs a short conversation at the learner’s level and answers the help phrases. |
| End-of-Conversation Review | server/converse.mjs |
15 | Picks the two or three most useful gentle corrections once the scene is over. |
| Writing Notes Prompt | server/converse.mjs |
42 | Notes on meaning, grammar and missing points. Not a score. |
| Explanation Prompt | server/explain.mjs |
112 | Explains one wrong answer in plain words. |
| Self-Study Prompt | server/generate.mjs |
61 | Turns the learner’s request into practice that fits the question types. |
| Total | 13,003 |
Counted on 17 November 2026 from the repo, not estimated. CLAUDE.md is read first by every session,
so a rule changed there reaches the next agent without anyone being told.
05 — Evaluation
Each row takes one industry term and points to the piece of this project that does that job, with a link to the tool or artifact.
| Industry Term | Project Artifact | Status |
|---|---|---|
| Every lesson of every course, built and walked: 123,247 questions in French, 116,809 in German, 110,967 in Spanish | Built: Every-Lesson Check (opens in a new tab) | |
| Nine craft criteria scored 1 to 5, from “no dead time” to “obvious in one second” | Built: Craft Review (opens in a new tab) | |
| An independent model session reviews every sentence batch and screen. It changes no code, and a person has the final word | Built: Quality Pass | |
| A verdict on every sentence (Use, Reject, Keep, Fix, Cut), each with a reason | Built: Quality Pass | |
| Every new word is shown before it’s tested, across 14,355 lessons in five courses. The exception is 83 words that look the same in English, like taxi and train. No lesson adds more than four new words. | Built: Word Audit (opens in a new tab) | |
| Every fixed bug gets a test that fails without the fix. 43 test files | Built: Test Suite (opens in a new tab) | |
| A script taps through a real lesson on a simulated iPhone and iPad before every push | Built: Pre-Push Check (opens in a new tab) | |
| A fast check before each push (about 30 seconds for an engine-only change, 6.5 minutes for a French content change), the full suite on GitHub after | Built: GitHub Actions (opens in a new tab) | |
| Coverage of official A1 word lists: French 97% of the core 600, German 91%, Spanish 90% | Built: Coverage Report (opens in a new tab) | |
| A small model runs the live features, with a daily cap per device and a monthly limit | Built: Conversation Partner (opens in a new tab) | |
| Learner flags (“my answer should be accepted”) collected for review | In Progress | |
| Native speakers checking the drafted sentences | Planned |