# Authoring with an AI agent

This page is for anyone who wants an AI agent to turn a rulebook into a Tabletwin model, and for
the agent itself. It gives the workflow, the rules the agent must follow, a prompt to copy, and
a checklist for when the model is done.

The short version: give the agent the documentation and an example, let it write the model in
small steps, and check it with the [validator](https://tabletwin.com/validate/) after every step
until there are no errors, the model is executable and test games finish.

## What the agent needs

| Input | Where |
|---|---|
| All documentation in one file | [`https://tabletwin.com/llms-full.txt`](https://tabletwin.com/llms-full.txt) |
| Everything needed on one page (keys, ops, flow, end conditions, names in scope, patterns) | [Quick reference](https://tabletwin.com/docs/cheatsheet/) |
| An index of the docs, schemas and example models | [`https://tabletwin.com/llms.txt`](https://tabletwin.com/llms.txt) |
| The JSON schema of a model | [`https://tabletwin.com/models/docs/schema.json`](https://tabletwin.com/models/docs/schema.json) |
| Example models to copy patterns from | [`/games/`](https://tabletwin.com/games/), and the files under `https://tabletwin.com/models/` |
| The rulebook | from the person who asks: a PDF, text or the publisher's rules page |
| A way to check its work | the [validator](https://tabletwin.com/validate/) in the browser; an agent without a browser asks the person to paste the model in (see [checking the model](#checking-the-model)) |

Pick the example that is closest to the game:

| The game has … | Start from |
|---|---|
| turns, a deck, hidden hands | [higher-lower.yaml](https://tabletwin.com/models/docs/examples/higher-lower.yaml) |
| dice and a push-your-luck choice | [pig.yaml](https://tabletwin.com/models/docs/examples/pig.yaml) |
| a board with squares or hexes, movement, line of sight | [hex-skirmish.yaml](https://tabletwin.com/models/docs/examples/hex-skirmish.yaml), [chess.yaml](https://tabletwin.com/models/games/chess.yaml) |
| reactions and a stack (players respond to each other) | [ambush.yaml](https://tabletwin.com/models/docs/examples/ambush.yaml) |
| bidding | [auction.yaml](https://tabletwin.com/models/docs/examples/auction.yaml) |
| several scenarios with lasting state | [expedition.yaml](https://tabletwin.com/models/docs/examples/expedition.yaml) |
| skill shots or other physical actions | [eightball.yaml](https://tabletwin.com/models/games/eightball.yaml) (outcome models) |
| a very small complete game | [tictactoe.yaml](https://tabletwin.com/models/games/tictactoe.yaml), [kuhn-poker.yaml](https://tabletwin.com/models/games/kuhn-poker.yaml) |

The validator's "Start from" menu loads these examples too.

## The workflow

Work in this order. Check the model with the validator after every step and fix what it reports
before you go on.

1. **Read the rulebook and list what exists.** Players, components (cards, dice, boards,
   tokens), where components can be (these become *zones*), numbers that change (these become
   *variables*), and the structure of a game: setup, rounds, phases, turns, how it ends. Write
   rules you are unsure about as `open_questions` right away; do not guess silently.
2. **Write the skeleton.** `game`, `label`, `players`, `num_players`, `mode`, `summary`, then
   `state` (zones and variables), `flow` (the nested sequence, loops, branches and steps),
   `actions` (empty effects are fine for now) and `end`. The validator must accept this.
3. **Fill the actions with ops.** Each action's `effect` is a list of ops: `move`, `draw`,
   `shuffle`, `set`, `add`, `choose`, `roll`, `if`, `for_each`, `emit`, and so on (see the
   [reference](https://tabletwin.com/docs/reference/)). Write readable text fields first if that helps (`cond: "player has
   no cards"`), then add the executable twin (`cond_x: "len(hand[actor]) == 0"`).
4. **Make it executable.** Every field the engine needs must have an `_x` expression or a literal
   value. The validator's executability (and its list of gaps) tells you what is missing. Aim for
   100% on the rules layer.
5. **Add the end conditions** with `if_x` and, in competitive games, `who_x`. A game that never
   ends shows up in the test games as "did not end within 5000 requests".
6. **Play test games.** The validator plays 20 games with random choices. All of them should
   finish, and the endings should look plausible (not every game ending the same way unless the
   game is like that). Open the model in the player and follow one game step by step.
7. **Add content** (cards, monsters, scenarios) as data under `content`, with effects in the same
   ops. Give every item a `status`: `verified` (checked against the source), `uncertain` or
   `missing`. Card texts are descriptions in your own words, never copied text.
8. **Record what is open.** Every rule that the rulebook leaves unclear goes into
   `open_questions` with `status: open` (or `assumed` with the assumption you made in the model).
9. **Optional: a view** for how the table looks in the player (paste it into the validator's view
   field next to the model, or the workshop's View tab), and a **tactic** for how a reasonable
   player plays (the workshop's Tactic tab checks it and plays it). See [views](https://tabletwin.com/docs/views/) and
   [tactics](https://tabletwin.com/docs/tactics/).

## Rules for the agent

- **Follow the documentation, not your memory of other formats.** Keys, op names and field names
  must exist in the [reference](https://tabletwin.com/docs/reference/). The engine ignores keys it does not know, so a
  misspelled key silently does nothing; the [JSON schema](https://tabletwin.com/models/docs/schema.json) catches most of them,
  and the validator reports them as `unknown key` warnings (outside `content`).
- **Expressions are the expression language, not Python.** Only the syntax and functions in
  [expressions](https://tabletwin.com/docs/expressions/) are allowed. No imports, no attributes except `get`, `count`,
  `index`, `items`, `keys` and `values`, no names starting with `_`.
- **Names are short English snake_case** (`draw_pile`, `end_turn`). Labels are for people.
- **Own words.** Rules and card texts are paraphrased. Official names of cards and components may
  be used; long rule or card texts may not be copied.
- **Do not invent rules.** If the rulebook does not say it, make an `open_questions` entry and,
  if the model needs a choice, mark it `assumed` and say what you assumed.
- **Keep the model honest about what it cannot run.** Something too complex for the ops goes in
  `code` with a `doc` and `kind: content` or `kind: algorithm`; the validator counts it as a gap.
- **Small steps.** Validate after each change. Fix errors before warnings.

## Checking the model

The [validator](https://tabletwin.com/validate/) is the agent's check. Paste the model into
"Model (YAML)" (and a view, if any, into "View (optional YAML)") and press Check. It runs in the
browser and shows:

- errors and warnings, including `unknown key` warnings for misspelled keys;
- `% executable`, with "What the engine still misses": every field that still needs an `_x`;
- "Test games: X of 20 finished", with how the games ended, where games stopped (engine errors such
  as a `NameError`), and games that did not end within 5000 requests;
- "The flow as a tree", to compare with the rulebook.

When at least one test game finished, "Open in the player" opens the model in the
[player](https://tabletwin.com/play/), where a game can be followed question by question.

**Agents without a browser.** An agent that cannot open web pages hands the model to the person
and asks them to paste it into the validator and send back what it shows: the errors and
warnings, the executability and the gap list, and the test-game summary with "Where games
stopped". The agent fixes what was reported and hands over the next version. Ask for the full
text of each message; the place names in them (`action stop`, `step choice`) point to the line to
fix.

**People with a browser** can also open the model in the [workshop](https://tabletwin.com/workshop/)
(Import, or paste it into the Model tab): the same checks as you type, with the line each message is
about, plus the table, playing it and simulating many games (win rates, comparing tactics). "Done" is
judged by the validator's checks and a game followed in the player.

## A prompt to copy

Replace the parts in angle brackets.

```
You are writing a Tabletwin model: a board game as YAML, run by the Tabletwin engine.

Read first: https://tabletwin.com/llms-full.txt (all documentation and two example models).
Closest example to start from: <URL of an example model from https://tabletwin.com/llms.txt>.

The game: <name>. The rules: <attached rulebook / pasted rules>.

Write the model as one YAML file, <game-id>.yaml, following the workflow in "Authoring with an
AI agent": skeleton first, then actions, then expressions until the model is executable, then end
conditions, then content. After every step, check it with the validator at
https://tabletwin.com/validate/ and fix all errors. If you cannot open web pages, give me the
model and I will paste it into the validator and send you what it shows.

Rules: only keys, ops and functions from the reference; English snake_case names; rules and
card texts in your own words; every unclear rule becomes an open_questions entry; nothing
invented.

Done means: no validator errors, 100% executable on the rules layer, 20 of 20 test games finish,
and a short list of open questions. Report the open questions and any rule you could not model.
```

## Done checklist

- [ ] The validator reports no errors; warnings are understood.
- [ ] Rules layer 100% executable (content may be lower while content is still being added).
- [ ] 20 of 20 test games finish, with plausible endings.
- [ ] One game followed step by step in the player looks like the real game.
- [ ] Every content item has a `status`; unclear rules are in `open_questions`.
- [ ] No copied rule or card text.