The CLAUDE.md ### Tooling section is the short list; this file is the full set of rules and their rationale.
pnpm. Run scripts via pnpm run foo --flag, never foo:bar. After package.json edits, pnpm install.
NEVER use npx, pnpm dlx, or yarn dlx — use pnpm exec <package> or pnpm run <script> # socket-hook: allow npx
Bare pnpm@<version> is correct for pnpm 11+. pnpm 11 stores the integrity hash in pnpm-lock.yaml (separate YAML document) instead of inlining it in packageManager; on install pnpm rewrites the field to its bare form and migrates legacy inline hashes automatically. Don't fight the strip. Older repos may still ship pnpm@<version>+sha512.<hex> — leave it; pnpm migrates on first install. The lockfile is the integrity source of truth.
Only the workspace root needs engines.node. Private ("private": true) sub-packages in packages/* don't need their own engines.node field; the field is dead, drift-prone, and removing it is the cleaner play. Public-published sub-packages (the npm-published ones with no "private": true) keep their engines.node because external consumers see it.
Place tool / test / build configs in .config/: taze.config.mts, vitest.config.mts, tsconfig.base.json (the abstract compiler-options layer — fleet-canonical, byte-identical across the fleet), esbuild.config.mts. New abstract configs go in .config/ by default.
Repo root keeps only what must be there: package manifests + lockfile (package.json, pnpm-lock.yaml, pnpm-workspace.yaml), the linter / formatter dotfiles whose tools require root placement (.oxlintrc.json, .oxfmtrc.json, .npmrc, .gitignore, .node-version), AND every concrete tsconfig (tsconfig.json, tsconfig.check.json, tsconfig.dts.json, tsconfig.test.json, etc. — anything with include/exclude/files). Concrete tsconfigs live at the package root so tsc + IDE language-servers discover them natively at cwd; burying them in .config/ breaks the lookup. In monorepos the concrete tsconfig.json lives at each packages/<pkg>/. Concrete configs extend ./.config/tsconfig.base.json (single-repo at root) or ../../.config/tsconfig.base.json (monorepo per-package).
Every executable script (skill runner, hook handler, fleet automation) is TypeScript via node <file>.mts. Bash works on macOS/Linux but breaks on Windows; bash isn't on Windows PATH by default and if [ ... ] / ${VAR:-default} aren't portable. The fleet runs on developer machines (mixed macOS / Linux / Windows / WSL) and CI (Linux), so cross-platform is a hard requirement. Use @socketsecurity/lib/spawn (spawn, isSpawnError) instead of child_process — it ships consistent error shapes (SpawnError), stdioString: true for buffered stdout, and integrates with the rest of the lib. Reach for _shared/scripts/*.mts for cross-skill helpers (default-branch resolution, report formatting); reach for <skill>/run.mts for skill-specific implementation. Reserve .sh for tiny one-shot snippets that genuinely have no Windows audience (e.g., a bin/ wrapper). The lib/ vs scripts/ distinction matches @socketsecurity/lib (public, importable surface) vs per-package scripts/ (private, internal automation) — skill helpers are internal, hence scripts/.
(pnpm-workspace.yaml minimumReleaseAge, default 7 days) — never add packages to minimumReleaseAgeExclude in CI. Locally, ASK before adding (security control).
Every entry in .gitmodules MUST set shallow = true. Every git submodule update --init call (postinstall.mts, CI, manual) MUST pass --depth 1 --single-branch. Upstream repos like yarnpkg/berry, oven-sh/bun, rust-lang/cargo are multi-GB with full history; we only ever need the pinned SHA's tree. A non-shallow init can take 30+ minutes and waste GB of disk on every fresh clone. There is no scenario where the fleet needs upstream submodule history.
FORBIDDEN to maintain. Actively remove when encountered.