Working with coding agents
Everything a coding agent needs to build a Duolith app is in the app itself: an AGENTS.md (with a CLAUDE.md that points to it), Duolith's packs (its rules and skills, one topic each, which the compiler carries), and the reference in llms.txt and llms/. The duolith command answers in JSON, and a tool server gives the same answers as Model Context Protocol tools. Decisions: 0060 (the reference), 0061 (the tool server), 0062 (skill evaluations).
Making a new app
The scaffolder in packages/create makes a new app from a template, with its agent files:
node packages/create/src/main.ts my-app --template tabs # blank, tabs or data
blank is one screen, tabs a tab bar with three screens, and data a list loaded from a server with a detail screen. Each app gets AGENTS.md, CLAUDE.md and a copy of llms.txt and llms/; the skills are Duolith's packs, which every build of duolith carries.
The reference
llms.txt is an index in the llms.txt format, with one line per topic; each topic is a full file in llms/: the language, elements, kit parts, diagnostics, styling, data, navigation, production, motion and islands, platform effects, testing, native builds, the command and lint. They are generated by pnpm generate from spec/ and the guides, so they always match the compiler. An agent reads the index, then only the topic it needs.
Reading the command's JSON
Every command takes --json (llms/cli.md lists them). A build that works, and one that does not:
{"files":50,"ok":true,"out":"examples/minimal/dist"}
{"diagnostics":[{"code":"E0101","column":10,"file":"pages/index.duo","help":"Use one of: button, checkbox, …","line":1,"message":"<widget> is not an element","severity":"error"}],"ok":false}
A project that cannot be read gives {"error":"… has no pages/ folder","ok":false}. duolith explain E0101 --json gives the catalogue entry: title, message, explanation and fix. duolith fmt --check --json lists each page with its status, and the paths it could not use under missing and skipped:
{"files":[{"errors":null,"file":"pages/index.duo","status":"not-formatted"}],"missing":[],"ok":false,"skipped":[]}
The tool server
packages/mcp-server gives agents the command as tools: explain a code; check, format and build pages; list kit parts and routes; look up an element, utility, effect or theme token; list, load and check the app's packs; run the tests; lint (and fix); scan the npm packages; check the whole project; upgrade it; build for native or with a build report; and screenshot a route after tapping, typing and navigating, with the page's console log. Start it with node packages/mcp-server/src/main.ts (standard input and output), from the folder it may write in: the tools write files (a checked copy, a formatted page, a build, a screenshot, lint fixes, an upgrade, new visual baselines) only inside that folder, or inside the folders DUOLITH_MCP_ROOT lists. format_page reads and rewrites only .duo files. Screenshots need Playwright's Chromium, and use ports 4330 to 4339, or DUOLITH_MCP_PORTS such as 4500-4509.
To give it to an agent, register it with the agent's client as a standard-input server. For Claude Code, from the app's folder:
claude mcp add duolith -- node <path-to-the-duolith-repository>/packages/mcp-server/src/main.ts
Packs
Duolith's rules and skills come as packs, one topic each (decision 0160): language, components, styling, data and the rest. Every rule says what to do, why, and the codes that report a break of it, with examples the compiler proves. An app's own pack in packs/<topic>/ builds on Duolith's pack of that topic with the app's conventions (its brand, its components), checked as W0100. The tool server serves every pack as tools (list_packs, packs_for_file, load_pack, read_pack_reference, check_pack) and as one prompt per pack, and duolith packs sync --agents writes one subagent for each of the app's own packs. See packs.md.
Skills
Each pack's skill (duolith packs show <topic>) says when to use it and walks through its topic: how it works, the steps, the decisions, a worked example the compiler checks, and the mistakes agents make. The tasks they teach (a screen, a form, a list, data, navigation, styling, accessibility, checking a screen in a browser, platform effects, tests, translation, native builds, Rust modules) each have an evaluation in this repository that grades an agent's attempt:
pnpm skills:eval --skill build-a-screen --workspace path/to/the/app