AGENTS.md — TypeScript npm library

A publishable TypeScript package with an explicit exports map, correct types for every consumer, a tracked public API and semver releases from changesets.

Setup and commands

• dev: pnpm dev
• lint: pnpm lint && pnpm typecheck && pnpm publint && pnpm attw --pack .
• test: pnpm test
• build: pnpm build
• deploy: pnpm changeset publish
• install: pnpm install --frozen-lockfile

Project structure

• src/index.ts — The public entry point; re-exports only what is part of the API
• src/<module>/ — Implementation, one folder per concept, with tests beside the code
• src/internal/ — Helpers that are never exported from the package
• etc/<package>.api.md — API report generated by API Extractor; changes show up in review
• .changeset/ — One changeset per user-facing change, with its semver bump
• examples/ — Small consumer projects (ESM and CJS) used as smoke tests
• package.json — exports map, files allow-list, sideEffects:false, engines and peerDependencies

Code style

• Files: kebab-case.ts
• Tests: *.test.ts beside the file; *.test-d.ts for type-only tests
• Branches: type/short-description, e.g. fix/retry-backoff-jitter
• Components: Exported functions camelCase verbs; classes and types PascalCase; error classes end in Error

Code

• Prefer small, pure functions and explicit types at module boundaries. (Easier to test, review and change.)
• Expose the API only through the exports map; every exported function has explicit parameter and return types and a doc comment with an example. (Consumers cannot depend on internals, and the API report stays readable.)
• Any removal, rename, narrowed input or widened output in the API report is a major version; additions are minor; fixes are patch. (Consumers rely on semver ranges to upgrade without reading every release.)

Components

• Components read design tokens; no raw hex values, pixel sizes or font names in component code. (One token change restyles the product.)

Data

• Analytics events are object_action in snake_case and come from the experience skill’s measures. (Names stay consistent across teams and tools.)
• Accept I/O dependencies (fetch, timers, storage) as options with sensible defaults instead of reaching for globals. (Works across runtimes and is easy to test.)

Errors

• Every async action has loading, empty, error and success states, matching the experience skill. (Unhandled states are where users get stuck.)
• Throw subclasses of Error with a stable code property and the original error as cause; never throw strings. (Callers can branch on codes that survive message rewording.)

Security

• Secrets never live in the repository; read them from the environment or a secret store. (A leaked key outlives the commit that removed it.)
• Validate every input on the server, even when the client already did. (Clients can be bypassed.)
• Web pages ship a Content-Security-Policy, HSTS, X-Frame-Options and nosniff. (Cheap protection against the most common attacks.)
• Publish only from CI with provenance and a granular, automation-only token; the files allow-list excludes tests, fixtures and source maps of private code. (A hijacked laptop or a stray .env must not end up in a published tarball.)

Performance

• Keep sideEffects:false and no top-level work; prefer zero runtime dependencies, and frameworks only as peerDependencies. (Bundlers can tree-shake unused exports and consumers avoid duplicate copies.)

Accessibility

• Use native elements first; add ARIA only when no native element fits. (Native controls bring keyboard and screen-reader support for free.)

Design and journeys

This stack has no UI; design skills do not apply.

When a Celestial experience skill is in use, give each journey one end-to-end test (happy path plus its error and empty states) and name analytics events object_action from its measures.

Testing and checks (must pass before a pull request)

Pull requests

• Branching: Trunk-based: short-lived branches off main; maintenance branches only for supported previous majors.

Review checklist

• Correctness: does it do what the issue asks, including edge cases?
• Readability: could a new teammate change it safely?
• Architecture: is it in the right place, with the right boundaries?
• Security: inputs, secrets, permissions, dependencies
• Performance: budgets, queries, bundle size
• Tests fail when the code is broken (flip a condition and re-run)
• One approving review; two for any change to the API report
• Reviewer reads the changeset as release notes

Definition of done

• Acceptance criteria met and demoed on the preview link
• Tests added for new behaviour and every state
• Accessibility and performance gates green
• Analytics events named from the experience skill
• Docs or changelog updated when behaviour changes
• Changeset added for every user-facing change
• Doc comments and README examples updated and type-checked

Release

• Small pull requests (aim for under 400 changed lines)
• CI green before review
• Squash-merge to main; main is always deployable
• Every release has a written rollback path
• A release pull request collects changesets; merging it versions, tags and publishes from CI
• CHANGELOG.md generated from changesets in Keep a Changelog sections

Incidents

• Publish a fixed patch and deprecate the bad version with a message pointing to it
• Write a blameless note within 48 hours: what happened, impact, fix, prevention

Generated from the Celestial engineering skill “TypeScript npm library” (engineering core v1.0, checked 2026-10-26).