# Project-Specific Instructions for Claude

## Setup

This repository uses [`devenv`](https://devenv.sh) for development environment management. Run `devenv shell` to enter the development environment.

## Intent Layer (`context/`)

`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).

- 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.
- 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.
- `vision.md` and `requirements.md` are protected — confirm with a maintainer before editing them; specs, decisions, deltas, and open questions evolve freely.
- 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/`.

## Tooling

- If tools aren't directly in `$PATH`, enter the dev environment first with `devenv shell`.

- For dependency management see ./context/03-delivery/02-release/dependency-management.md

### `mono` CLI

Use the `mono` CLI for common workflows:

- `devenv tasks run lint:full` / `devenv tasks run lint:full:fix` to run the linting checks
- `mono test <unit|integration|perf>` to run the tests
  - Some tests can take a while to run.
- `mono ts [--watch] [--clean]` to build the TypeScript code
- `mono docs <dev|build|deploy>` for docs workflows
- `mono examples <run|deploy|test>` for example workflows
- ... and more

## Testing

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

## TypeScript

- Avoid `as any`, force-casting etc as much as possible.
- When writing non-trivial code, make sure to leave some concise code comments explaining the why. (Preferably jsdoc style.)
- When refactoring code you don't need to consider backwards compatibility unless specifically asked for.
- Keep exported members at the top of the file and move unexported helpers to the bottom.
- Never add `paths` to `tsconfig.json`. Prefer using `package.json#exports` instead.

## Task Management

Use GitHub issues or an issue checklist for non-trivial work.

- Link the issue in the PR when the repo workflow expects it
- File follow-up GitHub issues for out-of-scope work discovered during implementation

## Git

- The default branch of this repository is `main`.
- Before committing, run `devenv tasks run lint:full:fix` to auto-fix most linting errors. Make sure there are no type check/lint errors.

### Branch Naming Conventions

- 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`
- Keep branch names concise but specific (under 30 characters when possible)
- Use kebab-case for consistency

### Development Workflow

- Run the full test suite before pushing: `devenv tasks run test:run`
- Ensure TypeScript compilation passes: `devenv tasks run ts:check`
- Use `devenv tasks run lint:full:fix` to automatically fix formatting issues

### Issues

- When asked to create a GitHub issue, use the GitHub CLI to do so.
- Add appropriate labels to the issue. Only use existing labels, don't create new ones.

### Pull Requests

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

Checklist:

- State the problem, solution, and validation steps in the PR body using the template sections.
- Mention any trade-offs or follow-up work the reviewer should know about.
- Research relevant issues and link them to the PR.
- Note which tests were run (or why none were needed).
- Keep the title and description in sync with the current scope as the work evolves—update them whenever the plan shifts.
- Keep CHANGELOG.md up to date with the changes in the PR according to `contributor-docs/changelog-guide.md`.
- Make sure to apply appropriate labels. Don't create new labels, but only reuse existing ones.
- After every substantial change (new commit, merge, or rebase), reread the PR title/body and refresh them before pushing or requesting review.
- 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.

### Environment Variables

- Keep sensitive environment variables in `.envrc.local` and never commit them to the repository.

## Documentation / Examples

- 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.
- 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.
- For code snippets make sure to follow ./contributor-docs/docs/snippets.md