Skip to content

Latest commit

 

History

History
134 lines (119 loc) · 9.34 KB

AGENTS.md

File metadata and controls

134 lines (119 loc) · 9.34 KB

Kiro Crew Website — Agent Guidelines

This file is a ROUTER, not a manual. It carries only the rules whose violation causes damage before a pointer could be read. Everything else is a link you MUST open before touching that area. The backend router is ../AGENTS.md.

React + TypeScript + Vite SPA for the Kiro Crew dashboard. Built assets go to dist/ and are staged into ../src/kiro_crew/static/dist/ so the gateway serves them.

Read before you touch

If you are touching… Read first
layout of a page, panels, headers page-layout
narrow screens, gutters, page zoom, touch gestures narrow-viewport
themes, colors, CSS vars, stable class hooks theming-contract
Tailwind: a new utility for a token, src/tailwind-theme.css, src/index.css's Tailwind header, safe-area utilities frontend-conventions § Styling
shared components, a11y, URL sanitization, data fetching, the stack, adding a dependency frontend-conventions
any user-facing string, date, number, or sort order i18n-catalog + i18n gates
src/extensions.ts, edition composition, registries extension-seams
src/api/ — client.ts, api/client/*.ts, adding an API method extension-seams (the transport seam and the method ratchets)
a registered find_ui location: src/uiLocations/ area descriptors, a {...uiLocation(id)} spread, conditions.ts, or anything the generated index is cut from (a registry, marker, descriptor or catalog) find_ui and the UI location index + Adding a UI location — register at both sites, then run npm run gen:ui and commit the regenerated index, or the freshness gate fails
tests (vitest, MSW, Playwright, Electron), or a test that fails only in CI testing
the Electron desktop shell electron/README.md
a file nearing 2,000 lines, or splitting one code-style § No file over 2,000 lines: scripts/check_file_line_cap.py enforces it in CI's lint jobs. A change that takes a file past 1,600 lines splits it per § Splitting a file: the facade re-exports with explicit export { … } from lists, never export *, and no owner imports it
anything backend, or a whole-system question ../AGENTS.md

Everything under website/docs/ is indexed by its README.

Build and test: a gotcha that produces a silent false green

  • The localStorage test polyfill must stay on Storage.prototype. Assigning it elsewhere makes the mock silently miss.

npm run test runs the website vitest suite AND the Electron node:test suite, and a pretest jscpd duplication check runs first, so npm test can fail on copy-paste before a single test executes. Commands and layers: testing.

This is a public OSS fork: don't reintroduce internal couplings

The public build is plain npm + Vite, src/rum.ts is an inert no-op stub that stays inert, and a downstream edition re-adds a removed surface additively through the extension seams, never by editing core. The full list — build and infra, identity and telemetry, the removed product surfaces, and the Channels / Board divergences an upstream sync must not restore — is oss-fork-boundaries, gated by the internal-content-scan check.

AUTOSDE.yaml in this directory is live and authoritative. The frontend review rules it declares are read by the claude-review, codex-review, code-review, fork-gpt-review, and fork-opus-review workflows, and a blocking: true rule there outranks a reviewer's own prompt. Read it before changing frontend code; never treat it as historical.

No built-in app pages

Kiro Crew accepts no new built-in app, so the frontend gets no new per-app code: never add a per-app directory under src/apps/<app>/, a per-app entry in src/apps/builtinRegistry.ts, overlayRegistry.ts or builtinIcons.tsx, a per-app asset directory under public/app-assets/, or an app.json outside a test fixture. A new app's UI, first-party included, is its own ESM bundle (ui.entry) shipped from a dedicated GitHub repository listed in the official registry (kirodotdev/KiroCrewApps). The built-in pages that still ship belong to apps being moved out; fixing one in place until it leaves is fine. A host surface an app cannot reach is an App Kit seam gap: fix the seam. Rule: no-new-builtin-apps in ../AUTOSDE.yaml; the backend half: ../AGENTS.md § No built-in apps.

Rules that must not wait for a pointer

  • Settings primitives: pass configKey on every new SettingsToggle/SettingsField that writes a config path, or the <SettingRef configKey="..."> chip silently degrades to a CLI popover even though a toggle exists. Backend drift guards catch bad keys, not missing ones, so this rule is the only gate for the missing case.
  • Icons: use lucide-react; use className="lucide-inline" when a glyph sits inline with text. Never use an emoji or hand-rolled SVG as an icon. Size props are valid for standalone glyphs. Enforced by AUTOSDE.yaml (use-lucide-icons, no-emoji-as-icons).
  • Errors shown to the user render through ErrorNotice, never a hand-written <div className="text-danger">{err}</div>. Turn on askAgent wherever the hand-off cannot lose anything. Next to an unsaved draft, leave it off and name that draft in a {/* No hand-off: … */} comment. Inside a Radix menu, leave it off and render a sibling ErrorNoticeMenuItem; its describedBy must point to the passive notice's id, so the hand-off is a real menu focus stop rather than a nested button. When the agent the hand-off would open cannot run (its own credential or backend is what failed), pass noHandoffReason="…" instead: a reason for the reviewer, never rendered, and a type error next to askAgent. Enforced by AUTOSDE.yaml (errors-use-error-notice).
  • Security: every dangerouslySetInnerHTML goes through DOMPurify via md() / sanitize() / esc() in src/api/helpers.ts. A bypass is an XSS bug, so there is no acceptable pointer for this one.
  • Never format a date, number, or sort order without naming a locale. Route through the src/i18n/format.ts seam; naming a locale explicitly IS the opt-out. CI-gated, and the failure (a Chinese UI rendering 7/30/2026) ships silently.
  • Never hardcode a user-facing English string. The dashboard ships in 12 languages; add a catalog key. CI-gated.
  • Data fetching is React Query, never useState + useEffect. Follow the existing query-key convention.
  • Animation is Framer Motion. Do not add new CSS @keyframes.
  • A persistent element that changes form or place stays one element. When a user action or a state flip minimizes, collapses, relocates or replaces something the user already has on screen, animate that one element between the two states (layoutId / layout, a landing spot the eye can follow, text that stays continuous, restore as the reverse). Never a hard swap of two components (flag ? <Chip/> : <Card/>): the user reads it as "that vanished and something else appeared" and no label repairs it. prefers-reduced-motion drops the motion, not the continuity. Loading/empty/error → content transitions are not this rule. Evidence for such a change is a recording, not a screenshot. Gated by the UX Review lane (lens 13) — a hard swap with no stated reason is a BLOCK.
  • Styling uses design tokens (var(--bg), var(--text), …), never a literal color.
  • Frontend tests are deterministic. No promise-sleep barrier and no page.waitForTimeout barrier; Date pinned with vi.setSystemTime; fake timers restored in an afterEach or onTestFinished, which still run when the test times out; wait for every value you read whose content comes from a different async source than the one you awaited. Enforced on new and changed test lines by AUTOSDE.yaml (frontend-tests-are-deterministic). A Playwright spec that passes only on a retry is flaky: fix it, never raise retries. Detail in testing § Determinism.
  • Typography: no text-xs, and no text below 10px.
  • Accessibility: use <Clickable> rather than <div onClick>; give every icon-only button an aria-label; use <Btn> / <SendBtn> rather than a raw <button>; announce streaming regions with aria-live; honor the modal focus-trap contract.
  • Compose from src/components/ui.tsx. Never hand-roll a panel section header; use PanelSectionHeader.
  • src/extensions.ts is core-owned and must register nothing. Core registrations belong in the seed maps.
  • Edition composition is fail-closed: it needs KIROCREW_EDITION_DIR and KIROCREW_ALLOW_EDITION=1. Never set the latter in a release or publish job. A contaminated public wheel cannot be unpublished.