Duolith docs

0160. Packs: Duolith's and an app's rules and skills, one topic each, proved by the compiler and served to agents

  • Status: Accepted
  • Date: 2026-11-17
  • Decided by: Mik (first design answered and approved on 17 Nov 2026; the redesign's four questions answered on 17 Nov 2026)
  • Planning item: Mik, 17 Nov 2026: "our MCP should probably have multiple agents or tools that we can use to import our skills and rules … they basically control their own rules and details so for example styles is consistent and doesn't clutter the details … say we want a different style and components in our app built on duolith"
  • Answers: Mik, 17 Nov 2026, first round: a broken rule is a finding with a level per rule; the tool server serves fixed tools, a prompt per pack and generated subagents; packs come from the app's own folder and from npm packages; one owner per topic, which may extend one other pack. Second round, after the first build, when Mik asked for rules "well more fleshed out and expanded thoroughly" so they cause no confusion or context drift: Duolith's own rules become built-in topic packs with every diagnostic code in exactly one pack; an app's rules at error fail the build; the app skills fold into the topic packs; and every checked rule has bad and good examples the compiler proves.
  • Built as: what follows. The first build (app packs only, replaces: pointing at the app skills, W0100 only in duolith lint, no editors) was redesigned before it merged; "The first design" at the end says what changed.

Context

An agent working on a Duolith app learned Duolith from llms/ and from 22 app skills copied into every app, and learned nothing of the app. What an app could enforce was theme.yaml (decision 0103) and the levels of the built-in lint rules (decision 0080). So an app's own conventions (an AppButton instead of the kit's Button, only rounded-lg corners, colours only from the brand tokens) lived in AGENTS.md, where every agent read all of them for every task and nothing checked them, or nowhere.

Duolith's own rules had the opposite problem: they were checked (some 230 diagnostic codes) but stated in many places at once: a catalogue entry, a line in a skill, a paragraph in a guide. Nothing tied a skill's advice to the code that enforces it, so the words drifted from the compiler, and an agent read three descriptions of one rule that did not quite agree.

Decision

Add packs: one folder per topic holding, for that topic only, its rules (each a sentence an agent follows, why it exists, and how a break of it is found), its skill (in the Agent Skills format) and its references (detail read on demand). There are two kinds, served the same way.

Duolith's own packs

skills/packs/<topic>/ holds Duolith's rules and skills by topic: language, components, styling, kit, forms, accessibility, navigation, data, assets, motion, effects, native, rust-modules, types, packages, i18n, security, performance, testing, project and packs. The compiler embeds them (crates/lint/build.rs), so every app has them and they always match the duolith that runs; their folder is written duolith:<topic>. The 22 app skills are folded into them (their evaluations, decision 0062, move to eval/<task>/ in the pack), and duolith create no longer copies skills into an app.

