From b9c00f21fbc3d53dd9d13774dcf8b0a9cfd4751d Mon Sep 17 00:00:00 2001
From: Eric Wheeler <roo-code@z.ewheeler.org>
Date: Tue, 3 Jun 2025 15:07:56 -0700
Subject: [PATCH 1/2] docs: add monorepo management rules

Add comprehensive documentation for monorepo structure and workflows:
- Workspace organization and primary development areas
- Package dependency management with pnpm
- Turborepo configuration guidelines
- Test execution strategies for both vitest and jest
- Migration path from deprecated test formats to modern ones

Fixes: #4295
Signed-off-by: Eric Wheeler <roo-code@z.ewheeler.org>
---
 .roo/rules/monorepo.md | 51 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 .roo/rules/monorepo.md

diff --git a/.roo/rules/monorepo.md b/.roo/rules/monorepo.md
new file mode 100644
index 0000000000..77ca9c6e20
--- /dev/null
+++ b/.roo/rules/monorepo.md
@@ -0,0 +1,51 @@
+# Monorepo (pnpm)
+
+- Work primarily in:  
+  • src/  
+  • webview-ui/package  
+  • packages/types (shared DTOs)
+- Other workspaces (modify only if instructed):  
+  • evals/  
+  • packages/_/  
+  • apps/_/  
+  • [others]
+- To install deps:  
+  → run `pnpm add <package>` in `<cwd>workspace/directory</cwd>` (updates `<workspace>/package.json`)
+- ⚠️ DO NOT run pnpm in root (root only holds CLI dev-tools in devDependencies, e.g. prettier)
+
+# Turborepo
+
+- ❌ Don’t modify `turbo` config without instruction
+- ✅ You may propose config changes when:
+    1. Adding a shared, cacheable npm task
+    2. Declaring an internal-package dependency that affects the extension build
+
+# Running tests
+
+- Always execute commands using `<cwd>workspace/directory</cwd>` when running any test command
+- To fix failures:
+    1. Target one failing test:  
+       → `npx vitest relative/path/__tests__/name.spec.ts -t "substring"`
+    2. Verify all tests in that module pass:  
+       → `npx vitest relative/path/__tests__/name.spec.ts`
+- File conventions:  
+  • `.spec.ts` → vitest  
+  • `.test.ts` → jest (deprecated)
+- If a test in `.test.ts` fails:  
+  → delete it & recreate in `.spec.ts`
+- Keep passing tests in `.test.ts`
+- Use `npx jest <file> -t "substring"` for deprecated test execution using the same strategy above
+- Run all tests in the root workspace:  
+  → `pnpm test`
+
+# Creating tests
+
+- Use vitest (native ESM, jest-compatible)
+- Steps:
+    1. Create `path/to/__tests__/name.spec.ts` (must be `.spec.ts`)
+    2. Omit ESM mocks unless necessary
+    3. Run via vitest
+- For modules with existing `.test.ts`:
+    1. Move any failing tests → `name.spec.ts`
+    2. Add new tests → `name.spec.ts`
+    3. Leave successful tests in `.test.ts`

From 7d1edb290ac345197f7682ea16aaea7ce7cd0151 Mon Sep 17 00:00:00 2001
From: Eric Wheeler <roo-code@z.ewheeler.org>
Date: Tue, 3 Jun 2025 15:39:48 -0700
Subject: [PATCH 2/2] docs: add workspace command execution guidelines

Add a new section to monorepo documentation that clarifies how to execute
commands in specific workspaces using the cwd parameter.

This helps models understand the importance of specifying the correct
workspace context when running commands in the monorepo structure.

Fixes: #4298
Signed-off-by: Eric Wheeler <roo-code@z.ewheeler.org>
---
 .roo/rules/monorepo.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.roo/rules/monorepo.md b/.roo/rules/monorepo.md
index 77ca9c6e20..be19393a6b 100644
--- a/.roo/rules/monorepo.md
+++ b/.roo/rules/monorepo.md
@@ -49,3 +49,7 @@
     1. Move any failing tests → `name.spec.ts`
     2. Add new tests → `name.spec.ts`
     3. Leave successful tests in `.test.ts`
+
+# Executing package specific commands
+
+Any time you are using a workspace to run commands, you must always specify `<cwd>workspace/directory</cwd>`