Skip to content

AGENTS.md

Latest commit

 

History

History
122 lines (83 loc) · 6.75 KB

AGENTS.md

File metadata and controls

122 lines (83 loc) · 6.75 KB
Raw

Project-Specific Instructions for Coding Agents

Setup

Minimal Setup

For ordinary TypeScript, core unit-test, Vite, local Wrangler, and docs-check work, provide Node.js 24, Bun, and the exact pnpm version declared by package.json#packageManager, then run:

./scripts/bootstrap-minimal.sh

The script verifies prerequisites and performs a frozen install; it never installs tools globally. Bun 1.3.13 is the known-good Docker realization. The optional root compose.yaml supplies that toolchain in an exclusive bind-mounted checkout.

Full Setup (Nix + devenv)

Run devenv shell for Playwright and full docs builds, generated-source or wa-sqlite changes, release and infrastructure work, or repository-wide parity. Before final handoff, escalate to this lane whenever the relevant validation extends beyond the finite Minimal Setup checks; setup success never substitutes for the full required CI bar. The authoritative boundary is context/03-delivery/01-composition/01-developer-environment/spec.md.

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