kiln-conventions

One set of rules for how code is written in Kiln, the facts about the current code that are easy to get wrong, and a cheap check on the lines you add. Existing code is grandfathered: the rules apply to what your change adds or modifies.

Docs-only and spec-only changes don't need this skill.

1. Read the rules

Read references/rules.md in full. It is short, and every rule has a ❌/✅ example.

2. Read the reference for each area you touch

Pick the references from the paths you are editing. Read only those.

Paths	Reference
libs/core/**	references/core.md
libs/server/**, app/desktop/**	references/server_desktop.md
app/web_ui/**	references/web_ui.md

UI changes (anything under app/web_ui that renders) also need the kiln-ui skill (.agents/skills/kiln-ui/SKILL.md) for visual design and house controls. This skill covers code structure only.

3. Write the code

Follow the rules even where the surrounding code doesn't (rules.md H24). Don't copy a nearby pattern that breaks a rule, and don't rewrite neighbouring code to comply unless your change already touches it.

4. Run the gate on your change

From the repo root:

uv run python .agents/skills/kiln-conventions/scripts/conventions_gate.py --worktree               # uncommitted changes + untracked files
uv run python .agents/skills/kiln-conventions/scripts/conventions_gate.py --range origin/main...HEAD  # a branch or PR
uv run python .agents/skills/kiln-conventions/scripts/conventions_gate.py --files <path>...          # whole files or directories (audits)

It prints one line per hit, SEV<TAB>RULE<TAB>path:line<TAB>snippet, then a summary. Exit 1 means at least one FAIL.