agentleFS
kenxlekenxle/live-agentic-html-editor/CLAUDE.md

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

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
  1. Distinctive:

    When a decision is about how the project runs rather than what a feature does (process, testing, review, CI, tooling), weigh it in this …

    line 20
  2. Very specific:

    Put new code in the directory that matches its job in the architecture doc, not wherever is convenient.

    line 135
  3. Very specific:

    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.

    line 162
  4. Very specific:

    Every checkout needs npm install once before npm run lint or any gate: lint runs TypeScript and ESLint, which are dev dependencies.

    line 192
  5. Very specific:

    Stop it by what you own: Use the pid in your own temp state folder's service.json, or the process you spawned.

    line 209
  6. Distinctive:

    The suite checks: After a run, no helper whose state folder is under the temp folder may still be running.

    line 213
  7. Distinctive:

    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.

    line 254
  8. Very specific:

    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".

    line 288
  9. Very specific:

    After a merge, pull main and run npm run gate locally again.

    line 293
  10. Very specific:

    Check, then merge, as two steps.

    line 299
  11. Very specific:

    Never cancel a run by hand, and never push a branch just to trigger a run.

    line 301
  12. Distinctive:

    Remove a temporary workflow before the branch merges, and delete the branch from the remote when the PR closes.

    line 304
  13. Distinctive:

    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, …

    line 314
  14. Distinctive:

    Run the browser suite as its own command, read the pass and fail counts, and push as a separate step.

    line 342
  15. Distinctive:

    No em dashes anywhere: not in commit messages, not in code comments, not in docs.

    line 357
  16. Distinctive:

    Commit messages describe why, not just what changed.

    line 359
  17. Very specific:

    Don't touch docs/features/20260812.01_live_agentic_html_editor/ without reason.

    line 360

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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:

  1. 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.
  2. 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.
  3. 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/tiny 11.16.1, MIT.
  • vendor/heroicons/arrow-right-start-on-rectangle.svg, swatch.svg and document-arrow-down.svg: Heroicons 2.2.0, MIT.
  • vendor/stclair-doc-style/: the St. Clair AI document style. system-tokens.css and document.css are 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.css is 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.md

Put 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:

Commandlintcheck:layercheck:menubarunitbrowsers
npm run gate:unityesnonoyesnone
npm run gate:builderyesnonoyesChromium
npm run gateyesyesyesyesChromium
npm run gate:allyesyesyesyesChromium, 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 a finally. 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, and skills/lahe/SKILL.md are 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: true on 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 --help with 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 gate locally 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 gate locally again. Two PRs can each pass and still break together. A failure there is fixed on main before anything else lands.
  • 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 run gh 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_dispatch inputs (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 .bak files that sed -i leaves (on macOS, write sed -i '' so none is made)
  • a locally rebuilt dist/ file: put it back with git 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.md and skills/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 no contract field, and test/unit/review_format.test.js asserts 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.