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 after every step until there are no errors, the model is executable and test games finish.

#What the agent needs

Pick the example that is closest to the game:

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). 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), and a tactic for how a reasonable player plays (it cannot be loaded on the site yet). See views and 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. The engine ignores keys it does not know, so a misspelled key silently does nothing; the JSON schema 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 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 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, 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.

Simulating many games (win rates, comparing variants or tactics) is not yet available on the site; "done" is judged by the validator and 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.