diff --git a/src/services/command/__tests__/built-in-commands.spec.ts b/src/services/command/__tests__/built-in-commands.spec.ts index a934874b02..5a191b3860 100644 --- a/src/services/command/__tests__/built-in-commands.spec.ts +++ b/src/services/command/__tests__/built-in-commands.spec.ts @@ -89,8 +89,8 @@ describe("Built-in Commands", () => { expect(content).toContain("Please analyze this codebase") expect(content).toContain("Build/lint/test commands") expect(content).toContain("Code style guidelines") - expect(content).toContain("mode-specific rule directories") - expect(content).toContain("analysis_workflow") + expect(content).toContain("non-obvious") + expect(content).toContain("discovered by reading files") // Should mention important concepts expect(content).toContain("AGENTS.md") diff --git a/src/services/command/built-in-commands.ts b/src/services/command/built-in-commands.ts index f3c823bac2..db113c4895 100644 --- a/src/services/command/built-in-commands.ts +++ b/src/services/command/built-in-commands.ts @@ -18,24 +18,48 @@ Please analyze this codebase and create an AGENTS.md file containing: - - Create (or update) a concise AGENTS.md file that enables immediate productivity for AI assistants. - Focus on project-specific, non-obvious information. Prioritize brevity and scannability. - - Usage notes: - - The file you create will be given to agentic coding agents (such as yourself) that operate in this repository - - Keep the main AGENTS.md concise - aim for about 20 lines, but use more if the project complexity requires it - - If there's already an AGENTS.md, improve it - - If there are Claude Code rules (in CLAUDE.md), Cursor rules (in .cursor/rules/ or .cursorrules), or Copilot rules (in .github/copilot-instructions.md), make sure to include them - - Be sure to prefix the file with: "# AGENTS.md\\n\\nThis file provides guidance to agents when working with code in this repository." - + + Create (or update) a concise AGENTS.md file that enables immediate productivity for AI assistants. + Focus ONLY on project-specific, non-obvious information that you had to discover by reading files. + + CRITICAL: Only include information that is: + - Non-obvious (couldn't be guessed from standard practices) + - Project-specific (not generic to the framework/language) + - Discovered by reading files (config files, code patterns, custom utilities) + - Essential for avoiding mistakes or following project conventions + + Usage notes: + - The file you create will be given to agentic coding agents (such as yourself) that operate in this repository + - Keep the main AGENTS.md concise - aim for about 20 lines, but use more if the project complexity requires it + - If there's already an AGENTS.md, improve it + - If there are Claude Code rules (in CLAUDE.md), Cursor rules (in .cursor/rules/ or .cursorrules), or Copilot rules (in .github/copilot-instructions.md), make sure to include them + - Be sure to prefix the file with: "# AGENTS.md\\n\\nThis file provides guidance to agents when working with code in this repository." + If the update_todo_list tool is available, create a todo list with these focused analysis steps: - 1. Quick scan for existing docs - - AI assistant rules (.cursorrules, CLAUDE.md, AGENTS.md, .roorules) - - README and key documentation + 1. Check for existing AGENTS.md files + CRITICAL - Check these EXACT paths IN THE PROJECT ROOT: + - AGENTS.md (in project root directory) + - .roo/rules-code/AGENTS.md (relative to project root) + - .roo/rules-debug/AGENTS.md (relative to project root) + - .roo/rules-ask/AGENTS.md (relative to project root) + - .roo/rules-architect/AGENTS.md (relative to project root) + + IMPORTANT: All paths are relative to the project/workspace root, NOT system root! + + If ANY of these exist: + - Read them thoroughly + - CRITICALLY EVALUATE: Remove ALL obvious information + - DELETE entries that are standard practice or framework defaults + - REMOVE anything that could be guessed without reading files + - Only KEEP truly non-obvious, project-specific discoveries + - Then add any new non-obvious patterns you discover + + Also check for other AI assistant rules: + - .cursorrules, CLAUDE.md, .roorules + - .cursor/rules/, .github/copilot-instructions.md 2. Identify stack - Language, framework, build tools @@ -50,8 +74,9 @@ Please analyze this codebase and create an AGENTS.md file containing: - Key entry points 5. Document critical patterns - - Project-specific utilities - - Non-standard approaches + - Project-specific utilities (that you discovered by reading code) + - Non-standard approaches (that differ from typical patterns) + - Custom conventions (that aren't obvious from file structure) 6. Extract code style - From config files only @@ -61,16 +86,16 @@ Please analyze this codebase and create an AGENTS.md file containing: - Framework and run commands - Directory requirements - 8. Compile concise AGENTS.md - - Essential sections only - - Brief, scannable format - - Project-specific focus - - 9. Create mode-specific rule directories - - Create directory structures for the four core modes: .roo/rules-code/, .roo/rules-ask/, .roo/rules-architect/, .roo/rules-debug/ - - Create mode-specific AGENTS.md files with rules specific to that mode's purpose and capabilities - - These rules should provide additive context and not just repeat the mode definitions - - Only include rules that you have high confidence are accurate, valuable, and non-obvious + 8. Compile/Update AGENTS.md files + - If files exist: AGGRESSIVELY clean them up + * DELETE all obvious information (even if it was there before) + * REMOVE standard practices, framework defaults, common patterns + * STRIP OUT anything derivable from file structure or names + * ONLY KEEP truly non-obvious discoveries + * Then add newly discovered non-obvious patterns + * Result should be SHORTER and MORE FOCUSED than before + - If creating new: Follow the non-obvious-only principle + - Create mode-specific files in .roo/rules-*/ directories (IN PROJECT ROOT) Note: If update_todo_list is not available, proceed with the analysis workflow directly without creating a todo list. @@ -79,7 +104,25 @@ Please analyze this codebase and create an AGENTS.md file containing: Follow the comprehensive analysis workflow to: - 1. **Discovery Phase**: Find existing documentation and AI assistant rules + 1. **Discovery Phase**: + CRITICAL - First check for existing AGENTS.md files at these EXACT locations IN PROJECT ROOT: + - AGENTS.md (in project/workspace root) + - .roo/rules-code/AGENTS.md (relative to project root) + - .roo/rules-debug/AGENTS.md (relative to project root) + - .roo/rules-ask/AGENTS.md (relative to project root) + - .roo/rules-architect/AGENTS.md (relative to project root) + + IMPORTANT: The .roo folder should be created in the PROJECT ROOT, not system root! + + If found, perform CRITICAL analysis: + - What information is OBVIOUS and must be DELETED? + - What violates the non-obvious-only principle? + - What would an experienced developer already know? + - DELETE first, then consider what to add + - The file should get SHORTER, not longer + + Also find other AI assistant rules and documentation + 2. **Project Identification**: Identify language, stack, and build system 3. **Command Extraction**: Extract and verify essential commands 4. **Architecture Mapping**: Create visual flow diagrams of core processes @@ -93,128 +136,150 @@ Please analyze this codebase and create an AGENTS.md file containing: - Create AGENTS.md with: + Create or deeply improve AGENTS.md with ONLY non-obvious information: + + If AGENTS.md exists: + - FIRST: Delete ALL obvious information + - REMOVE: Standard commands, framework defaults, common patterns + - STRIP: Anything that doesn't require file reading to know + - EVALUATE: Each line - would an experienced dev be surprised? + - If not surprised, DELETE IT + - THEN: Add only truly non-obvious new discoveries + - Goal: File should be SHORTER and MORE VALUABLE + + Content should include: - Header: "# AGENTS.md\\n\\nThis file provides guidance to agents when working with code in this repository." - - Project overview (brief description, core functionality, key technologies) - - Build/lint/test commands - especially for running a single test - - Code style guidelines including imports, formatting, types, naming conventions, error handling, etc. - - Architecture overview (visual flow diagrams using ASCII/markdown) - - Development guides (step-by-step for common tasks) - - Project-specific patterns (custom utilities, non-standard approaches) - - Testing guidelines (how to write and run tests) - - Critical rules (must-follow requirements) + - Build/lint/test commands - ONLY if they differ from standard package.json scripts + - Code style - ONLY project-specific rules not covered by linter configs + - Custom utilities or patterns discovered by reading the code + - Non-standard directory structures or file organizations + - Project-specific conventions that violate typical practices + - Critical gotchas that would cause errors if not followed + + EXCLUDE obvious information like: + - Standard npm/yarn commands visible in package.json + - Framework defaults (e.g., "React uses JSX") + - Common patterns (e.g., "tests go in __tests__ folders") + - Information derivable from file extensions or directory names - Keep it concise (aim for ~20 lines, but expand as needed for complex projects) and focused on essential, project-specific information. + Keep it concise (aim for ~20 lines, but expand as needed for complex projects). Include existing AI assistant rules from CLAUDE.md, Cursor rules (.cursor/rules/ or .cursorrules), or Copilot rules (.github/copilot-instructions.md). - Additionally, create mode-specific rule directories and AGENTS.md files. - For the complete list of available modes with detailed descriptions, refer to the system prompt. - The system prompt contains comprehensive information about each mode's purpose, when to use it, and its specific capabilities. + Create or deeply improve mode-specific AGENTS.md files IN THE PROJECT ROOT. + + CRITICAL: For each of these paths (RELATIVE TO PROJECT ROOT), check if the file exists FIRST: + - .roo/rules-code/AGENTS.md (create .roo in project root, not system root!) + - .roo/rules-debug/AGENTS.md (relative to project root) + - .roo/rules-ask/AGENTS.md (relative to project root) + - .roo/rules-architect/AGENTS.md (relative to project root) - Example structure: + IMPORTANT: The .roo directory must be created in the current project/workspace root directory, + NOT at the system root (/) or home directory. All paths are relative to where the project is located. + + If files exist: + - AGGRESSIVELY DELETE obvious information + - Remove EVERYTHING that's standard practice + - Strip out framework defaults and common patterns + - Each remaining line must be surprising/non-obvious + - Only then add new non-obvious discoveries + - Files should become SHORTER, not longer + + Example structure (ALL IN PROJECT ROOT): \`\`\` - AGENTS.md # General project guidance - .roo/ - ├── rules-code/ - │ └── AGENTS.md # Code mode specific instructions - ├── rules-debug/ - │ └── AGENTS.md # Debug mode specific instructions - ├── rules-ask/ - │ └── AGENTS.md # Ask mode specific instructions - └── rules-architect/ - └── AGENTS.md # Architect mode specific instructions + project-root/ + ├── AGENTS.md # General project guidance + ├── .roo/ # IN PROJECT ROOT, NOT SYSTEM ROOT! + │ ├── rules-code/ + │ │ └── AGENTS.md # Code mode specific instructions + │ ├── rules-debug/ + │ │ └── AGENTS.md # Debug mode specific instructions + │ ├── rules-ask/ + │ │ └── AGENTS.md # Ask mode specific instructions + │ └── rules-architect/ + │ └── AGENTS.md # Architect mode specific instructions + ├── src/ + ├── package.json + └── ... other project files \`\`\` - Create mode-specific AGENTS.md files in: - - .roo/rules-code/AGENTS.md - Project-specific coding rules: - - Custom utilities that must be used - - API patterns and retry mechanisms - - UI component guidelines - - Database query patterns - - Provider implementation requirements - - Test coverage requirements + .roo/rules-code/AGENTS.md - ONLY non-obvious coding rules discovered by reading files: + - Custom utilities that replace standard approaches + - Non-standard patterns unique to this project + - Hidden dependencies or coupling between components + - Required import orders or naming conventions not enforced by linters - Example of actual rules to document: + Example of non-obvious rules worth documenting: \`\`\` - # Project Coding Rules - - All API calls must use the retry mechanism in src/api/providers/utils/ - - UI components should use Tailwind CSS classes, not inline styles - - New providers must implement the Provider interface in packages/types/src/ - - Database queries must use the query builder in packages/evals/src/db/queries/ - - Always use safeWriteJson() from src/utils/ instead of JSON.stringify for file writes - - Test coverage required for all new features in src/ and webview-ui/ + # Project Coding Rules (Non-Obvious Only) + - Always use safeWriteJson() from src/utils/ instead of JSON.stringify for file writes (prevents corruption) + - API retry mechanism in src/api/providers/utils/ is mandatory (not optional as it appears) + - Database queries MUST use the query builder in packages/evals/src/db/queries/ (raw SQL will fail) + - Provider interface in packages/types/src/ has undocumented required methods + - Test files must be in same directory as source for vitest to work (not in separate test folder) \`\`\` - .roo/rules-debug/AGENTS.md - Project-specific debugging approaches: - - Where to find logs and debug output - - Common debugging tools and commands - - Test patterns for reproducing issues - - Database and migration debugging - - IPC and communication debugging - - Build-specific debugging tips + .roo/rules-debug/AGENTS.md - ONLY non-obvious debugging discoveries: + - Hidden log locations not mentioned in docs + - Non-standard debugging tools or flags + - Gotchas that cause silent failures + - Required environment variables for debugging - Example of actual rules to document: + Example of non-obvious debug rules worth documenting: \`\`\` - # Project Debug Rules - - Check VSCode extension logs in the Debug Console - - For webview issues, inspect the webview dev tools via Command Palette - - Provider issues: check src/api/providers/__tests__/ for similar test patterns - - Database issues: run migrations in packages/evals/src/db/migrations/ - - IPC communication issues: review packages/ipc/src/ message patterns - - Always reproduce in both development and production extension builds + # Project Debug Rules (Non-Obvious Only) + - Webview dev tools accessed via Command Palette > "Developer: Open Webview Developer Tools" (not F12) + - IPC messages fail silently if not wrapped in try/catch in packages/ipc/src/ + - Production builds require NODE_ENV=production or certain features break without error + - Database migrations must run from packages/evals/ directory, not root + - Extension logs only visible in "Extension Host" output channel, not Debug Console \`\`\` - .roo/rules-ask/AGENTS.md - Project documentation context: - - Repository structure explanation - - Where to find examples and patterns - - Key documentation locations - - Build and test command references - - Localization and i18n patterns - - Architecture-specific explanations + .roo/rules-ask/AGENTS.md - ONLY non-obvious documentation context: + - Hidden or misnamed documentation + - Counterintuitive code organization + - Misleading folder names or structures + - Important context not evident from file structure - Example of actual rules to document: + Example of non-obvious documentation rules worth documenting: \`\`\` - # Project Documentation Rules - - Reference the monorepo structure: src/ (VSCode extension), apps/ (web apps), packages/ (shared) - - Explain provider patterns by referencing existing ones in src/api/providers/ - - For UI questions, reference webview-ui/ React components and their patterns - - Point to package.json scripts for build/test commands - - Reference locales/ for i18n patterns when discussing translations - - Always mention the VSCode webview architecture when discussing UI + # Project Documentation Rules (Non-Obvious Only) + - "src/" contains VSCode extension code, not source for web apps (counterintuitive) + - Provider examples in src/api/providers/ are the canonical reference (docs are outdated) + - UI runs in VSCode webview with restrictions (no localStorage, limited APIs) + - Package.json scripts must be run from specific directories, not root + - Locales in root are for extension, webview-ui/src/i18n for UI (two separate systems) \`\`\` - .roo/rules-architect/AGENTS.md - Project architectural considerations: - - Extension and plugin architecture - - State management patterns - - Database schema requirements - - Package organization rules - - API compatibility requirements - - Performance and scaling considerations + .roo/rules-architect/AGENTS.md - ONLY non-obvious architectural constraints: + - Hidden coupling between components + - Undocumented architectural decisions + - Non-standard patterns that must be followed + - Performance bottlenecks discovered through investigation - Example of actual rules to document: + Example of non-obvious architecture rules worth documenting: \`\`\` - # Project Architecture Rules - - New features must work within VSCode extension + webview architecture - - Provider implementations must be stateless and cacheable - - UI state management uses React hooks, not external state libraries - - Database schema changes require migrations in packages/evals/src/db/migrations/ - - New packages must follow the existing monorepo structure in packages/ - - API changes must maintain backward compatibility with existing provider contracts + # Project Architecture Rules (Non-Obvious Only) + - Providers MUST be stateless - hidden caching layer assumes this + - Webview and extension communicate through specific IPC channel patterns only + - Database migrations cannot be rolled back - forward-only by design + - React hooks required because external state libraries break webview isolation + - Monorepo packages have circular dependency on types package (intentional) \`\`\` - - Include visual flow diagrams (ASCII/markdown) for architecture - - Provide actionable, step-by-step guides - - Focus on non-obvious, project-specific information - - Include real code examples from the project - - Be concise and scannable - - Adapt to the specific project needs - - Document only what's essential for productivity + - ONLY include non-obvious information discovered by reading files + - Exclude anything that could be guessed from standard practices + - Focus on gotchas, hidden requirements, and counterintuitive patterns + - Include specific file paths when referencing custom utilities + - Be extremely concise - if it's obvious, don't include it + - Every line should prevent a potential mistake or confusion + - Test: Would an experienced developer be surprised by this information? + - If updating existing files: DELETE obvious info first, files should get SHORTER + - Measure success: Is the file more concise and valuable than before? Remember: The goal is to create documentation that enables AI assistants to be immediately productive in this codebase, focusing on project-specific knowledge that isn't obvious from the code structure alone.`,