From 9847080e329ab1c370bb1317ba6d0ef741584d79 Mon Sep 17 00:00:00 2001 From: Hannes Rudolph Date: Mon, 25 Aug 2025 15:51:36 -0600 Subject: [PATCH 1/6] feat: update /init command to focus only on non-obvious discoveries - Emphasize that only non-obvious information discovered by reading files should be included - Update all mode-specific examples to show truly non-obvious rules - Add CRITICAL section explaining what qualifies as non-obvious - Exclude standard patterns and framework defaults - Focus on gotchas, hidden requirements, and counterintuitive patterns --- src/services/command/built-in-commands.ts | 179 +++++++++++----------- 1 file changed, 89 insertions(+), 90 deletions(-) diff --git a/src/services/command/built-in-commands.ts b/src/services/command/built-in-commands.ts index f3c823bac2..664649c4ac 100644 --- a/src/services/command/built-in-commands.ts +++ b/src/services/command/built-in-commands.ts @@ -18,17 +18,23 @@ 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: @@ -50,8 +56,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 @@ -93,18 +100,22 @@ Please analyze this codebase and create an AGENTS.md file containing: - Create AGENTS.md with: + Create AGENTS.md with ONLY non-obvious information: - 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). @@ -129,92 +140,80 @@ Please analyze this codebase and create an AGENTS.md file containing: 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? 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.`, From 1a46dc97ef0b36a60c229529f073c14c36365d31 Mon Sep 17 00:00:00 2001 From: Hannes Rudolph Date: Mon, 25 Aug 2025 16:00:35 -0600 Subject: [PATCH 2/6] fix: ensure /init command checks for and updates existing AGENTS.md files - Check for existing AGENTS.md in root directory - Check for existing AGENTS.md in all .roo/rules-*/ directories - Read and improve existing files rather than replacing them - Update discovery phase to explicitly look for these files --- src/services/command/built-in-commands.ts | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/src/services/command/built-in-commands.ts b/src/services/command/built-in-commands.ts index 664649c4ac..e68c34bdc5 100644 --- a/src/services/command/built-in-commands.ts +++ b/src/services/command/built-in-commands.ts @@ -41,6 +41,8 @@ Please analyze this codebase and create an AGENTS.md file containing: 1. Quick scan for existing docs - AI assistant rules (.cursorrules, CLAUDE.md, AGENTS.md, .roorules) + - Check for existing AGENTS.md in root directory + - Check for existing AGENTS.md in .roo/rules-code/, .roo/rules-debug/, .roo/rules-ask/, .roo/rules-architect/ - README and key documentation 2. Identify stack @@ -87,6 +89,9 @@ 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 + - Check for existing AGENTS.md in root directory + - Check for existing AGENTS.md files in .roo/rules-*/ directories + - If found, read and improve them rather than replacing 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 @@ -100,7 +105,8 @@ Please analyze this codebase and create an AGENTS.md file containing: - Create AGENTS.md with ONLY non-obvious information: + Create or update AGENTS.md with ONLY non-obvious information: + - If AGENTS.md exists, read it first and improve/update it - Header: "# AGENTS.md\\n\\nThis file provides guidance to agents when working with code in this repository." - Build/lint/test commands - ONLY if they differ from standard package.json scripts - Code style - ONLY project-specific rules not covered by linter configs @@ -138,9 +144,11 @@ Please analyze this codebase and create an AGENTS.md file containing: └── AGENTS.md # Architect mode specific instructions \`\`\` - Create mode-specific AGENTS.md files in: + Create or update mode-specific AGENTS.md files in: .roo/rules-code/AGENTS.md - ONLY non-obvious coding rules discovered by reading files: + - Check if this file already exists and read it first + - Improve and update existing content rather than replacing - Custom utilities that replace standard approaches - Non-standard patterns unique to this project - Hidden dependencies or coupling between components @@ -157,6 +165,8 @@ Please analyze this codebase and create an AGENTS.md file containing: \`\`\` .roo/rules-debug/AGENTS.md - ONLY non-obvious debugging discoveries: + - Check if this file already exists and read it first + - Improve and update existing content rather than replacing - Hidden log locations not mentioned in docs - Non-standard debugging tools or flags - Gotchas that cause silent failures @@ -173,6 +183,8 @@ Please analyze this codebase and create an AGENTS.md file containing: \`\`\` .roo/rules-ask/AGENTS.md - ONLY non-obvious documentation context: + - Check if this file already exists and read it first + - Improve and update existing content rather than replacing - Hidden or misnamed documentation - Counterintuitive code organization - Misleading folder names or structures @@ -189,6 +201,8 @@ Please analyze this codebase and create an AGENTS.md file containing: \`\`\` .roo/rules-architect/AGENTS.md - ONLY non-obvious architectural constraints: + - Check if this file already exists and read it first + - Improve and update existing content rather than replacing - Hidden coupling between components - Undocumented architectural decisions - Non-standard patterns that must be followed From 9993247692e2e8353a0af4a10afaa067fb06c0b1 Mon Sep 17 00:00:00 2001 From: Hannes Rudolph Date: Mon, 25 Aug 2025 16:19:58 -0600 Subject: [PATCH 3/6] refactor: clean up /init command to properly handle existing AGENTS.md files - Consolidate all AGENTS.md path checking into step 1 with CRITICAL emphasis - Add explicit instructions for deep dive improvement of existing files - Remove redundant mentions throughout the workflow - Emphasize iterating and enhancing existing files, not just appending - Add clear guidance on cleaning up outdated info and reorganizing - Make discovery phase the single source of truth for file checking --- src/services/command/built-in-commands.ts | 100 ++++++++++++++-------- 1 file changed, 66 insertions(+), 34 deletions(-) diff --git a/src/services/command/built-in-commands.ts b/src/services/command/built-in-commands.ts index e68c34bdc5..a916239370 100644 --- a/src/services/command/built-in-commands.ts +++ b/src/services/command/built-in-commands.ts @@ -39,11 +39,23 @@ Please analyze this codebase and create an AGENTS.md file containing: 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) - - Check for existing AGENTS.md in root directory - - Check for existing AGENTS.md in .roo/rules-code/, .roo/rules-debug/, .roo/rules-ask/, .roo/rules-architect/ - - README and key documentation + 1. Check for existing AGENTS.md files + CRITICAL - Check these EXACT paths: + - ./AGENTS.md (root directory) + - ./.roo/rules-code/AGENTS.md + - ./.roo/rules-debug/AGENTS.md + - ./.roo/rules-ask/AGENTS.md + - ./.roo/rules-architect/AGENTS.md + + If ANY of these exist: + - Read them thoroughly + - Analyze what's already documented + - Plan improvements: what to add, update, or clean up + - Focus on iterating and enhancing, not replacing + + Also check for other AI assistant rules: + - .cursorrules, CLAUDE.md, .roorules + - .cursor/rules/, .github/copilot-instructions.md 2. Identify stack - Language, framework, build tools @@ -70,16 +82,14 @@ 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: Deep dive into improving them + * Clean up outdated information + * Add newly discovered non-obvious patterns + * Reorganize for better clarity + * Ensure consistency across all files + - If creating new: Follow the non-obvious-only principle + - Create mode-specific files in .roo/rules-*/ directories Note: If update_todo_list is not available, proceed with the analysis workflow directly without creating a todo list. @@ -88,10 +98,22 @@ 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 - - Check for existing AGENTS.md in root directory - - Check for existing AGENTS.md files in .roo/rules-*/ directories - - If found, read and improve them rather than replacing + 1. **Discovery Phase**: + CRITICAL - First check for existing AGENTS.md files at these EXACT locations: + - ./AGENTS.md (root) + - ./.roo/rules-code/AGENTS.md + - ./.roo/rules-debug/AGENTS.md + - ./.roo/rules-ask/AGENTS.md + - ./.roo/rules-architect/AGENTS.md + + If found, perform deep analysis: + - What information is already captured? + - What's outdated or incorrect? + - What non-obvious patterns are missing? + - How can the organization be improved? + + 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 @@ -105,8 +127,16 @@ Please analyze this codebase and create an AGENTS.md file containing: - Create or update AGENTS.md with ONLY non-obvious information: - - If AGENTS.md exists, read it first and improve/update it + Create or deeply improve AGENTS.md with ONLY non-obvious information: + + If AGENTS.md exists: + - Perform thorough review and enhancement + - Clean up any outdated or obvious information + - Add newly discovered non-obvious patterns + - Improve organization and clarity + - Ensure it follows the non-obvious-only principle + + Content should include: - Header: "# AGENTS.md\\n\\nThis file provides guidance to agents when working with code in this repository." - Build/lint/test commands - ONLY if they differ from standard package.json scripts - Code style - ONLY project-specific rules not covered by linter configs @@ -126,9 +156,20 @@ Please analyze this codebase and create an AGENTS.md file containing: - 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. + + CRITICAL: For each of these paths, check if the file exists FIRST: + - ./.roo/rules-code/AGENTS.md + - ./.roo/rules-debug/AGENTS.md + - ./.roo/rules-ask/AGENTS.md + - ./.roo/rules-architect/AGENTS.md + + If files exist: + - Perform deep analysis and improvement + - Clean up redundant or obvious information + - Add new non-obvious discoveries + - Ensure consistency with main AGENTS.md + - Reorganize for better clarity Example structure: \`\`\` @@ -144,11 +185,7 @@ Please analyze this codebase and create an AGENTS.md file containing: └── AGENTS.md # Architect mode specific instructions \`\`\` - Create or update mode-specific AGENTS.md files in: - .roo/rules-code/AGENTS.md - ONLY non-obvious coding rules discovered by reading files: - - Check if this file already exists and read it first - - Improve and update existing content rather than replacing - Custom utilities that replace standard approaches - Non-standard patterns unique to this project - Hidden dependencies or coupling between components @@ -165,8 +202,6 @@ Please analyze this codebase and create an AGENTS.md file containing: \`\`\` .roo/rules-debug/AGENTS.md - ONLY non-obvious debugging discoveries: - - Check if this file already exists and read it first - - Improve and update existing content rather than replacing - Hidden log locations not mentioned in docs - Non-standard debugging tools or flags - Gotchas that cause silent failures @@ -183,8 +218,6 @@ Please analyze this codebase and create an AGENTS.md file containing: \`\`\` .roo/rules-ask/AGENTS.md - ONLY non-obvious documentation context: - - Check if this file already exists and read it first - - Improve and update existing content rather than replacing - Hidden or misnamed documentation - Counterintuitive code organization - Misleading folder names or structures @@ -201,8 +234,6 @@ Please analyze this codebase and create an AGENTS.md file containing: \`\`\` .roo/rules-architect/AGENTS.md - ONLY non-obvious architectural constraints: - - Check if this file already exists and read it first - - Improve and update existing content rather than replacing - Hidden coupling between components - Undocumented architectural decisions - Non-standard patterns that must be followed @@ -228,6 +259,7 @@ Please analyze this codebase and create an AGENTS.md file containing: - 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: Ensure deep improvement, not just appending 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.`, From ff25da0fd28b9e209860abaf181f8183c5f40afc Mon Sep 17 00:00:00 2001 From: Hannes Rudolph Date: Mon, 25 Aug 2025 16:29:02 -0600 Subject: [PATCH 4/6] fix: strengthen /init command to aggressively remove obvious information - Add explicit instructions to DELETE obvious information first - Emphasize that files should get SHORTER, not longer - Use stronger language: CRITICALLY EVALUATE, AGGRESSIVELY DELETE - Make clear that standard practices must be removed even if previously included - Add success metric: files should be more concise and valuable - Goal is to fix the tendency to just append instead of clean up --- src/services/command/built-in-commands.ts | 57 +++++++++++++---------- 1 file changed, 33 insertions(+), 24 deletions(-) diff --git a/src/services/command/built-in-commands.ts b/src/services/command/built-in-commands.ts index a916239370..20fb8c4b2d 100644 --- a/src/services/command/built-in-commands.ts +++ b/src/services/command/built-in-commands.ts @@ -49,9 +49,11 @@ Please analyze this codebase and create an AGENTS.md file containing: If ANY of these exist: - Read them thoroughly - - Analyze what's already documented - - Plan improvements: what to add, update, or clean up - - Focus on iterating and enhancing, not replacing + - 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 @@ -83,11 +85,13 @@ Please analyze this codebase and create an AGENTS.md file containing: - Directory requirements 8. Compile/Update AGENTS.md files - - If files exist: Deep dive into improving them - * Clean up outdated information - * Add newly discovered non-obvious patterns - * Reorganize for better clarity - * Ensure consistency across all 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 @@ -106,11 +110,12 @@ Please analyze this codebase and create an AGENTS.md file containing: - ./.roo/rules-ask/AGENTS.md - ./.roo/rules-architect/AGENTS.md - If found, perform deep analysis: - - What information is already captured? - - What's outdated or incorrect? - - What non-obvious patterns are missing? - - How can the organization be improved? + 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 @@ -130,11 +135,13 @@ Please analyze this codebase and create an AGENTS.md file containing: Create or deeply improve AGENTS.md with ONLY non-obvious information: If AGENTS.md exists: - - Perform thorough review and enhancement - - Clean up any outdated or obvious information - - Add newly discovered non-obvious patterns - - Improve organization and clarity - - Ensure it follows the non-obvious-only principle + - 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." @@ -165,11 +172,12 @@ Please analyze this codebase and create an AGENTS.md file containing: - ./.roo/rules-architect/AGENTS.md If files exist: - - Perform deep analysis and improvement - - Clean up redundant or obvious information - - Add new non-obvious discoveries - - Ensure consistency with main AGENTS.md - - Reorganize for better clarity + - 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: \`\`\` @@ -259,7 +267,8 @@ Please analyze this codebase and create an AGENTS.md file containing: - 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: Ensure deep improvement, not just appending + - 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.`, From a26f659043d7e5f009a9711fdab105b7a2710074 Mon Sep 17 00:00:00 2001 From: Hannes Rudolph Date: Mon, 25 Aug 2025 16:56:38 -0600 Subject: [PATCH 5/6] fix: ensure .roo directory is created in project root, not system root CRITICAL FIX: Paths were being interpreted as absolute, causing .roo to be created at system root - Clarify all paths are relative to PROJECT/WORKSPACE root - Add explicit warnings that .roo must be in project root, not system root - Update example to show proper project structure - Add IMPORTANT notes throughout emphasizing relative paths - Fix prevents accidental creation of /.roo at system level --- src/services/command/built-in-commands.ts | 73 +++++++++++++---------- 1 file changed, 42 insertions(+), 31 deletions(-) diff --git a/src/services/command/built-in-commands.ts b/src/services/command/built-in-commands.ts index 20fb8c4b2d..db113c4895 100644 --- a/src/services/command/built-in-commands.ts +++ b/src/services/command/built-in-commands.ts @@ -40,12 +40,14 @@ Please analyze this codebase and create an AGENTS.md file containing: If the update_todo_list tool is available, create a todo list with these focused analysis steps: 1. Check for existing AGENTS.md files - CRITICAL - Check these EXACT paths: - - ./AGENTS.md (root directory) - - ./.roo/rules-code/AGENTS.md - - ./.roo/rules-debug/AGENTS.md - - ./.roo/rules-ask/AGENTS.md - - ./.roo/rules-architect/AGENTS.md + 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 @@ -93,7 +95,7 @@ Please analyze this codebase and create an AGENTS.md file containing: * 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 + - 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. @@ -102,13 +104,15 @@ Please analyze this codebase and create an AGENTS.md file containing: Follow the comprehensive analysis workflow to: - 1. **Discovery Phase**: - CRITICAL - First check for existing AGENTS.md files at these EXACT locations: - - ./AGENTS.md (root) - - ./.roo/rules-code/AGENTS.md - - ./.roo/rules-debug/AGENTS.md - - ./.roo/rules-ask/AGENTS.md - - ./.roo/rules-architect/AGENTS.md + 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? @@ -163,13 +167,16 @@ Please analyze this codebase and create an AGENTS.md file containing: - Create or deeply improve mode-specific AGENTS.md files. + 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) - CRITICAL: For each of these paths, check if the file exists FIRST: - - ./.roo/rules-code/AGENTS.md - - ./.roo/rules-debug/AGENTS.md - - ./.roo/rules-ask/AGENTS.md - - ./.roo/rules-architect/AGENTS.md + 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 @@ -179,18 +186,22 @@ Please analyze this codebase and create an AGENTS.md file containing: - Only then add new non-obvious discoveries - Files should become SHORTER, not longer - Example structure: + 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 \`\`\` .roo/rules-code/AGENTS.md - ONLY non-obvious coding rules discovered by reading files: From 8bcae24e5e52401aa7f08f5255f7f49b824b9865 Mon Sep 17 00:00:00 2001 From: Hannes Rudolph Date: Mon, 25 Aug 2025 20:51:18 -0600 Subject: [PATCH 6/6] test: update built-in-commands test to match new init command content - Replace 'mode-specific rule directories' with 'non-obvious' - Replace 'analysis_workflow' with 'discovered by reading files' - Tests now align with the new focus on non-obvious discoveries --- src/services/command/__tests__/built-in-commands.spec.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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")