typescript-monorepo

---
name: typescript-monorepo
description: >-
  Guidance for TypeScript monorepos with mixed package managers.
  Use when codebase has inherited package manager and a workspace root.
---

## TypeScript Monorepo Workflow Guidance

### Install Commands
- Workspace-scoped install runs from workspace root, not leaf
- bun: `bun install` at workspace root
- pnpm: `pnpm install` at workspace root
- npm: `npm ci` at workspace root
- working_directory = workspace root (repo-relative)

### Workspace Root Discovery
- If `workspace_root` is present, use it as the direct hint for workspace-owned commands
- If `workspace_root` is missing but provenance is inherited, walk upward from `codebase_path` to find the nearest owning workspace root
- Inspect parent directories one level at a time with absolute paths using `get_directory_tree` and `read_file_content`
- Stop when you find the nearest workspace-owned signals such as `pnpm-workspace.yaml`, a root `package.json` with `workspaces`, a lockfile, `turbo.json`, or `nx.json`
- Do not assume the leaf owns install/build commands just because the exact workspace root was not precomputed

### Build Commands
- Turborepo: `turbo run build` or `bun run build` at workspace root
- Individual: `bun run build --filter <package>` from workspace root
- Check turbo.json or nx.json for build pipeline configuration
- working_directory = workspace root

### Test/Lint/TypeCheck Commands
- Usually leaf-specific: run from codebase root (omit working_directory)
- Some monorepos configure workspace-level lint/test via turbo.json/nx.json
- Inspect the leaf's package.json scripts section for available commands

### Working Directory Rules
- working_directory = workspace root for install/build commands
- working_directory = omit (None) for leaf-local test/lint/type_check
- working_directory = "." when command must run from repository root
- If both workspace-level and leaf-level commands exist for same stage, emit both with distinct working_directory

### Config File Path Rules
- config_file must always be repository-root-relative
- Never use absolute paths in config_file
- Never use codebase-relative `..` segments in config_file
- For workspace-owned configs above the leaf, emit the full repository-root path, for example:
  - `infra/services/turbo.json`
  - `infra/services/pnpm-workspace.yaml`

### Upward Discovery Example
- Given `codebase_path = /opt/unoplat/repositories/acme/infra/services/apps/api` and inherited provenance with no `workspace_root`
- Inspect `/opt/unoplat/repositories/acme/infra/services/apps/api`, then `/opt/unoplat/repositories/acme/infra/services/apps`, then `/opt/unoplat/repositories/acme/infra/services`
- If `/opt/unoplat/repositories/acme/infra/services/pnpm-workspace.yaml` exists, use repo-relative `infra/services` as the workspace root
- Then emit workspace-owned commands like install/build with `working_directory = "infra/services"`

### Package Manager Inheritance
- Leaf inherits manager from nearest workspace aggregator
- Commands use the inherited manager's CLI (bun, pnpm, npm, yarn)
- Lock files live at workspace root, not leaf
- If leaf has its own local manager, provenance=local and no workspace root