diff --git a/.roo/rules-architect/AGENTS.md b/.roo/rules-architect/AGENTS.md new file mode 100644 index 0000000000..0bfd625eaa --- /dev/null +++ b/.roo/rules-architect/AGENTS.md @@ -0,0 +1,7 @@ +# Project Architecture Rules (Non-Obvious Only) + +- Webview and extension communicate ONLY through `src/core/webview/webviewMessageHandler.ts` patterns +- React hooks required in webview - external state libraries break VSCode webview isolation +- Monorepo has circular dependency on types package (intentional design) +- `safeWriteJson()` mandatory for JSON writes - uses atomic writes with file locking +- Database operations require specific directory: must `cd packages/evals` before running migrations diff --git a/.roo/rules-ask/AGENTS.md b/.roo/rules-ask/AGENTS.md new file mode 100644 index 0000000000..1c35929def --- /dev/null +++ b/.roo/rules-ask/AGENTS.md @@ -0,0 +1,7 @@ +# Project Documentation Rules (Non-Obvious Only) + +- `src/` contains VSCode extension code, NOT general source (counterintuitive naming) +- `webview-ui/` is React UI in VSCode webview with severe restrictions (no localStorage, limited APIs) +- Two separate i18n systems: `locales/` for extension, `webview-ui/src/i18n/` for UI +- Monorepo workspace roots are `"src"` and `"webview-ui"` (not standard `packages/` structure) +- Extension bundled with custom `esbuild.mjs`, webview uses Vite diff --git a/.roo/rules-code/AGENTS.md b/.roo/rules-code/AGENTS.md new file mode 100644 index 0000000000..686588167d --- /dev/null +++ b/.roo/rules-code/AGENTS.md @@ -0,0 +1,8 @@ +# Project Coding Rules (Non-Obvious Only) + +- Always use `safeWriteJson()` from `src/utils/safeWriteJson.ts` instead of `JSON.stringify` for file writes (prevents corruption) +- Extension code in `src/` directory, NOT in `apps/` (counterintuitive structure) +- Webview UI in `webview-ui/` runs with restricted APIs - no localStorage, limited browser features +- IPC patterns MUST follow `src/core/webview/webviewMessageHandler.ts` structure +- Tests must be in `__tests__` folders or `.spec.ts` files (vitest won't find them otherwise) +- VSCode API mocked differently: `src/__mocks__/vscode.js` vs `webview-ui/src/__mocks__/vscode.ts` diff --git a/.roo/rules-debug/AGENTS.md b/.roo/rules-debug/AGENTS.md new file mode 100644 index 0000000000..fa068f6ca6 --- /dev/null +++ b/.roo/rules-debug/AGENTS.md @@ -0,0 +1,7 @@ +# Project Debug Rules (Non-Obvious Only) + +- Extension logs only visible in "Extension Host" output channel, NOT Debug Console +- Webview dev tools accessed via Command Palette > "Developer: Open Webview Developer Tools" (not F12) +- Database migrations MUST run from `packages/evals/` directory: `cd packages/evals && pnpm db:migrate` +- IPC messages fail silently if not wrapped in try/catch in webview message handlers +- Two separate mock systems: `src/__mocks__/vscode.js` for extension, `webview-ui/src/__mocks__/vscode.ts` for UI diff --git a/.roo/rules/rules.md b/.roo/rules/rules.md deleted file mode 100644 index 5726770a28..0000000000 --- a/.roo/rules/rules.md +++ /dev/null @@ -1,24 +0,0 @@ -# Code Quality Rules - -1. Test Coverage: - - - Before attempting completion, always make sure that any code changes have test coverage - - Ensure all tests pass before submitting changes - - The vitest framework is used for testing; the `vi`, `describe`, `test`, `it`, etc functions are defined by default in `tsconfig.json` and therefore don't need to be imported from `vitest` - - Tests must be run from the same directory as the `package.json` file that specifies `vitest` in `devDependencies` - - Run tests with: `npx vitest run ` - - Do NOT run tests from project root - this causes "vitest: command not found" error - - Tests must be run from inside the correct workspace: - - Backend tests: `cd src && npx vitest run path/to/test-file` (don't include `src/` in path) - - UI tests: `cd webview-ui && npx vitest run src/path/to/test-file` - - Example: For `src/tests/user.test.ts`, run `cd src && npx vitest run tests/user.test.ts` NOT `npx vitest run src/tests/user.test.ts` - -2. Lint Rules: - - - Never disable any lint rules without explicit user approval - -3. Styling Guidelines: - - - Use Tailwind CSS classes instead of inline style objects for new markup - - VSCode CSS variables must be added to webview-ui/src/index.css before using them in Tailwind classes - - Example: `
` instead of style objects diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..cd0c0c31b2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,37 @@ +# AGENTS.md + +This file provides guidance to agents when working with code in this repository. + +## Critical Non-Obvious Rules + +- **MUST** use `safeWriteJson()` from `src/utils/safeWriteJson.ts` for ALL JSON file writes (prevents corruption via atomic writes with locking) +- Test files exempt from safeWriteJson rule + +## Project Structure (Non-Standard) + +- `src/` contains VSCode extension code (NOT general source - counterintuitive naming) +- `webview-ui/` is the React UI that runs in VSCode webview (separate from extension) +- Two separate i18n systems: root `locales/` for extension, `webview-ui/src/i18n/` for UI +- Monorepo uses pnpm workspaces with unusual paths: `"src"` and `"webview-ui"` as workspace roots + +## Testing Specifics + +- Tests MUST be in `__tests__` folders or `.spec.ts` files (vitest configured this way) +- VSCode module mocked at `src/__mocks__/vscode.js` and `webview-ui/src/__mocks__/vscode.ts` +- Run single test: `pnpm test -- path/to/test.spec.ts` + +## Build Commands (Directory-Sensitive) + +- Database operations MUST run from `packages/evals/` directory: `cd packages/evals && pnpm db:migrate` +- Extension bundling uses custom `esbuild.mjs` script, not standard vite/webpack + +## Webview Restrictions + +- Webview has NO localStorage, limited browser APIs +- IPC communication through specific patterns in `src/core/webview/webviewMessageHandler.ts` +- State management requires React hooks only (external state libraries break isolation) + +## Code Style (Non-Standard) + +- Tabs not spaces (4-width), no semicolons, bracket same line +- Line width 120 chars (not default 80)