Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 5 additions & 31 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,8 @@
# Working in `native-dates`

Read [`ai/contributing/README.md`](ai/contributing/README.md) first for the contributor routing table (`ai/skills/` is reserved for downstream user skills published with the npm package, while `ai/contributing/` holds internal repository records).
Read [`ai/contributing/curriculum.md`](ai/contributing/curriculum.md) before authoring or editing code (`ai/skills/` is reserved for downstream user skills published with the npm package, while [`ai/contributing/`](ai/contributing/README.md) holds internal agent context and repository records).

**Fixing or reporting a bug, or adding a feature?** Read [`CONTRIBUTING.md`](CONTRIBUTING.md), then load [`ai/contributing/workflows/contribute.md`](ai/contributing/workflows/contribute.md) for the reading order, workflow steps, and human-author requirements.

Before authoring or editing code in this repository, read:

1. **[`ai/contributing/north-star.md`](ai/contributing/north-star.md)**: Hand-authored by the maintainer on project goals, the Golden Rule, call-site SNR, lowercase-"c" correctness, conciseness, and Bayesian rulings. Read with the weight of a live user turn, and never edit or polish its human voice.
2. **[`ai/contributing/standards/lessons/naming-lessons.md`](ai/contributing/standards/lessons/naming-lessons.md)**: Hand-authored by the maintainer on callsite legibility, plain industry terms over metaphors, function signatures, and naming. Read with the weight of a live user turn.
3. **[`ai/contributing/standards/lessons/simplicity-lessons.md`](ai/contributing/standards/lessons/simplicity-lessons.md)**: Mental-model simplicity over clever mechanisms, synthetic adapters, or cross-module monkey-patching.
4. **[`ai/contributing/standards/coding-standards.md`](ai/contributing/standards/coding-standards.md)** and **[`ai/contributing/standards/code-comments.md`](ai/contributing/standards/code-comments.md)**: Class anatomy with `Symbol.for` branding, plus folder homogeneity and comment standards.
5. **[`ai/contributing/reference/architecture.md`](ai/contributing/reference/architecture.md)**: Package boundaries across `native-dates` (`src/`), `@native-dates/plugins` (`packages/plugins/`), `@native-dates/polyfill` (`packages/polyfill/`), and `ai/skills/`, plus invariants and size measurement.
6. **[`ai/contributing/budget.md`](ai/contributing/budget.md)**: Bundle ceilings, per-PR byte limits, and the size budget rules.
7. **[`ai/contributing/decisions.md`](ai/contributing/decisions.md)**: Package design decisions. Grep the noun you are about to touch and check the latest dated entry.

Load task-specific guides when relevant:

- **[`ai/contributing/standards/legibility/`](ai/contributing/standards/legibility/README.md)**: Craft guides for `code-structures`, `errors-and-logs`, `folders-and-filenames`, `tests-and-test-names`, and `traces-and-timelines`. Paths in those files reference the upstream repo they were written in, while the rules apply here.
- **[`ai/contributing/workflows/author-user-skill.md`](ai/contributing/workflows/author-user-skill.md)** and **[`ai/contributing/standards/ai-author-context.md`](ai/contributing/standards/ai-author-context.md)**: Authoring, chunking, and evaluating downstream user skills in `ai/skills/`.
- **[`ai/contributing/workflows/clean-room-dx-review.md`](ai/contributing/workflows/clean-room-dx-review.md)**: Running a quarantined fresh-reader DX review over candidate public API surface.
- **[`ai/contributing/workflows/read-ci-reports.md`](ai/contributing/workflows/read-ci-reports.md)**: Interpreting Bundle Size and Bench pull request comments (`Unsure` is unresolved noise, and within budget does not mean free).
- **[`ai/contributing/workflows/extend-bench-suite.md`](ai/contributing/workflows/extend-bench-suite.md)**: Adding or modifying benchmark operations in `bench/`.
- **[`ai/contributing/workflows/docs-writing.md`](ai/contributing/workflows/docs-writing.md)**: Writing or editing guide, API, or plugin pages under `docs/src/content/`.
- **[`ai/contributing/workflows/docs-authoring.md`](ai/contributing/workflows/docs-authoring.md)**: Updating the Astro docs site and its required features.
- **[`ai/contributing/workflows/docs-i18n.md`](ai/contributing/workflows/docs-i18n.md)**: Translating finalized documentation before a release or changing locale routing.
- **[`ai/contributing/standards/name-public-api.md`](ai/contributing/standards/name-public-api.md)** and **[`ai/contributing/standards/author-pull-requests.md`](ai/contributing/standards/author-pull-requests.md)**: Naming public API symbols and titling pull requests.
- **[`ai/contributing/standards/types.md`](ai/contributing/standards/types.md)**: Hand-authoring `.d.ts` files in `types/` and `packages/plugins/types/`. Their doc comments power editor hover/autocomplete, and each `@see` link opens the matching docs page on `nativedates.dev`.
- **[`ai/contributing/standards/utility-functions.md`](ai/contributing/standards/utility-functions.md)**: Reference for `@semantic-ui/utils`. **`native-dates` has zero runtime dependencies** — never install or import `@semantic-ui/utils`; check here for canonical names and behavior, then copy only the minimal reached implementation into `src/helpers/utils.js` or `src/helpers/environment.js`.

