From 962ced65daa7f765f80d345ec2de81b57309d004 Mon Sep 17 00:00:00 2001 From: Matt Rubens Date: Mon, 25 Aug 2025 17:09:55 -0400 Subject: [PATCH] Add the results of running /init --- .roo/rules-architect/AGENTS.md | 42 ++++++++++++++++++++++ .roo/rules-ask/AGENTS.md | 39 ++++++++++++++++++++ .roo/rules-code/AGENTS.md | 39 ++++++++++++++++++++ .roo/rules-debug/AGENTS.md | 40 +++++++++++++++++++++ AGENTS.md | 65 ++++++++++++++++++++++++++++++++++ 5 files changed, 225 insertions(+) create mode 100644 .roo/rules-architect/AGENTS.md create mode 100644 .roo/rules-ask/AGENTS.md create mode 100644 .roo/rules-code/AGENTS.md create mode 100644 .roo/rules-debug/AGENTS.md create mode 100644 AGENTS.md diff --git a/.roo/rules-architect/AGENTS.md b/.roo/rules-architect/AGENTS.md new file mode 100644 index 0000000000..303c4039a5 --- /dev/null +++ b/.roo/rules-architect/AGENTS.md @@ -0,0 +1,42 @@ +# Architect Mode Rules + +## Design Principles + +- **VSCode Extension Architecture**: Work within VSCode's webview + extension host model +- **Monorepo Organization**: Maintain clear separation between packages +- **Provider Pattern**: New AI providers must follow existing interface patterns +- **State Management**: React hooks for UI, VSCode context for extension state + +## Package Structure Requirements + +- New packages go in `packages/` directory +- Must include proper TypeScript configuration extending base +- Shared types belong in `packages/types/src/` +- Follow existing naming conventions (e.g., @roo-code/package-name) + +## API Design + +- All providers implement Provider interface from packages/types +- IPC messages must be strongly typed +- Backwards compatibility required for existing provider contracts +- Error handling must include proper error types and recovery + +## Performance Considerations + +- Large JSON operations must use streaming (see safeWriteJson) +- Webview content should lazy-load heavy components +- Code indexing happens asynchronously in background +- Terminal operations should not block UI + +## Evals Database & Migrations + +- Evals database schemas in `packages/evals/src/db/` +- Migrations required for schema changes +- Use proper transaction handling for data consistency + +## Security Patterns + +- Never expose sensitive data in webview +- API keys stored in VSCode SecretStorage +- File operations must validate paths +- Command execution requires user approval diff --git a/.roo/rules-ask/AGENTS.md b/.roo/rules-ask/AGENTS.md new file mode 100644 index 0000000000..794ffea27d --- /dev/null +++ b/.roo/rules-ask/AGENTS.md @@ -0,0 +1,39 @@ +# Ask Mode Rules + +## Documentation Sources + +- Main documentation: README.md, CONTRIBUTING.md, CHANGELOG.md +- API docs: Check provider implementations in `src/api/providers/` +- UI patterns: Reference `webview-ui/src/components/` for React components +- Types: Refer to `packages/types/src/` for TypeScript interfaces + +## Code Examples + +- Provider examples: Each provider in `src/api/providers/` shows implementation patterns +- Test examples: `src/__tests__/` and `webview-ui/src/**/*.test.tsx` +- IPC patterns: `packages/ipc/src/` for communication examples +- Custom modes: Check `.roo/rules-*/` directories for mode-specific patterns + +## Architecture Explanations + +- **Monorepo Structure**: + - `src/` - VSCode extension backend + - `webview-ui/` - React frontend + - `packages/` - Shared libraries + - `apps/` - Additional applications +- **Webview Architecture**: VSCode extension hosts React app via webview API +- **Provider Pattern**: All AI providers implement common interface for consistency +- **IPC Communication**: Typed messages between extension and webview + +## Command References + +- Build commands: See `package.json` scripts section +- Test commands: Must run from workspace directory with package.json +- Development: F5 launches extension in new VSCode window +- VSIX packaging: `pnpm vsix` creates installable package + +## Localization + +- i18n files in `locales/` directory +- Extension uses vscode.l10n API for translations +- Webview uses i18next for React component translations diff --git a/.roo/rules-code/AGENTS.md b/.roo/rules-code/AGENTS.md new file mode 100644 index 0000000000..ee1d428265 --- /dev/null +++ b/.roo/rules-code/AGENTS.md @@ -0,0 +1,39 @@ +# Code Mode Rules + +## JSON File Operations + +- **MANDATORY**: Use `safeWriteJson()` from `src/utils/safeWriteJson.ts` for ALL JSON writes +- Never use `JSON.stringify` with direct file writes - always use `safeWriteJson` +- `safeWriteJson` handles directory creation, atomic writes, and locking automatically + +## Provider Implementation + +- All new providers MUST implement the Provider interface from `packages/types/src/` +- Provider implementations go in `src/api/providers/` +- Each provider needs proper error handling and retry mechanisms + +## UI Component Guidelines + +- Use Tailwind CSS classes exclusively - no inline styles +- VSCode CSS variables must be added to `webview-ui/src/index.css` before use +- React components use functional components with hooks +- State management via React hooks, not external state libraries + +## Testing Requirements + +- All new features require test coverage +- Tests use vitest framework (vi, describe, test, it are global) +- Run tests from workspace directory: `cd src && npx vitest run` +- Never run tests from project root + +## IPC Communication + +- Use packages/ipc for webview ↔ extension communication +- Messages must be typed using interfaces from packages/types +- Handle all async operations with proper error boundaries + +## File Restrictions + +- Code mode can edit all file types +- Always verify file exists before operations +- Use proper file locking for concurrent access safety diff --git a/.roo/rules-debug/AGENTS.md b/.roo/rules-debug/AGENTS.md new file mode 100644 index 0000000000..645eb93b2b --- /dev/null +++ b/.roo/rules-debug/AGENTS.md @@ -0,0 +1,40 @@ +# Debug Mode Rules + +## Debugging Entry Points + +- VSCode Debug Console shows extension logs via `outputChannel` +- Webview DevTools accessible via Command Palette → "Developer: Open Webview Developer Tools" +- Extension host debugging: Press F5 to launch new VSCode window with extension loaded + +## Common Debug Patterns + +- Provider issues: Check `src/api/providers/__tests__/` for test patterns +- IPC communication: Review `packages/ipc/src/` for message flow +- Webview state issues: Check React DevTools in webview developer tools +- Extension activation: Review `src/extension.ts` and `src/activate/` + +## Log Locations + +- Extension logs: VSCode Output panel → "Roo Code" +- Terminal command logs: Check TerminalRegistry in `src/integrations/terminal/` +- MCP server logs: Check McpServerManager output +- Cloud service logs: Check CloudService initialization in extension.ts + +## Testing Debug Workflow + +1. Add console.log or debugger statements +2. Run tests with: `cd src && npx vitest run --reporter=verbose` +3. For UI tests: `cd webview-ui && npx vitest run --reporter=verbose` +4. Use VSCode's built-in debugger for stepping through code + +## Performance Debugging + +- Memory issues: Check for proper cleanup in `deactivate()` function +- Slow operations: Profile with Chrome DevTools for webview +- Extension performance: Use VSCode's Extension Host profiler + +## Error Handling + +- All async operations should have try-catch blocks +- Errors should be logged to outputChannel +- Critical errors should provide user-friendly messages via vscode.window.showErrorMessage diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..53e901fd09 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,65 @@ +# AGENTS.md + +This file provides guidance to agents when working with code in this repository. + +## Project Overview + +Roo Code - AI-powered autonomous coding agent VSCode extension with React webview UI, supporting multiple AI providers and custom modes. + +## Build/Test/Lint Commands + +```bash +# Install dependencies (from root) +pnpm install + +# Build entire project +pnpm build + +# Run tests (CRITICAL: run from workspace directory containing package.json) +cd src && npx vitest run tests/user.test.ts # Backend tests +cd webview-ui && npx vitest run src/components/Button.test.tsx # UI tests + +# Lint/format +pnpm lint +pnpm format +``` + +## Code Style + +- **Formatting**: Tabs (4 width), 120 char lines, no semicolons, bracket same line +- **Imports**: ESM modules, use `.js` extensions in packages/ +- **Types**: TypeScript strict mode, `noUncheckedIndexedAccess: true` +- **Naming**: camelCase functions/variables, PascalCase components/classes +- **UI**: Tailwind CSS classes only (no inline styles), VSCode CSS vars via webview-ui/src/index.css + +## Architecture + +``` +src/ # VSCode extension backend (TypeScript) +├── extension.ts # Entry point, registers providers & commands +├── api/providers/ # AI provider implementations +├── core/webview/ # Webview provider & IPC +└── utils/ # Utilities (MUST use safeWriteJson for JSON writes) + +webview-ui/ # React frontend +├── src/components/ # React components with Tailwind CSS +└── src/hooks/ # Custom React hooks + +packages/ # Shared packages +├── types/ # Shared TypeScript types +├── ipc/ # IPC communication layer +└── evals/ # Evaluation framework +``` + +## Critical Patterns + +- **JSON Writes**: ALWAYS use `safeWriteJson()` from src/utils/safeWriteJson.ts (atomic writes with locking) +- **Testing**: Run vitest from workspace directory containing package.json, NOT from project root +- **Providers**: Implement Provider interface from packages/types/src/ +- **Webview**: VSCode webview architecture with IPC messaging between extension and UI + +## Development + +- **Debug**: Press F5 in VSCode to launch extension host +- **Hot Reload**: Webview changes appear immediately, core changes auto-reload in dev mode +- **VSIX**: `pnpm vsix` to build, `pnpm install:vsix` to install locally