CLAUDE.md — Wafflebase

Wafflebase is a web-based collaborative office suite — spreadsheets, word documents, presentations, markdown notes, an infinite-canvas board, and PDF/image/file viewers. Yorkie CRDTs for real-time collaboration, ANTLR4-based formula engine, Canvas rendering.

• Sheets — Spreadsheet engine (data model, ANTLR4 formulas, Canvas grid rendering)
• Docs — Word processor engine (rich text, Canvas rendering, pagination)
• Slides — Presentation engine (free-position elements, theme system, Canvas + DOM overlay editor); reuses the docs rich-text engine inside text boxes
• Notes — Markdown note engine (CodeMirror source editor, single Yorkie Text CRDT)
• Board — Infinite-canvas engine (boundless pan/zoom plane; reuses the Slides scene engine)
• PDF / Image / File — Static blob document types (blob-stored original, no CRDT editing)

See @docs/design/README.md for architecture, @packages/sheets/README.md, @packages/docs/README.md, @packages/slides/README.md, @packages/frontend/README.md, @packages/backend/README.md for package details.

Commands

pnpm install                        # Install all dependencies
docker compose up -d                # Start PostgreSQL, Yorkie, MinIO, Azurite
pnpm dev                            # Start frontend (:5173) + backend (:3000) + docs site
pnpm verify:fast                    # Lint + unit tests (pre-commit gate)
pnpm verify:self                    # verify:fast + all builds + chunk/entropy (no browser lane)
pnpm verify:full                    # verify:self + browser + integration (DB required)
pnpm verify:browser:docker          # Visual + interaction tests in Docker
pnpm test                           # Unit tests across all packages (Vitest; backend is Jest)
pnpm sheets build:formula           # IMPORTANT: regenerate ANTLR formula parser
pnpm backend migrate                # Run Prisma database migrations

Commit Messages

Subject ≤70 chars (what changed). Body explains why. Blank line 2. In shell, use multiple -m flags or $'...' for real newlines — not \n in "...".

Remove the synced seq when detaching the document

To collect garbage like CRDT tombstones left on the document, all
the changes should be applied to other replicas before GC. For this,
if the document is no longer used by this client, it should be
detached.

Pitfalls

• ANTLR generated files have @ts-nocheck — do NOT hand-edit or add type fixes. Regenerate with pnpm sheets build:formula and commit the output.
• Store abstraction — all spreadsheet behavior must go through the Store interface, all document behavior through DocStore. Do not bypass with ad-hoc persistence.
• Integration/e2e tests require docker compose up -d first.
• Frontend chunk-gate defaults are in harness.config.json; override with FRONTEND_CHUNK_LIMIT_KB / FRONTEND_CHUNK_COUNT_LIMIT.

Task Workflow

Non-trivial tasks use paired files in docs/tasks/active/: YYYYMMDD-<slug>-todo.md and YYYYMMDD-<slug>-lessons.md. Architecture changes go to docs/design/<topic>.md. Code lands via PR, not direct push to main.

1. Plan — write the todo file before touching code; update docs/design/ if architecture changes.
2. Branch + commit — feature branch from main; each commit pnpm verify:fast green (commit format above).
3. Self review — /self-review: a bounded loop of review → fix → pnpm verify:fast → re-review over the full branch diff, max 3 rounds, stopping at the first round with no blocking findings. Rotate the lens per round (1 correctness/tests, 2 design fit + superpowers:requesting-code-review, 3 security/docs) — the same reviewer asked three times mostly restates itself. Whether an agent can launch /code-review or /simplify depends on its harness (/ultrareview is always user-triggered); when a reviewer cannot be launched, say so and ask — never let a skipped round read as a clean one. Log each round in *-lessons.md. A finding you believe is wrong goes in a --rebuttals file with evidence; one merely ignored is re-raised every round. Non-blocking findings become known limitations in the PR body. Still past round 3 with blockers? Stop looping and get a human.
4. Sync + open PR — git fetch && git rebase origin/main to surface conflicts before pushing. Title ≤70 chars; body = Summary + Test plan. The PR gets no automated review unless you ask: the panel admits only agent/* branches and PRs labelled agent:managed, so comment @claude review (advisory, once per commit) or @claude loop (panel + auto-fix) if you want one.
5. Address review — evaluate each finding technically; push back with reasoning when wrong. Reply in the comment thread (gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies), not top-level. If main moved during review, rebase again.
6. Before merge — CI green and review approved: manual smoke in pnpm dev if UI changed; capture lessons in *-lessons.md, archive (pnpm tasks:archive && pnpm tasks:index), commit + push. Merge, then start a new session for the next task.