Agent notes
pnpm, TypeScript 7, Oxlint and Oxfmt mistakes to avoid.
Look up a version with pnpm view <package> version when you add or bump it, and pin it exactly in the pnpm-workspace.yaml catalog. Workspaces reference it as "catalog:". Do not rely on a version you remember.
minimumReleaseAge (1440 minutes) blocks packages published less than a day ago. Do not disable it or add broad excludes to install a new release. Pick the newest version that clears the gate, and add a narrow, commented exclude only for the packages already listed in the toolchain rule.
Typecheck runs tsc --noEmit from TypeScript 7; it keeps the default of four checkers (ADR 0017). Do not add TypeScript 5 or 6 shims for repo code, and do not enable Oxlint's typeCheck option. Omit optional properties instead of passing undefined, and read index signatures with obj["key"].
Ultracite 8 supplies the Oxlint and Oxfmt presets. The root oxlint.config.ts extends core, vitest, shadcn, and anti-slop, plus the react-doctor and tsdoc plugins, with typeAware on. eslint-plugin-github stays out: it loads typescript-eslint, which rejects TypeScript 7. Next.js apps also extend react, next, and next/js-plugins. React workspaces extend react. Other workspaces extend the root config only, and each one repeats ignorePatterns and settings because Oxlint does not inherit those through extends. Run pnpm lint (Turbo) for workspaces and pnpm lint:root for root tooling files. pnpm check and pnpm fix run ultracite check and ultracite fix. Fix the code when a rule fires. Do not turn a rule off. A disable comment is only for a case the code cannot change, and it names the rule and the reason.
House rules after the presets ban the schema and icon packages the repo does not use, read process.env only in env modules, config files, scripts, and tests, and keep Testing Library checks on test files.
The anti-slop plugin requires a // SAFETY: comment above every as assertion that explains why it holds. Prefer a schema parse or a typed helper, and never write as unknown as T.
Do not add code comments or doc blocks: no // explanations, JSDoc or TSDoc, /* */ blocks, or -- explanations in hand-written SQL. Say it with names instead. The exceptions are lint suppressions the toolchain requires, the // SAFETY: comments above, and the route JSDoc that pnpm openapi:generate reads. Before a commit, git diff --cached | grep -E '^\+\s*(//|/\*|\*|--)' shows any you added.
Oxfmt formats with semicolons at print width 80, from ultracite/oxfmt plus the house sort and ignore settings in oxfmt.config.ts. Run pnpm format (root files plus every workspace). Vendored ReUI, AI Elements, and cropper.tsx stay on the lint and format ignore list.
redirectPassing the typed-routes Route union straight to redirect() from next/navigation makes tsc hang with no output. Write redirect<string>(toRoute(...)), as the existing auth and OAuth pages do.
Install, update and remove skills with pnpm dlx skills add, pnpm dlx skills update -p -y and pnpm dlx skills remove, so skills-lock.json lists them. reui is the one exception: the ReUI installer writes it, and its header names the version to compare against the ReUI MCP's get_agent_skill. Update it by running the ReUI installer again, not by editing the folder, and keep .agents/rules/reui.mdc in step.
tsgo can report phantom errors, such as TS4111 on a property the schema declares, from a stale tsconfig.tsbuildinfo. Delete that workspace's tsconfig.tsbuildinfo and run the typecheck again before changing code.
Last updated on