Init agents
init-agents writes the agent contract at the project root: AGENTS.md, which
tells any AI harness (or human) opening the repo how this project is built and
where the installed docs are, and CLAUDE.md, which re-exports it.
bunx @defold-typescript/cli init-agents . # current folder
bunx @defold-typescript/cli init-agents path/to/project # a specific projectA destination is required
Like init, the verb takes an explicit
destination — there is no implicit "current folder" default, so it never writes
where you did not mean to. Pass a path, or . for the folder you are already in.
A missing path fails fast and writes nothing.
What it writes
AGENTS.md carries a managed block delimited by HTML-comment markers:
<!-- defold-typescript:agents:start -->
…the managed contract…
<!-- defold-typescript:agents:end -->Only the content between those markers is ever rewritten. Notes you add above
or below the block survive every re-run untouched. If AGENTS.md already exists
without the markers, the block is appended after one blank line and your prior
content is left intact.
CLAUDE.md re-exports it, for harnesses that look for that filename instead of
AGENTS.md, so the contract itself lives in one file. Written fresh, it is the
single line @AGENTS.md. A CLAUDE.md that already says exactly that is left
byte-for-byte unchanged and reported as untouched; one holding your own notes
keeps them and takes the re-export in a managed block appended below, the same
shape AGENTS.md gets.
The block tells an agent to author TypeScript under the include paths in
tsconfig.json, to drive the CLI with --json, where the typed API and the
guide live, and the hard rules that are expensive to rediscover — never commit
build/ or .defold-types/, one define* factory per script file, the
defold-target pin's exact package.json key, and that .gui and .collection
edits are checked with build --editor-compile --json while the Defold editor
has the project open (Compile in the editor),
because type-checking and a plain build do not fully validate or compile them.
It also lists the built-in
libraries with their import paths and guide pages — @defold-typescript/types/hsm
(State machines) and @defold-typescript/types/ecs
(Entity systems) — so an agent imports them instead of
writing its own state flags and update loops.
Re-running is safe
The block is versionless: its pointers resolve to
node_modules/@defold-typescript/docs/llms.txt, llms-full.txt, and
guide/<page>.md — paths the install swaps under you — so none of them has to be
rewritten when the toolchain moves. A run that would reproduce the file
byte-for-byte skips the write entirely, so re-running the verb on a current
project touches nothing and reports nothing.
The block's wording does change between toolchain releases, and you rarely have
to think about it: upgrade re-scaffolds with --force, which
refreshes the managed block for you. So does init . --force. A plain re-init
does not — it leaves a contract that is already there untouched.
That leaves this verb for the cases those do not cover: a project that has no contract yet, or a managed block you edited or deleted and want restored without re-scaffolding anything else.
Machine-readable output
--json writes exactly one JSON object to stdout:
{ "command": "init-agents", "ok": true, "written": ["AGENTS.md", "CLAUDE.md"] }written lists only the files actually touched: a re-run that changes nothing
returns [], and one that refreshes a stale block lists AGENTS.md alone. On
failure — a missing destination, or an unwritable path — the envelope carries the
reason and no written field:
{ "command": "init-agents", "ok": false, "error": "<message>" }The two files are written one after another rather than as a transaction, so a
failure on the second leaves the first on disk. ok: false therefore means this
run did not finish, not nothing changed — re-run the verb rather than assuming
the project was left as it was.
See Agent runbooks for this verb inside a full agent procedure.