Eunjae LeeGitHubClaude Haiku 4.5Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>* refactor: consolidate agent config folders into agents directory - Move .claude/skills and .claude/rules content to agents/ - Remove duplicate .cursor/ and .goose/ folders - Create symlinks from .claude/ and .cursor/ to agents/ - Convert review.mdc to quality-review-checklist.md with proper frontmatter Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> * feat: add Cal.com APIv2 skills to agents directory Move the Cal.com API v2 skills from PR #27445 into the consolidated agents/skills/ directory structure. This includes: - SKILL.md - Main skill file with API overview - references/authentication.md - Authentication methods - references/bookings.md - Bookings API reference - references/calendars.md - Calendars API reference - references/event-types.md - Event types API reference - references/schedules.md - Schedules API reference - references/slots-availability.md - Slots and availability API reference - references/webhooks.md - Webhooks API reference Co-Authored-By: eunjae@cal.com <hey@eunjae.dev> * fix: update calcom-api skill to use Claude Code frontmatter format Remove non-standard frontmatter fields (license, metadata) and keep only the Claude Code supported fields (name, description) as per the Claude Code skills specification. Co-Authored-By: eunjae@cal.com <hey@eunjae.dev> * refactor: restructure calcom-api SKILL.md as index file Convert SKILL.md from a comprehensive API doc (317 lines) to a concise index file (108 lines) that references the detailed documentation in the references/ folder. This follows the Claude Code skills pattern of keeping SKILL.md focused with supporting files for detailed content. The SKILL.md now: - Provides a quick start guide with essential examples - References all 7 detailed reference docs in a table - Lists common workflows and best practices - Points to external resources Co-Authored-By: eunjae@cal.com <hey@eunjae.dev> * docs: preserve deleted content in reference files Move content that was removed from SKILL.md to appropriate reference files: - Add Error Handling and Pagination sections to authentication.md - Add Organization endpoints to event-types.md - Add Core Concepts section back to SKILL.md This ensures no useful API documentation is lost during the restructuring. Co-Authored-By: eunjae@cal.com <hey@eunjae.dev> --------- Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com> Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Cal.com Development Guide for AI Agents
This directory contains comprehensive documentation for AI agents working on the Cal.com codebase.
Quick Navigation
- Rules - Modular engineering rules derived from our 2026 standards
- Commands - Build, test, and development commands
- Knowledge Base - Knowledge base & best practices
- Architecture Overview - System structure and patterns
Getting Started
Cal.com is a monorepo using Yarn workspaces and Turbo for build orchestration. The main application is in apps/web/ with shared packages in packages/.
Key Directories
apps/web/- Main Next.js applicationpackages/prisma/- Database schema and migrationspackages/trpc/- API layer using tRPCpackages/ui/- Shared UI componentspackages/features/- Feature-specific codepackages/app-store/- Third-party app integrations
Architecture Overview
Database Layer
- Prisma ORM with PostgreSQL
- Schema in
packages/prisma/schema.prisma - Always use
selectinstead ofincludefor better performance - Never expose
credential.keyfield in API responses
API Layer
- tRPC for type-safe APIs
- Routers in
packages/trpc/server/routers/ - Authentication handled via NextAuth.js
Frontend
- Next.js 13+ with App Router in some areas
- React 18 with TypeScript
- Tailwind CSS for styling
- Internationalization with
next-i18next
Common Patterns
Error Handling
- Use early returns to reduce nesting
- Throw descriptive errors with proper error codes
- Prefer composition over prop drilling
Performance
- Avoid O(n²) logic in backend code
- Minimize Day.js usage in performance-critical paths
- Use
selectqueries to only fetch needed data - Consider using
.utc()for Day.js operations
Security
- Never commit secrets or API keys
- Always validate input data
- Use proper authentication checks
- Never expose sensitive credential fields
Testing Strategy
- Unit tests with Vitest
- Integration tests for complex workflows
- E2E tests with Playwright
- Test files use
.test.tsor.spec.tsextensions
Pull Request Guidelines
For large PRs (>500 lines or >10 files):
- Split by feature boundaries
- Separate database migrations, backend logic, frontend components
- Create dependency chains that can be merged sequentially
- Pattern: Database → Backend → Frontend → Tests