CLAUDE.md

1# Project-Specific Instructions for Claude
2 
3## Setup
4 
5This repository uses [`devenv`](https://devenv.sh) for development environment management. Run `devenv shell` to enter the development environment.
6 
7## Intent Layer (`context/`)
8 
9`context/` is the project's **intent layer** (a VRS tree) — the always-current source of truth for the system's design: vision, requirements, subsystem contracts (`spec.md`), ontology, decisions, and tracked drift. Read [`context/spec.md`](./context/spec.md) for its structure and conventions (branch layout, ID scheme, maturity markers, enforcement).
10 
11- When you change system behavior or a contract, update the owning `context/` node. The docs site (`docs/`) derives from the intent layer and must not contradict it; `context/ontology.md` is the canonical source for terms.
12- Consequential choices → the node's `.decisions/`; confirmed divergence between intent and code → its `.delta/`; open design questions → `open-questions.md`. New/unaccepted proposals live in `contributor-docs/rfcs/`, not in spec bodies — they fold into the owning nodes on acceptance.
13- `vision.md` and `requirements.md` are protected — confirm with a maintainer before editing them; specs, decisions, deltas, and open questions evolve freely.
14- A Vitest suite (`tests/package-common/src/intent-layer/`) checks the tree's mechanical invariants (ID uniqueness, `refines:` resolution, links, decision shape, …); run it and keep it green when editing `context/`.
15 
16## Tooling
17 
18- If tools aren't directly in `$PATH`, enter the dev environment first with `devenv shell`.
19 
20- For dependency management see ./context/03-delivery/02-release/dependency-management.md
21 
22### `mono` CLI
23 
24Use the `mono` CLI for common workflows:
25 
26- `devenv tasks run lint:full` / `devenv tasks run lint:full:fix` to run the linting checks
27- `mono test <unit|integration|perf>` to run the tests
28  - Some tests can take a while to run.
29- `mono ts [--watch] [--clean]` to build the TypeScript code
30- `mono docs <dev|build|deploy>` for docs workflows
31- `mono examples <run|deploy|test>` for example workflows
32- ... and more
33 
34## Testing
35 
36- When working on specific Vitest tests, use the `vitest` CLI directly instead of `mono test` and make sure to target the specific test file and test name: e.g. `vitest run packages/@livestore/common/src/index.test.ts --testNamePattern "should be able to get the number of users"`.
37 
38## TypeScript
39 
40- Avoid `as any`, force-casting etc as much as possible.
41- When writing non-trivial code, make sure to leave some concise code comments explaining the why. (Preferably jsdoc style.)
42- When refactoring code you don't need to consider backwards compatibility unless specifically asked for.
43- Keep exported members at the top of the file and move unexported helpers to the bottom.
44- Never add `paths` to `tsconfig.json`. Prefer using `package.json#exports` instead.
45 
46## Task Management
47 
48Use GitHub issues or an issue checklist for non-trivial work.
49 
50- Link the issue in the PR when the repo workflow expects it
51- File follow-up GitHub issues for out-of-scope work discovered during implementation
52 
53## Git
54 
55- The default branch of this repository is `main`.
56- Before committing, run `devenv tasks run lint:full:fix` to auto-fix most linting errors. Make sure there are no type check/lint errors.
57 
58### Branch Naming Conventions
59 
60- Use descriptive branch names that clearly indicate the purpose: `my-username/feat/add-user-auth`, `my-username/fix/memory-leak`, `my-username/docs/api-reference`
61- Keep branch names concise but specific (under 30 characters when possible)
62- Use kebab-case for consistency
63 
64### Development Workflow
65 
66- Run the full test suite before pushing: `devenv tasks run test:run`
67- Ensure TypeScript compilation passes: `devenv tasks run ts:check`
68- Use `devenv tasks run lint:full:fix` to automatically fix formatting issues
69 
70### Issues
71 
72- When asked to create a GitHub issue, use the GitHub CLI to do so.
73- Add appropriate labels to the issue. Only use existing labels, don't create new ones.
74 
75### Pull Requests
76 
77Describe the pull request in terms of the problem it addresses and the approach it takes—avoid titles like "update tests" that hide the intent. A good title should hint at both the underlying issue and the chosen fix, e.g. `Fix backlog replay flake by stabilizing event helper`. Frame the story around the impact to downstream data consumers or workflows rather than generic "user-facing" language.
78 
79Checklist:
80 
81- State the problem, solution, and validation steps in the PR body using the template sections.
82- Mention any trade-offs or follow-up work the reviewer should know about.
83- Research relevant issues and link them to the PR.
84- Note which tests were run (or why none were needed).
85- Keep the title and description in sync with the current scope as the work evolves—update them whenever the plan shifts.
86- Keep CHANGELOG.md up to date with the changes in the PR according to `contributor-docs/changelog-guide.md`.
87- Make sure to apply appropriate labels. Don't create new labels, but only reuse existing ones.
88- After every substantial change (new commit, merge, or rebase), reread the PR title/body and refresh them before pushing or requesting review.
89- When possible, include demo evidence (logs, screenshots, CLI commands, or quick diagrams like Mermaid/ASCII) that demonstrates the change from a data-workflow perspective so reviewers can visualize the impact faster.
90 
91### Environment Variables
92 
93- Keep sensitive environment variables in `.envrc.local` and never commit them to the repository.
94 
95## Documentation / Examples
96 
97- It's critical that the documentation and examples are up to date and accurate. When changing code, make sure to update the documentation and examples.
98- The `docs/` site derives from the intent layer (see Intent Layer above): update the owning `context/` node first, then the derived docs page — divergence between them is a docs bug.
99- For code snippets make sure to follow ./contributor-docs/docs/snippets.md
100