CodeVetter · Repo Unpack · Contributor handoff
colinhacks/zod
Future agents should treat this as a performance-sensitive library with several mutually dependent execution modes, not as a conventional web application. The safest workflow is to inspect the relevant facade, core implementation, and focused tests before making the smallest possible change. Runtime correctness alone is insufficient for changes under `packages/zod/src`; memory and bundle impact are first-class acceptance criteria. Release operations, version changes, GitHub ticket workflows, and new files all have explicit repository-specific constraints.
- Read `AGENTS.md`, the relevant public facade, the corresponding core schema/check implementation, and the focused test file before editing; `CLAUDE.md` is only a symlink to the same instructions.
- Use Nub exclusively: install with `nub install --frozen-lockfile`, run repository TypeScript with `nub`, scripts with `nub run`, and third-party tools with `nub exec --node`.
- Start verification with the smallest relevant Vitest file or test name, then run broader tests; every bug fix or feature must include focused TypeScript test coverage for success, failure, and meaningful edges.
- For compiler changes, run the direct compiler and differential suites plus `nub run test:compile`; compile mode is already part of the full root test command.
- Any non-trivial source change must report runtime, retained-memory, and bundle-size measurements together; core changes affect every distribution, and mini requires a separate bundle-size result.
- When changing constructor or property-placement machinery, preserve descriptors and instance shapes, then run the memory surface and dictionary-mode checks because accessor placement can cause large V8 regressions.
- Do not add schema-type-specific branching to shared parse paths; expose capabilities structurally through internals such as `optin`, `optout`, `values`, `pattern`, or `propValues`.
- Do not widen format validators solely because a specification permits more inputs; repository policy prioritizes observed producer/consumer compatibility, JSON Schema consistency, hot-path cost, and narrow defaults.
- Keep comments short, avoid consecutive prose `//` lines, add no debug logging, and run `nub run check:comments` alongside format and lint checks.
- Do not bump package versions or dispatch the release workflow without explicit maintainer direction; release publication is manual and protected by an npm environment approval.
- For docs changes, remember that production ecosystem builds require `GITHUB_TOKEN`, content lives under `packages/docs/content`, and the build is a Next/Turbopack invocation from the docs workspace.
- Run built-package resolution and integration checks after `nub run build`; source-condition tests cannot prove CommonJS, ESM, declaration, or downstream framework compatibility.
- For GitHub issues or PRs, use the repository triage workflow and `gh`; contributor PR modifications belong in a worktree, and new remote branches must be pushed with an explicit refspec to avoid updating `main`.