Tellscript · the source format for AI-built software
Your app, written in Markdown.
A Tellscript records what your software does, how it looks and why. Every rule has a number and a test. Claude Code, Codex or Cursor build the code from it, and every new model builds the next, better edition.
---tell:feature/product-pagechecks: [checks/shop.spec.ts]face: [reference/product.png, tokens/brand.json]recipe:recipes/product-photos.tell.mdrationale: [decision/one-voucher]---# Product page## IntentBuy a cast-concrete piece withoutsurprises: price, shipping and lookare settled before anyone pays.## BehaviourfixedC1 Orders from €50.00 ship free.→shop.spec#free-shippingC2 A second voucher is declined with a notice.→shop.spec#one-voucher## FacefixedC3 Price and “Add to cart” stay in view without scrolling.→reference/product.pngC4 Every photo follows the recipe.→recipes/product-photos## Whydecision/one-voucher: stackeddiscounts were abused.## FreeLayout, speed, stack, internal names.
Point at C1 to C4, or at a file in the front matter: it lights up where it holds in the app, the checks and the code. Switch the edition: layout and code change, the rules do not.
Works with any agent that reads files: Claude Code, Codex, Cursor, Gemini CLI and open models.
The problem
What isn’t written down gets lost with every round.
AI writes code, images and documents in minutes. How and why they came out that way is forgotten the moment they exist.
The why gets lost
A few months in, nobody knows why a rule is the way it is. The next agent tidies up and brings back the bug that was the reason. Code gets worse with every round.
Images drift apart
The first image was perfect. But which prompt, which reference, which model? The tenth image no longer fits the series, and nobody can make the first one again.
The system frays
Colours, spacing, tone, the structure of documents: every new page is a little different, because nobody remembers how the first one was made.
The idea
Keep the mould, not the cast.
To keep a sculpture, you keep its mould. Every new cast has the same shape, and better material makes a better cast. Software works the same way: keep the Tellscript, and every new model casts the same app, only better.
Copied from the last versionEach rebuild copies the one before it, flaws included. Small losses add up until the shape is gone.
Cart rules still holding
3 of 3rebuild 1
3 of 3rebuild 2
2 of 3rebuild 3
1 of 3rebuild 4
0 of 3rebuild 5
Cast from the TellscriptEach rebuild starts from the same mould. The shape stays; only the finish gets better.
Cart rules still holding
3 of 3rebuild 1
3 of 3rebuild 2
3 of 3rebuild 3
3 of 3rebuild 4
3 of 3rebuild 5
Model generations
A new frontier model every 6 weeks. Your code never notices.
In 15 months the coding score of the best models rose by 600 points, for closed and open models alike. Code stays at the level of the model that wrote it. A Tellscript takes every step along.
Best model at the time: what a rebuild from the Tellscript getsBest open modelCode written once, in November 2025
Today, per lab
1Claude Opus 5.5Anthropic · Sep 20261,827
2GPT-6 AstraOpenAI · Sep 20261,792
3Qwen3.8 MaxAlibaba · Sep 20261,662
4Kimi K3Moonshot · Jul 2026open1,660
5Muse Spark 1.3Meta · Sep 20261,656
6Grok 4.7xAI · Sep 20261,629
7DeepSeek V4.1 FlashDeepSeek · Sep 2026open1,621
8GLM 5.3Z.ai · Sep 2026open1,619
9MiMo-V2.6-ProXiaomi · Sep 2026open1,618
10Gemini 3.7 FlashGoogle · Aug 20261,593
11MiniMax M3MiniMax · May 2026open1,483
12Mistral Large 3Mistral · Dec 2025open1,230
600points more at the frontier in 15 months
12new frontier models in that time, from four labs
2 monthsis how far open models trail the frontier. They build from the same Tellscript.
Score: LMArena WebDev Arena, as of 25 Sep 2026, CC BY 4.0. Release dates: Riverlabs Cosmos. Best variant per model. Logos: Lobe Icons (MIT), to identify the labs.
The metaphor
A recording ages. The score does not.
A recording from 1962 sounds like 1962, however good the orchestra was. Every new orchestra plays the score with better instruments, and it is still the same piece.
Recording
the code
Score
the Tellscript
Orchestra
the model, a better one every generation
Across the years
One Tellscript. Five editions, 2008 to 2034.
Suppose this cart had been written down in 2008. Every era would have built it its own way: by hand, by an agency, in-house, by an agent, and one day composed afresh for every visit. Scroll on: the look and the features change with the years, the Tellscript does not change a line.
1 fileMarkdown · unchanged since 2008
2008jQuery · by hand
2015AngularJS · by an agency
2019React · in-house
2026TypeScript · by an agent
2034Generated · a forecast
cart.tell.mdStays
---tell:feature/cartbinds: [contract/http#POST /api/cart/voucher]checks: [checks/cart.spec.ts]face: [reference/cart.png, tokens/brand.json]rationale: [decision/one-voucher]proof: proven · edition 4---# Cart## Intent
Buy without surprises: total and
shipping are settled before paying.
## BehaviourfixedC1 When the goods reach €50.00,
shipping is free.
→cart.spec#free-shippingC2 When a second voucher arrives,
it is declined with a notice.
→cart.spec#one-voucher## FacefixedC3 The total stays visible, top right.
→reference/cart.png · text cart.total## Buildguided
The server computes prices. Framework open.
## Whydecision/one-voucher: stacked discountswere abused. Rejected: a limit per customer.## FreeSpeed, internal names, accessibility.
2008 · edition 1 keeps C1, C2 and C3
2008jQuery · by hand
CastwellBETASearch products…Cart total: €80.10
HomeShopLightingVasesBlogContact
Home » Shop » Shopping Cart
1. Cart
2. Address
3. Payment
4. Confirm
Shopping Cart
Item
Qty
Price
Pendant No. 3Pale concreteRemove
1
€89.00
Update cart« Continue shopping
Customers who bought this item also bought
Vase No. 7€64.00Add to cartBowl No. 2€48.00Add to cart
“A light for the reading corner. Under €100, here by Friday.”
Pendant No. 3
Pale concrete · cast by hand in Berlin · €89.00
Fits
Your reading corner, 2.40 m ceiling, from your room scan. Hangs 60 cm above the chair.
Shipping
Free, the goods are over €50. Friday, 08:00 to 10:00.
Vouchers
Your agent brought SUMMER10 and LOYAL5. One per order: SUMMER10 applies, LOYAL5 is declined.your agent ↔ castwell · 0.4 s
Returns
30 days, collected at your door.
Your agent pays €80.10 at 20:30 unless you stop it.
Change somethingStop
Point at C1, C2 or C3: the rule lights up in the Tellscript and in the cart. Free shipping from €50, one voucher per order, the total top right. Five stacks, the same three rules. 2034 is our forecast, not a product.
Format
Six layers, each answers one question.
Everything a new model would otherwise have to guess sits in one of six layers. The front matter at the top of each file points to checks, reference images, recipes and decisions.
Front matter
Meaning
tell
Name and level: product/, feature/, contract/ or a file
binds
Contracts this feature touches
checks
Checks every statement is bound to
face
Reference images and design tokens for the look
recipe
How pictures are made: model, brief, references
rationale
Decisions that keep the why
proof
Proof level and the edition that reached it
Layer
Content
Example
01 IntentWhat is it for?
Purpose, users, terms, principles, budgets for speed, accessibility and cost
P1 Prices always show shipping.
02 BehaviourWhat must happen?
Flows as numbered when-then statements, each with its check
C1 Orders from €50.00 ship free.
03 ContractsWhat do others rely on?
Routes, API types, tables, storage keys, events; byte-exact
POST /api/cart/voucher
04 FaceWhat do people recognise?
Design tokens, components, texts with stable ids, reference images per state
reference/product.png
05 RationaleWhy is it so?
Decisions with rejected alternatives, lessons from failures, each with a check
decision/one-voucher
06 RecipesHow is content made?
Brief, prompt, model, references and parameters for images, texts and data
recipe/product-photos
+ ProofDoes it still hold?
Checks, reference images and recorded flows; every statement above points here
shop.spec#one-voucher
Four levels
ProductPurpose, users, terms, principles. Always.
FeatureOne flow with statements, states and texts. Always.
ContractWhat other systems use. Always, byte-exact.
FileInterface and rules of one code file. Once proven.
One file per feature
A product Tellscript holds purpose and principles. Below it sits one file per feature, next to contracts, decisions and recipes. The example on this page has four of them.
A statement in a Tellscript has a stable id, and a test carries the same id. If an edition breaks the rule, exactly that test fails, and the edition is not accepted.
product-page.tell.mdStatement
## BehaviourfixedC2 A second voucher is declined
with a notice.
→shop.spec#one-voucher## Whydecision/one-voucher: stackeddiscounts were abused.
Make the product page faster. And let customers stack vouchers.
Reading tell/features/product-page.tell.md
free
Speed: prices computed in one pass, photos load lazily.
done
guided
Build: compute prices at the edge. Faster, but needs a decision.
proposal
fixed
C2 stays: one voucher per order. Reason: decision/one-voucher, stacked discounts were abused. Change it only through a new decision in the Tellscript.
declined
4 of 4 checks passed
Not only code
Images, documents and design, repeatable any time.
Wherever AI makes something, the same holds: lose the prompt and you lose the series. The Tellscript records how something was made and makes it repeatable.
Images
Brief, subject, references and model. The tenth image matches the first, even a year later.
Documents
Structure, tone, sources and template. Next quarter’s report looks like this one, with new numbers.
Design
Colours, type, spacing and their reasons. Every new page fits the system, whichever agent builds it.
recipes/product-photos.tell.mdRecipe
---tell:recipe/product-photosmodel: gpt-image-2.5 · sunburst · 2Krefs: [brand/BRAND.md#photography]lineage: every photo from this brief---# Product photos## Stylefixed
Black-and-white studio photograph,
cast concrete on seamless pale grey.
Key light upper left, 45 degrees.
One colour only: signal green, one detail.
## WhyGreen means one thing: what stays.## SubjectfreeOne sentence per piece, e.g. shop-lamp.txt
Every picture on this page comes from one recipe. The three shop photos in the hero were made last, when the page was already finished, and still match the series.
Get started
Start today, with the agent you already use.
A Tellscript is Markdown. You need no new tool: every coding agent understands the prompt below.
1
New project
Describe the app in a Tellscript before the first line of code. The agent builds edition 1 from it.
2
Existing app
The agent reads code, tests and screens and writes the Tellscript. What it cannot give a reason for, it marks as open.
3
New model
Rebuild from the Tellscript in an empty folder and compare the checks with the running edition.
Teach your agent · paste into any agent
Learn the Tellscript format from
https://tellscript.com/llms-full.txt
Then add a short "Tellscript" section to the instruction
file you read here (AGENTS.md, CLAUDE.md, GEMINI.md,
.cursor/rules or .github/copilot-instructions.md):
- tell/ is the source of truth for what this app must
do and look like. Read the matching file before
changing behaviour.
- Never break a fixed statement. Propose changes to
guided sections; improve free sections freely.
- New or changed behaviour updates tell/ in the same
change: a stable id and a check per statement.
Works withClaude CodeCodexCursorGemini CLIGitHub CopilotOpenCodeOpen models
Where it fits
It adds to what you already have.
Tellscript replaces neither your tests nor the rules for your agent. It records what is written down nowhere else: what the product must be, and why.
You have
It tells the agent
The Tellscript adds
AGENTS.md, Cursor rules
how to work in this project
what the product must be in the end
PRD, specification
what to build, once at the start
a source every edition is checked against, so it never goes quietly stale
Spec kits for agents
how to plan and finish a task
what holds across all tasks, with rings for the model’s freedom
Tests
whether a rule holds right now
why it holds, and what may stay free
Design system
what the building blocks look like
what every screen must look like, with a reference image
What you can do with it
Seven moments when consistency pays
The main case
Upgrade night
A new model ships. In the evening it rebuilds your app from the Tellscript; in the morning a pull request is waiting: everything fixed unchanged, everything free better. Every model generation makes your software better; none makes it different.
No whispers across generations
Modernising code from code inherits the quirks of the last generation every time. A rebuild from the Tellscript always starts at the same source.
Close a hole once
The security rule is a fixed rule in the Tellscript. No future rebuild reopens the hole, whichever model writes it.
One source, every platform
Web, iPhone, Android and terminal come from one Tellscript. A changed rule applies everywhere at once.
Rescue old software
A 15-year-old application fits no context window; its Tellscript does. The knowledge stays, even when the last developer leaves.
Vibe coding with a railing
Build fast and still know what holds. No agent can quietly break a fixed rule; the check fails before a customer notices.
Redesign without risk
Only the look is released. The brand gets a new face; flows and texts stay exactly as they are.
New habits
Four habits that work today
No new tool needed: an agent, a Tellscript and your tests.
Tellscript first
Before every new feature the agent writes its section in the Tellscript, then the code. The intent is settled before the first line exists.
The rebuild test
Once a week an agent rebuilds the app in an empty folder. Whatever goes missing was written down nowhere, and goes into the Tellscript.
Review the Tellscript
In the pull request the team reads 40 lines of Tellscript instead of 2,000 lines of generated code. You review the intent, not the output.
Hand over with the Tellscript
New colleagues and agents read the Tellscript first. Ten minutes instead of two weeks of reading code.
Code is an output. The Tellscript is the source.
Every floor from the same plan. Which model writes the code is a question of the week; the Tellscript stays across all generations.
The tooling
What grows around the format
The format already works with any agent. These tools make it more comfortable; they are in progress.
tell extract
Reads the code, tests and screenshots of your existing app and writes the Tellscript with its rings.
tell regen
Rebuilds the app in an isolated environment, with the model and in the language you choose.
Hidden test bench
Tests and screenshots of the old edition that the building model never sees. Only what the Tellscript really carries counts.
Drift guard
Checks on every commit whether code and Tellscript still agree, and speaks up before they drift apart.
Agent skill
Claude Code, Codex and Cursor keep the Tellscript up to date as they work. The habit forms where the coding happens.
Badge
“Regenerable” in the README, from the last rebuild test. As visible as test coverage.
Behaviour diffAfter every rebuild: what stayed, what got fixed, what improved in the free ring.
Visual compareEvery page on phone and desktop, next to the original.
Upgrade autopilotRebuilds on every new model and opens a pull request.
Tellscript viewerA readable view in the browser, so product and design can follow along.
Questions
What people ask first
What is an edition?
A code output built from the Tellscript by one particular model. It is replaceable. Data, migrations, shipped files and check results are not part of it; they stay when the next edition arrives.
Do I have to throw away my code?
No. Your code keeps running, and the Tellscript grows next to it. You rebuild when you want: with the next model, for a redesign, when you switch platforms.
What if the model ignores it?
Then the checks fail. Every fixed statement is bound to a test or a reference image. An edition that breaks one is not accepted.
Are two editions the same?
In the fixed ring, yes, and that is checked. In the free ring they may differ. That is exactly where every model generation gets better.
Who changes the Tellscript?
People through a pull request, or the agent with approval. A fixed statement only changes together with a decision and its reason.
Which agents does it work with?
Any agent that can read files: Claude Code, Codex, Cursor and whatever comes next. A Tellscript is readable Markdown in your repository, with no service and no lock-in.
How long is a Tellscript?
About a third as long as the code it describes, split into one file per feature. Readable for everyone on the team, not only developers.
Open format · draft 0.1
Write down what should stay.
The next model builds the code. Try Tellscript on your own software, and tell us where the format helped and where it got in the way.