# Tellscript

> A Tellscript records what your software does, how it looks and why, with numbered rules and tests. Any AI agent builds the code from it, and every new model a better edition.

A Tellscript is a folder `tell/` of Markdown files (`*.tell.md`) next to the code: one file per product, feature, contract and recipe. Each file has front matter (tell, checks, face, rationale, proof), sections (Intent, Behaviour, Face, Why, Free), numbered statements with stable ids (C1, P1) and a `→` line to the check that proves each one, and a ring per section: fixed (rebuilt exactly), guided (propose with a measurable gain), free (improve freely). Agents never break a fixed statement, and update `tell/` in the same change as the code.

## Docs

- [Introduction](https://tellscript.com/docs.md): Tellscript is an open Markdown format that records what your software must do, how it looks and why, so any AI agent can build it and every new model can rebuild it better.
- [Quickstart](https://tellscript.com/docs/quickstart.md): Write your first Tellscript in an afternoon, with the coding agent you already use. One prompt, five steps, one rebuild test.
- [Teach your agent](https://tellscript.com/docs/agents.md): Make Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot or any other coding agent read, write and respect your Tellscript, with one file or one prompt.
- [Files and folders](https://tellscript.com/docs/files.md): A Tellscript is a folder called tell/ in your repository, with one Markdown file per product, feature, contract and recipe, plus decisions and reference images.
- [Front matter](https://tellscript.com/docs/front-matter.md): The block at the top of every Tellscript file names it and points to its checks, contracts, reference images, recipes and decisions.
- [Layers](https://tellscript.com/docs/layers.md): Six layers, each answering one question a new model would otherwise have to guess, plus the proof layer that every statement points to.
- [Statements](https://tellscript.com/docs/statements.md): A statement is one checkable sentence with a stable id and a reference line to the check that proves it. How to write, number and retire them.
- [Rings](https://tellscript.com/docs/rings.md): Every section carries a ring, fixed, guided or free, that tells the next model how much it may change and who decides.
- [Levels and proof](https://tellscript.com/docs/proof.md): Tellscripts come in four levels, from product to file, and three proof levels, from described to proven by a model from another lab.
- [Checks](https://tellscript.com/docs/checks.md): How a Tellscript statement is bound to a test, a contract, a reference image or a recipe, and what happens when an edition breaks a rule.
- [Editions and upgrades](https://tellscript.com/docs/editions.md): An edition is one build of your app from the Tellscript by one model. What it replaces, what it keeps, and how an upgrade to a new model runs overnight.
- [The rebuild test](https://tellscript.com/docs/rebuild-test.md): Once a week, let an agent rebuild the app from the Tellscript in an empty folder. Whatever goes missing was never written down.
- [Recipes](https://tellscript.com/docs/recipes.md): A recipe records how a picture, text or data set was made, so the tenth image matches the first and any of them can be made again.
- [Decisions](https://tellscript.com/docs/decisions.md): A decision records why a rule exists and which alternatives were rejected, so no future rebuild tidies away the reason.

## Reference

- [Example: Castwell](https://tellscript.com/docs/example.md): A complete, small Tellscript for Castwell, a cast-concrete homeware shop: product, product page, cart, a photo recipe and the check that binds them.
- [CLI preview](https://tellscript.com/docs/cli.md): The tell command line tool is in development. It extracts Tellscripts from existing code, checks code against them and rebuilds editions with any model.
- [Questions](https://tellscript.com/docs/faq.md): What people ask first about Tellscript: editions, existing code, models that ignore it, who changes it, which agents it works with, and how long it gets.
- [Glossary](https://tellscript.com/docs/glossary.md): The terms used in Tellscript, from binding and edition to ring, recipe and the rebuild test, in one sentence each.

## Optional

- [Complete example as one file](https://tellscript.com/downloads/castwell.tell.md): Castwell, a small shop: product, product page, cart, photo recipe and a check
- [All docs in one file](https://tellscript.com/llms-full.txt): every page above, for one context window