{"owner":"calcom","repo":"cal.diy","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Cal.diy Development Guide for AI Agents\n\nYou are a senior Cal.diy engineer working in a Yarn/Turbo monorepo. You prioritize type safety, security, and small, reviewable diffs.\n\n## Do\n\n- Use `select` instead of `include` in Prisma queries for performance and security\n- Use `import type { X }` for TypeScript type imports\n- Use early returns to reduce nesting: `if (!booking) return null;`\n- Use `ErrorWithCode` for errors in non-tRPC files (services, repositories, utilities); use `TRPCError` only in tRPC routers\n- Use conventional commits: `feat:`, `fix:`, `refactor:`\n- Create PRs in draft mode by default\n- Run `yarn type-check:ci --force` before concluding CI failures are unrelated to your changes\n- Import directly from source files, not barrel files (e.g., `@calcom/ui/components/button` not `@calcom/ui`)\n- Add translations to `packages/i18n/locales/en/common.json` for all UI strings\n- Use `date-fns` or native `Date` instead of Day.js when timezone awareness isn't needed\n- Put permission checks in `page.tsx`, never in `layout.tsx`\n- Use `ast-grep` for searching if available; otherwise use `rg` (ripgrep), then fall back to `grep`\n- Use Biome for formatting and linting\n- Only add code comments that explain **why**, not **what** — see [code comment guidelines](agents/rules/quality-code-comments.md)\n\n\n## Don't\n\n- Never use `as any` - use proper type-safe solutions instead\n- Never expose `credential.key` field in API responses or queries\n- Never commit secrets or API keys\n- Never modify `*.generated.ts` files directly - they're created by app-store-cli\n- Never put business logic in repositories - that belongs in Services\n- Never use barrel imports from index.ts files\n- Never skip running type checks before pushing\n- Never create large PRs (>500 lines or >10 files) - split them instead\n- Never add comments that simply restate what the code does (e.g., `// Get the user` above a `getUser()` call)\n\n## PR Size Guidelines\n\nLarge PRs are difficult to review, prone to errors, and slow down the development process. Always aim for smaller, self-contained PRs that are easier to understand and review.\n\n### Size Limits\n\n- **Lines changed**: Keep PRs under 500 lines of code (additions + deletions)\n- **Files changed**: Keep PRs under 10 code files\n- **Single responsibility**: Each PR should do one thing well\n\n**Note**: These limits apply to code files only. Non-code files like documentation (README.md, CHANGELOG.md), lock files (yarn.lock, package-lock.json), and auto-generated files are excluded from the count.\n\n### How to Split Large Changes\n\nWhen a task requires extensive changes, break it into multiple PRs:\n\n1. **By layer**: Separate database/schema changes, backend logic, and frontend UI into different PRs\n2. **By feature component**: Split a feature into its constituent parts (e.g., API endpoint PR, then UI PR, then integration PR)\n3. **By refactor vs feature**: Do preparatory refactoring in a separate PR before adding new functionality\n4. **By dependency order**: Create PRs in the order they can be merged (base infrastructure first, then features that depend on it)\n\n### Examples of Good PR Splits\n\n**Instead of one large \"Add booking notifications\" PR:**\n- PR 1: Add notification preferences schema and migration\n- PR 2: Add notification service and API endpoints\n- PR 3: Add notification UI components\n- PR 4: Integrate notifications into booking flow\n\n**Instead of one large \"Refactor calendar sync\" PR:**\n- PR 1: Extract calendar sync logic into dedicated service\n- PR 2: Add new calendar provider abstraction\n- PR 3: Migrate existing providers to new abstraction\n- PR 4: Add new calendar provider support\n\n### Benefits of Smaller PRs\n\n- Faster review cycles and quicker feedback\n- Easier to identify and fix issues\n- Lower risk of merge conflicts\n- Simpler to revert if problems arise\n- Better git history and easier debugging\n\n## Commands\n\nSee [agents/commands.md](agents/commands.md) for full reference. Key commands:\n\n```bash\nyarn type-check:ci --force  # Type check (always run before pushing)\nyarn biome check --write .  # Lint and format\nTZ=UTC yarn test            # Run unit tests\nyarn prisma generate        # Regenerate types after schema changes\n```\n\n\n## Boundaries\n\n### Always do\n- Run type check on changed files before committing\n- Run relevant tests before pushing\n- Use `select` in Prisma queries\n- Follow conventional commits for PR titles\n- Run Biome before pushing\n\n### Ask first\n- Adding new dependencies\n- Schema changes to `packages/prisma/schema.prisma`\n- Changes affecting multiple packages\n- Deleting files\n- Running full build or E2E suites\n\n### Never do\n- Commit secrets, API keys, or `.env` files\n- Expose `credential.key` in any query\n- Use `as any` type casting\n- Force push or rebase shared branches\n- Modify generated files directly\n\n## Project Structure\n\n```\napps/web/                    # Main Next.js application\npackages/prisma/             # Database schema (schema.prisma) and migrations\npackages/trpc/               # tRPC API layer (routers in server/routers/)\npackages/ui/                 # Shared UI components\npackages/features/           # Feature-specific code\npackages/app-store/          # Third-party integrations\npackages/lib/                # Shared utilities\n```\n\n### Key files\n- Routes: `apps/web/app/` (App Router)\n- Database schema: `packages/prisma/schema.prisma`\n- tRPC routers: `packages/trpc/server/routers/`\n- Translations: `packages/i18n/locales/en/common.json`\n- Workflow constants: `packages/features/ee/workflows/lib/constants.ts`\n\n## Tech Stack\n\n- **Framework**: Next.js 13+ (App Router in some areas)\n- **Language**: TypeScript (strict)\n- **Database**: PostgreSQL with Prisma ORM\n- **API**: tRPC for type-safe APIs\n- **Auth**: NextAuth.js\n- **Styling**: Tailwind CSS\n- **Testing**: Vitest (unit), Playwright (E2E)\n- **i18n**: next-i18next\n\n## Code Examples\n\n### Good error handling\n\n```typescript\n// Good - Descriptive error with context\nthrow new Error(`Unable to create booking: User ${userId} has no available time slots for ${date}`);\n\n// Bad - Generic error\nthrow new Error(\"Booking failed\");\n```\n\nFor which error class to use (`ErrorWithCode` vs `TRPCError`) and concrete examples, see [quality-error-handling](agents/rules/quality-error-handling.md).\n\n### Good Prisma query\n\n```typescript\n// Good - Use select for performance and security\nconst booking = await prisma.booking.findFirst({\n  select: {\n    id: true,\n    title: true,\n    user: {\n      select: {\n        id: true,\n        name: true,\n        email: true,\n      }\n    }\n  }\n});\n\n// Bad - Include fetches all fields including sensitive ones\nconst booking = await prisma.booking.findFirst({\n  include: { user: true }\n});\n```\n\n### Good imports\n\n```typescript\n// Good - Type imports and direct paths\nimport type { User } from \"@prisma/client\";\nimport { Button } from \"@calcom/ui/components/button\";\n\n// Bad - Regular import for types, barrel imports\nimport { User } from \"@prisma/client\";\nimport { Button } from \"@calcom/ui\";\n```\n\n### API v2 Imports (apps/api/v2)\n\nWhen importing from `@calcom/features` or `@calcom/trpc` into `apps/api/v2`, **do not import directly** because the API v2 app's `tsconfig.json` doesn't have path mappings for these modules, which causes \"module not found\" errors.\n\nInstead, re-export from `packages/platform/libraries/index.ts` and import from `@calcom/platform-libraries`:\n\n```typescript\n// Step 1: In packages/platform/libraries/index.ts, add the export\nexport { ProfileRepository } from \"@calcom/features/profile/repositories/ProfileRepository\";\n\n// Step 2: In apps/api/v2, import from platform-libraries\nimport { ProfileRepository } from \"@calcom/platform-libraries\";\n\n// Bad - Direct import causes module not found error in apps/api/v2\nimport { ProfileRepository } from \"@calcom/features/profile/repositories/ProfileRepository\";\n```\n\n## PR Checklist\n\n- [ ] Title follows conventional commits: `feat(scope): description`\n- [ ] Type check passes: `yarn type-check:ci --force`\n- [ ] Lint passes: `yarn lint:fix`\n- [ ] Relevant tests pass\n- [ ] Diff is small and focused (<500 lines, <10 files)\n- [ ] No secrets or API keys committed\n- [ ] UI strings added to translation files\n- [ ] Created as draft PR\n\n## When Stuck\n\n- Ask a clarifying question before making large speculative changes\n- Propose a short plan for complex tasks\n- Open a draft PR with notes if unsure about approach\n- Fix type errors before test failures - they're often the root cause\n- Run `yarn prisma generate` if you see missing enum/type errors\n\n## Spec-Driven Development (Opt-In)\n\nFor complex features, you can use spec-driven development when explicitly requested.\n\n**To enable:** Tell the AI \"use spec-driven development\" or \"follow the spec workflow\"\n\nSee [SPEC-WORKFLOW.md](SPEC-WORKFLOW.md) for the full workflow documentation.\n\n## Extended Documentation\n\nFor detailed information, see the `agents/` directory:\n\n- **[agents/README.md](agents/README.md)** - Rules index and architecture overview\n- **[agents/rules/](agents/rules/)** - Modular engineering rules\n- **[agents/commands.md](agents/commands.md)** - Complete command reference\n- **[agents/knowledge-base.md](agents/knowledge-base.md)** - Domain knowledge and business rules\n"},"files":{"AGENTS.md":"# Cal.diy Development Guide for AI Agents\n\nYou are a senior Cal.diy engineer working in a Yarn/Turbo monorepo. You prioritize type safety, security, and small, reviewable diffs.\n\n## Do\n\n- Use `select` instead of `include` in Prisma queries for performance and security\n- Use `import type { X }` for TypeScript type imports\n- Use early returns to reduce nesting: `if (!booking) return null;`\n- Use `ErrorWithCode` for errors in non-tRPC files (services, repositories, utilities); use `TRPCError` only in tRPC routers\n- Use conventional commits: `feat:`, `fix:`, `refactor:`\n- Create PRs in draft mode by default\n- Run `yarn type-check:ci --force` before concluding CI failures are unrelated to your changes\n- Import directly from source files, not barrel files (e.g., `@calcom/ui/components/button` not `@calcom/ui`)\n- Add translations to `packages/i18n/locales/en/common.json` for all UI strings\n- Use `date-fns` or native `Date` instead of Day.js when timezone awareness isn't needed\n- Put permission checks in `page.tsx`, never in `layout.tsx`\n- Use `ast-grep` for searching if available; otherwise use `rg` (ripgrep), then fall back to `grep`\n- Use Biome for formatting and linting\n- Only add code comments that explain **why**, not **what** — see [code comment guidelines](agents/rules/quality-code-comments.md)\n\n\n## Don't\n\n- Never use `as any` - use proper type-safe solutions instead\n- Never expose `credential.key` field in API responses or queries\n- Never commit secrets or API keys\n- Never modify `*.generated.ts` files directly - they're created by app-store-cli\n- Never put business logic in repositories - that belongs in Services\n- Never use barrel imports from index.ts files\n- Never skip running type checks before pushing\n- Never create large PRs (>500 lines or >10 files) - split them instead\n- Never add comments that simply restate what the code does (e.g., `// Get the user` above a `getUser()` call)\n\n## PR Size Guidelines\n\nLarge PRs are difficult to review, prone to errors, and slow down the development process. Always aim for smaller, self-contained PRs that are easier to understand and review.\n\n### Size Limits\n\n- **Lines changed**: Keep PRs under 500 lines of code (additions + deletions)\n- **Files changed**: Keep PRs under 10 code files\n- **Single responsibility**: Each PR should do one thing well\n\n**Note**: These limits apply to code files only. Non-code files like documentation (README.md, CHANGELOG.md), lock files (yarn.lock, package-lock.json), and auto-generated files are excluded from the count.\n\n### How to Split Large Changes\n\nWhen a task requires extensive changes, break it into multiple PRs:\n\n1. **By layer**: Separate database/schema changes, backend logic, and frontend UI into different PRs\n2. **By feature component**: Split a feature into its constituent parts (e.g., API endpoint PR, then UI PR, then integration PR)\n3. **By refactor vs feature**: Do preparatory refactoring in a separate PR before adding new functionality\n4. **By dependency order**: Create PRs in the order they can be merged (base infrastructure first, then features that depend on it)\n\n### Examples of Good PR Splits\n\n**Instead of one large \"Add booking notifications\" PR:**\n- PR 1: Add notification preferences schema and migration\n- PR 2: Add notification service and API endpoints\n- PR 3: Add notification UI components\n- PR 4: Integrate notifications into booking flow\n\n**Instead of one large \"Refactor calendar sync\" PR:**\n- PR 1: Extract calendar sync logic into dedicated service\n- PR 2: Add new calendar provider abstraction\n- PR 3: Migrate existing providers to new abstraction\n- PR 4: Add new calendar provider support\n\n### Benefits of Smaller PRs\n\n- Faster review cycles and quicker feedback\n- Easier to identify and fix issues\n- Lower risk of merge conflicts\n- Simpler to revert if problems arise\n- Better git history and easier debugging\n\n## Commands\n\nSee [agents/commands.md](agents/commands.md) for full reference. Key commands:\n\n```bash\nyarn type-check:ci --force  # Type check (always run before pushing)\nyarn biome check --write .  # Lint and format\nTZ=UTC yarn test            # Run unit tests\nyarn prisma generate        # Regenerate types after schema changes\n```\n\n\n## Boundaries\n\n### Always do\n- Run type check on changed files before committing\n- Run relevant tests before pushing\n- Use `select` in Prisma queries\n- Follow conventional commits for PR titles\n- Run Biome before pushing\n\n### Ask first\n- Adding new dependencies\n- Schema changes to `packages/prisma/schema.prisma`\n- Changes affecting multiple packages\n- Deleting files\n- Running full build or E2E suites\n\n### Never do\n- Commit secrets, API keys, or `.env` files\n- Expose `credential.key` in any query\n- Use `as any` type casting\n- Force push or rebase shared branches\n- Modify generated files directly\n\n## Project Structure\n\n```\napps/web/                    # Main Next.js application\npackages/prisma/             # Database schema (schema.prisma) and migrations\npackages/trpc/               # tRPC API layer (routers in server/routers/)\npackages/ui/                 # Shared UI components\npackages/features/           # Feature-specific code\npackages/app-store/          # Third-party integrations\npackages/lib/                # Shared utilities\n```\n\n### Key files\n- Routes: `apps/web/app/` (App Router)\n- Database schema: `packages/prisma/schema.prisma`\n- tRPC routers: `packages/trpc/server/routers/`\n- Translations: `packages/i18n/locales/en/common.json`\n- Workflow constants: `packages/features/ee/workflows/lib/constants.ts`\n\n## Tech Stack\n\n- **Framework**: Next.js 13+ (App Router in some areas)\n- **Language**: TypeScript (strict)\n- **Database**: PostgreSQL with Prisma ORM\n- **API**: tRPC for type-safe APIs\n- **Auth**: NextAuth.js\n- **Styling**: Tailwind CSS\n- **Testing**: Vitest (unit), Playwright (E2E)\n- **i18n**: next-i18next\n\n## Code Examples\n\n### Good error handling\n\n```typescript\n// Good - Descriptive error with context\nthrow new Error(`Unable to create booking: User ${userId} has no available time slots for ${date}`);\n\n// Bad - Generic error\nthrow new Error(\"Booking failed\");\n```\n\nFor which error class to use (`ErrorWithCode` vs `TRPCError`) and concrete examples, see [quality-error-handling](agents/rules/quality-error-handling.md).\n\n### Good Prisma query\n\n```typescript\n// Good - Use select for performance and security\nconst booking = await prisma.booking.findFirst({\n  select: {\n    id: true,\n    title: true,\n    user: {\n      select: {\n        id: true,\n        name: true,\n        email: true,\n      }\n    }\n  }\n});\n\n// Bad - Include fetches all fields including sensitive ones\nconst booking = await prisma.booking.findFirst({\n  include: { user: true }\n});\n```\n\n### Good imports\n\n```typescript\n// Good - Type imports and direct paths\nimport type { User } from \"@prisma/client\";\nimport { Button } from \"@calcom/ui/components/button\";\n\n// Bad - Regular import for types, barrel imports\nimport { User } from \"@prisma/client\";\nimport { Button } from \"@calcom/ui\";\n```\n\n### API v2 Imports (apps/api/v2)\n\nWhen importing from `@calcom/features` or `@calcom/trpc` into `apps/api/v2`, **do not import directly** because the API v2 app's `tsconfig.json` doesn't have path mappings for these modules, which causes \"module not found\" errors.\n\nInstead, re-export from `packages/platform/libraries/index.ts` and import from `@calcom/platform-libraries`:\n\n```typescript\n// Step 1: In packages/platform/libraries/index.ts, add the export\nexport { ProfileRepository } from \"@calcom/features/profile/repositories/ProfileRepository\";\n\n// Step 2: In apps/api/v2, import from platform-libraries\nimport { ProfileRepository } from \"@calcom/platform-libraries\";\n\n// Bad - Direct import causes module not found error in apps/api/v2\nimport { ProfileRepository } from \"@calcom/features/profile/repositories/ProfileRepository\";\n```\n\n## PR Checklist\n\n- [ ] Title follows conventional commits: `feat(scope): description`\n- [ ] Type check passes: `yarn type-check:ci --force`\n- [ ] Lint passes: `yarn lint:fix`\n- [ ] Relevant tests pass\n- [ ] Diff is small and focused (<500 lines, <10 files)\n- [ ] No secrets or API keys committed\n- [ ] UI strings added to translation files\n- [ ] Created as draft PR\n\n## When Stuck\n\n- Ask a clarifying question before making large speculative changes\n- Propose a short plan for complex tasks\n- Open a draft PR with notes if unsure about approach\n- Fix type errors before test failures - they're often the root cause\n- Run `yarn prisma generate` if you see missing enum/type errors\n\n## Spec-Driven Development (Opt-In)\n\nFor complex features, you can use spec-driven development when explicitly requested.\n\n**To enable:** Tell the AI \"use spec-driven development\" or \"follow the spec workflow\"\n\nSee [SPEC-WORKFLOW.md](SPEC-WORKFLOW.md) for the full workflow documentation.\n\n## Extended Documentation\n\nFor detailed information, see the `agents/` directory:\n\n- **[agents/README.md](agents/README.md)** - Rules index and architecture overview\n- **[agents/rules/](agents/rules/)** - Modular engineering rules\n- **[agents/commands.md](agents/commands.md)** - Complete command reference\n- **[agents/knowledge-base.md](agents/knowledge-base.md)** - Domain knowledge and business rules\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Cal.diy Development Guide for AI Agents\n\nYou are a senior Cal.diy engineer working in a Yarn/Turbo monorepo. You prioritize type safety, security, and small, reviewable diffs.\n\n## Do\n\n- Use `select` instead of `include` in Prisma queries for performance and security\n- Use `import type { X }` for TypeScript type imports\n- Use early returns to reduce nesting: `if (!booking) return null;`\n- Use `ErrorWithCode` for errors in non-tRPC files (services, repositories, utilities); use `TRPCError` only in tRPC routers\n- Use conventional commits: `feat:`, `fix:`, `refactor:`\n- Create PRs in draft mode by default\n- Run `yarn type-check:ci --force` before concluding CI failures are unrelated to your changes\n- Import directly from source files, not barrel files (e.g., `@calcom/ui/components/button` not `@calcom/ui`)\n- Add translations to `packages/i18n/locales/en/common.json` for all UI strings\n- Use `date-fns` or native `Date` instead of Day.js when timezone awareness isn't needed\n- Put permission checks in `page.tsx`, never in `layout.tsx`\n- Use `ast-grep` for searching if available; otherwise use `rg` (ripgrep), then fall back to `grep`\n- Use Biome for formatting and linting\n- Only add code comments that explain **why**, not **what** — see [code comment guidelines](agents/rules/quality-code-comments.md)\n\n\n## Don't\n\n- Never use `as any` - use proper type-safe solutions instead\n- Never expose `credential.key` field in API responses or queries\n- Never commit secrets or API keys\n- Never modify `*.generated.ts` files directly - they're created by app-store-cli\n- Never put business logic in repositories - that belongs in Services\n- Never use barrel imports from index.ts files\n- Never skip running type checks before pushing\n- Never create large PRs (>500 lines or >10 files) - split them instead\n- Never add comments that simply restate what the code does (e.g., `// Get the user` above a `getUser()` call)\n\n## PR Size Guidelines\n\nLarge PRs are difficult to review, prone to errors, and slow down the development process. Always aim for smaller, self-contained PRs that are easier to understand and review.\n\n### Size Limits\n\n- **Lines changed**: Keep PRs under 500 lines of code (additions + deletions)\n- **Files changed**: Keep PRs under 10 code files\n- **Single responsibility**: Each PR should do one thing well\n\n**Note**: These limits apply to code files only. Non-code files like documentation (README.md, CHANGELOG.md), lock files (yarn.lock, package-lock.json), and auto-generated files are excluded from the count.\n\n### How to Split Large Changes\n\nWhen a task requires extensive changes, break it into multiple PRs:\n\n1. **By layer**: Separate database/schema changes, backend logic, and frontend UI into different PRs\n2. **By feature component**: Split a feature into its constituent parts (e.g., API endpoint PR, then UI PR, then integration PR)\n3. **By refactor vs feature**: Do preparatory refactoring in a separate PR before adding new functionality\n4. **By dependency order**: Create PRs in the order they can be merged (base infrastructure first, then features that depend on it)\n\n### Examples of Good PR Splits\n\n**Instead of one large \"Add booking notifications\" PR:**\n- PR 1: Add notification preferences schema and migration\n- PR 2: Add notification service and API endpoints\n- PR 3: Add notification UI components\n- PR 4: Integrate notifications into booking flow\n\n**Instead of one large \"Refactor calendar sync\" PR:**\n- PR 1: Extract calendar sync logic into dedicated service\n- PR 2: Add new calendar provider abstraction\n- PR 3: Migrate existing providers to new abstraction\n- PR 4: Add new calendar provider support\n\n### Benefits of Smaller PRs\n\n- Faster review cycles and quicker feedback\n- Easier to identify and fix issues\n- Lower risk of merge conflicts\n- Simpler to revert if problems arise\n- Better git history and easier debugging\n\n## Commands\n\nSee [agents/commands.md](agents/commands.md) for full reference. Key commands:\n\n```bash\nyarn type-check:ci --force  # Type check (always run before pushing)\nyarn biome check --write .  # Lint and format\nTZ=UTC yarn test            # Run unit tests\nyarn prisma generate        # Regenerate types after schema changes\n```\n\n\n## Boundaries\n\n### Always do\n- Run type check on changed files before committing\n- Run relevant tests before pushing\n- Use `select` in Prisma queries\n- Follow conventional commits for PR titles\n- Run Biome before pushing\n\n### Ask first\n- Adding new dependencies\n- Schema changes to `packages/prisma/schema.prisma`\n- Changes affecting multiple packages\n- Deleting files\n- Running full build or E2E suites\n\n### Never do\n- Commit secrets, API keys, or `.env` files\n- Expose `credential.key` in any query\n- Use `as any` type casting\n- Force push or rebase shared branches\n- Modify generated files directly\n\n## Project Structure\n\n```\napps/web/                    # Main Next.js application\npackages/prisma/             # Database schema (schema.prisma) and migrations\npackages/trpc/               # tRPC API layer (routers in server/routers/)\npackages/ui/                 # Shared UI components\npackages/features/           # Feature-specific code\npackages/app-store/          # Third-party integrations\npackages/lib/                # Shared utilities\n```\n\n### Key files\n- Routes: `apps/web/app/` (App Router)\n- Database schema: `packages/prisma/schema.prisma`\n- tRPC routers: `packages/trpc/server/routers/`\n- Translations: `packages/i18n/locales/en/common.json`\n- Workflow constants: `packages/features/ee/workflows/lib/constants.ts`\n\n## Tech Stack\n\n- **Framework**: Next.js 13+ (App Router in some areas)\n- **Language**: TypeScript (strict)\n- **Database**: PostgreSQL with Prisma ORM\n- **API**: tRPC for type-safe APIs\n- **Auth**: NextAuth.js\n- **Styling**: Tailwind CSS\n- **Testing**: Vitest (unit), Playwright (E2E)\n- **i18n**: next-i18next\n\n## Code Examples\n\n### Good error handling\n\n```typescript\n// Good - Descriptive error with context\nthrow new Error(`Unable to create booking: User ${userId} has no available time slots for ${date}`);\n\n// Bad - Generic error\nthrow new Error(\"Booking failed\");\n```\n\nFor which error class to use (`ErrorWithCode` vs `TRPCError`) and concrete examples, see [quality-error-handling](agents/rules/quality-error-handling.md).\n\n### Good Prisma query\n\n```typescript\n// Good - Use select for performance and security\nconst booking = await prisma.booking.findFirst({\n  select: {\n    id: true,\n    title: true,\n    user: {\n      select: {\n        id: true,\n        name: true,\n        email: true,\n      }\n    }\n  }\n});\n\n// Bad - Include fetches all fields including sensitive ones\nconst booking = await prisma.booking.findFirst({\n  include: { user: true }\n});\n```\n\n### Good imports\n\n```typescript\n// Good - Type imports and direct paths\nimport type { User } from \"@prisma/client\";\nimport { Button } from \"@calcom/ui/components/button\";\n\n// Bad - Regular import for types, barrel imports\nimport { User } from \"@prisma/client\";\nimport { Button } from \"@calcom/ui\";\n```\n\n### API v2 Imports (apps/api/v2)\n\nWhen importing from `@calcom/features` or `@calcom/trpc` into `apps/api/v2`, **do not import directly** because the API v2 app's `tsconfig.json` doesn't have path mappings for these modules, which causes \"module not found\" errors.\n\nInstead, re-export from `packages/platform/libraries/index.ts` and import from `@calcom/platform-libraries`:\n\n```typescript\n// Step 1: In packages/platform/libraries/index.ts, add the export\nexport { ProfileRepository } from \"@calcom/features/profile/repositories/ProfileRepository\";\n\n// Step 2: In apps/api/v2, import from platform-libraries\nimport { ProfileRepository } from \"@calcom/platform-libraries\";\n\n// Bad - Direct import causes module not found error in apps/api/v2\nimport { ProfileRepository } from \"@calcom/features/profile/repositories/ProfileRepository\";\n```\n\n## PR Checklist\n\n- [ ] Title follows conventional commits: `feat(scope): description`\n- [ ] Type check passes: `yarn type-check:ci --force`\n- [ ] Lint passes: `yarn lint:fix`\n- [ ] Relevant tests pass\n- [ ] Diff is small and focused (<500 lines, <10 files)\n- [ ] No secrets or API keys committed\n- [ ] UI strings added to translation files\n- [ ] Created as draft PR\n\n## When Stuck\n\n- Ask a clarifying question before making large speculative changes\n- Propose a short plan for complex tasks\n- Open a draft PR with notes if unsure about approach\n- Fix type errors before test failures - they're often the root cause\n- Run `yarn prisma generate` if you see missing enum/type errors\n\n## Spec-Driven Development (Opt-In)\n\nFor complex features, you can use spec-driven development when explicitly requested.\n\n**To enable:** Tell the AI \"use spec-driven development\" or \"follow the spec workflow\"\n\nSee [SPEC-WORKFLOW.md](SPEC-WORKFLOW.md) for the full workflow documentation.\n\n## Extended Documentation\n\nFor detailed information, see the `agents/` directory:\n\n- **[agents/README.md](agents/README.md)** - Rules index and architecture overview\n- **[agents/rules/](agents/rules/)** - Modular engineering rules\n- **[agents/commands.md](agents/commands.md)** - Complete command reference\n- **[agents/knowledge-base.md](agents/knowledge-base.md)** - Domain knowledge and business rules\n","category":"root","tokens":2306}]}