Files in [`ai/contributing/standards/`](ai/contributing/standards/README.md) are synced from upstream Semantic repositories. Some internal links reference skills outside this repo, and those files are not edited directly here.
**Fixing or reporting a bug, or adding a feature?** Read [`CONTRIBUTING.md`](CONTRIBUTING.md), follow [`ai/contributing/curriculum.md`](ai/contributing/curriculum.md), and load [`ai/contributing/workflows/contribute.md`](ai/contributing/workflows/contribute.md) for the workflow steps and human-author requirements.

## House Rules

Expand All @@ -42,7 +16,7 @@ Files in [`ai/contributing/standards/`](ai/contributing/standards/README.md) are
- **Structured errors:** Build every error via `refuse()` or `refuseType()` in `src/helpers/errors.js` (`dates refused [code] at`). Explanations are gated behind `isDevelopment` (`NODE_ENV !== 'production'`) so production builds omit diagnostic prose (`ai/contributing/standards/legibility/errors-and-logs.md`, checked by `npm run errors` and `npm run size`).
- **Behavioral tests and environments:** Assert `error.code` and `error.at` rather than matching prose sentences (`ai/contributing/standards/legibility/tests-and-test-names.md`). Each package's tests live with it (`test/` for `native-dates` and `packages/<name>/test/` for the others) and import packages by their public names; repo and CI tooling tests live under `tools/`. Place pure Node tests in `test/` (core nouns at the top, cross-cutting suites in subfolders like `test/format/` and `test/helpers/`), DOM tests in `test/dom/`, and real Chromium Playwright tests in `test/browser/` (`vitest.config.js`).
- **Category-grouped helpers:** Group free functions by domain in `src/helpers/` (`intl.js`, `zones.js`, `parse.js`, `format.js`, `errors.js`, `utils.js`, `environment.js`).
- **Decision records:** Record package behavior decisions in `ai/contributing/decisions.md` and repository process decisions in `ai/contributing/project-decisions.md`, each dated with a reopen condition and an optional maintainer confidence score.
- **Decision records:** Read [`ai/contributing/decisions/README.md`](ai/contributing/decisions/README.md) before recording a decision. Only log entries in `ai/contributing/decisions/package.md` (`D<n>`) or `ai/contributing/decisions/project.md` (`P<n>`) when choosing between competing mental models, rejecting a tempting alternative, or reverting a measured experiment (never for normal features, enhancements, or bug fixes), then run `npm run ai:index` to update `ai/contributing/decisions.md`.
- **Scratch directory:** Put temporary plans and notes in git-ignored `ai/workspace/`.

