docs: add agent rules for dev server management and browser verification

- Section 6: Never start dev servers from the agent (prevents orphan
  processes and broken tmux panes)
- Section 7: Check tmux panes for compile errors (renumbered)
- Section 8: Verify compiled output in browser before committing
  (catches squint's silent empty-file failures)
This commit is contained in:
Florian Schroedl
2026-03-05 14:30:01 +01:00
parent 2500cc4b1a
commit e003e1c4a8
7 changed files with 285 additions and 2 deletions

View File

@@ -192,7 +192,18 @@ bb build-theme # Regenerate CSS with new component styles
bb test # All tests pass
```
### 6. Check running dev servers before committing — CRITICAL
### 6. Never start dev servers from the agent — CRITICAL
**Do not run `bb dev`, `bb dev-hiccup`, `bb dev-replicant`, `bb dev-squint`, or any long-running server process from the agent.** The user manages dev servers in a separate tmux session (`ui-dev`). Starting servers from the agent blocks the session, spawns orphan processes, and can break existing tmux panes.
The agent may only:
- Run short commands: `bb test`, `bb build-theme`, `curl`, `wc -l`, `grep`
- Inspect tmux panes via `tmux capture-pane`
- Touch files to trigger recompilation: `touch src/ui/<module>.cljc`
If a dev server needs restarting, **tell the user** — don't do it yourself.
### 7. Check running dev servers before committing — CRITICAL
A tmux session `ui-dev` runs all three dev servers (`bb dev-all`). **Always check every pane for compile errors before committing:**
@@ -212,6 +223,30 @@ Look for:
Do **not** commit if any pane shows errors. Fix them first.
### 8. Verify pages load in browser before committing — CRITICAL
Terminal compile checks alone are **not enough**. Squint can produce empty `.mjs` files silently (no errors in the terminal). Use the `fetch` tool to verify each dev server actually serves a working page:
```sh
# Check hiccup (server-rendered — look for actual HTML content)
curl -s http://localhost:4003 | grep -c 'sidebar-layout'
# Check squint compiled output is not empty (must be >1 line)
wc -l dev/squint/.compiled/dev/squint.mjs
wc -l dev/squint/.compiled/ui/*.mjs | sort -n | head -5
# Any file with only 1 line is broken — recompile it:
# touch src/ui/<module>.cljc
# Check replicant compiled JS exists
ls -la dev/replicant/public/js/cljs-runtime/ui.sidebar.js
```
If any compiled file is suspiciously small (1 line = just the import), touch the source file to trigger rewatch, or manually compile:
```sh
cd dev/squint && npx squint compile ../../src/ui/<module>.cljc
cd dev/squint && npx squint compile src/dev/squint.cljs
```
## Theme System
### Token naming