live-agentic-html-editor
CLAUDE.md5 starsChanged 28 days agoMITView on GitHub
A zero-runtime-dependency Node service plus a vanilla JS review layer that gets injected into an HTML page. A reviewer comments on and directly edits the page; everything goes to their coding agent. See docs/features/20260812.01_live_agentic_html_editor/ for the brief, architecture, and plan. Read the architecture doc before touching src/; it pins the design decisions (D1-D12) that every component below has to honor. Some code in src/ predates the current architecture (it was built against an archived draft with different decision numbering); where…
- Commits and pushes
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- laheSkill
- maintain-verification-skillSkill
- verify-laheSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
17 rules. About 0 are common, 8 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
When a decision is about how the project runs rather than what a feature does (process, testing, review, CI, tooling), weigh it in this …
- Very specific: line 135
Put new code in the directory that matches its job in the architecture doc, not wherever is convenient.
- Very specific: line 162
Run the full gate alone: Start npm run gate or gate:all only when no builder is running its spec and no other browser run is open.
- Very specific: line 192
Every checkout needs npm install once before npm run lint or any gate: lint runs TypeScript and ESLint, which are dev dependencies.
- Very specific: line 209
Stop it by what you own: Use the pid in your own temp state folder's service.json, or the process you spawned.
- Distinctive: line 213
The suite checks: After a run, no helper whose state folder is under the temp folder may still be running.
- Distinctive: line 254
When the brief would have to describe code that no doc covers, that is the gap: write the doc, or have the builder's design note become it.
- Very specific: line 288
Before opening a pull request, and before any push to an open one, run npm run gate locally on that exact commit and read "0 failed".
- Very specific: line 293
After a merge, pull main and run npm run gate locally again.
- Very specific: line 299
Check, then merge, as two steps.
- Very specific: line 301
Never cancel a run by hand, and never push a branch just to trigger a run.
- Distinctive: line 304
Remove a temporary workflow before the branch merges, and delete the branch from the remote when the PR closes.
- Distinctive: line 314
Write what you would like removed into your notes or progress page under a "To delete at cleanup" heading, one line each saying what it is, …
- Distinctive: line 342
Run the browser suite as its own command, read the pass and fail counts, and push as a separate step.
- Distinctive: line 357
No em dashes anywhere: not in commit messages, not in code comments, not in docs.
- Distinctive: line 359
Commit messages describe why, not just what changed.
- Very specific: line 360
Don't touch docs/features/20260812.01_live_agentic_html_editor/ without reason.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md: live-agentic-html-editor
A zero-runtime-dependency Node service plus a vanilla JS review layer that
gets injected into an HTML page. A reviewer comments on and directly edits
the page; everything goes to their coding agent. See
docs/features/20260812.01_live_agentic_html_editor/ for the brief,
architecture, and plan. Read the architecture doc before touching src/;
it pins the design decisions (D1-D12) that every component below has to
honor. Some code in src/ predates the current architecture (it was built
against an archived draft with different decision numbering); where code
and the architecture doc disagree, the doc wins and the code is what
changes.
Priorities for decisions about the project
When a decision is about how the project runs rather than what a feature does (process, testing, review, CI, tooling), weigh it in this order:
- Velocity. Get working changes onto main quickly. The main user is Ken, so a change can merge once lint, the bundle check and the unit suite pass. The slow checks (the full browser suite, all three browsers, idle measurements, walkthroughs) can run after the merge, and a problem they find gets a follow-up fix.
- Dogfooding. Ken using the tool on his real work is the most valuable test there is. Prefer whatever gets a change in front of him sooner.
- Security. It still matters, and a real hole still blocks. But a review finding that slows his everyday use (for example, refusing links he clicks all the time) is a trade-off for him to decide, not a default.
Zero runtime dependencies (hard rule)
The tool must run from a git clone with no install step: no npm install,
no lockfile resolution, nothing fetched at runtime. dependencies in
package.json stays {}, always. This is why the audience (someone
running a coding agent) can point their agent at this repo and have it
work immediately, and why a stray dependency can't break on a machine with
no network access or a locked-down npm registry.
devDependencies are fine and expected: they are the test harness
(Playwright), not something the shipped tool needs at runtime.
One system dependency: pandoc, optional. Ken allowed it on 2026-10-17
(docs/features/20261017.02_pandoc_render). The feature-forge and
research-report builds turn Markdown into HTML with pandoc, and their docs use
pandoc syntax (::: callout-req fenced divs) that marked cannot read. So when
pandoc 3 is on the machine, src/service/pandoc.js renders Markdown with it,
through the filter src/service/lahe_render.lua, and LAHE and the builds never
disagree about syntax. It is never installed for the user and never fetched:
a machine without it renders every page with the vendored marked, writes one
helper-log line, and the rail says "Ask your agent to install pandoc to get
the correct styles" on a page whose fenced divs show as text. No other system
dependency is allowed without the same kind of decision from Ken.
Third-party files are vendored under vendor/ rather than installed:
vendor/marked/marked.cjs: marked 15.0.12, MIT.vendor/mermaid/mermaid.tiny.js:@mermaid-js/tiny11.16.1, MIT.vendor/heroicons/arrow-right-start-on-rectangle.svg,swatch.svganddocument-arrow-down.svg: Heroicons 2.2.0, MIT.vendor/stclair-doc-style/: the St. Clair AI document style.system-tokens.cssanddocument.cssare this repo's own, and the official copy of the style (Ken decided this on 2026-10-12; the personal repo's copy is no longer the source);lahe-markdown.cssis a thin layer over them.fonts/holds three latin-subset variable woff2 files (Schibsted Grotesk, Hanken Grotesk, JetBrains Mono), all OFL 1.1.
Each folder carries the upstream LICENSE and a README naming the package and
version. Never add any of them to dependencies.
The two Markdown packages are loaded: src/service/markdown.js requires them by
relative path. To take a newer version, copy the new file and its license over
the old ones and update the README (for mermaid, also update MERMAID_ASSET in
src/service/markdown.js, which names the version in the served filename).
The document style is read, not required: src/service/markdown.js joins the
three CSS files into one bundle, inlines it into every rendered Markdown page,
and serves it at .lahe-doc-style.css for pages an agent writes. The fonts are
copied beside a written artifact and served at .lahe-fonts/<file>.woff2. To
change the style, edit the vendored files here and update
vendor/stclair-doc-style/README.md. Nothing is copied in from the personal repo.
The paid Lahe Styles never enter this repo. This repo is public, and the styles
are sold. Their files live in Ken's private personal repo, and a user installs
them with lahe style add <folder> from wherever they bought them. Tests, fixtures
and screenshots use the made-up styles in test/fixtures/styles/, or show a paid
style only as a picture. A builder may read a paid style in place to check it, but
never copies its CSS, fonts or metadata into the repo.
The icons are copied, not loaded. The rail inlines their path data as
EXIT_ICON_PATH, STYLE_ICON_PATH and PDF_ICON_PATH in src/layer/overlay.js, so the
vendored files are provenance: they are what the drawings came from, and they
exist so the next person can diff them against a newer release instead of
guessing whether an icon was hand-drawn. To take a newer version, copy the new
file over the old one and copy its d attribute into the matching constant.
Node version
engines.node is >=24.12.0. That is the first Node release where running
TypeScript files directly is stable, and the migration to TypeScript depends on
it. The tool and the dev tools share one floor. A .nvmrc (24.22.3) is
checked in; run nvm use if you have nvm, and CI runs Node 24.
An older Node gets a message, not a crash. bin/lahe.js checks the running
version before it loads anything and prints the version found, the version
needed and the fix (install Node 24, then run npm run install-cli and
lahe install in the clone). npm run install-cli refuses to write a wrapper
from an older Node. Both use bin/node_floor.js, which is written in plain
ES5 so it still parses on an old Node. Change the floor there, in
package.json, in .nvmrc and in the CI workflow together;
test/unit/node_floor.test.js checks that they agree.
Install the command with npm run install-cli, not npm link. It writes a
wrapper at ~/.local/bin/lahe naming absolute paths to the Node that ran it and
to the clone. npm link under nvm puts lahe in that version's own bin
directory, which is off PATH the moment the shell default is a different Node:
the install reports success and the command is then not found.
Directory layout
src/
service/ Local Node service: auth, event log, projection, HTTP endpoints
layer/ Vanilla JS review layer (browser-side): overlay, anchor engine,
item store, edit recorder, replay engine, sync client, in-page
injection/remount
shared/ The one place a wire-protocol field name or item-record shape
is spelled. Both service and layer import from here. If you
find yourself defining the same shape twice, it belongs here
instead.
cli/ The helper's commands (serve, add, status)
test/
unit/ node:test unit tests
browser/ Playwright tests (Chromium by default, three lanes on gate:all)
fixtures/ Static HTML pages used as review targets in tests
macos/
menubar/ The optional Mac menu bar app: one Swift file and its plist,
built on the Mac by `lahe install --menu-bar`. Nothing here is
required; see docs/ongoing/MENU_BAR.mdPut new code in the directory that matches its job in the architecture doc,
not wherever is convenient. If nothing fits, that's a sign the architecture
needs an update, not that src/ needs a new top-level folder.
Running the gate
A builder runs npm run gate:unit. Four gates exist and they are not
interchangeable:
| Command | lint | check:layer | check:menubar | unit | browsers |
npm run gate:unit | yes | no | no | yes | none |
npm run gate:builder | yes | no | no | yes | Chromium |
npm run gate | yes | yes | yes | yes | Chromium |
npm run gate:all | yes | yes | yes | yes | Chromium, Firefox, WebKit |
check:menubar builds the menu bar app and runs its self-test and its tests
against the fake helper on a Mac; it skips with one line anywhere else.
Builders and reviewers run gate:unit. The browser suite runs ONCE per
checkpoint, by the orchestrator, on the integrated diff. On 2026-09-16 the full
Chromium suite ran at least six times in one afternoon across parallel builders
and fix rounds, which drained Ken's battery in two hours and bought no coverage
the checkpoint run would not have. A builder whose change is browser-only
behaviour (the rail, replay, protection) may run one named spec file with
npx playwright test test/browser/<file>.spec.js, never the whole suite.
Run the full gate alone. Start npm run gate or gate:all only when no
builder is running its spec and no other browser run is open. Two runs at once
fail each other: tests the change never touched miss their timing limits or time
out. A failure seen during overlap is rerun alone before anyone calls it real or
a flake.
check:layer fails when either committed bundle (dist/lahe-layer.js, the review layer, or dist/lahe-library.js, the Library page) is stale. esbuild builds both.
Builders never commit dist/: it is generated, and four parallel branches
rebuilding it means a machine-generated conflict at every checkpoint. Rebuild it
locally if you need it for a browser test, but do not stage it. The orchestrator
rebuilds and commits it once per checkpoint, then runs gate and gate:all.
lint is more than syntax. It runs tsc -b over every TypeScript project and
ESLint over every .ts file, with the strict rules described in
docs/ongoing/code/README.md. It also runs node --check over every .js file, no
function declared twice at a file's top level, a compile of every .lua file
under src/ (with luac or pandoc lua, skipped with a line when the machine
has neither), no jsdom (not in package.json, not imported anywhere under
test/), and manifest completeness (every non-TypeScript file under src/
appears exactly once across src/shared/manifest.js's lists, forwarders
included). npm run test:unit
and npm run test:browser also run individually. test:unit stops itself and
fails after 30 minutes (--limit-minutes in scripts/no_stray_helpers.js), so a
stuck test cannot hold the run.
Browsers install once: npx playwright install chromium, plus
npx playwright install firefox webkit for the lanes. A bare playwright test
is Chromium only, so the inner loop stays one browser wide; --project=webkit
runs a single lane by name.
Every checkout needs npm install once before npm run lint or any gate:
lint runs TypeScript and ESLint, which are dev dependencies. That includes a
fresh worktree under the clone. Run it, then git checkout -- package-lock.json
if it changed the lockfile.
Tests leave nothing running
On 2026-10-07 Ken's Mac had 1,892 Lahe helpers left over from test runs. They used about 12 GB of memory, filled swap, and kept kernel_task at 200% CPU while his battery drained. Each test started a helper in its own temp state folder, the helper is detached on purpose so it outlives the command, and no test ever stopped it. So:
- A test stops every process it starts. That covers a helper, a page
server, a monitor, a browser or anything spawned. Stop it in teardown, even
when the test fails:
afterEach,afterAll, or afinally. Closing the session is not enough: closing it can leave the helper running. - Stop it by what you own. Use the pid in your own temp state folder's
service.json, or the process you spawned. Never kill by name or port pattern, and never touch the real helper (port 7817,~/.local/state/lahe). - The suite checks. After a run, no helper whose state folder is under the temp folder may still be running. A new test that starts processes passes that check before it merges.
- A test that leaks is a failing test, even when its assertions pass.
- Background test commands get the same rule. A dev server,
npx serve, or a Playwright run you start by hand is stopped when you are done, not left for the OS. - Check before you finish. A builder runs
ps -axo command | grep -c "[l]ahe.js serve"before and after its test runs and reports both numbers. Anything above the starting count is a leak to fix before pushing.
Running the loop (lessons from 2026-09-16)
Reviews, worktrees, docs for decisions, and tests first all stay. What was slow that day was how the loop ran around them, so:
- Review the integrated diff at the checkpoint, not each builder branch. Merge green builder branches into an integration branch, then run one review set on that diff. Per-branch reviews found the same defects three times over at three times the cost.
- One fix round, verified by the tests the reviewer asked for. The reviewer names the test; the builder writes it red then green; the orchestrator checks it exists and passes. A second review only when a fix is itself risky.
- Reviewer count follows the process. A whetstone-size change gets one reviewer. Feature-forge gets the set its phases define. Security joins when the diff touches auth, serving, paths, or tokens.
- A builder's brief points at the docs; it does not restate the code.
docs/ongoing/(how a subsystem works now),docs/diagrams/(the shape of the system),docs/CONTRACTS.md,docs/CLI.md, andskills/lahe/SKILL.mdare what a builder reads first, and the brief names which ones. Paraphrasing the code in a brief is how three specs on 2026-09-16 each carried a wrong detail. - A visual change ships with a screenshot, every time. Ken (2026-09-16), after a builder's progress page showed the rail it had actually built: "I love that you added screencaps... it lets me see things and comment on them without having to go try and create the situation, and it makes a good record." Any change to the rail, a card, a banner, or anything else drawn on screen gets a real screenshot from the built page (light and dark when the change touches both) on the change's own progress page, not a description of what it should look like. Take it after the browser test that proves the change, so the picture and the passing test are the same run. When the brief would have to describe code that no doc covers, that is the gap: write the doc, or have the builder's design note become it.
- A builder that hits a limit checks in instead of documenting around it. "This cannot be done" in a report is a claim the reviewer will test; a one-line question mid-build is cheaper than the fix round.
- A stalled small task gets a status check, not a longer wait. A builder that has made no commits after a reasonable stretch is asked where it is.
Platform and browser target
Cross-platform: macOS, Linux, and Windows all run the helper (standard
Node), and the layer is standard DOM APIs that current Chrome, Edge,
Safari, and Firefox all support. One caveat on Windows: npm run install-cli
writes a POSIX shell wrapper to ~/.local/bin/lahe, so it is a macOS and Linux
convenience only. Windows users run node bin/lahe.js from the clone, or work
inside WSL, where the wrapper installs normally. The one capability floor is the CSS
Custom Highlight API, stated with its reason in the architecture doc. The
Playwright suite has all three lanes (Chromium, Firefox, WebKit) and runs them
on npm run gate:all at every checkpoint; a builder's default run is Chromium,
which is a loop-speed choice rather than a support statement.
CI runs mail Ken
GitHub emails the pusher for every failed or cancelled workflow run, and on 2026-09-15 a flake hunt done as branch pushes sent him seven in six hours. So:
- A stress or bisect workflow never fails the run. Put
continue-on-error: trueon the step, write the verdict to the log or an artifact, and read it there. - The browser suite runs here, not on GitHub. CI first runs
lahe --helpwith nothing installed, which proves a fresh clone works on a clean Linux machine (all only GitHub can prove). Then it installs the dev tools and runs lint, the bundle check and the unit tests. Waiting 14 minutes on GitHub for the same suite we run locally cost Ken most of a day on 2026-10-11. So:- Before opening a pull request, and before any push to an open one, run
npm run gatelocally on that exact commit and read "0 failed". Put the counts in the PR body ("npm run gate: N passed, 0 failed"). A builder's narrow spec run is not enough: on 2026-10-01 a PR failed on a spec its builder never ran. - After a merge, pull main and run
npm run gatelocally again. Two PRs can each pass and still break together. A failure there is fixed on main before anything else lands.
- Before opening a pull request, and before any push to an open one, run
- Batch pushes to an open pull request. Each push starts a run, and a red run is an email. Progress-page and doc commits wait for the next real push. The style switcher PR alone failed six times in a day this way.
- Check, then merge, as two steps. Run
gh pr checks <n>, read "pass", then rungh pr merge <n>. Never put both in one command. - Never cancel a run by hand, and never push a branch just to trigger a run.
Bisect arms are
workflow_dispatchinputs (a ref to check out), not branches. - Main gets a push only after the pull request's gate is green.
- Remove a temporary workflow before the branch merges, and delete the branch from the remote when the PR closes.
Never remove files while work is running
No rm, no git clean, no deleting a scratch script, a screenshot helper or a
stale worktree, not even your own temp files at the end of your own task. Every
removal stops and waits for Ken's approval, which stalls whatever else is
running.
Write what you would like removed into your notes or progress page under a
"To delete at cleanup" heading, one line each saying what it is, and leave the
files where they are. Removals happen in one batch at the end, by the
orchestrator, with the whole list in front of Ken. Files under /tmp are never
removed at all; the operating system owns that folder.
The rule covers everything a builder makes along the way:
- temp and probe specs
- screenshots
test-results/folders- the
.bakfiles thatsed -ileaves (on macOS, writesed -i ''so none is made) - a locally rebuilt
dist/file: put it back withgit checkout -- dist/, never by deleting it
A builder's prompt states this rule near the top, not only in closing
boilerplate. A one-line "never delete files" at the end did not hold on
2026-09-29: builders ran rm anyway and Ken was blocked on the prompts.
One exception: a finished worktree. At cleanup, the orchestrator removes
every worktree made for the feature whose work is all on main, without asking,
with git worktree remove --force (not rm). forge-cleanup's last step says
how to tell a finished worktree from one in use. That includes the
orchestrator's own feature worktree, removed last from the main checkout.
Builders still never remove their own. Skipping this left 50 worktrees and 27 clones behind by 2026-10-21.
Read the result, then push
Run the browser suite as its own command, read the pass and fail counts, and
push as a separate step. A chained suite; git push pushes whatever the suite
said: on 2026-09-23 two specs failed, the push went out anyway, and main
carried a regression until it was reverted. The gate is a person reading
"0 failed", not the shell's exit code.
Undoing a revert before re-merging
Reverting a merge commit leaves git believing the branch is already merged, so
a later merge of the fixed branch brings nothing or conflicts in every file the
revert touched. Revert the revert first (git revert <the revert>), then merge
the branch with its fixes on top.
Commit conventions
- No em dashes anywhere: not in commit messages, not in code comments, not in docs. Use a comma, period, colon, or semicolon instead.
- Commit messages describe why, not just what changed.
- Don't touch
docs/features/20260812.01_live_agentic_html_editor/without reason; those files are the source of truth for the design and may be under active edit by someone else.
Where the design lives
docs/features/20260812.01_live_agentic_html_editor/ has the brief,
architecture, and plan. The architecture doc's Key Decisions (D1-D12) are
binding: they resolved specific blockers found in review (protected
regions and replay, the per-review token model, path-safety rules,
prompt-injection fencing). Don't re-litigate a decision in code without
updating the doc first. Files prefixed archive_ in the feature folder
are historical drafts, never current design.
Agent-facing docs: what is truth, and what travels together
The feature folder (brief, architecture, plan) is HISTORY: what we set out to build and why. It is not rewritten as the tool evolves. The living truth for how the tool works now is:
skills/lahe/SKILL.mdandskills/lahe/references/: every instruction for running a review, and the only home of agent instructions. Hosts load the skill automatically. review.json carries no instructions: it has nocontractfield, andtest/unit/review_format.test.jsasserts that.AGENTS.md: about the tool, not the task. How each agent host connects, a pointer to install, and pointers to the docs.
A workflow change goes into the skill, then npm run install-skills copies it
to the hosts. Tests pin the skill's wording through test/support/skill.js,
which reads SKILL.md and its references together. When you move or reword a
pinned instruction, change the test that pins it in the same commit.
The skill is skills/lahe/SKILL.md plus skills/lahe/references/.
npm run install-skills copies both, and copies
vendor/stclair-doc-style/COMPONENTS.md in as references/components.md. A test
that pins skill wording reads SKILL.md and the references together, because
text moves between them.
Change the skill in the repo, never the installed copy. A rule written into
~/.claude/skills/lahe/SKILL.md by hand is erased by the next
npm run install-skills. Skill changes go in skills/lahe/ in the repo.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

