Under construction — everything on this page is draft content.

System Card for Tamago

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.

One Job Each,
Written Down


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]

The Planner’s agent story
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.
  • Collect my notes
  • Write specs
  • Write one labeled instruction per agent
  • Keep the project record
  • Touch the code
  • Send instructions while I’m still giving notes
  • Present a guess as a fact
  • What goes in a batch
  • Which agent gets it
  • What waits
  • The instruction is written and labeled for one agent
  • The builder needs no follow-up questions
  • The checklist that comes back matches what I asked for
The Builder’s agent story
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.
  • Read the spec and the project rules
  • Write code and course content
  • Run tests and audits
  • Push to the live site
  • Spend money or create accounts
  • Make anything public or delete data without me
  • Take facts from model memory
  • Swap in content before the judge’s review
  • Push without pulling and testing first
  • How to build it
  • Which checked sentences fit a lesson
  • When to stop and ask
  • The batch is live with a Live / Not Done checklist, or a stop rule is reached
  • Every push passes the tests
  • Both content audits are clean
  • The checklist matches the request
The Judge’s agent story
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.
  • Read every new sentence and screen
  • Mark each one Use, Reject, Keep, Fix or Cut
  • Score screens against the craft rubric
  • Check facts against Wiktionary
  • Change code
  • Write outside the review folder
  • Claim a native speaker’s authority
  • Whether a sentence is natural, correct and right for A1
  • The fix or the swap
  • The craft score
  • The review file is written, with counts for each verdict
  • Every part is reviewed before it’s swapped in
  • Each fix names the line, the correction and the reason
  • The audits stay clean after the fixes
The Debugger’s agent story
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.
  • Reproduce the bug on a simulated iPhone and iPad
  • Read the code
  • Fix it
  • Add a test
  • Ship a guess
  • Fix more than its one bug
  • Touch another agent’s unfinished work
  • The cause
  • Whether it can be shown
  • What only a real phone can confirm
  • The fix is live with its test, or it reports that the cause wasn’t found and what it needs from the phone
  • The new test fails without the fix
  • The bug doesn’t come back

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.

Who This Helps,
Who It Doesn’t


This section defines the product: who it helps, who it hands to teachers and real exams, and where it stops.

Where it helps

  • Adults starting French, German or Spanish from zero
  • Getting from reading to first conversations
  • Learners who stalled on gamified apps
  • Practicing for the DELF, DELE or Goethe A1 exam
  • Reaching A1 with an honest measure of progress
  • Self-directed study with no locks or streaks
  • Ten-minute daily lessons
  • Travel tasks: ordering, directions, forms

Where it might help

  • A2 learners reviewing the basics
  • Classroom learners who want extra practice
  • Heritage speakers filling gaps in reading and writing
  • Italian and Brazilian Portuguese (courses still in progress)
  • Listening at natural speed
  • Pronunciation (record and compare, never graded)
  • Spain’s Spanish (the course teaches Latin American Spanish)

Where it hands off

  • Anything needing a native speaker’s ear (the content is AI-reviewed, not yet native-checked)
  • B1 and above
  • Certified proof of level (the official exams)
  • Children under 13
  • Graded pronunciation and accent coaching
  • Languages in other alphabets (Arabic, Greek, Asian languages)
  • Live conversation with a person (tutors, language exchanges)
  • Professional language (legal, medical, business)

How We Guide the Model,
How the Model Guides the Learner


The lessons are fixed, checked content. The model steps in only where a live answer helps: conversation, explanations and notes on writing.

  • Model GoalHelp learners practice real conversation at their level.

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.

Behavioral Spec Inventory


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.

What the Agents Get Right,
How We Know


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