refactor: clean up AGENTS.md files to only include non-obvious patterns

- Reduced main AGENTS.md from 65 to 21 lines
- Reduced .roo/rules-code/AGENTS.md from 39 to 11 lines
- Reduced .roo/rules-debug/AGENTS.md from 40 to 13 lines
- Reduced .roo/rules-ask/AGENTS.md from 39 to 8 lines
- Reduced .roo/rules-architect/AGENTS.md from 42 to 10 lines

Removed all obvious information like standard commands, framework defaults, and common patterns. Files now only contain truly non-obvious, project-specific gotchas discovered by reading the actual code.

Author: hannesrudolph

.roo/rules-architect/AGENTS.md

@@ -1,42 +1,10 @@
 # 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
+## Non-Obvious Architecture Constraints
+
+- Providers MUST be stateless - hidden caching layer assumes this
+- Webview and extension communicate through specific IPC channel patterns only
+- React hooks required because external state libraries break webview isolation
+- Large JSON operations must use `safeWriteJson()` for streaming (prevents memory issues)
+- TypeScript `noUncheckedIndexedAccess: true` - array/object access may return undefined
+- Import paths in packages/ require `.js` extensions despite TypeScript source

.roo/rules-ask/AGENTS.md

@@ -1,39 +1,8 @@
 # Ask Mode Rules
 
-## Documentation Sources
+## Non-Obvious Documentation Context
 
-- 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
+- `src/` contains VSCode extension code, NOT generic source (counterintuitive naming)
+- Two separate i18n systems: root `locales/` for extension, `webview-ui/src/i18n/` for UI
+- Provider examples in `src/api/providers/` are canonical reference (docs may be outdated)
+- Webview runs in VSCode context with restrictions (no localStorage, limited browser APIs)

.roo/rules-code/AGENTS.md

@@ -1,39 +1,10 @@
 # Code Mode Rules
 
-## JSON File Operations
+## Critical Non-Obvious Patterns
 
-- **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
+- **MANDATORY**: Use `safeWriteJson()` from `src/utils/safeWriteJson.ts` for ALL JSON writes (prevents corruption via atomic writes with locking)
+- Tests MUST run from workspace directory: `cd src && npx vitest run` (NOT from root)
 - 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
+- State management via React hooks only (external state libraries break webview isolation)
+- Providers MUST be stateless (hidden caching layer assumes this)
+- Import paths in packages/ require `.js` extensions despite TypeScript source

.roo/rules-debug/AGENTS.md

@@ -1,40 +1,13 @@
 # Debug Mode Rules
 
-## Debugging Entry Points
+## Non-Obvious Debug Access
 
-- 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
+- Webview DevTools: Command Palette → "Developer: Open Webview Developer Tools" (NOT F12)
+- Extension logs: VSCode Output panel → "Roo Code" channel
+- Extension Host output channel shows different logs than Debug Console
 
-## Common Debug Patterns
+## Critical 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
+- IPC messages fail silently without try/catch in `packages/ipc/src/`
+- Tests MUST run from workspace directory: `cd src && npx vitest run`
+- Webview runs in restricted context (no localStorage, limited browser APIs)

AGENTS.md

@@ -2,64 +2,20 @@
 
 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
+## Critical Non-Obvious Patterns
+
+- **JSON Writes**: MUST use `safeWriteJson()` from `src/utils/safeWriteJson.ts` for ALL JSON writes (atomic writes with locking, handles streaming)
+- **Test Execution**: Tests MUST run from workspace directory: `cd src && npx vitest run` or `cd webview-ui && npx vitest run` (NOT from root)
+- **Import Extensions**: Use `.js` extensions in packages/ imports despite TypeScript source files
+- **Bootstrap**: `pnpm install` auto-bootstraps via `scripts/bootstrap.mjs` if pnpm not found
+- **Webview DevTools**: Access via Command Palette → "Developer: Open Webview Developer Tools" (not F12)
+- **VSCode CSS Variables**: Must be added to `webview-ui/src/index.css` before use in components
+- **React Hooks Required**: External state libraries break webview isolation - use React hooks only
+- **noUncheckedIndexedAccess**: TypeScript strict mode with this enabled - array/object access may return undefined
+
+## Architecture Gotchas
+
+- `src/` contains VSCode extension backend (not generic source)
+- `webview-ui/` is React frontend in VSCode webview (restricted APIs, no localStorage)
+- IPC messages between extension/webview must use typed interfaces from `packages/types`
+- Provider implementations must be stateless (hidden caching layer assumes this)