---
url: /guide/agents.md
description: The loop a coding agent follows, AGENTS.md and kiln docs, and llms.txt.
---

# Working with agents

Kiln is designed around the loop a coding agent runs: change files, ask the tools whether the change
is right, fix what they report. This page is that loop, and the files an agent reads.

## The loop

```bash
kiln describe            # traits, systems in run order (reads/writes/after), resources, events
kiln test                # bun test over scenarios/ (headless, deterministic)
kiln replay recordings/x.json        # replay a play session the user recorded (F8 in the game)
kiln run --steps 600 --snapshot Transform,Health --resources Score   # JSON world after N steps
kiln check               # determinism lint (Math.random, Date.now, performance.now)
kiln shot --steps 120 out.png        # one rendered frame from headless Chromium, when you need eyes
kiln docs                # regenerate AGENTS.md
kiln add <plugin>        # vendor a community plugin into src/plugins/ (kiln add --list)
```

Work in this order:

1. Write or change files.
2. `kiln describe`. Schedule errors (write conflicts, cycles, a bad `.after()`) show here.
3. Write a scenario test for the change.
4. `kiln test`.
5. `kiln shot` only if the change is visual.
6. `kiln docs` if exports or the schedule changed.

Every command takes `--json` and prints errors as `error <code>: <message>`. The message names the
fix, so the usual next step is to do what it says. The full command reference is in
[CLI](../reference/cli).

## AGENTS.md

Every game has an `AGENTS.md` at its root, which agents that follow the
[AGENTS.md convention](https://agents.md) read before working. It has two parts:

* **The Kiln guide** at the top: the API, the phases, the rules the schedule enforces, every plugin,
  testing, recordings, a TSL cheat sheet and a table of common errors. `kiln new` writes it from
  `packages/kiln/docs/agents-guide.md`. You may edit this part; `kiln docs` keeps it.
* **This game**, below a marker comment, generated by `kiln docs` from the code: the config, the
  plugins, the schedule as a table (writes, reads, resources and order for every system, with the
  file it lives in), every trait with its fields, every relation, prefab, resource, event, system
  and plugin with its JSDoc, and the names of the scenario tests.

```bash
kiln docs            # rewrite the generated section, keep everything above the marker
kiln docs --guide    # also replace the top with the current Kiln guide
kiln docs --check    # exit 1 if AGENTS.md is out of date (for CI)
```

`kiln docs` also prints a `note` for each trait, system, plugin, resource, event or prefab without
JSDoc, since that line is what the next agent will read about it.

## This site, for agents

The guides on this site are also published as plain text, following the
[llms.txt](https://llmstxt.org) convention:

* `/llms.txt`: an index of every page with its description.
* `/llms-full.txt`: every guide page in one file.
* Each page as Markdown at its own URL with `.md` appended.

The [API reference](/api/) is generated by TypeDoc from the same JSDoc the code carries, so it
is never out of step with the source.

## Habits that keep agents fast

* **One feature, a few exports.** A trait in `data.ts`, a system in `systems.ts`, one line in
  `main.ts`. Don't spread a feature across a new folder until a file is genuinely long.
* **Read before guessing.** `kiln describe` answers "what runs, in what order, touching what"
  faster and more reliably than reading the code.
* **Assert on JSON.** `kiln run --snapshot` and scenario tests are exact. Screenshots are for
  checking that something looks right, not that it happened.
* **Reproduce from recordings.** When a user says "I recorded it", run `kiln replay` before
  reading code. See [Recordings and replay](../testing/recordings).
* **Keep it deterministic.** Randomness from `res.mut(Rng)`, time from `ctx.time`. `kiln check`
  flags the rest. See [Determinism](../concepts/determinism).