ilamy-calendar
AGENTS.md353 starsChanged 43 days agoMITView on GitHub
This file is the canonical instructions for any AI coding assistant working on this repo. CLAUDE.md and GEMINI.md are symlinks to this file, as are .claude/{commands,hooks,rules,settings.json} → .agents/…. Git on Windows defaults to writing symlinks as regular text files containing the target path, which breaks this repo's .claude/* and CLAUDE.md/GEMINI.md symlinks. Before cloning, run: Alternatively, enable Windows Developer Mode (Windows 10+) which flips the default. macOS and Linux work out of the box. These are non-negotiable. Violating any of these…
- Deletes or force-pushes
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository5 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- code-refactor-reviewSkill
- react-doctorSkill
- reduce-bundle-sizeSkill
- release-new-versionSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
32 rules. About 0 are common, 19 are distinctive, and 13 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈19
Distinctive · estimate
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Prefer the plainest solution that works: fewer moving parts, fewer layers, fewer options, no indirection that does not earn its place.
- Distinctive: line 28
If a change needs a long explanation to be understood, simplify the change, not the explanation.
- Distinctive: line 30
NEVER start/stop the dev server.
- Distinctive: line 31
NEVER commit or push without explicit user approval.
- Distinctive: line 35
NEVER commit until the user has TESTED the change themselves and said it is good.
- Distinctive: line 50
NEVER skip writing tests. TDD is mandatory, and a change that touches behaviour needs BOTH unit and e2e coverage, written before the fix.
- Distinctive: line 66
If you cannot verify something yet, say "unverified" in plain words.
- Very specific: line 70
NEVER call a feature done, or a release ready, until it has been exercised in the app people actually use: apps/demo with its default …
- Very specific: line 105
ALWAYS read all the docs in docs/ (every .md file.
- Very specific: line 116
NEVER use npm/node/pnpm as the package manager or runtime.
- Very specific: line 118
NEVER use YYYY-MM-DD format for storage/transmission.
- Very specific: line 119
NEVER import dayjs directly.
- Very specific: line 120
NEVER import datetime from rrule.
- Distinctive: line 121
NEVER add Claude/AI as co-author in commits.
- Distinctive: line 122
NEVER commit directly to main.
- Very specific: line 123
ALWAYS update the dev log (docs/logs/) after making any codebase changes.
- Distinctive: line 131
Update logs: after making any codebase changes — do this BEFORE reporting completion to the user
- Distinctive: line 133
Max 10 files: delete oldest when exceeded
- Very specific: line 156
Run /load-context to load the full codebase map, rules, and recent dev logs before starting work.
- Distinctive: line 231
Before believing any dev-server measurement, confirm which port answered and that only one server is listening.
- Distinctive: line 236
If an error names a missing export that the installed version plainly has, or a React context is "not found" when there is one provider, …
- Very specific: line 298
All CRUD flows through context: addEvent, updateEvent, deleteEvent.
- Very specific: line 318
Every event must have a globally unique uid.
- Distinctive: line 433
Follow the Shadcn design system.
- Distinctive: line 437
Write tests FIRST, then implement (red-green-refactor)
- Distinctive: line 445
Don't add a parallel function next to one that already does the job: update the existing implementation instead of writing a second version …
- Very specific: line 500
Add a scenario to src/scenarios.ts when a fixture is genuinely new.
- Distinctive: line 544
Create a feature branch
- Very specific: line 546
Run tests (bun run test at the root, or bun test inside a package)
- Distinctive: line 547
Ask user to review
- Distinctive: line 548
Wait for explicit approval
- Very specific: line 549
Commit with conventional prefix (feat:, fix:, docs:, etc.), max 100 chars
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — @ilamy/calendar
This file is the canonical instructions for any AI coding assistant working on this repo. CLAUDE.md and GEMINI.md are symlinks to this file, as are .claude/{commands,hooks,rules,settings.json} → .agents/….
Setup (Windows)
Git on Windows defaults to writing symlinks as regular text files containing the target path, which breaks this repo's .claude/* and CLAUDE.md/GEMINI.md symlinks. Before cloning, run:
git config --global core.symlinks trueAlternatively, enable Windows Developer Mode (Windows 10+) which flips the default. macOS and Linux work out of the box.
Hard Rules
These are non-negotiable. Violating any of these is a bug.
- SIMPLICITY IS THE TOP PRIORITY. Code must be dead simple, and so must the
architecture. Code that is hard to read, hard to understand, or built in a
complicated way is not acceptable, however correct it is.
- Prefer the plainest solution that works: fewer moving parts, fewer layers, fewer options, no indirection that does not earn its place.
- Data flows in one obvious, logical direction. A reader can follow where a value comes from and where it goes without jumping around the codebase.
- Name things so the code reads like a description of what it does (see "Code Quality": name every condition and computed value before use).
- If a change needs a long explanation to be understood, simplify the change, not the explanation.
- NEVER start/stop the dev server. It's already running with hot reload.
- NEVER commit or push without explicit user approval. Approval is PER COMMIT and does not carry forward: "commit and push" authorises that one commit, not the next one, and never the rest of the session. Re-asking is the cost of getting this wrong, which is low; committing unasked is not.
- NEVER commit until the user has TESTED the change themselves and said it is good. Green tests are not that signal: they only prove what is covered. When the work is done, say what changed, say how to exercise it, and STOP. Wait. This applies however obvious the fix looks and however many gates pass.
- EXCEPTION to the two rules above, and to the "post it" rule below, for the
roadmap program only (
docs/roadmap.md): the owner has given standing approval for the main session (the "manager") to commit on aroadmap/*branch, push that branch and open its PR againstmain, once the plan's final verification (Delivery process, step 5) passes in full. That verification replaces the owner's manual test. The owner merges; nobody else does. Still NEVER commit tomain, never leave work as a local-only commit, and never comment on, review, label or close issues or PRs without a fresh "post it". Sub-agents never commit, push or post; only the manager does. The PR hook still applies: chaintouch .claude/state/pr-post-approved.flag && gh pr create .... - NEVER skip writing tests. TDD is mandatory, and a change that touches behaviour needs BOTH unit and e2e coverage, written before the fix. Unit tests alone have twice missed real defects on this repo because they construct their own inputs: a hand-made rect hid that dnd-kit measures a time-grid bar as its 28px label rather than the 1463px column, so every drag grabbed the wrong point. Only a spec driving a real pointer over real geometry caught it.
- DOUBLE-VERIFY every claim before you state it. A bug, a cause, a fix, a
standard ("FullCalendar does X"), a measurement: each is a hypothesis until
checked twice, and you do not report it as fact before then.
- Reproduce a bug through the real UI or the public API, never only through
a hand-built input. Then confirm the input is one the app can actually
produce. Two bugs were reported here that did not exist: a "7-hour drop"
that was the probe triggering drag auto-scroll, and a "split business
hours" misplacement fed columns that
getViewHoursnever builds. - Cite the source for a standard (file and line, or the docs URL), read at the version people actually run.
- If you cannot verify something yet, say "unverified" in plain words. When a claim turns out wrong, retract it explicitly and fix every place it was written (code comments, docs, the dev log).
- Reproduce a bug through the real UI or the public API, never only through
a hand-built input. Then confirm the input is one the app can actually
produce. Two bugs were reported here that did not exist: a "7-hour drop"
that was the probe triggering drag auto-scroll, and a "split business
hours" misplacement fed columns that
- ALWAYS hunt the repercussions of a change before claiming it is done. Name the meaning you are changing, sweep for everything that depends on it (duplicated predicates in plugins, siblings in the same function, compensating hacks, tests and docs pinning the old contract), and prove the fix by reverting it and watching a test fail. Passing tests only prove that nothing covered broke. See
.agents/rules/change-impact.md. - NEVER call a feature done, or a release ready, until it has been exercised in
the app people actually use:
apps/demowith its default settings and seed events, and after a website deploy the live demo at https://ilamy.dev/demo. The e2e harness is not that app. Each harness spec loads a small, clean fixture under near-default settings; the demo combines a 600px scrolling calendar,dayMaxEvents,scrollToNow, business hours, atimezone, all three plugins and dense overlapping events. A bug that needs that combination passes every harness spec, and so does behaviour that is correct but that a person meeting the demo reads as broken.- For every user-facing feature a change adds or touches, drive it in the
demo with a real pointer (Playwright
page.mouse, small steps), with the target verified under the pointer (document.elementFromPoint), and check the result in the publishedonEventsChange/onEventUpdate, not in a screenshot. Then record it as a spec that runs against the demo's own configuration, so it gates from then on. - "Renders with no console errors" is not "works". A smoke check that never drags, types or saves proves only that the page loads.
- A probe is evidence only once you have shown it can fail and succeed: run it first where the behaviour is known to work. A handle scrolled out of the grid's viewport, under a sticky header, or a drag that leaves the grid all read as "nothing happened" and are not bugs.
- Example: 3.3.0 shipped event resize as its headline feature, and on release day the owner tried it in the demo and could not resize anything. 19 resize specs, two QA rounds, a regression check against 3.2.1 and a smoke test of the Vite example had all passed, and none had dragged an edge in the demo. Resize worked. The demo turns business hours on (Mon-Fri 9:00-17:00), business hours refuse a drop on a closed cell, and release day was a Sunday, so the events a person reaches for first were refused with only a not-allowed cursor. Nobody had seen the feature through the demo's defaults before release, so nobody had seen that. Then the first investigation reported a bug that did not exist: its probes pressed handles scrolled out of view or under the sticky header, and measured width on a vertical resize. Checked properly, the same drag on the live demo stayed at 371px with business hours on and grew to 497px with them off.
- For every user-facing feature a change adds or touches, drive it in the
demo with a real pointer (Playwright
- ALWAYS match the established standard, never invent your own semantics. This library is RFC 5545 compliant, and where the RFC is silent its behavior must match FullCalendar and Google Calendar. A deviation is a bug even when it is self-consistent and even when the tests pass. Before choosing behavior for anything a calendar already has a convention for (event boundaries, recurrence and overrides, all-day handling, drag/drop across a resource axis, scheduling semantics), look it up and cite it: the RFC section, the FullCalendar docs or source, or Google Calendar's documented behavior. Two deviations already shipped and had to be undone — an inclusive
end(the RFC's DTEND is exclusive, #248), and a recurrence override emitted from two places at once. If the standard genuinely does not cover the case, say so explicitly and justify the choice; do not quietly pick one. - ALWAYS read all the docs in
docs/(every.mdfile;docs/logs/is covered under Session Start) before changing code. They hold contracts and known gaps the code does not show, and they are what stops a fix from contradicting an earlier decision. In particular,docs/timezones.mdrecords a known gap that matters on any date or time work: dayjs still reads zoned dates through the machine's zone, so a bug can appear only on a machine whose own clocks change. The decided fix is a Temporal migration (withtemporal-polyfill) in the next major, and it is required. Until then, do not pile more patches ontopackages/utils/src/dayjs.tswithout raising it with the user first, and reproduce date bugs with the machine zone set (PlaywrighttimezoneId, or a child process withTZ), not only in UTC. - NEVER use npm/node/pnpm as the package manager or runtime. Always use
bun(invoke tools viabunx, e.g. the demo dev server runsbunx vite). - ALWAYS use the latest published version when adding a dependency. Check
npm view <pkg> versionfor the true latest — never copy version numbers from existing in-repo examples or from memory. Verify peer/engine compatibility and confirm the new major has no breaking changes for the APIs used (per the docs-first rule). - NEVER use
YYYY-MM-DDformat for storage/transmission. Always use ISO strings. - NEVER import dayjs directly. Always import the configured instance from
@ilamy/utils/dayjs. - NEVER import
datetimefrom rrule. Use dayjs. - NEVER add Claude/AI as co-author in commits.
- NEVER commit directly to main. Use feature branches.
- ALWAYS update the dev log (
docs/logs/) after making any codebase changes. This is mandatory — not optional. See "Development Logs" section below. Review-only sessions (nosrc/changes) don't require a log entry — the stop hook (.claude/hooks/check-dev-log.sh) checksgit diff --quiet HEAD -- srcand skips for clean trees. - NEVER post public-facing GitHub content (PR comments, PR reviews, PR creation, issue comments, issue creation) without an explicit, fresh "post it" (or unambiguous equivalent) from the user in their most recent message. "Okay", "looks good", and stale approval from earlier in the conversation do NOT count. A PreToolUse hook (
.claude/hooks/check-pr-post-approval.sh) enforces this by blocking theghcommand unless the same Bash command contains the literal substringtouch .claude/state/pr-post-approved.flagahead of the gh part. Chain the touch and the post in one command:touch .claude/state/pr-post-approved.flag && gh .... The ritual is the deliberate, auditable bridge between conversational approval and the actual post.
Development Logs (MANDATORY)
Daily logs in docs/logs/ track changes across sessions. Update the log after every task that modifies the codebase.
- Check logs at session start to understand recent changes
- Update logs after making any codebase changes — do this BEFORE reporting completion to the user
- Naming:
YYYY-MM-DD.md - Max 10 files: delete oldest when exceeded
- One file per day: append if today's log exists
Log Format
# Development Log - YYYY-MM-DD
## Changes
- **[area]**: What changed and why
## Files Modified
- `path/to/file.ts` - What was changed
## Notes
Context, decisions, things to watch out for.Session Start
Run /load-context to load the full codebase map, rules, and recent dev logs before starting work.
The plugins this repo relies on are declared, not installed, the way Claude Code
documents for team marketplaces. .claude/settings.json lists the kc-claude-kit
marketplace in extraKnownMarketplaces, which Claude Code adds once you trust the folder,
and enables its plugins in enabledPlugins. Since Claude Code v2.1.195 that does not
install a plugin from an external source: Claude Code reports it as not installed and
shows the claude plugin install command to run
(docs).
Installing is a deliberate step because a plugin runs code with your user privileges, so
this repo leaves it to you. Once per machine:
claude plugin install kc-gates@kc-claude-kit
claude plugin install kc-conventions@kc-claude-kit
claude plugin install kc-instructions@kc-claude-kit
claude plugin install kc-verify@kc-claude-kit
claude plugin install kc-usage-band@kc-claude-kit
claude plugin install kc-image-preview@kc-claude-kitclaude plugin install takes one plugin per call, so run each line. They load from the
next session, or after /reload-plugins. A plugin cannot ship rules, so the kit's
conventions load only as rule files: run /kc-conventions:kc-init once to copy them into
this repo's .claude/rules/, or install them for every project into ~/.claude/rules/
as the kit's README describes. The kit's session-start hook says when they are missing or
older than the plugin.
Commands
bun run test # All tests (fans out per package via --filter)
# NEVER run bare `bun test` at the repo root — it bypasses each package's
# bunfig happy-dom preload and fails en masse. Inside a package it's fine.
bun test --coverage # Tests with coverage (run inside a package)
bun run lint # Lint (Biome)
bun run lint:fix # Fix lint issues
bun run format:check # Check formatting (Biome)
bun run format # Fix formatting
bun run check:fix # Combined lint + format fixes
bun run pre-commit # = check:fix
bun run build # Production build (bunup)
bun run type-check # TypeScript check
bun run check:dist-types # Strict tsc over the BUILT dist/*.d.ts (run after build)
bun run ci # Full CI: check + build + check:dist-types + type-check + test
# Match the CI gate locally (Fallow static analysis; CI runs fallow-rs/fallow@v3
# pinned to 3.20.0, config in fallow.toml). Always pass --no-cache:
# `--changed-since` otherwise registers a per-base-sha git worktree under $TMPDIR
# as a cache, and those accumulate in `git worktree list`. --no-cache leaves none.
bunx fallow@3.20.0 audit --changed-since main --gate new-only --no-cacheTroubleshooting the dev server and installs
Two failures that waste hours because they lie about their cause.
A stale dev server serves old config
astro dev prints Stop: astro dev stop and, since Astro 7, supports
astro dev stop / status / logs
(https://docs.astro.build/en/reference/cli-reference/). The running process is
node .../astro.mjs dev, so pkill -f "astro dev" does not match it and
leaves the server alive. Start another and Astro takes the next free port —
4201, 4202 — while your browser and your curl keep hitting 4200.
The result is that you edit config, restart, re-test, and read the old server's behaviour as evidence about the new config. This has already produced a confident and completely wrong "I proved these two changes are load-bearing".
bunx astro dev stop # the reliable stop
lsof -nP -iTCP -sTCP:LISTEN | grep -E ':420[0-9]' # find strays before trusting a resultBefore believing any dev-server measurement, confirm which port answered and that only one server is listening.
A build error that contradicts the lockfile
If an error names a missing export that the installed version plainly has, or a React context is "not found" when there is one provider, suspect duplicate or stale installs rather than the version:
find . -path "*/node_modules/<pkg>/package.json" -not -path "*/node_modules/*/node_modules/*"Nested copies under apps/*/node_modules shadow the hoisted one. This repo has
hit it twice: a nested astro@6.4.6 surviving an upgrade to 7.2.10, which made
the build fail on an export the new version exports; and duplicate copies that
split the calendar context so a plugin could not see its provider.
The fix is a clean regeneration, and it is the first thing to try, not the last:
rm -rf node_modules apps/*/node_modules packages/*/node_modules \
packages/plugins/*/node_modules bun.lock
bun installexamples/* keep their own lockfiles and are installed separately; they are not
part of this.
Architecture
React calendar component library. TypeScript, Shadcn-UI, Tailwind CSS, @dnd-kit, rrule.js.
Monorepo layout (Bun workspaces)
Only @ilamy/calendar is published. It's a monorepo for development, but at build time the internal packages are bundled into the single @ilamy/calendar package; the others are private: true.
packages/
types/ @ilamy/types (private) shared plugin-contract types (no runtime)
utils/ @ilamy/utils (private) configured dayjs (./dayjs) + helpers (./helpers: safeDate, overlapsRange, …)
ui/ @ilamy/ui (private) shadcn primitives
playground/ @ilamy/playground (private) shared interactive demo UI, source-only; consumed by apps/demo + apps/website
plugins/
recurrence/ @ilamy/calendar-recurrence (private) RFC 5545 recurrence plugin
agenda/ @ilamy/calendar-agenda (private) agenda view plugin
drag-to-create/ @ilamy/calendar-drag-to-create (private) drag-to-create plugin
calendar/ @ilamy/calendar (PUBLISHED) the core; bundles the internal packages above
apps/
demo/ @ilamy/demo (private) Vite demo app; consumes @ilamy/calendar's public API
website/ @ilamy/website (private) docs website (deployed via `bun run deploy:website`)
examples/ standalone consumer apps (astro, nextjs, vite) depending on the published package@ilamy/calendar ships these entry points: . (core), ./testing (test harness), ./plugins/recurrence, ./plugins/agenda, ./plugins/drag-to-create. The plugin subpaths' import … from '@ilamy/calendar' self-references the same package at runtime. It ships no CSS — "bring your own design system": components use the conventional shadcn token classes, and consumers @source the package's dist so Tailwind generates the utilities, styled by their own tokens. The demo (apps/demo/src/styles/globals.css) is the reference consumer that supplies a shadcn theme.
Paths in the Key Paths section below are relative to packages/calendar/. Run scripts at the repo root (they fan out via bun run --filter '*' …) or inside a single package. Build resolution: calendar's bunup noExternals the internal @ilamy/* packages (resolved to source via each package's own tsconfig paths: Bun reads the tsconfig nearest the importing file) so they're bundled in; their third-party deps (react, radix, clsx, rrule, …) stay external and are declared in calendar's dependencies. bun run ci builds before type-check/test (the plugin packages + demo resolve @ilamy/calendar through its built dist/*.d.ts).
Data Flow
IlamyCalendar
-> CalendarProvider (all state: events, view, date, translations, CRUD)
-> CalendarDndContext (@dnd-kit wrapper)
-> View components (month/week/day/year)All CRUD flows through context: addEvent, updateEvent, deleteEvent.
Recurring events: updateRecurringEvent, deleteRecurringEvent.
Hook access: useIlamyCalendarContext().
Recurring Events (RFC 5545)
Uses rrule.js with strict RFC 5545 compliance. Three event types:
| Type | Has rrule | Has recurrenceId | ID pattern |
| Base event | yes | no | any |
| Generated instance | no | no | originalId_number |
| Modified instance | no | yes | any |
Core logic in packages/plugins/recurrence/src/utils/ (one file per operation):
generateRecurringEvents()(generate-recurring-events.ts) — create instances from rruleupdateRecurringEvent()(update-recurring-event.ts) — scoped updates (this/following/all) with EXDATEdeleteRecurringEvent()(delete-recurring-event.ts) — scoped deletionsisRecurringEvent()(series-helpers.ts) — identify base vs instance
Every event must have a globally unique uid. EXDATE uses ISO strings in exdates[].
i18n
CalendarProvider handles translations. Props: translations?: Translations or translator?: TranslatorFunction. Falls back to English. All components access via useIlamyCalendarContext().t(). 94 translation keys. See docs/translation-usage.md for full details.
Key Paths
packages/calendar/src/ # (= @/… via tsconfig paths). Bulletproof React layout: imports flow
# shared -> features -> app; biome.json rejects a shared file importing @/features/*
index.ts # Public API exports (app layer)
testing/ # CalendarTestProvider (@ilamy/calendar/testing, app layer) + test fixtures
plugins/ # Plugin subpath entries (@ilamy/calendar/plugins/*, app layer)
features/calendar/ # THE calendar feature: everything calendar-specific
components/
ilamy-calendar.tsx # Main component (carries the resource axis props)
ilamy-resource-calendar.tsx # DEPRECATED alias of IlamyCalendar
views/ # built-in PluginView specs + ViewRenderer dispatcher + resource arrangements, year-view
header/ # Calendar header, title, view controls
event-form/ # Event creation/editing forms
vertical-grid/ # Time-based grid (day/week views)
events-layer/ # The layer, its event bar, and its drag mirror
horizontal-grid/ # Date-based grid (month view)
events-layer/ # Same three, for the row axis
grid-cell/ # The cell and its parts
all-day-row/ # All-day event bar
drag-and-drop/ # @dnd-kit integration + the drag mirror card
draggable-event/ # Draggable event bar + default content
calendar-slots.tsx # SLOT_* mount points + host slot components (context shapes in @ilamy/types)
calendar.tsx (the popover day picker), droppable-cell.tsx, resource-cell.tsx, current-time-marker.tsx, hour-label.tsx, date-picker.tsx, time-picker.tsx
hooks/ # use-calendar-engine composer + engine slices (use-calendar-{config,navigation,interaction}),
# use-smart-calendar-context, use-processed-{day,week}-events, use-effective-business-hours,
# drag hooks (use-calendar-drag, use-drop-commit, use-drag-preview-event), use-scoped-event-mutation, …
calendar-data/ # the data slice: use-calendar-data composes use-event-store, use-event-mutations,
# use-plugin-mutations, use-resource-lookups; event-changes (pure reporting helpers)
stores/ # Calendar STATE (Bulletproof `stores/`)
calendar-context/ # CalendarContext + CalendarProvider (the ONE state provider)
calendar-cell-context/ # CalendarCellContext + CalendarCellProvider (the narrow subset grid cells read)
drag-preview-context.tsx # The in-flight drag candidate (the snapped mirror reads it)
grid-axis-context.tsx # Which grid drew a bar; decides its truncation affordances
utils/ # business-hours, view-hours, event-form-utils, event-pipeline (resource membership),
# keys, normalize, export-ical, drag-preview, grab-offset, event-surface, pointer-within-lazily
layout/ # geometry.ts (PositionedEvent), vertical.ts, horizontal.ts
types/
components/ # Shared, feature-independent UI: animations/, ui/ (picker-nav)
hooks/ # Shared hooks: use-latest-handler, use-autocomplete-timepicker
lib/plugins/ # Plugin kernel; PluginRuntime (contract types live in @ilamy/types)
config/ # constants.ts, translations/ (default translations, types)
utils/ # date-utils (generic date math)
types/ # Shared types (CalendarView, TimeFormat)
# Recurrence plugin (separate package; agenda + drag-to-create siblings follow the same shape):
packages/plugins/recurrence/src/
utils/ # generate-recurring-events, update-/delete-recurring-event, series-helpers (isRecurringEvent)
components/recurrence-editor/ # Recurrence rule builder UI (@ilamy/ui Radix)
components/recurrence-edit-dialog/ # Edit/delete scope dialog
components/date-input.tsx # Native date input for the series end
stores/recurrence-editor-context.ts # The editor's state
augment.ts # declare module '@ilamy/calendar' { CalendarEvent.rrule … }
# Shadcn primitives live in @ilamy/ui (packages/ui/src/components/*), imported via @ilamy/ui/components/<name>.
# Shared React hooks live there too (packages/ui/src/hooks/*), imported via @ilamy/ui/hooks/<name>
# (useRequiredContext: read a context or throw outside its provider).
docs/
rfc-5545.md # iCalendar spec reference
rrule.js.md # rrule.js API reference
export-ical.md # iCal export guide
resource-calendar.md # Resource calendar docs
translation-usage.md # i18n guide
time-grid.md # Time grid architecture & DST handling
timezones.md # Timezone contract: what anchors a date, and when
testing-guide.md # Test patterns, wrappers, mocking
e2e-testing.md # Browser harness: scenarios, what is pinned, what is not tested
types-and-interfaces.md # Type catalog and relationships
hooks-and-context.md # Hook architecture, context system
writing-plugins.md # Plugin authoring guide
custom-views.md # Custom view (PluginView) guide
agenda-view.md # Agenda plugin docs
migration-v2.md # v1 → v2 migration guide
migration-v4.md # v3 → v4: removed names, replacements, defaults under consideration
monorepo-architecture.md # Workspace/build architecture
logs/ # Daily dev logs (see Development Logs)Public API (src/index.ts)
Components: IlamyCalendar (+ IlamyResourceCalendar deprecated alias)
Hooks: useIlamyCalendarContext() (returns IlamyCalendarApi)
Plugin SDK: SLOT_EVENT_FORM, SLOT_EVENT_MUTATION_SCOPE, configured dayjs, contract types (IlamyPlugin, PluginView, ViewConfig, …)
Types: CalendarEvent, CalendarView, TimeFormat, BusinessHours, WeekDays, Resource, Translations, TranslatorFunction, CellInfo, IlamyCalendarProps
Recurrence exports live on the plugin subpath, NOT the core: generateRecurringEvents(), isRecurringEvent(), RRule, RRuleOptions, recurrencePlugin come from @ilamy/calendar/plugins/recurrence.
Code Rules
Dates
- Storage/transmission:
dayjs().toISOString()— always ISO strings - Display only:
YYYY-MM-DDformat is acceptable in UI - Tests: use
'2025-10-13T00:00:00.000Z'ordayjs().toISOString(), never'2025-10-13' - Timezones: with a
timezoneprop the machine's zone decides nothing; without one everything falls back to it. A string carryingZ/±HH:MMkeeps its instant, a string carrying no offset is anchored in the configured zone, and the zone must be applied DURING render (an effect is too late). Readdocs/timezones.mdbefore touching anything that parses a date or callsdayjs.tz.setDefault(see the Hard Rules: the machine's zone still leaks through dayjs until the Temporal migration).
Code Quality
- Extract complex operations into descriptive variables
- Readability beats brevity. Name a value before you use it: every condition
(
const isCurrentHour = isHourGutter && showsToday && isNowHourOfDay), every operand of a boolean chain, and every computed argument, prop or JSX attribute. Pass the name, not the expression:showsToday={isTodayVisible}, notshowsToday={visibleDays.some((day) => isToday(day))}. Write it this way the first time; it is not a cleanup pass for later. - One operation per line, no long chains
- Meaningful names:
targetEventStartISOnottargetEvent.start.toISOString() - Follow the Shadcn design system. Use predefined sizes (sm, default, lg). Don't override design tokens (h-8, h-9, custom spacing) unless absolutely necessary.
TDD
- Write tests FIRST, then implement (red-green-refactor)
- Both layers, not one: a unit test for the rule, an e2e spec for the behaviour through the real UI. Anything involving geometry, pointers, or measurement is e2e or it is unverified.
- Hand the change to the user to test before committing. See the Hard Rules.
- One test file per unit. If
component.test.tsxexists, add to it; never split it into a second file such ascomponent.someFunction.test.tsx. A unit with no tests yet gets a new co-located test file. - Don't add a parallel function next to one that already does the job: update the existing implementation instead of writing a second version of it.
- Exact assertions:
toHaveLength(3),toBe('exact-value')— nottoBeGreaterThan(0)
Testing
- Co-located:
component.test.tsxnext to component files - Integration focus: test through context and user interactions
- Recurring events: verify RFC 5545 compliance
- ~62 test files across the calendar package (45) and the plugin packages
Browser testing (E2E)
apps/e2e is a deterministic browser harness. It mounts IlamyCalendar with
its entire configuration taken from the URL, so any state is reachable by
navigating rather than by clicking through setup. Full rationale, including what
is deliberately not tested, is in docs/e2e-testing.md.
?scenario=resources&view=week&orientation=vertical&slot=15&dayMaxEvents=3&height=500pxA scenario supplies the events (src/scenarios.ts); every calendar
setting is a query parameter (src/harness-config.ts). There are far more
combinations of settings than anyone would write fixtures for, so none are
written. Unknown values render an error rather than falling back to a default.
bun run e2e # the gate
bun run e2e:ui # the same, in Playwright's UI mode- There is no screenshot comparison. Pixel baselines only match the platform that produced them, and every intentional restyle means reviewing a dozen image diffs; a check nobody genuinely reads is worse than no check. Layout is asserted through behaviour and geometry. Revisit this if a purely visual regression ever ships unnoticed.
- Everything is pinned: the clock (
page.clock.setFixedTime), zone, locale, viewport and colour scheme. A calendar renders almost everything from "today", so a suite that lets any of them through asserts something different tomorrow. The pinned instant is2025-03-12T09:00:00.000Z. - Headers animate in over 500ms. Anything that screenshots or measures geometry has to wait them out, or it reads a half-faded, mid-transition frame.
Driving the browser yourself
The repo ships a project-scoped .mcp.json with @playwright/mcp, so browser
tools are available without per-machine setup. Use them to investigate — to
answer "does this look right" on a state no spec covers yet.
Anything you find that way gets recorded as a spec before the work is done. An exploratory pass is not coverage: it proves the bug exists once, on your machine, and proves nothing tomorrow. Only specs gate; an agent's judgement never does.
Add a scenario to src/scenarios.ts when a fixture is genuinely new. Reach for
a query parameter first — most "new cases" are an existing fixture under a
different setting.
Code review
Reviews use the kc-gates:kc-code-review skill from the kc-claude-kit marketplace
(source),
installed as described under Session Start. It triggers on "review this PR", a PR URL
or a branch name, runs one gate agent per rule file, and never posts to GitHub on its
own. Two competitors are switched off for this repo in .claude/settings.json: the
official code-review@claude-plugins-official plugin (enabledPlugins: false) and
Claude Code's bundled /code-review (skillOverrides, which applies to bundled skills
but not plugin ones, per the skills docs).
The kit's rules are generic. What is specific to this repo (the RFC 5545 / FullCalendar
standard, the configured dayjs, package boundaries, unit + e2e coverage, the dev log,
linked issues, the posting ritual) lives in .agents/review-conventions.md, read by the
kit's project-conventions gate as .claude/review-conventions.md. A new review rule
for this repo goes there, not into the kit.
The plugin is Claude Code only. Gemini CLI and Antigravity load no review skill here; when
reviewing, walk the ## Gate checklist in .agents/review-conventions.md and the rules
it points to.
Releases
Cut a release with the release-new-version skill (.agents/skills/release-new-version/,
or /release-new-version), never by hand. It covers the steps that are easy to skip:
the semver table, the changelog with its contributor-credit sweep, the lightweight tag,
the GitHub release, the npm publish hand-off and registry check, the website update and
deploy, and the "Fixed in" comments on closed issues. Where it conflicts with the Hard
Rules, the Hard Rules win: the release commit goes through a PR, not straight to main.
A release is not ready until every feature and fix in its changelog has been exercised in
apps/demo (Hard Rules: "NEVER call a feature done…"), and it is not done until the same
pass has run against https://ilamy.dev/demo after the website deploy. If the owner planned
to test by hand and has not, say so and wait; a green suite does not stand in for it.
Other repo workflows also live in .agents/skills/ (refactor review, bundle size,
React checks). Check there before improvising one.
Git Workflow
- Create a feature branch
- Make changes
- Run tests (
bun run testat the root, orbun testinside a package) - Ask user to review
- Wait for explicit approval
- Commit with conventional prefix (
feat:,fix:,docs:, etc.), max 100 chars - Ask before pushing
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

