Skip to content

0015 — Agent Skills: Svelte Embedded UIs

Status: DRAFT Last updated: 2026-07-06

1. Purpose

As krites heavily leverages agentic AI (like Claude and Antigravity) for development, we need to ensure AI agents strictly adhere to our specific stack and architectural boundaries when working on the frontend.

This spec defines the creation of a reusable Agent Skill (svelte-embedded-ui) that enforces the rules for developing our Svelte application embedded within the Go binary, preventing hallucinations or regressions to generic web dev patterns.

2. Skill Definition (.gemini/skills/svelte-embedded-ui/SKILL.md)

The skill must be authored as a markdown instruction set that agents can load. It should mandate the following constraints:

2.1 Architectural Rules

  • The Setup: The app is a Svelte 5 SPA, embedded into a Go binary using go:embed.
  • No SSR: Server-Side Rendering (SSR) via SvelteKit is explicitly prohibited. The UI is a pure client-side SPA communicating with the Go backend via JSON REST APIs and Server-Sent Events (SSE).
  • Styling: Use Vanilla CSS with CSS Variables. TailwindCSS is not used and should not be introduced.

2.2 Svelte 5 Directives

  • Agents MUST use Svelte 5 Runes ($state, $derived, $effect, $props()). Reference: Runes
  • Agents MUST NOT use legacy reactivity ($:, export let).
  • Agents MUST proactively break down large components into smaller, single-file components (.svelte).

2.3 Performance Directives

  • Virtualisation First: When generating code for lists or grids exceeding 50 items, agents MUST proactively implement virtualisation. Use the custom hand-rolled, zero-dependency grid (pluggable layout engine — uniform / masonry / justified — over a shared windowing core; see 0014 §2.2); do not add TanStack Virtual, svelte-virtual, or any runtime npm dependency. The frontend ships zero runtime deps inside the notarized binary and stays that way (supply-chain posture, 0014 §2.3).
  • No new runtime dependencies: agents MUST NOT introduce a runtime npm dependency without explicit human sign-off; pin exact versions, commit the lockfile, and assume npm ci --ignore-scripts in CI.
  • Debouncing: Agents MUST debounce continuous user inputs (keyboard holding, scroll events) that trigger state changes or API calls.

2.4 TDD Enforcement

  • Agents MUST write Vitest + @testing-library/svelte tests BEFORE modifying or creating components.
  • The workflow must explicitly be: Write Test -> Run Test (Fail) -> Implement -> Run Test (Pass).
  • If an agent generates code without first generating tests, it is violating the skill rules.

3. Implementation Plan

  1. Create the skill directory and SKILL.md file locally in the skills/ directory.
  2. Register the skill in the agent's configuration system so it can be loaded dynamically.
  3. Apply the skill explicitly to the 0014 Svelte UI Refactor task to validate its effectiveness.