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/features/product-page.tell.mdSource
---
tell: feature/product-page
checks: [checks/shop.spec.ts]
face: [reference/product.png, tokens/brand.json]
recipe: recipes/product-photos.tell.md
rationale: [decision/one-voucher]
---
# Product page

## Intent
Buy a cast-concrete piece without
surprises: price, shipping and look
are settled before anyone pays.

## Behaviour fixed
C1 Orders from €50.00 ship free.
   → shop.spec#free-shipping
C2 A second voucher is declined
   with a notice.
   → shop.spec#one-voucher

## Face fixed
C3 Price and “Add to cart” stay in
   view without scrolling.
   → reference/product.png
C4 Every photo follows the recipe.
   → recipes/product-photos

## Why
decision/one-voucher: stacked
discounts were abused.

## Free
Layout, speed, stack, internal names.
Edition 45castwell.shop/pendant-no-3
castwell
LightingVasesBowlsCart (1)
C3

Lighting · cast concrete

Pendant No. 3

€89.00incl. VAT
Pale concrete
C1Ships free from €50.00
C2
LOYAL5

SUMMER10 is applied. One voucher per order.

Material
Cast concrete, sealed
Size
Ø 24 cm · 1.8 kg
Cable
2 m, braided green
Made
Berlin, by hand

From the same recipe

  • Vase No. 7€64.00
  • Bowl No. 2€48.00
  • Pendant No. 3€89.00

$ tell check --edition 45

  • C1free-shippingshop.spec.ts
  • C2one-vouchershop.spec.ts
  • C3price-in-viewreference/product.png
  • C4photo-reciperecipes/product-photos

4 of 4 statements hold

// Edition 4 · from tell/features/product-page.tell.md
export function ProductPage({ product, cart }) {
  const priced = usePrice(cart);               // C1
  const [notice, setNotice] = useState(null);

  async function redeem(code) {
    const res = await api.cart.redeem(cart.id, code);
    if (res.error === "cart.voucher.used") {   // C2
      setNotice(t("cart.voucher.used"));
    }
  }

  return (
    <main className="product">
      <Photo src={product.photo} />            // C4
      <aside className="buy">                  // C3
        <Price value={product.price} />
        <AddToCart product={product} />
        <Voucher onRedeem={redeem} notice={notice} />
      </aside>
    </main>
  );
}
// Edition 5 · from tell/features/product-page.tell.md
export const FREE_FROM = eur(50);              // C1

export async function redeem(cart: Cart, code: string) {
  if (cart.vouchers.length > 0) {              // C2
    return err("cart.voucher.used");
  }
  return ok(price(await cart.apply(code)));
}

export const ProductPage = ({ product }: Props) => (
  <main className="product">
    <Gallery photos={product.photos} />        // C4
    <BuyPanel sticky>                          // C3
      <Price value={product.price} />
      <AddToCart product={product} />
    </BuyPanel>
  </main>
);
product-photosrecipe · 3 photos
product.pngscreen reference
brand.jsontokens · 4 colours
4/4 statements hold

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.

Five concrete columns, each a worse copy of the one before
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

  1. 3 of 3rebuild 1
  2. 3 of 3rebuild 2
  3. 2 of 3rebuild 3
  4. 1 of 3rebuild 4
  5. 0 of 3rebuild 5
Five identical concrete columns in front of their open mould
Cast from the TellscriptEach rebuild starts from the same mould. The shape stays; only the finish gets better.

Cart rules still holding

  1. 3 of 3rebuild 1
  2. 3 of 3rebuild 2
  3. 3 of 3rebuild 3
  4. 3 of 3rebuild 4
  5. 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.

OpenAIAnthropicGooglexAIMetaDeepSeekAlibabaMoonshotZ.aiMistral
1,2001,3001,4001,5001,6001,7001,800Jul 2025Oct 2025Jan 2026Apr 2026Jul 2026todayGPT-5Claude Opus 4.5Claude Fable 5GPT-6 AstraClaude Opus 5.51,827 · rebuilt1,660 · best open1,493 · code from Nov 2025
Best model at the time: what a rebuild from the Tellscript gets Best open model Code written once, in November 2025

