Picking the Agent Root in a Monorepo

In monorepo agent work, the most common failure is not the model—it is a bad root (cwd) / workspace scope. Agents resolve relative paths, lockfiles, tests, and nested AGENTS.md from “what is the work root right now?” Opening only at the tip invites sibling-package edits; opening only inside one package hides workspace scripts.

Adjacent posts stay on other axes. repo-map-inject is what to put in a terrain map and how to inject it. This post is which cwd / agent root to pick for the session. A correct map still fails if commands run from the wrong directory. No pricing, plans, or affiliate links. Grounded in pnpm Workspaces, npm workspaces, and Cursor Rules / AGENTS.md.

Which cwd?

One-line answer: Default cwd to the package (or app) that owns the change; move up to the repo tip only for cross-package work, root scripts, or workspace installs. Neither “always tip” nor “always package” is correct.

Task	Prefer cwd	Why
Single-package bug, UI, unit tests	`apps/web` or `packages/api`	Relative imports and local `package.json` scripts match
`pnpm --filter` / `turbo run` / Nx targets	Usually repo tip	Workspace definition and pipelines live at tip
Lockfile, root CI, shared tsconfig	Repo tip	Only root files change
Fully split trees (firmware vs host)	That tree’s root	Do not install firmware with the host lockfile
Subagent delegation	Explicit cwd in the brief	Parent at tip, child in a package is fine

Instruction snippet:

Default cwd for this task: <path-from-repo-tip>
Repo tip is only for workspace installs, turbo/nx, and root CI.
Do not cd to sibling packages unless the ticket lists them.
Before running a command, state: cwd=<abs-or-repo-relative> · command=…

Editor / CLI tips:

In Cursor/VS Code, opening a package folder vs opening the monorepo tip is the agent’s default root. With multi-root workspaces, name the active folder in the brief.
Shell agents should report pwd once at session start—do not assume.
Nested AGENTS.md / Project Rules apply cleanly under the opened root. Tip-open can weaken package-local rules; package-open can hide tip rules—@-mention paths when needed (prompt-layers, repo-map-inject).

Session start checklist (agent):
1. pwd / workspace folders
2. Nearest package.json / Cargo.toml / pyproject.toml
3. Is there a workspace root above? (pnpm-workspace.yaml, etc.)
4. Which AGENTS.md applies? (nested vs tip)
5. Confirm allowlist packages before edits

What package scope?

One-line answer: Fix an allowlist of packages the agent may touch and the workspace commands (with filters) to run. Cwd ≠ scope—you can sit at the tip and still forbid packages/legacy.

Slot	Example	Forbidden
Touch	`packages/api/`, `apps/web/src/api/`	“Anything that looks related”
Do not touch	`packages/legacy/`, `firmware/`	Silence
Commands	`pnpm --filter api test` (cwd=tip)	Root `test` with no filter
Install	One tip-level `pnpm install`	Creating a new lockfile inside a package
Shared types	Only if `packages/types` is allowlisted	Quiet API changes to shared packages

Workspace commands vs cwd:

# cwd = repo tip (typical)
pnpm --filter @acme/api test
pnpm --filter web build
npx turbo run test --filter=api

# cwd = packages/api (local scripts only)
pnpm test          # uses this package.json
# Avoid: npm install here if the repo is pnpm-workspace at tip

Instruction snippet:

Package scope for this task:
- Touch: packages/api/**
- Do not touch: apps/**, packages/legacy/**, firmware/**
- Run tests: from repo tip → pnpm --filter @acme/api test
- If you need another package, stop and ask (or open a follow-up)
- Never invent a package name that is not on disk / not in the workspace list

One-line vs repo-map-inject: the map’s Layout/Boundaries are agreed terrain; this section’s allowlist is this session’s execution scope. Reading the map does not auto-fix cwd or filters.

Wrong-root symptoms?

One-line answer: When symptoms appear, verify cwd, workspace, and filters before swapping models. Wrong root looks like “smart hallucination” but is usually path / lockfile / script context.

Symptom	Likely cause	Fix
`command not found` / missing script	Package cwd running tip-only scripts	`cd` to tip, use `--filter`
New `package-lock.json` inside a package	npm at package cwd	Remove; confirm tip pnpm/yarn
Tests green, bug remains	Ran tests in the wrong package	Re-run with allowlisted filter
Import/path hallucinations	Treating the whole tip tree as one app	Own-package cwd; recheck map/tree
Wrong `AGENTS.md` rules	Opened root ≠ nested docs	Name the rule path in the brief
Huge sibling-package diffs	No scope + tip cwd	Do not touch + path allowlist
CI-only failures	Local cwd ≠ CI `working-directory`	Put the same cwd+filter in the Test plan

Recovery loop:

1. Print pwd and workspace root candidates
2. Show nearest package manifest vs workspace definition at tip
3. Re-state Touch / Do not touch
4. Re-run the one command CI uses (same cwd + filter)
5. If still wrong: stop editing; fix root before more patches

Ops tips:

PR Test plans should list cwd + command together (agent-pr-body).
Subagent briefs without a root let children cd arbitrarily even when the parent is at tip (subagent-brief).
“Map looks right but builds fail” → suspect root/filters, not the map—that is this post’s axis.

Bottom line: Own-package cwd by default, tip + filter for workspace commands, allowlist for scope, and on bad symptoms fix the root before the model. repo-map-inject stays on the map-injection axis.

FAQ

Should we always open the agent at the monorepo tip?

You can—if the team is strong on tip rules and filters. Heavy single-package work still pays a tax at tip cwd (sibling exploration, wrong scripts). Default to the owning package; tip is the exception.

How is this different from repo-map-inject?

That post is REPO_MAP content, injection, and refresh. This post is session cwd, workspace root, package allowlist, and wrong-root symptoms. Injecting a map does not fix a bad cwd.

pnpm vs turbo vs Nx—which is the rule?

Follow the team standard. The shared rule is the same: run filtered workspace commands from where the workspace is defined (usually tip), run package-local scripts in that package’s cwd, do not mix lockfile tools.

What about multi-root workspaces?

Put workspace folders: … and the primary folder for this task in the brief. Do not let the agent assume “the first folder is the root.”

Sources

pnpm Workspaces — workspaces, filters, tip installs
npm workspaces — workspace definition and where to run
Cursor Docs — Rules / AGENTS.md — nested project guidance
Adjacent: repo-map-inject (terrain map injection), prompt-layers (rule layers), subagent-brief (cwd in delegation), agent-pr-body (cwd + command in Test plan)