Kiln-AI/Kiln / .agents/skills/kiln-conventions
kiln-conventions
VerifiedKiln's code conventions and per-area gotchas, plus a diff gate that enforces the mechanical ones. Invoke before writing or changing any Python, TypeScript or Svelte code in the Kiln repo (libs/core, libs/server, app/desktop, app/web_ui), and when reviewing such a change. Covers comments, startup and entry points, globals and module state, config reads, module layering, library-vs-app rules and async I/O.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.5 KB |
| references/core.md | markdown | 7.6 KB |
| references/rules.md | markdown | 13.8 KB |
| references/server_desktop.md | markdown | 8.8 KB |
| references/web_ui.md | markdown | 5.3 KB |
| scripts/conventions_gate.py | script | 22.2 KB |
| scripts/gate_allow.txt | markdown | 657 B |
| scripts/gate_config.json | config | 1.8 KB |
| scripts/test_conventions_gate.py | script | 18.2 KB |
SKILL.md
View on GitHub---
name: kiln-conventions
description: Kiln's code conventions and per-area gotchas, plus a diff gate that enforces the mechanical ones. Invoke before writing or changing any Python, TypeScript or Svelte code in the Kiln repo (libs/core, libs/server, app/desktop, app/web_ui), and when reviewing such a change. Covers comments, startup and entry points, globals and module state, config reads, module layering, library-vs-app rules and async I/O.
allowed-tools: Read Grep Glob Bash
---
# 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.
- **FAIL**: fix it. If the hit is not a violation, add an entry to `scripts/gate_allow.txt` with a `#` reason line above it. Don't allowlist a real violation.
- **FAIL you can't fix without an out-of-scope refactor** (rules.md H24): leave it, and don't allowlist it. List it in your end-of-task summary and the PR description with the rule id, `path:line`, and the refactor it waits on. The gate isn't in CI, so a FAIL reported this way blocks nothing.
- **WARN**: fix it, or name it in your end-of-task summary with a one-line justification (for example "module-level-call `app.command(...)(...)` in `cli/cli.py`: Typer command registration at the CLI's composition root").
Only added lines are checked in `--worktree` and `--range` mode, so a hit is always on a line you wrote. `--files` reports existing code too; it's for audits, not for gating.
## 5. Self-check what the gate can't see
The gate catches history comments, `global`, `bool(os.getenv…)`, env reads outside the allowed paths, new `Config.shared()` in `libs/core`, `lib/` → `routes/` imports, and module-level calls, constructions and subscriptions. Before you finish, check the review-only rules yourself against your diff:
- A2/A3: no comment restates the code; each remaining comment is a 1–3 line *why*.
- B4/B6: startup work is in the entry point or `lifespan`, not in an app factory or a module.
- C7: no new module-level dict, list or set that gets mutated, and no ClassVar registries (the gate only catches `global`).
- C8–C10: no reset hooks for tests, no asyncio primitives in singletons, every cache has an owner, a bound and invalidation.
- D11/D14/D15: config is read at the edge; validators and `default_factory` are pure; no branching on the environment name to pick an implementation.
- E16–E21: thin handlers and pages, no router-to-router imports, no `HTTPException` in services, no catch-all modules, no test helpers in production packages, no near-copies.
- F22: library code doesn't touch host-process globals.
- G23: no blocking I/O in `async def`; every outbound call has a timeout.
If a rule couldn't be followed without a refactor, say so in your summary (H24); for a gate FAIL, report it as in step 4.
## For reviewers
Apply `references/rules.md` and the area references for the changed paths. Run the gate with `--range <base>...<head>` on the PR and report every FAIL and every WARN that the author didn't justify. Accept a FAIL the author reported with its rule id, `path:line` and the refactor it waits on (rules.md H24); an allowlist entry for a real violation is a finding. Rule violations in added code are findings, not nits.
## Maintaining the gate
Files in this skill:
- `references/rules.md`, `scripts/conventions_gate.py` and `scripts/test_conventions_gate.py`: each repo keeps its own copy, and kiln_server's started from Kiln's.
- `scripts/gate_config.json` (skipped paths, which checks run where, allowed env-access paths, module-level patterns) and `scripts/gate_allow.txt` are Kiln-only. The gate reads both from its own directory.
Run the gate's tests (stdlib + pytest only; the default repo test run doesn't collect dot-directories):
```
uv run python -m pytest .agents/skills/kiln-conventions/scripts/test_conventions_gate.py
```
Config notes: a check missing from `checks` is disabled; an unknown check id or an invalid regex exits 2. Globs support `*` and `?` (within one path segment) and `**/` (zero or more directories); brackets are literal, so `routes/[project_id]/**` works. Allowlist lines are Python regexes searched in `path<TAB>stripped line`, optionally prefixed `rule-id:`.
Known limitations:
- Python docstrings aren't scanned for history phrases; only `#` comments are.
- Comment detection is per line. A multi-line `/* */` or `<!-- -->` block is scanned only on its first line and on lines that start with `*`.
- Quote tracking is per line too: an apostrophe earlier on the line (Svelte markup text like `<p>Don't</p> <!-- … -->`, or a `'` in a regex literal) hides a comment that follows it.
- The `module-level-*` checks are heuristics, which is why they are WARN. A module-level call written as an assignment is caught only when the right-hand side matches `module_level_construct_patterns`.
- The `history-comment` phrase list skips common runtime-state phrasings ("no longer matches", "previously selected"), so some history phrased that way slips through. Review still applies rules.md A1.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |