Skip to main content
Set up the repository, verify your change, and prepare it for independent review.

​
Prerequisites

  • A local checkout of this repository.
  • The Node version in .node-version and the pnpm version in package.json.
  • The root AGENTS.md and the instructions for any package you change.

​
Local setup

​
1. Install dependencies and build

From the repository root:
Expected result: pnpm installs the locked dependencies and Nx builds packages in dependency order. A successful build exits with status 0.

​
2. Make your change

Follow the workflow and conventions below.

​
Before submitting a PR

​
3. Run the checks

From the repository root:
Expected result: Nx reports successful build and test targets; lint and format checks exit with status 0. Build before lint so typed linting can resolve package declarations. pnpm check runs pnpm lint and pnpm format:check. A documentation change also runs pnpm docs:check:drift, which regenerates module pages and constants before comparing them. Run it from the repository root after committing your authored docs edits, because its comparison includes all tracked changes under docs/:
Expected result: regeneration leaves no diff, constants and imports checks report success, and the link check reports no broken internal links.

​
Monorepo conventions

  • Package manager: pnpm 10+ with workspaces
  • TypeScript: strict mode, ES modules
  • Runtime model: Effect services and typed error channels
  • Formatting: oxfmt
  • Testing: vitest
  • Task graph: Nx derives package order from declared dependencies

​
Workflow

Understand the task, decide if needed, implement and test, obtain independent review, then ship. A routine fix stays in its issue/PR. A coordinated feature gets one plan; a durable design choice gets one complete ADR with source evidence, independent review, and explicit owner approval. The original request or issue authorizes bounded implementation without another approval ritual. Public specifications in docs/vision.md and docs/spec/, together with the checks in this repository, are the authority for every contribution. A new boundary choice updates its public specification before implementation.

​
Architecture checks

pnpm lint runs the architecture gates: the package graph and boundary check, arch:check for every package, and arch:config:check. Run a gate on its own from the repository root while you work. Successful analysis and drift checks exit with status 0; generation writes the package configuration files: Package budgets come from scripts/architecture/gen-configs.ts; the JSON files are its output, so change a budget in the generator and regenerate. Exceptions are safer-arch-ignore directives in the source, most at the top of the file they cover. List them from the repository root:
Expected output: matching source paths, line numbers, and directives. Raising a budget or adding a directive is an architecture review point: say so in the PR description.

​
Documentation

The docs site at docs/ is built with Mintlify. Source JSDoc generates per-folder module pages, and source-owned constants generate shared snippets. Run pnpm docs:generate before landing changes to either surface.
  • Guides and development pages: edit the MDX files directly in docs/.
  • Module pages and constants: edit their source or generator, then run pnpm docs:generate.
  • Reusable content: shared snippets live in docs/snippets/.

​
Code style

  • Decode network, disk, environment, and dynamic-import inputs with Effect Schema.
  • Declare branded domain values in their owning package.
  • Keep typed errors in the Effect error channel.
  • Prefer integration tests at real process and storage boundaries.

​
Maintainer releases and records

​
Branches and releases

  • main is the only long-lived branch; every change lands there by pull request.
  • Releases are manual runs of .github/workflows/publish.yml. The dispatched run computes one calendar version, commits it for the public packages that changed since their last published version, along with any changelog section it writes from the fragments in changelog.d/, pushes that release commit and its tag, and dispatches a second run. The second run publishes from the release commit, so npm’s provenance names it. Building and packing run in a job that holds no token; the push and the publish run in separate jobs in the release GitHub environment, whose required reviewers gate every release. The push uses a GitHub App token: RELEASE_APP_ID is an Actions variable and RELEASE_APP_PRIVATE_KEY an Actions secret for an App installed on this repository with contents write access and allowed to push main. npm publishes without a token, so each published package lists publish.yml on this repository as a trusted publisher.
  • A release commit on main whose version some package still lacks on npm is resumed by every later run. When that release can never complete, dispatch with Start a new version checked: the run leaves the release commit alone, takes the next free version from the tip, and the maintainer deprecates whatever the abandoned version did publish.
  • The OpenClaw and NanoClaw agent images are built and published outside this repository, not by a release here.
  • Public design contracts live in docs/vision.md and docs/spec/; see AGENTS.md for package-specific instructions.

​
Next steps

  • Obtain independent review and submit your pull request using the workflow in AGENTS.md.
  • Read the architecture and applicable specifications before changing a package boundary.
  • Follow the upgrade guide when deploying a reset release.