## Undecided
Expand All @@ -59,8 +33,8 @@ Ask the maintainer rather than inventing conventions for:
- `npm run types`: Type-check `.d.ts` declarations via `tsc --noEmit` under NodeNext and `bundler` resolution (`test/types.ts`)
- `npm run errors`: Check error and log prose register (`tools/gates/errors.js`)
- `npm run comments`: Check comment density, overlap, and banned jargon (`tools/gates/comments.js`)
- `npm run ai`: Validate markdown links, `#anchors`, GFM tables, `ai/` paths, `decisions-index.md`, and `AGENTS.md` symlinks (`tools/gates/ai.js`)
- `npm run ai:index`: Regenerate `ai/contributing/decisions-index.md` from `ai/contributing/decisions.md` (`tools/gates/decisions-index.js`)
- `npm run ai`: Validate markdown links, `#anchors`, GFM tables, `ai/` paths, `decisions.md`, and `AGENTS.md` symlinks (`tools/gates/ai.js`)
- `npm run ai:index`: Regenerate `ai/contributing/decisions.md` from `ai/contributing/decisions/package.md` (`tools/gates/decisions-index.js`)
- `npm run size`: Measure minified and Brotli-11 sizes for `native-dates` and every plugin in `@native-dates/plugins`, and check `ai/contributing/budget.md` ([`tools/ci/bundle/README.md`](tools/ci/bundle/README.md))
- `npm run docs`: Start the Astro docs dev server (`docs/`, see [`docs/README.md`](docs/README.md))
- `npm run format`: Format files with `dprint`
Expand Down
24 changes: 8 additions & 16 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,30 +7,23 @@ Short guide for contributors and coding agents working on their behalf.
| Goal | Starting point |
|---|---|
| Report a bug | Follow [Bug Reports](#4-bug-reports) |
| Fix a bug | Complete [Required Reading](#2-required-reading), then open a pull request |
| Fix a bug | Check [Before Coding](#2-before-coding), then open a pull request |
| Add a feature or change public exports | Open an issue first to agree on scope and API before writing code |
| Fix a typo or broken link | Open a pull request directly |

## 2. Required Reading
## 2. Before Coding

Read these files in order so new code matches existing conventions:

1. [`ai/contributing/north-star.md`](ai/contributing/north-star.md): hand-authored by the maintainer on project goals, the Golden Rule, call-site SNR, lowercase-"c" correctness, conciseness, and Bayesian rulings
2. [`ai/contributing/standards/lessons/naming-lessons.md`](ai/contributing/standards/lessons/naming-lessons.md) and [`ai/contributing/standards/lessons/simplicity-lessons.md`](ai/contributing/standards/lessons/simplicity-lessons.md): callsite design, naming, and mental-model simplicity across Semantic packages
3. [`ai/contributing/standards/coding-standards.md`](ai/contributing/standards/coding-standards.md) and [`ai/contributing/standards/code-comments.md`](ai/contributing/standards/code-comments.md)
4. [`ai/contributing/budget.md`](ai/contributing/budget.md): bundle size ceilings and per-PR limits
5. [`ai/contributing/decisions.md`](ai/contributing/decisions.md): prior design decisions and reopen conditions

**Using a coding agent?** Point it at [`ai/contributing/workflows/contribute.md`](ai/contributing/workflows/contribute.md) for the workflow and handoff checklist.
- **Human developers:** Scan [`ai/contributing/decisions.md`](ai/contributing/decisions.md) (and [`ai/contributing/decisions/project.md`](ai/contributing/decisions/project.md) for repo process) to see prior design decisions on the area you are touching, and run `npm install` so the pre-commit hook formats staged files with `dprint` automatically.
- **Coding agents:** Read [`ai/contributing/curriculum.md`](ai/contributing/curriculum.md) before working, and load [`ai/contributing/workflows/contribute.md`](ai/contributing/workflows/contribute.md) when assisting on an issue or pull request.

## 3. Pull Requests

- **Title:** `Category: Description` (both capitalized, without a trailing period). Categories: `Bug`, `Feat`, `Docs`, `Refactor`, `Perf`, `Test`, `Build`, `Chore`, `Harness`, `Bench`, `BREAKING`. Example: `Bug: Fix DST Offset Across Spring Forward`.
- **Description:** Fill out the [PR template](.github/pull_request_template.md) in your own words. One sentence of context and a few bullets is usually enough.
- **Single scope:** Separate bug fixes and refactors into independent pull requests.
- **Regression test:** Include a test that failed before the fix. Back up any size or performance claim with measurements.
- **Size budget:** The Bundle Size check compares production Brotli sizes against [`ai/contributing/budget.md`](ai/contributing/budget.md). Bug fixes aim for 0 added bytes. If a change exceeds the budget, follow the options in `ai/contributing/budget.md` (see [`ai/contributing/workflows/read-ci-reports.md`](ai/contributing/workflows/read-ci-reports.md)).
- **Checks and formatting:** Run `npm run check`, `npm run types`, `npm run errors`, `npm run comments`, and `npm run format`, or run `npm run setup` once to install git hooks.
- **Size budget:** The Bundle Size check compares production Brotli sizes against [`ai/contributing/budget.md`](ai/contributing/budget.md). Bug fixes aim for 0 added bytes.
- **Checks and formatting:** `npm install` sets up git hooks that run `dprint` on staged files. Run `npm run check` and `npm run types` before opening a pull request.

## 4. Bug Reports

Expand Down Expand Up @@ -61,12 +54,11 @@ Every pull request in this repository is reviewed and merged by a human maintain
## Local Setup

```sh
npm install # install all workspaces
npm run setup # install git hooks once
npm install # install workspaces and git hooks (dprint on commit)
npm run docs # start docs dev server
npm run check # run tests, ai markdown checks, and bundle size budget
npm run types # type-check .d.ts declarations
npm run errors # check error prose register
npm run comments # check comment density and voice
npm run format # format with dprint
npm run format # format all files with dprint
```
14 changes: 8 additions & 6 deletions ai/contributing/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@ Internal records and workflows for developing `native-dates`. Application develo

| Task | Reading order |
|---|---|
| Onboard a coding agent before working | [`curriculum.md`](curriculum.md) (stages 1–4) |
| Fix a bug, add a feature, or file a bug report | [`CONTRIBUTING.md`](../../CONTRIBUTING.md), then [`workflows/contribute.md`](workflows/contribute.md) |
| Check design or process rulings | [`decisions-index.md`](decisions-index.md) and [`decisions.md`](decisions.md) for package behavior, [`project-decisions.md`](project-decisions.md) for repo process |
| Check or record design and process decisions | [`decisions.md`](decisions.md) for the topic index, [`decisions/README.md`](decisions/README.md) before adding or reopening an entry, [`decisions/package.md`](decisions/package.md) (`D1`..`Dn`), and [`decisions/project.md`](decisions/project.md) (`P1`..`Pn`) |
| Check bundle size limits | [`budget.md`](budget.md), checked by `npm run size` |
| Configure GitHub secrets, bots, and Vercel deploys | [`reference/setup.md`](reference/setup.md) |
| View pending and completed launch tasks | [`plan/roadmap.md`](plan/roadmap.md) and [`plan/landed.md`](plan/landed.md) |
Expand All @@ -24,9 +25,10 @@ Internal records and workflows for developing `native-dates`. Application develo

| Record | Path | Policy |
|---|---|---|
| Agent curriculum | [`curriculum.md`](curriculum.md) | Ordered 4-stage reading list for coding agents |
| North star | [`north-star.md`](north-star.md) | Hand-authored by the maintainer on project goals, the Golden Rule, call-site SNR, lowercase-"c" correctness, conciseness, and Bayesian rulings (do not edit or polish) |
| Package decisions | [`decisions.md`](decisions.md), [`decisions-index.md`](decisions-index.md) | Append-only dated entries with reopen conditions and optional maintainer confidence scores (`npm run ai:index` updates the index) |
| Project decisions | [`project-decisions.md`](project-decisions.md) | Append-only dated entries for repo process, CI, and docs conventions |
| Decisions index | [`decisions.md`](decisions.md) | Generated topic and chronological index of package decisions (`npm run ai:index`) |
| Decision logs | [`decisions/`](decisions/README.md) | Authoring rules in `README.md`, package rationales in `package.md` (`D1`..`Dn`), and repo/CI process calls in `project.md` (`P1`..`Pn`) |
| Size budget | [`budget.md`](budget.md) | Entry bundles, Brotli ceilings, and per-PR growth rules, updated only by the maintainer |
| Launch plan | [`plan/`](plan/roadmap.md) | Pending rows in `roadmap.md`, completed rows in `landed.md`, and briefs in `plan/scopes/` |
| Shared standards | [`standards/`](standards/README.md) | Synced from upstream Semantic repos and not edited directly here |
Expand All @@ -38,9 +40,9 @@ Create `reopened-decisions.md` or folders for research and archived records only

## Conventions

- Decisions that constrain package behavior or public API belong in `decisions.md`. Repo process and tooling calls belong in `project-decisions.md`.
- Supersede an older decision by appending a new dated entry rather than editing history. The latest date wins.
- `decisions.md` records intent, while `plan/landed.md` records what merged. Source code and tests define current behavior.
- Read [`decisions/README.md`](decisions/README.md) before recording a decision: features, enhancements, and bug fixes do not belong in `decisions/package.md`, and repo process calls belong in `decisions/project.md`.
- Supersede an older decision by appending a new `D<n>` entry and marking the earlier entry `Superseded by D<n> (<YYYY-MM-DD>).` rather than deleting history.
- `decisions/package.md` records non-obvious design constraints, while `plan/landed.md` records milestones that merged. Source code and tests define current behavior.
- Bundle ceilings and benchmark settings are calibrated per package. Only [`standards/`](standards/README.md) is shared across repos.
- Open mutable reference docs with a dated status line instead of writing "not yet built" in body paragraphs.
- Run `npm run ai` after editing files here to check links, heading anchors, Markdown tables, and root symlinks.
Loading