add brain

.brain/.agent/skills/engineering-advanced-skills/monorepo-navigator/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: "monorepo-navigator"
+description: "Monorepo Navigator"
+---
+
+# Monorepo Navigator
+
+**Tier:** POWERFUL  
+**Category:** Engineering  
+**Domain:** Monorepo Architecture / Build Systems  
+
+---
+
+## Overview
+
+Navigate, manage, and optimize monorepos. Covers Turborepo, Nx, pnpm workspaces, and Lerna. Enables cross-package impact analysis, selective builds/tests on affected packages only, remote caching, dependency graph visualization, and structured migrations from multi-repo to monorepo. Includes Claude Code configuration for workspace-aware development.
+
+---
+
+## Core Capabilities
+
+- **Cross-package impact analysis** — determine which apps break when a shared package changes
+- **Selective commands** — run tests/builds only for affected packages (not everything)
+- **Dependency graph** — visualize package relationships as Mermaid diagrams
+- **Build optimization** — remote caching, incremental builds, parallel execution
+- **Migration** — step-by-step multi-repo → monorepo with zero history loss
+- **Publishing** — changesets for versioning, pre-release channels, npm publish workflows
+- **Claude Code config** — workspace-aware CLAUDE.md with per-package instructions
+
+---
+
+## When to Use
+
+Use when:
+- Multiple packages/apps share code (UI components, utils, types, API clients)
+- Build times are slow because everything rebuilds when anything changes
+- Migrating from multiple repos to a single repo
+- Need to publish packages to npm with coordinated versioning
+- Teams work across multiple packages and need unified tooling
+
+Skip when:
+- Single-app project with no shared packages
+- Team/project boundaries are completely isolated (polyrepo is fine)
+- Shared code is minimal and copy-paste overhead is acceptable
+
+---
+
+## Tool Selection
+
+| Tool | Best For | Key Feature |
+|---|---|---|
+| **Turborepo** | JS/TS monorepos, simple pipeline config | Best-in-class remote caching, minimal config |
+| **Nx** | Large enterprises, plugin ecosystem | Project graph, code generation, affected commands |
+| **pnpm workspaces** | Workspace protocol, disk efficiency | `workspace:*` for local package refs |
+| **Lerna** | npm publishing, versioning | Batch publishing, conventional commits |
+| **Changesets** | Modern versioning (preferred over Lerna) | Changelog generation, pre-release channels |
+
+Most modern setups: **pnpm workspaces + Turborepo + Changesets**
+
+---
+
+## Turborepo
+→ See references/monorepo-tooling-reference.md for details
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---|---|
+| Running `turbo run build` without `--filter` on every PR | Always use `--filter=...[origin/main]` in CI |
+| `workspace:*` refs cause publish failures | Use `pnpm changeset publish` — it replaces `workspace:*` with real versions automatically |
+| All packages rebuild when unrelated file changes | Tune `inputs` in turbo.json to exclude docs, config files from cache keys |
+| Shared tsconfig causes one package to break all type-checks | Use `extends` properly — each package extends root but overrides `rootDir` / `outDir` |
+| git history lost during migration | Use `git filter-repo --to-subdirectory-filter` before merging — never move files manually |
+| Remote cache not working in CI | Check TURBO_TOKEN and TURBO_TEAM env vars; verify with `turbo run build --summarize` |
+| CLAUDE.md too generic — Claude modifies wrong package | Add explicit "When working on X, only touch files in apps/X" rules per package CLAUDE.md |
+
+---
+
+## Best Practices
+
+1. **Root CLAUDE.md defines the map** — document every package, its purpose, and dependency rules
+2. **Per-package CLAUDE.md defines the rules** — what's allowed, what's forbidden, testing commands
+3. **Always scope commands with --filter** — running everything on every change defeats the purpose
+4. **Remote cache is not optional** — without it, monorepo CI is slower than multi-repo CI
+5. **Changesets over manual versioning** — never hand-edit package.json versions in a monorepo
+6. **Shared configs in root, extended in packages** — tsconfig.base.json, .eslintrc.base.js, jest.base.config.js
+7. **Impact analysis before merging shared package changes** — run affected check, communicate blast radius
+8. **Keep packages/types as pure TypeScript** — no runtime code, no dependencies, fast to build and type-check