Today, per lab

  1. 1Claude Opus 5.5Anthropic · Sep 20261,827
  2. 2GPT-6 AstraOpenAI · Sep 20261,792
  3. 3Qwen3.8 MaxAlibaba · Sep 20261,662
  4. 4Kimi K3Moonshot · Jul 2026open1,660
  5. 5Muse Spark 1.3Meta · Sep 20261,656
  6. 6Grok 4.7xAI · Sep 20261,629
  7. 7DeepSeek V4.1 FlashDeepSeek · Sep 2026open1,621
  8. 8GLM 5.3Z.ai · Sep 2026open1,619
  9. 9MiMo-V2.6-ProXiaomi · Sep 2026open1,618
  10. 10Gemini 3.7 FlashGoogle · Aug 20261,593
  11. 11MiniMax M3MiniMax · May 2026open1,483
  12. 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
  1. 2008jQuery · by hand
  2. 2015AngularJS · by an agency
  3. 2019React · in-house
  4. 2026TypeScript · by an agent
  5. 2034Generated · a forecast
cart.tell.mdStays
---
tell: feature/cart
binds: [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.

## Behaviour fixed
C1 When the goods reach €50.00,
   shipping is free.
   → cart.spec#free-shipping
C2 When a second voucher arrives,
   it is declined with a notice.
   → cart.spec#one-voucher

## Face fixed
C3 The total stays visible, top right.
   → reference/cart.png · text cart.total

## Build guided
The server computes prices. Framework open.

## Why
decision/one-voucher: stacked discounts
were abused. Rejected: a limit per customer.

## Free
Speed, internal names, accessibility.

2008 · edition 1 keeps C1, C2 and C3

2008jQuery · by hand

Search products…Cart total: €80.10
HomeShopLightingVasesBlogContact

Home » Shop » Shopping Cart

  1. 1. Cart
  2. 2. Address
  3. 3. Payment
  4. 4. Confirm

Shopping Cart

ItemQtyPrice
Pendant No. 3Pale concreteRemove1€89.00
Update cart« Continue shopping

Customers who bought this item also bought

Vase No. 7€64.00Add to cart
Bowl No. 2€48.00Add to cart
Bookmark: del.icio.usDigg itStumbleUpon

Order summary

Subtotal
€89.00
Voucher SUMMER10
−€8.90
Shipping
FREE!

Total€80.10

LOYAL5Redeem

! One voucher only!

Proceed to Checkout » PayPal

128-bit SSL · Visa · MasterCard

FREE shipping over €49.99!

© 2008 Castwell · Best viewed in Firefox 3 at 1024 × 768

2015AngularJS · by an agency

CastwellLightingVasesBowlsJournal€80.10

Your cart1 item

Pendant No. 3Pale concrete−1+Remove
€89.00
‹ Continue shopping

Customers also bought

Vase No. 7€64.00
Bowl No. 2€48.00
Pendant No. 3, dark€89.00

Order summary

LOYAL5Apply
Only one voucher per order.
Subtotal
€89.00
Voucher SUMMER10
−€8.90
Shipping
FREE

Total€80.10

Checkout fContinue with Facebook

Secure checkout

Get 10% off your first order

Your emailSign up
f t P

2019React · in-house

Cart€80.10C
Pendant No. 3Pale concreteQty 1 ▾
€89.00

You’ve reached free shipping

Recommended for you

Vase No. 7€64.00
+
Bowl No. 2€48.00
+
Pendant No. 3, dark€89.00
+
Voucher codeLOYAL5
Subtotal
€89.00
Voucher SUMMER10
−€8.90
Shipping
Free

Total€80.10

Klarna.3 payments of €26.70

Buy with Apple PayCHECKOUT
Only one voucher per orderOK

2026TypeScript · by an agent

Pendant lamp in pale cast concrete castwellIn your room
Lighting / Pendants€80.10

Pendant No. 3

€89.00Cast by hand in Berlin
Pale concrete
Free shippingfrom €50 · arrives Thu 1 Oct
SUMMER10 −€8.90LOYAL5

One voucher per order. SUMMER10 stays.

From the same recipe
Pay €80.10 with passkey

or let your agent pay, up to €100

2034Generated · a forecast

castwellComposed for you · 20:14

Total, settled€80.10

You, spoken

“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 matterMeaning
tellName and level: product/, feature/, contract/ or a file
bindsContracts this feature touches
checksChecks every statement is bound to
faceReference images and design tokens for the look
recipeHow pictures are made: model, brief, references
rationaleDecisions that keep the why
proofProof level and the edition that reached it
LayerContentExample
01 IntentWhat is it for?
Purpose, users, terms, principles, budgets for speed, accessibility and costP1 Prices always show shipping.
02 BehaviourWhat must happen?
Flows as numbered when-then statements, each with its checkC1 Orders from €50.00 ship free.
03 ContractsWhat do others rely on?
Routes, API types, tables, storage keys, events; byte-exactPOST /api/cart/voucher
04 FaceWhat do people recognise?
Design tokens, components, texts with stable ids, reference images per statereference/product.png
05 RationaleWhy is it so?
Decisions with rejected alternatives, lessons from failures, each with a checkdecision/one-voucher
06 RecipesHow is content made?
Brief, prompt, model, references and parameters for images, texts and datarecipe/product-photos
+ ProofDoes it still hold?
Checks, reference images and recorded flows; every statement above points hereshop.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.

Download castwell.tell.md

Read the format reference

From statement to proof

Every rule points to the test that checks it.

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
## Behaviour fixed
C2 A second voucher is declined
   with a notice.
   → shop.spec#one-voucher

## Why
decision/one-voucher: stacked
discounts were abused.
shop.spec.tsCheck
// checks/shop.spec.ts
test("one-voucher", async ({ cart }) => {  // C2
  await cart.redeem("SUMMER10");
  const second = await cart.redeem("LOYAL5");
  expect(second.error).toBe("cart.voucher.used");
  await expect(cart.notice)
    .toHaveText(t("cart.voucher.used"));
});
tell checkResult
Edition 3 · from old code
  ✓ C1 free-shipping
  ✗ C2 one-voucher
    second voucher accepted
  ✓ C3 price-in-view

Edition 5 · from the Tellscript
  ✓ C1 free-shipping
  ✓ C2 one-voucher
  ✓ C3 price-in-view
  ✓ C4 photo-recipe
  1. DescribedWritten from the code or by hand.
  2. BoundEvery statement has a check that fails when it no longer holds.
  3. ProvenA model from another lab rebuilt it and passed every check.

How checks and proof work

Rings

Fixed, what must stay. Free, what may improve.

Every section carries a ring, every rule its reason. So the agent knows what it may improve, what it should propose and what it leaves alone.

FixedBehaviour, contracts, look, texts. Changes only through a decision.
GuidedStack, architecture, libraries. The model proposes, with a measurable gain; accepting it becomes a decision.
FreeImplementation, internal names, algorithms. Every edition may improve it without asking; only the checks decide.

What each ring allows

Session · product pageExample
You

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-photos
model: gpt-image-2.5 · sunburst · 2K
refs: [brand/BRAND.md#photography]
lineage: every photo from this brief
---
# Product photos

## Style fixed
Black-and-white studio photograph,
cast concrete on seamless pale grey.
Key light upper left, 45 degrees.
One colour only: signal green, one detail.

## Why
Green means one thing: what stays.

## Subject free
One 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.
Or install the skill
npx skills add tellscript-dev/tellscript
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.

What you can do with it

Seven moments when consistency pays

A concrete staircase of identical steps, the top edge green

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.