# AGENTS.md This file defines **operational guidance for automated agents** (e.g., Codex, Claude Code, CI bots) working in this repository. It is intentionally tool-neutral. For deeper project context, architecture notes, and AI-specific guidance, see `CLAUDE.md`. --- ## Purpose Agents are welcome here to accelerate development, testing, and maintenance — **without compromising security, privacy, or deployment correctness**. This repo has intentionally strict security controls (CSP, audit mode behavior, analytics gating) and a multi-environment deployment model. Agents must treat these as **invariants** unless a human explicitly approves changes. --- ## Agent workflow (persona) - Prefer minimal diffs; avoid sweeping refactors unless requested. - Be explicit about tradeoffs and risks; don’t guess about CI/deploy behavior. - Preserve behavior by default; if a change alters behavior, call it out explicitly. - Preserve invariants: env detection, CSP, audit-mode guarantees, analytics gating. - If unsure, ask a single targeted question or leave a TODO rather than inventing. - Optimize for reproducibility: commands that work locally and in CI. --- ## Svelte MCP Server Agents are able to use the Svelte MCP server, which provides comprehensive Svelte 5 and SvelteKit documentation. Use the available tools as follows: ### Available Svelte MCP Tools #### 1. `list-sections` Use this FIRST to discover all available documentation sections. It returns a structured list with titles, use cases, and paths. When asked about Svelte or SvelteKit topics, ALWAYS use this tool at the start of the chat to find relevant sections. #### 2. `get-documentation` Retrieves full documentation content for specific sections. It accepts single or multiple sections. After calling `list-sections`, agents MUST analyze the returned documentation sections, especially the `use_cases` field, and then use `get-documentation` to fetch ALL documentation sections that are relevant for the user's task. #### 3. `svelte-autofixer` Analyzes Svelte code and returns issues and suggestions. Agents MUST use this tool whenever writing Svelte code before sending it to the user. Keep calling it until no issues or suggestions are returned. #### 4. `playground-link` Generates a Svelte Playground link with the provided code. After completing the code, ask the user if they want a playground link. Only call this tool after user confirmation and NEVER if code was written to files in their project. --- ## Quick Commands Use these commands as the “happy path” for local and CI-like validation: ### Development - `npm run dev` — start dev server - `npm run dev:audit` — dev server in audit mode (hardened CSP, no analytics) - `npm run preview` — preview production build locally ### Build - `npm run build` — production build - `npm run build:audit` — audit build (hardened CSP) ### Tests - `npm run test:all` — unit tests (client + server) - `npm run test:e2e` — Playwright E2E tests (with 1 retry) - `npm run lhci:run` — Lighthouse CI audits ### Lint / Format - `npm run lint:all` - `npm run lint:fix` - `npm run format:fix` ### Full Verification - `npm run checkout` (alias: `npm run verify`) --- ## Guardrails (Strict, but Practical) ### Environment and security invariants Agents MUST NOT change the following without explicit human approval: - **Environment detection logic** (notably `src/lib/utils/env.js`) or introduce new environment modes. - **Content Security Policy** generation/behavior (`svelte.config.js` `kit.csp` plus related `src/hooks.server.js` reporting headers) in a way that weakens enforcement. - **Audit-mode guarantees**: audit must remain hardened (no analytics, no external reporting, strict CSP). - **Analytics gating**: tracking must remain consent-based and environment-aware. - **Service worker exclusions**: analytics domains must not be cached; SW bypass behavior must remain intact. If a task requires touching any of the above, stop and ask for confirmation. ### Deployment and CI/CD accuracy Agents MUST NOT invent deployment behavior. The current model is: - **Production**: Vercel builds/deploys on merges to `master` (Vercel-managed). - **Audit**: Netlify deploy driven by a branch-scoped GitHub Actions workflow (`audit-netlify` branch only). If a change would affect build/deploy behavior, document assumptions and ask for confirmation. If referencing a workflow/config, point to the exact file path and branch it lives on. ### Secrets and sensitive data - Do **not** commit secrets, tokens, keys, or credentials. - `.env*` files must remain purpose-separated. Only non-sensitive, commit-safe env files belong in git. - If secrets are required for a task, request them via the tool’s secret mechanism and use placeholders in committed files. --- ## Allowed Agent Work Agents MAY do the following without additional approval (assuming guardrails are respected): - Explain code and architecture; summarize behavior and risks. - Implement **incremental** features or routes that follow existing patterns. - Fix bugs and reduce flakiness in tests using minimal, targeted changes. - For SPA E2E tests, prefer URL polling + page-ready assertions over navigation lifecycle waits. - Add/extend unit tests or E2E tests consistent with current test architecture. - Refactor for clarity **without changing behavior** (especially in security/env paths). - Improve documentation, comments, and JSDoc. - Propose dependency updates, with a short rationale and any expected impact. --- ## Sensitive Areas (Ask Before Major Changes) These areas are high-impact. Changes are allowed, but require extra care and usually a quick human check: - `src/lib/utils/env.js` (environment resolution) - `svelte.config.js` (`kit.csp`, adapters, build-time mode handling) - `src/hooks.server.js` (request-time security headers / diagnostics) - `src/service-worker.js` and SW registration logic - `src/lib/stores/posthog.js` and analytics init/gating - Auth, redirects, proxy/relay routes under `src/routes/relay-*` - Build tooling (`vite.config.js`, CI workflows, deploy scripts) When editing these, prefer: - minimal diffs - explicit control flow - comments describing intent and risk --- ## What “Done” Means for Agent Work Before claiming a task is complete, agents should: 1. Ensure changes are minimal and aligned with existing patterns. 2. Run (or at least recommend running) appropriate checks: - `npm run lint:all` - `npm run test:all` - `npm run test:e2e` (if UI/routes are affected) - `npm run build` (if build/runtime behavior is affected) 3. Include a short summary: - what changed - why it changed - risk/impact (especially CSP/env/analytics) - any follow-ups or TODOs If tests are flaky, call it out explicitly and propose stabilization steps rather than masking failures. --- ## Notes for Cloud / Ephemeral Runners Many agents run in ephemeral environments. To keep builds reproducible: - Do not assume local files exist unless they are committed. - Prefer deterministic commands (`npm ci` when appropriate to lockfile policy). - Avoid relying on interactive prompts. - If environment variables are required, document them and provide safe defaults where possible. --- ## References - `CLAUDE.md` — authoritative AI guidance and deeper repository context.