Nx Agent Workflow

Principle

AI coding agents should use Nx as the first repo navigation and validation surface for monorepo work.

Discovery

Useful commands:

pnpm nx show projects
pnpm nx show project @prox-os/os-shell
pnpm nx graph
pnpm nx affected -t lint typecheck build --exclude=prox-os

Use nx show project before guessing target names. Use affected when the change is scoped to a branch and the repo is large.

Validation Strategy

For routine changes:

pnpm lint
pnpm typecheck
pnpm arch:check
pnpm check:cjk

For structural changes:

pnpm check:file-size
pnpm nx affected -t lint typecheck build --exclude=prox-os

For broad migrations:

pnpm nx run-many -t lint typecheck --exclude=prox-os
pnpm nx run-many -t build --exclude=prox-os

Agents should report exact commands and failures. A cached Nx success is still a valid success, but the final response should mention that Nx restored or reused cached results when visible.

Multi-agent Branches

When multiple agents work in parallel:

1. Keep changes scoped by package, app, or architecture area.
2. Use pnpm nx affected -t lint typecheck build --exclude=prox-os before handoff.
3. Include affected project names in the summary when relevant.
4. Avoid unrelated root script changes unless the task is a monorepo migration.
5. Do not bypass app contracts or package taxonomy to make a quick task pass.

Non-goals

• Nx does not justify deep imports across package boundaries.
• Nx does not replace dependency-cruiser or security review.
• Nx does not make production deploys safe without explicit human approval.