Project-Specific Instructions

Stack And Package Management

This is a single-package TypeScript utility library. Use Node 24 from .nvmrc and pnpm 11.2.2 from package.json; do not substitute npm or yarn.
Install with pnpm install --frozen-lockfile. Add dependencies with pnpm add -E so versions remain exact.
The package builds strict ES2020 TypeScript with esbuild and tsc into CommonJS, ESM, and declaration outputs. Tests use Vitest; formatting and linting use Biome. Treat Biome as authoritative over legacy ESLint/Prettier references.

Keep each public utility in src/<kebab-case-name>/<kebab-case-name>.ts, export it by its camelCase name, and colocate tests in <kebab-case-name>.test.ts.
Match nearby source, JSDoc, and test patterns. Biome formatting uses two spaces, single quotes, semicolons, and an 80-column line width.
Name domain values and helpers by intent. Keep casing consistent in code-owned representations; preserve external names at the boundary and map them once. Comment only non-obvious constraints, invariants, tradeoffs, or workarounds.
Name constants for domain rules, limits, durations, units, and protocol values; keep obvious indexes and empty-state literals inline. For repeated closed-set runtime values, use one immutable source and derive TypeScript types from it.
src/index.ts is generated by pnpm run generate-index; do not hand-edit it. A public utility's directory and source filename must match for the generator to include it.
docs-md/api is generated from utility JSDoc by pnpm run docusaurus:generate, which replaces that directory and regenerates src/index.ts.
dist, build, and .docusaurus are generated outputs; do not edit them.

Match existing structure and reuse existing types and helpers. Keep changes minimal, localized, and limited to the requested behavior.
Add or update focused colocated Vitest tests for changed contracts, regressions, and meaningful boundaries, using one representative case per equivalent behavior. Preserve existing assertions unless behavior intentionally changes; skip redundant and implementation-detail cases.
After adding, updating, moving, or removing source code, use the project $verify-source-changes skill to determine the next SemVer version, update docs-md/changelog.md, regenerate documentation and exports, then inspect generated changes and run the required checks.
Do not use format or fix scripts for read-only validation because they rewrite files. Inspect generated changes after build or documentation generation.

Preserve unrelated and untracked user changes. Never use destructive Git commands such as git reset --hard or git checkout -- without explicit approval.
Do not publish the package, deploy documentation, change credentials, or modify dependency policy unless explicitly requested.
Do not stage, commit, tag, or push unless the current task explicitly asks for it.

TEMPLATE_AGENTS.md is a staged reusable reference; active guidance lives in this file and applicable project skills under .agents/skills.
When codex-kit project status reports reconciliation required, use the global $codex-kit-reconcile-agents skill. Preserve local rules, merge only applicable reusable guidance, validate changes, and run codex-kit project mark-applied only after validation succeeds.