Skip to content

Conversation

@mrubens
Copy link
Collaborator

@mrubens mrubens commented Aug 25, 2025

Important

Adds detailed documentation for architecture, documentation, coding, and debugging rules, consolidating them into AGENTS.md.

  • Documentation:
    • Adds .roo/rules-architect/AGENTS.md for architecture rules, emphasizing communication patterns and JSON write safety.
    • Adds .roo/rules-ask/AGENTS.md for documentation rules, detailing project structure and i18n systems.
    • Adds .roo/rules-code/AGENTS.md for coding rules, focusing on file writing and testing structure.
    • Adds .roo/rules-debug/AGENTS.md for debug rules, highlighting logging and migration requirements.
  • Consolidation:
    • Creates AGENTS.md to consolidate critical rules from individual files, covering JSON writes, project structure, testing, build commands, webview restrictions, and code style.

This description was created by Ellipsis for 053e159. You can customize this summary. It will automatically update as commits are pushed.

@mrubens mrubens requested review from cte and jr as code owners August 25, 2025 21:16
@dosubot dosubot bot added size:L This PR changes 100-499 lines, ignoring generated files. documentation Improvements or additions to documentation labels Aug 25, 2025
Copy link
Contributor

@roomote roomote bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your contribution! I've reviewed the changes and this is a good improvement over the previous single rules.md file, providing much better organization and mode-specific guidance. I have some suggestions for improvement.

AGENTS.md Outdated

## Architecture

```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I noticed the architecture section shows a simplified structure. Would it be helpful to also mention other important directories that are part of the monorepo? For example, apps/ (web-roo-code, web-evals, vscode-e2e), locales/, and scripts/ directories?

AGENTS.md Outdated
pnpm build

# Run tests (CRITICAL: run from workspace directory containing package.json)
cd src && npx vitest run tests/user.test.ts # Backend tests
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The test examples are helpful! Could we also show how to run all tests in a directory? For example:

Suggested change
cd src && npx vitest run tests/user.test.ts # Backend tests
# Run tests (CRITICAL: run from workspace directory containing package.json)
cd src && npx vitest run tests/user.test.ts # Specific backend test
cd src && npx vitest run tests/ # All backend tests
cd webview-ui && npx vitest run src/components/Button.test.tsx # Specific UI test
cd webview-ui && npx vitest run # All UI tests


## JSON File Operations

- **MANDATORY**: Use `safeWriteJson()` from `src/utils/safeWriteJson.ts` for ALL JSON writes
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since there's also a use-safeWriteJson.md file in this directory that provides additional context about the safeWriteJson requirement, should we cross-reference it? This could help developers find the detailed usage guidelines more easily.

AGENTS.md Outdated

## Project Overview

Roo Code - AI-powered autonomous coding agent VSCode extension with React webview UI, supporting multiple AI providers and custom modes.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I noticed that the PR adds AGENTS.md files for only 4 modes (architect, ask, code, debug), but there are many other modes in the .roo directory that still use XML format (e.g., issue-fixer, pr-reviewer, integration-tester). Is there a plan to convert all modes to the AGENTS.md format for consistency, or is the XML format intentionally kept for certain modes?

Copy link
Member

@daniel-lxs daniel-lxs left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good overall


## File Restrictions

- Code mode can edit all file types
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is too relevant

AGENTS.md Outdated

## Development

- **Debug**: Press F5 in VSCode to launch extension host
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess this could be useful if users ask the model how to run the extension?

@daniel-lxs daniel-lxs moved this from Triage to PR [Draft / In Progress] in Roo Code Roadmap Aug 25, 2025
- 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.
@dosubot dosubot bot added size:M This PR changes 30-99 lines, ignoring generated files. and removed size:L This PR changes 100-499 lines, ignoring generated files. labels Aug 25, 2025

## Non-Obvious Debug Access

- Webview DevTools: Command Palette → "Developer: Open Webview Developer Tools" (NOT F12)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure how relevant this is for the AI agent

AGENTS.md Outdated
- **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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again not sure if this is relevant

@github-project-automation github-project-automation bot moved this from New to Done in Roo Code Roadmap Sep 23, 2025
@github-project-automation github-project-automation bot moved this from PR [Draft / In Progress] to Done in Roo Code Roadmap Sep 23, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation PR - Draft / In Progress size:M This PR changes 30-99 lines, ignoring generated files.

Projects

Archived in project

Development

Successfully merging this pull request may close these issues.

4 participants