open-code-review CLAUDE.md

OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open @/openspec/AGENTS.md when the request:

• Mentions planning or proposals (words like proposal, spec, change, plan)
• Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
• Sounds ambiguous and you need the authoritative spec before coding

Use @/openspec/AGENTS.md to learn:

• How to create and apply change proposals
• Spec format and conventions
• Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

Code Conventions

• TypeScript only: Do not create raw .js or .mjs files unless they serve a config purpose (e.g., vite.config.mjs, eslint.config.mjs). All project code, scripts, and utilities must be written in TypeScript.
• Nx-native automation: Release process automation must use Nx extension points (e.g., VersionActions, preVersionCommand), not npm lifecycle scripts or standalone scripts.
• Agent assets — edit source, then sync: Agent docs, skills, commands, references, and other agent-related files have their source of truth in packages/agents/. ALWAYS edit them there, then run nx run cli:update to write the changes out to the local project's .ocr/ directory. Never hand-edit the generated .ocr/ copies directly — they will be overwritten on the next sync and your edits will drift from source.
• Shared layers live in packages/shared/*, apps never depend on apps (CI-enforced): cli and dashboard are application packages and MUST NOT depend on one another. This DAG is enforced by @nx/enforce-module-boundaries (root eslint.config.mjs, keyed off each project's scope:* tag) and gated in CI via nx run-many -t lint — an accidental dashboard → cli (or shared → app) import fails the build, not just review. Code both apps need (persistence, domain/state, config, cross-platform utilities) lives in dedicated library packages under packages/shared/* that each app depends on directly. The current shared packages are @open-code-review/platform (cross-platform/runtime utilities), @open-code-review/persistence (the node:sqlite adapter db + workflow state lifecycle + test-support + vendor-resume + the node:sqlite runtime precondition runtime-checks — kept in one package because db and state have a mutually-recursive type cycle (db/types.ts ↔ state/types.ts); a package boundary between them would form a dependency cycle. The single-module-instance connection-cache singleton is a consequence of that co-location, not its root cause), and @open-code-review/config (runtime-config + team-config + models).
• Shared packages are source-only, private, and inlined — never published: each packages/shared/* package mirrors platform exactly — private: true, version 0.0.0, every exports condition (types/source/default) points at ./src/*.ts (no build.mjs, no dist), and it is declared by its consumers as a devDependency: workspace:* (consumer-side rule). A shared package still declares its own runtime third-party deps in its dependencies — they are inlined into the consumer's bundle, so they must resolve at build time. esbuild inlines the .ts source into each app's published bundle, so these packages are excluded from the release set (!packages/shared/* in nx.json) and do not join the fixed cli+agents release group. Do NOT give a shared package a build target or a dist — that machinery was removed in the cutover and must not return.
• Graduation is by cause, not by count: a slice graduates from an app package into a packages/shared/* package the moment it is consumed across a package boundary (by the other app, an e2e package, or another shared package) rather than only by its owning app's own code. There is no subpath-count trigger. A genuinely app-internal module stays in its app; the goal is to keep the dependency graph a DAG of app → shared → shared, never app → app.