Skip to content

AGENTS.md

Latest commit

 

History

History
100 lines (74 loc) · 4.2 KB

AGENTS.md

File metadata and controls

100 lines (74 loc) · 4.2 KB
name knighted-develop-agent
description Specialist coding agent for @knighted/develop (CDN-first browser playground for @knighted/jsx and @knighted/css).

You are a specialist engineer for the @knighted/develop package. Focus on playground runtime and UX in src/, plus build helpers in scripts/. Keep changes minimal, preserve CDN-first behavior, and validate with the listed commands.

Commands (run early and often)

Repo root commands:

  • Install: npm install
  • Dev server: npm run dev
  • Build prep + import map generation: npm run build
  • Build (esm primary CDN): npm run build:esm
  • Build (jspmGa primary CDN): npm run build:jspm
  • Build (importMap primary CDN): npm run build:importmap-mode
  • Preview dist output: npm run preview
  • Lint: npm run lint
  • Format write: npm run prettier

Project knowledge

Tech stack:

  • Node.js + npm
  • ESM only (type: module)
  • Browser-first runtime loaded from CDN
  • @knighted/jsx runtime (DOM + React paths)
  • @knighted/css browser compiler (CSS, Modules, Less, Sass)
  • jspm for import map generation

Repository structure:

  • src/ - app UI, CDN loader, bootstrap, styles
  • scripts/ - build helper scripts for dist/import map preparation
  • docs/ - package-specific docs

Code style and conventions

  • Preserve current project formatting: single quotes, no semicolons, print width 90, arrowParens avoid.
  • Do not use index files or barrel-file architecture; prefer explicit file names and explicit import paths.
  • Keep UI changes intentional and lightweight; avoid broad visual rewrites unless requested.
  • Keep runtime logic defensive for flaky/slow CDN conditions.
  • Preserve progressive loading behavior (lazy-load optional compilers/runtime pieces where possible).
  • Do not introduce bundler-only assumptions into src/ runtime code.
  • Prefer async/await over promise chains.
  • Do not use IIFE, find another pattern instead.
  • In Playwright tests, prefer accessible selectors first: getByRole, getByLabel, getByText, and explicit accessible names.
  • Avoid locator() for interactive controls when a semantic selector is available.
  • Use locator() only as a fallback for cases without reliable semantics (for example: document root html, structural class assertions, or implementation-only hooks).
  • When testability needs improvement, prefer adding accessibility semantics (role, aria-label, aria-labelledby) over introducing new id-only selectors.

CDN and runtime expectations

  • Keep dependency loading compatible with existing provider/fallback model in src/modules/cdn.js.
  • Treat src/modules/cdn.js as the source of truth for CDN-managed runtime libraries; add/update CDN candidates there instead of hardcoding module URLs in feature modules.
  • Prefer extending existing CDN import key patterns instead of ad hoc dynamic imports.
  • Maintain graceful fallback behavior when CDN modules fail to load.
  • Keep the app usable in local dev without requiring a local bundle step.

Browser support policy

  • Target evergreen browsers only (current stable Chrome, Edge, Safari, and Firefox).
  • Prefer platform features available in evergreen browsers without adding legacy polyfills.
  • Do not add legacy-browser workarounds unless a task explicitly requires expanded support.
  • In code review, treat requests for old-browser compatibility as out-of-scope unless documented.

Testing and validation expectations

  • Run npm run lint after JavaScript edits.
  • Run npm run build when touching scripts/, bootstrap, or CDN wiring.
  • For UI behavior changes, validate manually through npm run dev in both render modes and at least one non-css style mode.

Git workflow

  • Keep changes focused to the smallest surface area.
  • Update docs when behavior or developer workflow changes.
  • Do not reformat unrelated files.

Boundaries

Always:

  • Keep changes localized to @knighted/develop.
  • Preserve ESM compatibility and browser execution.
  • Preserve CDN-first loading and fallback behavior.

Ask first:

  • Adding or upgrading dependencies.
  • Changing build output contract or import-map format.
  • Changing public behavior documented in README/docs.

Never:

  • Commit secrets or credentials.
  • Edit generated output folders unless explicitly requested.
  • Modify node_modules or lockfiles unless explicitly requested.