What keeps them whole, checked on every change to duolith:

  • Coverage: every code in spec/diagnostics/catalogue.yaml is in exactly one rule's enforced-by (duolith packs check --builtin). A new code cannot be added without saying which rule it enforces.
  • Every rule is defined: it says what to do and why (naming its decision), and is enforced-by codes or marked check: none on purpose.
  • Examples are proved: each checked rule has bad examples (each enforced code reported by one) and good ones, and duolith packs test --builtin compiles every one in an app of one page: a bad example must report exactly what it names, a good one nothing. A code no file can produce (a run-time error, a command's failure) says so in no-example, with where it is reported instead.
  • Every skill has the same shape: When to use it, How it works, Steps, Decisions, Worked example (a `duolith page the compiler checks; a fence that names a file, such as `ts file=behaviours/count.behaviour.ts , is a file of the next page's app, so an example may span files), Mistakes agents make; and it names only codes and rules that exist. The `duolith blocks of its references are compiled too.
  • A pack costs an agent only what it needs: a rule the compiler enforces is loaded as its sentence and its codes, since the diagnostic gives the fix and duolith explain <topic>/<id> the reason; a rule that duolith lint checks or nothing checks is loaded with its reason, and those nothing checks are listed first. A rule whose codes no build reports any more is not loaded. One rule says each thing: a pack names another pack's rule instead of repeating it, and a skill's mistakes are the ones nothing reports, or whose usual fix is the wrong one.

An app's own packs

packs/<topic>/ (or a package's, turned on in duolith.yaml under packs:) holds the app's conventions in the same format. A rule's check is one of a closed set of kinds the compiler answers from one file (classes, tokens, parts, imports, elements, style-blocks, files, lint), or none; there is no script in a pack. A break is W0100 with the rule's sentence, at the rule's level, which duolith.yaml can set by topic/id. At warning it is a duolith lint finding; **at error it fails duolith build and duolith check** like any other error (Mik's second round; decision 0080's "the build does not lint" stays true of warnings). The editor shows W0100 as you type: the language server reads the pack files and the compiler finds the packs from them as the command line does.

An app's pack whose topic is one of Duolith's builds on Duolith's pack: an agent reads Duolith's rules, then the app's. It may add rules, not change or remove Duolith's (E0563), since those are the compiler's own. Otherwise one pack owns each topic (E0562), and a pack may extend one installed pack, changing or removing its rules by id. duolith packs test compiles an app's examples in a copy of the app, so an app's rules are proved as Duolith's are.

Every build checks the packs themselves (E0560-E0566): a pack that does not read or lacks what a rule needs, names what does not exist, clashes with another, has a broken skill, is not installed, or whose generated agent files are stale.

Served to agents one topic at a time

  • Tools (a fixed set, so the list stays short): list_packs, packs_for_file, load_pack, read_pack_reference and check_pack (one pack's W0100 findings and the codes its rules are enforced by).
  • Prompts: one per pack, named after its topic, and pack for any topic.
  • Agents: duolith packs sync --agents writes one subagent for each of the app's own packs (.claude/agents/duolith-<topic>.md), holding Duolith's rules of that topic too; and a section of AGENTS.md lists the app's packs and Duolith's topics.
  • The command line: duolith packs [list|show|new|sync|check|test|read], and duolith explain for a code or a topic/id.

Alternatives considered

OptionWhy not
Conventions in AGENTS.mdEvery agent reads every convention for every task, and nothing checks them
Skills only, no rulesThe agent is told, but nothing proves what it was told is what the compiler does; Mik's rule is that what is statically knowable fails the build
App skills beside packs, with replaces: (the first build)Two places say how to style a screen, and nothing ties either to the codes; Mik found it would cause confusion and drift
Rules without examplesA rule's words drift from its check unnoticed; compiled examples make the drift a test failure
Rules written as TypeScript or a plugin APINeeds a script runtime in the compiler, and makes two apps' builds differ in ways no schema shows
One tool per packThe tool list grows with every pack, and every client sends every description with every request
Several packs per topic, mergedTwo packs on one topic will disagree; one owner, building on Duolith's, keeps one voice

Consequences

  • New: skills/packs/ with Duolith's topic packs, embedded by crates/lint/build.rs; the lint code W0100 and E0560-E0566; topic/id under lint: and packs: in duolith.yaml; spec/schemas/cli/packs.schema.json; the glossary term "pack" (a glossary change, approved with the design); the duolith packs commands; five tools and a prompt per pack in packages/mcp-server; llms/packs.md and docs/guide/packs.md; examples/packs; a styling pack in the themed template.
  • Changed: pack discovery lives in crates/lint/src/packs/find.rs, reading files through a function, so the command line and the editor (crates/wasm, packages/language-server) find the same packs. skills/app/ is gone: its skills are folded into the topic packs and its evaluations run from skills/packs/<topic>/eval/<task>/. packages/create copies no skills; a new app's AGENTS.md points to duolith packs.
  • Tests: duolith_packs_are_complete keeps duolith packs check --builtin empty, and duolith_packs_examples_report_what_they_say keeps duolith packs test --builtin passing; adding a diagnostic code means adding it to a rule with a bad example.
  • Not in v1 unless Mik asks: a comment that turns a pack rule off for one line (the reasoning of decision 0080).

The first design

The first build, on the same pull request, made packs the app's alone: Duolith's app skills stayed copied into every app, and an app pack said which skills it stood in for with replaces:; a broken rule was only a duolith lint finding; editors did not show W0100; a rule had a sentence and a check, without a reason or examples. Mik approved it and then asked, before it merged, for rules that define Duolith's own conventions thoroughly enough that agents are not confused and do not drift. The redesign above is the answer: Duolith's rules became packs too, every code in one, each rule with a reason and proved examples, and app rules at error fail the build.