The three previous attempts at this job died of endlessness, not difficulty. Nothing
stopped the next component arriving with its own `text-emerald-400` while an old one
was being fixed, so the number never fell for long.
`bun run check:theme` counts palette classes per directory against a committed
baseline. It does not care what the number is, only which way it moves. 942 across 21
directories today. Every directory can be paid down independently and none can quietly
regrow — which turns an infinite job into a finite one.
A baseline rather than a ban, deliberately: a rule forbidding palette classes outright
fails on its first run, and a check nobody can make pass is a check everybody turns
off.
Proven by adding one `text-emerald-400` and watching it fail with the directory, the
delta, and what to use instead.
── Documentation, which is part of the work rather than after it ──
`src/workspaces/theme/README.md` is new and is the contract: how to write a theme, all
84 declarations by family, why colours are unwrapped HSL triplets while surfaces are
complete CSS values, why assets are quoted paths, and the rules for components. Start
from Plain, not from Duck — every value you change is then one you decided about.
`plugins/EXTRACTING-A-PLUGIN.md` gains a rule beside the others: a plugin never
hardcodes a colour, and pays its debt down DURING the extraction. The counts are named
there — Soulseek 313, Invoices 95, Wallet 68 — because "some colours" does not convey
that it is two thirds of the platform's total. The kickoff prompt says the same thing
in the form a fresh agent will meet it.
That is what makes the plugin exemption safe rather than a way of losing the work: the
ratchet stops covering a directory the moment it leaves, so the rule has to travel with
it.
`THEMES-NOTES.md` rewritten to match reality — it still listed done things as open.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`plugins/EXTRACT-A-PLUGIN-PROMPT.md` is meant to be pasted into a fresh agent with
one word changed. It deliberately does not restate the runbook — it orders the
reading, says what "done" means, and sets the three behaviours that matter: map the
import graph before moving anything, ask rather than assume, and verify on a live
server after a purge.
── The runbook needed correcting before it could be handed to anyone ──
Its verification table told the reader to run `bun db:push` while the plugin was
uninstalled and expect "No changes detected". Following that today would hang on
drizzle-kit's interactive rename prompt, or — with `--force` — drop the tables of
every plugin not currently on disk. Struck out, with the reasoning, and the property
it was checking is now checked by reinstalling and finding the rows still there.
Also folded in: installs create tables through `pushPluginSchema` and verify them
afterwards; `purge` is the only honest way to test an install twice, because
uninstall keeps the directory and the tables on purpose; orphan tables are now
reported on screen; and the marketplace is part of the job — a public repo that
clones anonymously, a README that renders in both the store and the install pane, a
catalogue row, and a `BUNDLED` entry for machines with no internet.
Two rules from today that generalise beyond extraction: the platform must not carry
the plugin's VOCABULARY, not just its code — ten comments explained what Headscale
was months after it left, each correct and in the wrong repository — and nothing in
the install path may trust `$PATH`, which cost an install with
`Executable not found in $PATH: "bunx"`.
The stale "757 pass, 10 failures" is now "record the baseline before you start",
which does not go out of date.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pastilhasandClaude Opus 5