Introduction

Tellscript is an open format for the part of your software that should outlive its code. A Tellscript is a folder of Markdown files next to your code. It records what the product must do, how it must look, what other systems rely on and why things are the way they are. Every rule has a stable id and a check that fails when the rule breaks.

Any coding agent can read it. Claude Code, Codex, Cursor, Gemini CLI or an open model builds the code from it, and when a better model arrives, it builds the next edition of the same app: the fixed rules stay, the free parts get better.

Why a new format

AI writes code, images and documents in minutes. How and why they came out that way is forgotten the moment they exist. The next agent tidies up and brings back the bug that was the reason for an odd rule. The tenth image no longer matches the first. Every rebuild copies the last one, flaws included.

Tellscript keeps the mould instead of the cast. The code becomes an output you can throw away; the Tellscript is the source.

How it works

1. Write it down. One file per feature: intent, numbered statements, the look as a reference image, the reasons as decisions.
2. Bind it. Every statement points to the test, reference image or recipe that proves it.
3. Build and rebuild. Any agent builds an edition from the Tellscript. The checks decide whether it is accepted.

## 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

What is in these docs