Agent Behavioral Rules

♻️ This markdown file can be re-used anytime you wanna build a new app

1. 🧠 Cognitive Protocol (Mandatory MCP Usage)

Rule: Think Before You Code. For any task involving logic implementation, refactoring, debugging, or architectural changes, you MUST use the sequentialthinking tool (MCP) as your FIRST step.

Trigger Conditions:

• When the user asks for a feature implementation (e.g., "Implement Prompt Batching").
• When analyzing a bug or a complex error log.
• When planning a refactoring strategy.

Execution Steps:

1. Initiate sequentialthinking: Do not output any code or text explanation until you have invoked this tool.
2. Analyze & Plan: Use the tool to:
   • Break down the user's request into atomic steps.
   • Identify potential risks (e.g., "Will this break the dev branch?").
   • Formulate a hypothesis or a step-by-step implementation plan.
3. Review: Only after the sequential thinking process is complete and you have a clear path, proceed to write code or answer.

Rule: Terminal Command Notification. If a task requires terminal commands (e.g., mkdir, mv, rm, pnpm install), you MUST NOT execute them directly. Instead, notify the user of the exact commands needed so they can run them manually. This is to ensure efficiency and avoid delays in command processing.

Exception:

• Simple content generation (e.g., "Write a README") or trivial fixes (e.g., typos) do not require this tool.

2. Documentation Lookup

When I need code generation, setup or configuration steps, or library/API documentation:

1. Primary: Always use context7 when I need code generation, setup or configuration steps, or library/API documentation. This means you should automatically use the Context7 MCP tools to resolve library id and get library docs without me having to explicitly ask.
2. Fallback: If Context7 is unavailable, use web search to find the official documentation from:
   • GitHub repositories (README, docs folder)
   • Official documentation sites (e.g., svelte.dev, kit.svelte.dev)
   • Package registry pages (npm)

Always prioritize official sources over blog posts or Stack Overflow answers.

3. Commit Message Convention

We follow a convention combining Gitmoji and Conventional Commits.

Format: [Gitmoji] [Type]: [Title]

Gitmoji & Types:

• ✨ :sparkles: feat: New features
• 🐛 :bug: fix: Bug fixes
• 📚 :books: docs: Documentation changes
• 💄 :lipstick: ui: UI changes
• ♻️ :recycle: refactor: Code refactoring
• 🚀 :rocket: deploy: Deployment tasks
• ⚙️ :gear: chore: Build/config changes
• ✅ :white_check_mark: test: Adding/fixing tests
• 🚑 :ambulance: hotfix: Critical hotfixes

Rule: After completing a significant task or a series of related changes, ALWAYS provide a single-line git commit message in the format above with adding adequate gitmoji at the start of the commit message. Focus on the most significant change.

4. Testing Strategy

We prioritize automated testing to ensure high quality and reliability.

1. Framework: Use Vitest and Svelte Testing Library for frontend and API route testing.
2. Execution: Before finalizing complex logic, ensure tests are written and passing.

5. Coding Standards & Design Principles

5.1 SOLID Principles (Strict Enforcement)

• SRP (Single Responsibility Principle):
  • Each component or utility must have one and only one reason to change.
  • Do NOT create "God Components". If a Svelte component exceeds 300 lines or handles mixed concerns, split it.
• OCP (Open/Closed Principle):
  • Design for extension. Use slots and snippets for components that might change content.
• DIP (Dependency Inversion):
  • Always depend on abstractions. Use Svelte context or stores/runes for dependency injection where appropriate.

6. SvelteKit & Svelte 5 Best Practices

• Runes ($state): Convert let var = val; to let var = $state(val);.
• Props ($props): Replace export let prop; with let { prop } = $props();.
• Derived ($derived): Convert $: double = count * 2; to let double = $derived(count * 2);.
• Effects ($effect): Convert $: { sideEffect(); } to $effect(() => { sideEffect(); });.
• Events: Prefer callback props over createEventDispatcher.
• Icons: Use @lucide/svelte for icon imports. Rule: Always use individual sub-path imports (e.g., import Menu from "@lucide/svelte/icons/menu") instead of barrel imports to avoid deprecation warnings and improve tree-shaking.
• Cleanup: Remove unused imports and ensure lang="ts".

7. API Routes (SvelteKit Backend)

• Validation: Use Zod or similar for validating incoming request data in +server.ts.
• Error Handling: Use error() from @sveltejs/kit to return proper HTTP status codes.
• Security: Ensure sensitive operations are protected by authentication checks (e.g., Supabase session).

8. Frontend & Backend Logging & Environment Checks

• Logging: All console.log, console.error, and other debug logs MUST be wrapped in an environment check to prevent leaking information in production.

• Frontend Environment Check: Use IS_DEV_MODE from $lib/utils/env to check if the app is running in development mode (Local OR Staging/Preview).

• Backend Environment Check: Use dev || isDevHostname(url.hostname) since IS_DEV_MODE (which relies on window) is not available on the server.

• Example (Frontend):

  import { IS_DEV_MODE } from "$lib/utils/env";
  
  if (IS_DEV_MODE) {
    console.log("Debug info:", data);
  }
  

• Example (Backend):

  import { dev } from "$app/environment";
  import { isDevHostname } from "$lib/utils/env";
  
  export const POST: RequestHandler = async ({ request }) => {
    const isDevEnv = dev || isDevHostname(new URL(request.url).hostname);
    if (isDevEnv) console.log("Backend debug log");
    // ...
  };
  

9. Localization Rule

• English Only: All annotations, comments, and documentation MUST be written in English. This applies to all files (Svelte, TS, JS, etc.).

10. 📁 File Upload & Validation Rules

