Packs: rules and skills for agents, one topic each
A pack holds the rules and the skill for one topic of an app: its screens, its components, its styling, its data. Every rule says what to do, why, and how a break of it is found, and the examples beside it are compiled, so what a rule says cannot drift from what the compiler does. An agent loads only the packs for the work in front of it (decision 0160).
There are two kinds:
- Duolith's own packs, which every app has. They hold Duolith's rules: every diagnostic code the compiler or
duolith lintcan report belongs to exactly one rule of one of them. Their folder is writtenduolith:<topic>, such asduolith:styling, and the compiler carries them, so they match theduolithyou run. - The app's own packs, in
packs/<topic>/or from a package. They hold the app's conventions: its brand, its components, its way of loading data. One whose topic is one of Duolith's builds on Duolith's pack: it adds rules and may not change Duolith's.
duolith packs # every pack in brief: Duolith's and the app's
duolith packs show styling # one pack in full: its rules and its skill
duolith explain E0103 # a code, and the rule it belongs to
examples/packs is an app with a styling pack that builds on Duolith's and a components pack of its own.
A pack's files
packs/
styling/
pack.yaml the topic, what the pack covers and owns, its rules
SKILL.md the skill an agent follows, in the Agent Skills format
references/ detail read only when needed (a palette, a catalogue)
duolith packs new <topic> makes one that reads.
pack.yaml
topic: components
description: Use when adding a button, a card or any other part to a screen of this app.
scope: [pages/**, components/**] # the files the rules apply to (this is the default)
owns: [components/ui/**] # files only this pack's skill should change; its rules skip them
rules:
- id: one-button
says: Every button is components/ui/AppButton.duo, never the kit's Button.
why: AppButton is the kit's Button on brand; a page using the kit's directly shows a button no one chose.
level: error
check:
parts: { deny: [Button], use: components/ui/AppButton.duo }
examples:
bad:
- code: |
---
import { Button } from "@duolith/kit";
---
<screen>
<Button label="Save" />
</screen>
reports: [components/one-button]
good:
- code: |
---
import AppButton from "../components/ui/AppButton.duo";
---
<screen>
<AppButton label="Save" />
</screen>
- id: tone
says: Button labels are verbs, such as Save or Send.
why: A verb says what pressing does; a noun leaves the reader guessing.
check: none
A rule has:
| Field | Says |
|---|---|
id | Its name in the pack; it is written <topic>/<id> everywhere else |
says | What to do, in a sentence an agent follows |
why | Why the rule exists, naming its decision where there is one, so an agent can apply it where no check reaches |
check | How duolith lint checks it (see below), or none for a judgement only an agent or a person can make |
enforced-by | The diagnostic codes that report a break of it: how Duolith's own rules are checked, and how an app's rule can say which built-in code already covers it |
level | warning (the default), error or off |
scope | The files it applies to, narrower than the pack's |
fix | What to do when it is broken, where the check does not say |
see | Files that explain more |
examples | bad and good examples; a rule with a check or enforced-by needs both |
no-example | Why a checked rule has no examples, when no file can show it (a code reported only at run time, for instance) |
Examples are compiled
An example is a file's text (code, in pages/example.duo unless file says where) and any more files (files, a map of paths to texts). A bad one names what it reports (reports: codes, or pack rules by id); a good one reports nothing. target: native also builds it for native.
duolith packs test # the app's packs: each example in a copy of the app
duolith packs test --builtin # Duolith's packs, each example in an app of one page
A bad example must report exactly what it names, in its own files, and a good one nothing. So a rule's words, its check and the compiler cannot disagree without duolith packs test saying so. Duolith's own packs are tested this way on every change to Duolith.
The kinds of check
Each check is a question the compiler can answer from one file:
| Kind | Checks | Example |
|---|---|---|
classes | utility classes, by allow or deny patterns (* matches any text); replace gives the one class a denied class becomes, which duolith lint --fix writes, keeping its prefixes | { deny: [rounded-sm], replace: rounded-lg } |
tokens | the theme tokens a class or a var(--…) in a style block may name, by group (color, space, radius, shadow, text) | { color: [brand, on-brand, ink, muted] } |
parts | kit parts that may not be imported, and the component to use instead | { deny: [Card], use: components/ui/Panel.duo } |
imports | modules that may not be imported: a package by name, or a project file by path pattern | { deny: ["api/**"] } |
elements | elements or attributes that may not be used, and the component to use instead | { deny: [image], use: components/ui/Picture.duo } |
style-blocks | whether a file may have a style block | { allow: false } |
files | where a file named like name must live | { name: "*Button.duo", folder: components/ui } |
lint | the level of built-in lint rules inside the rule's scope | { hard-coded-colour: error } |
none | nothing; the agent reads it |
Paths are written from the project's folder: * matches within one folder name and ** any number of folders.
What is checked, and when
- A file that breaks a rule with a check is W0100, with the rule's sentence as the message and its id and fix in the help. At
warningit is aduolith lintfinding; aterrorit also failsduolith buildandduolith check, like any other error, and the editor shows it as you type.duolith.yamlsets any rule's level by its id, andpack-rule: offturns every pack rule off: ``yaml lint: components/one-button: warning styling/large-corners: error`duolith explain components/one-buttonprints a rule. Whatduolith packs show, the tool server and the subagents say of a rule's level is the levelduolith.yamlgives it, so runduolith packs sync` after changing one. - **Every build and
duolith check** check the packs themselves, since a broken pack is a mistake in the project that is known before anything runs.duolith packs checkmakes the same checks alone: | Code | When | | --- | --- | | E0560 |pack.yamldoes not read, or a rule has no sentence, reason, check or examples | | E0561 | A rule names what does not exist: a class, token, part, element, attribute, lint rule or diagnostic code, a component to use, a pattern that matches no file; orduolith.yamlsets a pack rule that no pack has | | E0562 | Two packs own the same topic, or the same file | | E0563 | Two packs' rules ask for opposite things of one file, or an app's pack gives a rule the id of one of Duolith's | | E0564 |SKILL.mdis missing, its front matter is wrong, or it links to a file the pack does not have | | E0565 | A pack named induolith.yamlor byextendsis not installed | | E0566 | The agent filesduolith packs syncwrote are out of date |
Building on a pack
An app's pack whose topic is one of Duolith's builds on Duolith's pack of that topic without saying so: an agent reads Duolith's rules, then the app's, and one skill after the other. It may add rules, not change or remove Duolith's (E0563), since those are the compiler's own.
A package lists its packs in its package.json, usually beside the components they describe:
{ "name": "@acme/duolith-brand", "duolith": { "packs": ["packs/styling"] } }
duolith add @acme/duolith-brand installs it, and duolith.yaml turns its packs on by the package's name and the topic, since a pack changes what lints:
packs:
- "@acme/duolith-brand/styling"
One pack owns each topic. To build on a package's pack, write your own with extends: "@acme/duolith-brand/styling" (and leave the package's off): it inherits the rules and the skill, changes a rule by giving its id again (a new sentence, level, scope or check), removes one with level: off and nothing else, and adds its own. It keeps the package pack's scope unless it writes its own. Agents read the one merged pack.
Serving packs to agents
- The tool server has five tools:
list_packs(each pack in brief, Duolith's and the app's: read it first),packs_for_file(which of the app's own packs cover or own a file; Duolith's cover every file),load_pack(one pack's rules, its skill merged with what it builds on, and its references; a rule the compiler enforces is its sentence and its codes, and only a rule the compiler does not enforce carries its reason and fix, so a pack costs little to load),read_pack_reference(one reference file, Duolith's too) andcheck_pack(what breaks one pack's rules, or every pack's, in the files given: its W0100 findings and the codes its rules are enforced by). Each pack is also an MCP prompt named after its topic, and thepackprompt takes any topic. - **
duolith packs sync** writes a section ofAGENTS.mdthat lists the app's packs and Duolith's topics and tells an agent to load the one that covers a file. With--agentsit also writes one subagent for each of the app's own packs,.claude/agents/duolith-<topic>.md, which knows only that pack (Duolith's rules of its topic included), so a main agent can hand styling work to the styling agent. Once written, every sync keeps them up to date, and a build reports them when they are stale (E0566).
Commands
| Command | Does |
|---|---|
duolith packs [list] [project] | Every pack in brief: where it came from, what it builds on, covers and owns, its rules checked and not |
duolith packs show <topic> [project] | One pack in full |
duolith packs new <topic> [project] | packs/<topic>/ with a pack.yaml that reads and a SKILL.md to fill in |
duolith packs sync [project] [--agents] | The AGENTS.md section and, with --agents, the subagents |
duolith packs check [project] | Every check a build makes of the packs |
duolith packs check --builtin | That Duolith's packs are complete: every code in one rule, every rule and skill whole |
duolith packs test [project] [--topic <topic>] | Compiles the app's packs' examples |
duolith packs test --builtin [--topic <topic>] | Compiles Duolith's packs' examples |
duolith packs read <file> [project] | One file of a pack, such as duolith:styling/SKILL.md |
Each takes --json (spec/schemas/cli/packs.schema.json).