{"owner":"vercel-labs","repo":"open-agents","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance for AI coding agents working in this repository.\n\n**This is a living document.** When you make a mistake or learn something new about this codebase, add it to [Lessons Learned](docs/agents/lessons-learned.md).\n\n## Quick Links\n\n- [Architecture & Workspace Structure](docs/agents/architecture.md)\n- [Code Style & Patterns](docs/agents/code-style.md)\n- [Lessons Learned](docs/agents/lessons-learned.md)\n\n## Authentication\n\nAuthentication uses [Better Auth](https://www.better-auth.com/) with Vercel OAuth (sign-in) and GitHub OAuth (repo access). Config lives in `apps/web/lib/auth/config.ts`. Sessions are managed by better-auth's built-in session system — there is no manual JWE/encryption layer.\n\nKey env vars: `BETTER_AUTH_SECRET` (session signing), `NEXT_PUBLIC_VERCEL_APP_CLIENT_ID` + `VERCEL_APP_CLIENT_SECRET` (Vercel OAuth), plus GitHub App credentials for repo access. See `apps/web/.env.example` for the full list.\n\n## Database & Migrations\n\nSchema lives in `apps/web/lib/db/schema.ts`. Migrations are managed by Drizzle Kit.\n\n**After modifying `schema.ts`, always generate a migration:**\n\n```bash\npnpm --dir apps/web db:generate   # Creates a new .sql migration file\n```\n\nCommit the generated `.sql` file alongside the schema change. **Do not use `db:push`** except for local throwaway databases.\n\nMigrations run automatically during `pnpm build` (via `lib/db/migrate.ts`), so every Vercel deploy — both preview and production — applies pending migrations to its own database.\n\n### Environment isolation\n\nNeon database branching is enabled in the Vercel project settings. Every preview deployment automatically gets its own isolated database branch forked from production. This means preview deployments never read or write production data. Production deployments use the main Neon database.\n\n## Commands\n\n```bash\n# Development\npnpm web            # Run web app\n\n# Quality checks (REQUIRED after making any changes)\npnpm run ci                             # Required: run format check, lint, typecheck, and tests\nturbo typecheck                            # Type check all packages\n\n# Linting and formatting (Ultracite - oxlint + oxfmt, run from root)\npnpm check                              # Lint and format check all files\npnpm fix                                # Lint fix and format all files\n\n# Filter by package (use --filter)\nturbo typecheck --filter=web # Type check web app only\n\n# Testing\nbun test                                              # Run all tests\nbun test path/to/file.test.ts                         # Run single test file\nbun test --watch                                      # Watch mode\npnpm test:verbose                                  # Run tests with JUnit reporter streamed to stdout (useful in non-interactive shells)\npnpm test:verbose path/to/file.test.ts             # Same verbose output for a single test file\n```\n\n**CI/script execution rules:**\n\n- Run project checks through package scripts (for example `pnpm run ci`, `pnpm --dir apps/web db:check`).\n- Prefer `pnpm <script>` over invoking tool binaries directly (`pnpm exec`, `tsc`, `eslint`, etc.) so local runs match CI behavior.\n\n## Git Commands\n\n- **Branch sync preference:** When bringing in `origin/main`, prefer a normal merge (`git fetch origin main` then `git merge origin/main`) instead of rebasing, unless explicitly requested otherwise.\n\n**Quote paths with special characters**: File paths containing brackets (like Next.js dynamic routes `[id]`, `[slug]`) are interpreted as glob patterns by zsh. Always quote these paths in git commands:\n\n```bash\n# Wrong - zsh interprets [id] as a glob pattern\ngit add apps/web/app/tasks/[id]/page.tsx\n# Error: no matches found: apps/web/app/tasks/[id]/page.tsx\n\n# Correct - quote the path\ngit add \"apps/web/app/tasks/[id]/page.tsx\"\n```\n\n## Architecture (Summary)\n\n```\nWeb -> Agent (packages/agent) -> Sandbox (packages/sandbox)\n```\n\nSee [Architecture & Workspace Structure](docs/agents/architecture.md) for details.\n\n## File Organization & Separation of Concerns\n\n- Do **not** append new functionality to the bottom of an existing file by default.\n- Before adding code, decide whether the behavior is a separate concern that should live in its own file.\n- Prefer creating a new colocated file for distinct concerns (components, hooks, utilities, schemas, data-access helpers, etc.).\n- If a file is already large or handling multiple responsibilities, extract the new logic (and related helpers/types) into focused modules and import them.\n- For large page/view/client components, default to adding new feature behavior in colocated hooks and colocated child components instead of growing the main file.\n- If a change introduces a distinct cluster of state, effects, handlers, API calls, or derived UI labels for one feature, treat that as a strong signal to extract it.\n- Keep each file focused on one primary responsibility; avoid mixing unrelated UI, business logic, and data-access code in the same file.\n\n## Code Style (Summary)\n\n- **pnpm exclusively for dependency management**; use Node 24 for utility scripts and Bun for tests\n- **Files**: kebab-case, **Types**: PascalCase, **Functions**: camelCase\n- **Never use `any`** -- use `unknown` and narrow with type guards\n- **No `.js` extensions** in imports\n- **Ultracite** (oxlint + oxfmt) for linting and formatting (double quotes, 2-space indent)\n- **Zod** schemas for validation, derive types with `z.infer`\n\nSee [Code Style & Patterns](docs/agents/code-style.md) for full conventions, tool implementation patterns, and dependency patterns.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance for AI coding agents working in this repository.\n\n**This is a living document.** When you make a mistake or learn something new about this codebase, add it to [Lessons Learned](docs/agents/lessons-learned.md).\n\n## Quick Links\n\n- [Architecture & Workspace Structure](docs/agents/architecture.md)\n- [Code Style & Patterns](docs/agents/code-style.md)\n- [Lessons Learned](docs/agents/lessons-learned.md)\n\n## Authentication\n\nAuthentication uses [Better Auth](https://www.better-auth.com/) with Vercel OAuth (sign-in) and GitHub OAuth (repo access). Config lives in `apps/web/lib/auth/config.ts`. Sessions are managed by better-auth's built-in session system — there is no manual JWE/encryption layer.\n\nKey env vars: `BETTER_AUTH_SECRET` (session signing), `NEXT_PUBLIC_VERCEL_APP_CLIENT_ID` + `VERCEL_APP_CLIENT_SECRET` (Vercel OAuth), plus GitHub App credentials for repo access. See `apps/web/.env.example` for the full list.\n\n## Database & Migrations\n\nSchema lives in `apps/web/lib/db/schema.ts`. Migrations are managed by Drizzle Kit.\n\n**After modifying `schema.ts`, always generate a migration:**\n\n```bash\npnpm --dir apps/web db:generate   # Creates a new .sql migration file\n```\n\nCommit the generated `.sql` file alongside the schema change. **Do not use `db:push`** except for local throwaway databases.\n\nMigrations run automatically during `pnpm build` (via `lib/db/migrate.ts`), so every Vercel deploy — both preview and production — applies pending migrations to its own database.\n\n### Environment isolation\n\nNeon database branching is enabled in the Vercel project settings. Every preview deployment automatically gets its own isolated database branch forked from production. This means preview deployments never read or write production data. Production deployments use the main Neon database.\n\n## Commands\n\n```bash\n# Development\npnpm web            # Run web app\n\n# Quality checks (REQUIRED after making any changes)\npnpm run ci                             # Required: run format check, lint, typecheck, and tests\nturbo typecheck                            # Type check all packages\n\n# Linting and formatting (Ultracite - oxlint + oxfmt, run from root)\npnpm check                              # Lint and format check all files\npnpm fix                                # Lint fix and format all files\n\n# Filter by package (use --filter)\nturbo typecheck --filter=web # Type check web app only\n\n# Testing\nbun test                                              # Run all tests\nbun test path/to/file.test.ts                         # Run single test file\nbun test --watch                                      # Watch mode\npnpm test:verbose                                  # Run tests with JUnit reporter streamed to stdout (useful in non-interactive shells)\npnpm test:verbose path/to/file.test.ts             # Same verbose output for a single test file\n```\n\n**CI/script execution rules:**\n\n- Run project checks through package scripts (for example `pnpm run ci`, `pnpm --dir apps/web db:check`).\n- Prefer `pnpm <script>` over invoking tool binaries directly (`pnpm exec`, `tsc`, `eslint`, etc.) so local runs match CI behavior.\n\n## Git Commands\n\n- **Branch sync preference:** When bringing in `origin/main`, prefer a normal merge (`git fetch origin main` then `git merge origin/main`) instead of rebasing, unless explicitly requested otherwise.\n\n**Quote paths with special characters**: File paths containing brackets (like Next.js dynamic routes `[id]`, `[slug]`) are interpreted as glob patterns by zsh. Always quote these paths in git commands:\n\n```bash\n# Wrong - zsh interprets [id] as a glob pattern\ngit add apps/web/app/tasks/[id]/page.tsx\n# Error: no matches found: apps/web/app/tasks/[id]/page.tsx\n\n# Correct - quote the path\ngit add \"apps/web/app/tasks/[id]/page.tsx\"\n```\n\n## Architecture (Summary)\n\n```\nWeb -> Agent (packages/agent) -> Sandbox (packages/sandbox)\n```\n\nSee [Architecture & Workspace Structure](docs/agents/architecture.md) for details.\n\n## File Organization & Separation of Concerns\n\n- Do **not** append new functionality to the bottom of an existing file by default.\n- Before adding code, decide whether the behavior is a separate concern that should live in its own file.\n- Prefer creating a new colocated file for distinct concerns (components, hooks, utilities, schemas, data-access helpers, etc.).\n- If a file is already large or handling multiple responsibilities, extract the new logic (and related helpers/types) into focused modules and import them.\n- For large page/view/client components, default to adding new feature behavior in colocated hooks and colocated child components instead of growing the main file.\n- If a change introduces a distinct cluster of state, effects, handlers, API calls, or derived UI labels for one feature, treat that as a strong signal to extract it.\n- Keep each file focused on one primary responsibility; avoid mixing unrelated UI, business logic, and data-access code in the same file.\n\n## Code Style (Summary)\n\n- **pnpm exclusively for dependency management**; use Node 24 for utility scripts and Bun for tests\n- **Files**: kebab-case, **Types**: PascalCase, **Functions**: camelCase\n- **Never use `any`** -- use `unknown` and narrow with type guards\n- **No `.js` extensions** in imports\n- **Ultracite** (oxlint + oxfmt) for linting and formatting (double quotes, 2-space indent)\n- **Zod** schemas for validation, derive types with `z.infer`\n\nSee [Code Style & Patterns](docs/agents/code-style.md) for full conventions, tool implementation patterns, and dependency patterns.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nThis file provides guidance for AI coding agents working in this repository.\n\n**This is a living document.** When you make a mistake or learn something new about this codebase, add it to [Lessons Learned](docs/agents/lessons-learned.md).\n\n## Quick Links\n\n- [Architecture & Workspace Structure](docs/agents/architecture.md)\n- [Code Style & Patterns](docs/agents/code-style.md)\n- [Lessons Learned](docs/agents/lessons-learned.md)\n\n## Authentication\n\nAuthentication uses [Better Auth](https://www.better-auth.com/) with Vercel OAuth (sign-in) and GitHub OAuth (repo access). Config lives in `apps/web/lib/auth/config.ts`. Sessions are managed by better-auth's built-in session system — there is no manual JWE/encryption layer.\n\nKey env vars: `BETTER_AUTH_SECRET` (session signing), `NEXT_PUBLIC_VERCEL_APP_CLIENT_ID` + `VERCEL_APP_CLIENT_SECRET` (Vercel OAuth), plus GitHub App credentials for repo access. See `apps/web/.env.example` for the full list.\n\n## Database & Migrations\n\nSchema lives in `apps/web/lib/db/schema.ts`. Migrations are managed by Drizzle Kit.\n\n**After modifying `schema.ts`, always generate a migration:**\n\n```bash\npnpm --dir apps/web db:generate   # Creates a new .sql migration file\n```\n\nCommit the generated `.sql` file alongside the schema change. **Do not use `db:push`** except for local throwaway databases.\n\nMigrations run automatically during `pnpm build` (via `lib/db/migrate.ts`), so every Vercel deploy — both preview and production — applies pending migrations to its own database.\n\n### Environment isolation\n\nNeon database branching is enabled in the Vercel project settings. Every preview deployment automatically gets its own isolated database branch forked from production. This means preview deployments never read or write production data. Production deployments use the main Neon database.\n\n## Commands\n\n```bash\n# Development\npnpm web            # Run web app\n\n# Quality checks (REQUIRED after making any changes)\npnpm run ci                             # Required: run format check, lint, typecheck, and tests\nturbo typecheck                            # Type check all packages\n\n# Linting and formatting (Ultracite - oxlint + oxfmt, run from root)\npnpm check                              # Lint and format check all files\npnpm fix                                # Lint fix and format all files\n\n# Filter by package (use --filter)\nturbo typecheck --filter=web # Type check web app only\n\n# Testing\nbun test                                              # Run all tests\nbun test path/to/file.test.ts                         # Run single test file\nbun test --watch                                      # Watch mode\npnpm test:verbose                                  # Run tests with JUnit reporter streamed to stdout (useful in non-interactive shells)\npnpm test:verbose path/to/file.test.ts             # Same verbose output for a single test file\n```\n\n**CI/script execution rules:**\n\n- Run project checks through package scripts (for example `pnpm run ci`, `pnpm --dir apps/web db:check`).\n- Prefer `pnpm <script>` over invoking tool binaries directly (`pnpm exec`, `tsc`, `eslint`, etc.) so local runs match CI behavior.\n\n## Git Commands\n\n- **Branch sync preference:** When bringing in `origin/main`, prefer a normal merge (`git fetch origin main` then `git merge origin/main`) instead of rebasing, unless explicitly requested otherwise.\n\n**Quote paths with special characters**: File paths containing brackets (like Next.js dynamic routes `[id]`, `[slug]`) are interpreted as glob patterns by zsh. Always quote these paths in git commands:\n\n```bash\n# Wrong - zsh interprets [id] as a glob pattern\ngit add apps/web/app/tasks/[id]/page.tsx\n# Error: no matches found: apps/web/app/tasks/[id]/page.tsx\n\n# Correct - quote the path\ngit add \"apps/web/app/tasks/[id]/page.tsx\"\n```\n\n## Architecture (Summary)\n\n```\nWeb -> Agent (packages/agent) -> Sandbox (packages/sandbox)\n```\n\nSee [Architecture & Workspace Structure](docs/agents/architecture.md) for details.\n\n## File Organization & Separation of Concerns\n\n- Do **not** append new functionality to the bottom of an existing file by default.\n- Before adding code, decide whether the behavior is a separate concern that should live in its own file.\n- Prefer creating a new colocated file for distinct concerns (components, hooks, utilities, schemas, data-access helpers, etc.).\n- If a file is already large or handling multiple responsibilities, extract the new logic (and related helpers/types) into focused modules and import them.\n- For large page/view/client components, default to adding new feature behavior in colocated hooks and colocated child components instead of growing the main file.\n- If a change introduces a distinct cluster of state, effects, handlers, API calls, or derived UI labels for one feature, treat that as a strong signal to extract it.\n- Keep each file focused on one primary responsibility; avoid mixing unrelated UI, business logic, and data-access code in the same file.\n\n## Code Style (Summary)\n\n- **pnpm exclusively for dependency management**; use Node 24 for utility scripts and Bun for tests\n- **Files**: kebab-case, **Types**: PascalCase, **Functions**: camelCase\n- **Never use `any`** -- use `unknown` and narrow with type guards\n- **No `.js` extensions** in imports\n- **Ultracite** (oxlint + oxfmt) for linting and formatting (double quotes, 2-space indent)\n- **Zod** schemas for validation, derive types with `z.infer`\n\nSee [Code Style & Patterns](docs/agents/code-style.md) for full conventions, tool implementation patterns, and dependency patterns.\n","category":"root","tokens":1397}]}