Duolith docs

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 lint can report belongs to exactly one rule of one of them. Their folder is written duolith:<topic>, such as duolith:styling, and the compiler carries them, so they match the duolith you 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:

FieldSays
idIts name in the pack; it is written <topic>/<id> everywhere else
saysWhat to do, in a sentence an agent follows
whyWhy the rule exists, naming its decision where there is one, so an agent can apply it where no check reaches
checkHow duolith lint checks it (see below), or none for a judgement only an agent or a person can make
enforced-byThe 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
levelwarning (the default), error or off
scopeThe files it applies to, narrower than the pack's
fixWhat to do when it is broken, where the check does not say
seeFiles that explain more
examplesbad and good examples; a rule with a check or enforced-by needs both
no-exampleWhy 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:

KindChecksExample
classesutility 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 }
tokensthe 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] }
partskit parts that may not be imported, and the component to use instead{ deny: [Card], use: components/ui/Panel.duo }
importsmodules that may not be imported: a package by name, or a project file by path pattern{ deny: ["api/**"] }
elementselements or attributes that may not be used, and the component to use instead{ deny: [image], use: components/ui/Picture.duo }
style-blockswhether a file may have a style block{ allow: false }
fileswhere a file named like name must live{ name: "*Button.duo", folder: components/ui }
lintthe level of built-in lint rules inside the rule's scope{ hard-coded-colour: error }
nonenothing; 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 warning it is a duolith lint finding; at error it also fails duolith build and duolith check, like any other error, and the editor shows it as you type. duolith.yaml sets any rule's level by its id, and pack-rule: off turns every pack rule off: ``yaml lint: components/one-button: warning styling/large-corners: error ` duolith explain components/one-button prints a rule. What duolith packs show, the tool server and the subagents say of a rule's level is the level duolith.yaml gives it, so run duolith 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 check makes the same checks alone: | Code | When | | --- | --- | | E0560 | pack.yaml does 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; or duolith.yaml sets 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.md is missing, its front matter is wrong, or it links to a file the pack does not have | | E0565 | A pack named in duolith.yaml or by extends is not installed | | E0566 | The agent files duolith packs sync wrote 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) and check_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 the pack prompt takes any topic.
  • **duolith packs sync** writes a section of AGENTS.md that lists the app's packs and Duolith's topics and tells an agent to load the one that covers a file. With --agents it 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

CommandDoes
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 --builtinThat 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).