• Size Limit: The maximum allowed size is 20MB (Total and individual files).
• UI/UX Feedback:
  • Global Error: Show a Red Toast notification with a message like "Total file size exceeds the 20MB limit."
  • Individual File Feedback: For specific files exceeding the limit, highlight the file card with a Red Border and display a Red Exclamation Icon (Tooltip) explaining the error.
• Implementation Note: Use Svelte 5 Runes for state management and ensure smooth transitions for toast/tooltip visibility.

11. 📦 Dependency Management (pnpm-lock.yaml)

• Rule: Review Lockfile After Changes.
• Whenever you add, remove, or update frontend dependencies (e.g., using pnpm add), you MUST run pnpm install to ensure pnpm-lock.yaml is up to date and consistent with package.json.

12. ♿ Accessibility (a11y)

• Interactive Elements: Use semantic tags like <button> or <a> for clickable elements. Avoid adding onclick to non-interactive tags like <div>, <span>, or <h3>. If a non-interactive tag must be used, it MUST be accompanied by appropriate ARIA roles and keyboard event handlers.
• Focus Management: Avoid the autofocus attribute as it can disrupt screen readers and navigation flow. Use a custom Svelte action (e.g., use:focus) to manage focus programmatically when elements appear or state changes.
• Keyboard Support: Ensure all interactive elements are reachable and operable via keyboard. Standard <button> and <a> tags provide this by default.
• Alt Text: All images and icons must have descriptive alt text or be marked as decorative (e.g., aria-hidden="true") if they don't convey unique information.

13. API Request Headers (415 Error Prevention)

• Content-Type: When making POST, PUT, or PATCH requests using fetch, you MUST explicitly set the Content-Type header to application/json if the body is a JSON string.

14. 📊 Vercel Insights & Analytics

• Rule: Wrap Injection in Environment Checks.

• Always wrap injectSpeedInsights() and injectAnalytics() in a check for browser && !IS_DEV_MODE. This ensures analytics are only running on the production site, not in local development or Vercel preview/staging deployments.

• Example:

  import { browser } from "$app/environment";
  import { IS_DEV_MODE } from "$lib/utils/env";
  
  if (browser && !IS_DEV_MODE) {
    injectSpeedInsights();
    injectAnalytics();
  }
  

15. 📦 Import Verification Rule

• Rule: Verify Imports After Every Edit.
• Whenever you add a new component, icon, or utility to a file, you MUST immediately verify and add the corresponding import statement.
• Verification: Before finishing a task, run pnpm run check to ensure no "cannot find symbol" or "missing import" errors exist.

16. 🛡️ XSS Prevention Rule

• Rule: Avoid {@html} with User-Controlled Input.
• To prevent Cross-Site Scripting (XSS) attacks, NEVER use Svelte's {@html} tag to render strings that contain or are derived from user input.
• Safe Alternative for Line Breaks: Use standard Svelte interpolation {} combined with the CSS property white-space: pre-wrap; and newline characters (\n) in your strings.

17. 🎨 Lucidify Aesthetic & UI Adaptation

When adapting external UI code:

1. Color Mapping: Strictly map primary colors to Lucidify theme (e.g., Zinc/Slate for dark mode, with vibrant accents).
2. Dark Mode First: Optimize all backgrounds and contrasts for a dark theme (Zinc-950/Black).
3. Tailwind Conversion: Prefer Tailwind CSS classes over raw <style> tags.
4. Consistency: Match existing design tokens: - Border Radius: Use rounded-2xl for main cards/modals, rounded-xl for buttons. - Typography: Use modern sans-serif fonts. - Transitions: Use smooth, consistent transitions (e.g., duration-200).

18. 📚 Documentation Protocol

• Rule: Continuous Status Updates.
• Whenever you finish a certain task, work, or feature implementation, you MUST update docs/what's_done_so_far.md to reflect the current state of the project. This ensures the project history and context remain accurate for future sessions.
• Rule: Selective Technical Memo Writing.
• You should only write to docs/technical_memo.md if the user is actively struggling with a specific problem or if a solution requires a deep dive into complex engineering trade-offs that need formal documentation. Do not use it for routine updates.

19. 🛡️ Security & Secret Management (Mandatory Protocol)

To protect the project from supply chain attacks and unauthorized access, agents follow a strict Zero-Trust Secret Management policy.

19.1 Zero-Trust Interaction

• No Secrets to AI: NEVER request OR read real API keys, passwords, or secrets from the user or .env files if they are meant for production. If you encounter them, immediately suggest rotation if they've been leaked to the chat.
• CLI-First Secret Management: To mitigate browser-based supply chain attacks (DOM poisoning, clipboard monitoring on Dashboard UI), prefer using the Vercel CLI for adding secrets.
• Blind CLI Updates: When adding environment variables, NEVER include the secret value in the command string (e.g., avoid vercel env add NAME VALUE). Use the interactive prompt method (vercel env add NAME) to ensure values are not saved in terminal history (.bash_history).

19.2 Deployment Configuration

• Sensitive Flag: When adding secrets via CLI or UI, always ensure the "Sensitive" property is enabled (blocking unmasking).
• Key Rotation: Following the April 2026 Vercel incident, a full rotation of all sensitive keys and a corresponding version bump (v1.6.2+) is mandatory.

19.3 Git Safety

• .env Protection: If you see a .env file not listed in .gitignore, your first priority is to fix the ignore file.

20. 🧹 Code Cleanup & Dead Code Removal

• Proactive Cleanup: When refactoring or adding features, always identify and remove any dead code in the file.
• Unused Elements: Actively delete unused variables, uncalled functions, and long-commented-out blocks of old code rather than leaving them indefinitely.
• Rule of Thumb: Make it a priority to leave the codebase cleaner than you found it.