scriptoriumadmin/Roo-Code
1
0
Fork 0
mirror of https://github.com/RooVetGit/Roo-Code.git synced 2026-08-28 05:27:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat: update /init command to focus only on non-obvious discoveries (#7400)

Browse source 
* 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

* 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

* 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

* 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

* 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

* 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
This commit is contained in:
Hannes Rudolph 2025-08-25 21:01:51 -06:00 • committed by GitHub
parent 91f3dd90fb
commit 0cfd314c00
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 188 additions and 123 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
src/services/command/__tests__/built-in-commands.spec.ts
View file

@ -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")

307
src/services/command/built-in-commands.ts
View file

@ -18,24 +18,48 @@ Please analyze this codebase and create an AGENTS.md file containing:
</task>
<initialization>
<purpose>
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."
</purpose>
<purpose>
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."
</purpose>
<todo_list_creation>
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.
</todo_list_creation>
@ -79,7 +104,25 @@ Please analyze this codebase and create an AGENTS.md file containing:
<analysis_workflow>
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:
<output_structure>
<main_file>
Create AGENTS.md with:
- 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)
Create or deeply improve AGENTS.md with ONLY non-obvious information:
Keep it concise (aim for ~20 lines, but expand as needed for complex projects) and focused on essential, project-specific 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."
- 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).
Include existing AI assistant rules from CLAUDE.md, Cursor rules (.cursor/rules/ or .cursorrules), or Copilot rules (.github/copilot-instructions.md).
</main_file>
<mode_specific_files>
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.
Example structure:
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)
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 - 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
.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
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)
\`\`\`
</mode_specific_files>
</output_structure>
<quality_criteria>
- 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?
</quality_criteria>
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.`,