| name | tomtom-maps-sdk-js-contribution |
| description | Orient to the SDK contributor context. Use when a contributor asks how to work on, build, or modify the TomTom Maps SDK — or when the current task involves editing SDK source files in core/, map/, services/, plugins/, examples/, or map-integration-tests/. |
| allowed-tools | Read, Glob |
You are working as an SDK contributor on the TomTom Maps SDK for JavaScript monorepo.
AGENTS.md files are the cross-tool source of truth for contributor guidance in this repo (architecture, commands, conventions, workflows). This skill orients you to them — do not restate or duplicate their content here.
Orientation steps
-
Always read the root AGENTS.md first for architecture, build order, dev commands, conventions, and key files.
-
Read the package-specific AGENTS.md for the area you're touching:
| If the task touches… | Read |
|---|
core/ | core/AGENTS.md |
map/ | map/AGENTS.md |
services/ | services/AGENTS.md |
examples/ | examples/AGENTS.md (and examples/E2E_TESTING.md for test work) |
map-integration-tests/ | map-integration-tests/AGENTS.md |
plugins/ (any) | plugins/AGENTS.md |
plugins/agent-toolkit/ | plugins/agent-toolkit/AGENTS.md + plugins/agent-toolkit/ENGINEERING-GUIDELINES.md |
plugins/viewport-places/ | plugins/AGENTS.md (no dedicated AGENTS.md; see src/viewportPlaces.ts) |
plugins/landmarks-3d/ | plugins/AGENTS.md (no dedicated AGENTS.md; see src/Landmarks3D.ts) |
shared-configs/ | shared-configs/AGENTS.md |
documentation/ | documentation/AGENTS.md |
documentation/docs-portal/ | documentation/docs-portal/AGENTS.md (guide writing with SDKGuideLiveCodingExample) |
If the area is unclear, read all package-level AGENTS.md files before acting.
-
Before you write code, silently confirm you're in contributor mode with these easy-to-violate rules top-of-mind:
- Biome for formatting/linting (not ESLint or Prettier). Run
pnpm lint from root.
- pnpm for package management; shared version pins live in
pnpm-workspace.yaml under catalog:.
- Vitest for unit tests; place tests in
tests/ subdirectories next to source.
- Strict TypeScript — no
any, no unnecessary casts.
- Coordinates: always
[longitude, latitude] (GeoJSON order) — easy to get wrong.
- Full variable names —
response not res, parameters not params, error not err, configuration not config, etc. (full list in root AGENTS.md).
- Arrow functions over
function declarations; omit braces/return for single-expression one-liners.
- No re-exports — import directly from canonical source, never barrel-forward.
- Blank line after single-line
if — Biome does not enforce; apply manually.
- Map modules: get instances via
await SomeModule.get(map), never new SomeModule().
- Tool
execute in plugins must catch and return { error: string }, never throw.
- Build order is strict:
core → services + map. Never import map from services or vice versa.
- Example E2E tests need
dist/: every pnpm test:e2e[:update-snapshots] (per-example or via pnpm e2e-test:examples:update-snapshot <name> / pnpm generate-thumbnails:examples <name> from root) requires pnpm -F map build + pnpm -F @examples/<name> build first — the Playwright server serves dist/, not the dev server. Skipping the build silently uses stale assets.
- New examples must ship both
e2e-tests/snapshots/upon-load.png (from pnpm test:e2e:update-snapshots) and content/thumbnail.png (derived via pnpm generate-thumbnails:examples <name>). Commit both.
After every change
Always run both of these from the repo root after editing any source file, before reporting the task as complete:
pnpm lint:fix
pnpm format:fix
lint:fix runs Biome's check+lint with --write; format:fix runs Biome's formatter with --write. If lint:fix exits non-zero, fix the reported errors (warnings about pre-existing complexity/non-null-assertions in unrelated files are not blocking — only address what your change introduced or what Biome flags as an error).
Cross-file consistency check (before pushing)
Most automated review nags come from references that drift between code, exports, tests, and docs. Before pushing, do a quick sweep matched to the kind of change you just made.
Renamed or removed a public symbol — start with git grep -l '<oldName>' from the repo root, then walk the hits across:
- the package's own
src/** (registries, barrels, schemas, tests, mocks, fixtures)
examples/** (entry points, hooks, eval cases, tests, snapshots)documentation/docs-portal/guides/** — both navigation.yml and every .mdx under the affected guide.claude/skills/** — skill descriptions list trigger keywords by symbol name and go stale silently
Replace every hit. If the rename also changed semantics (not just the name), re-read the touched code so descriptions, JSDoc, and guides still match the actual runtime behavior — they go stale silently.
Changed a public type shape (default generic, exported interface, output schema) — also:
- update the JSDoc
@typeParam / property docs to match the actual default and shape (a common review nag is "JSDoc says X but signature says Y")
- decide whether downstream consumers need a deprecated alias or a major-version bump (see
.release-please-manifest.json)
Added external-resource fetching — confirm bounded handling: explicit protocol allowlist, AbortController timeout, streamed size cap. Don't trust new URL alone.
Package-specific extras — when a package's own AGENTS.md lists "after adding X, also touch Y" rules (e.g. plugins/agent-toolkit/AGENTS.md for new state slices or registered tools), follow those as well. The root-level checks above don't replace them.
When to branch off this skill
- Building an SDK consumer app (not editing SDK source) → use the
tomtom-maps-sdk-js skill instead.
- Writing or editing customer-facing guides → follow
documentation/docs-portal/AGENTS.md.
- Working on the agent-toolkit plugin →
ENGINEERING-GUIDELINES.md is required reading before touching tools, state, or system prompts.
