chore: track Nx 22 AI tooling artefacts injected by generators

Nx 22 generators inject AI agent tooling into the repo via marked
sections and side files. Rather than re-deleting them after every
generator run, track the workspace-level ones and document why.

- CLAUDE.md gains a 'General Guidelines for working with Nx' section
  between Nx-managed markers; future Nx versions will update this
  section automatically without touching our project rules above.
  Pre-existing prettier-formatted blank lines added before code blocks
  are kept.
- .claude/settings.json (228 bytes) enables the nx-claude-plugins
  marketplace from nrwl/nx-ai-agents-config; tracked for contributor
  consistency. The personal .claude/settings.local.json stays
  gitignored.
- .github/ is the Nx AI skills/prompts/agents catalog. Kept despite
  being GitHub-named; it does not conflict with our Gitea workflows
  which will live under .gitea/workflows/ (per ADR-0015).
- .gitignore picks up Nx-managed transient dirs (.nx/polygraph,
  .claude/worktrees) and a trailing newline fix.

AGENTS.md is removed: it duplicated only the Nx auto-injected guidance
that CLAUDE.md already carries (CLAUDE.md is the strictly broader file
- project rules + Nx section). One source of truth for AI-agent
guidance.
This commit is contained in:
Julien Gautier
2026-04-30 17:46:04 +02:00
parent 3308fd6071
commit d797becc2b
22 changed files with 3285 additions and 0 deletions
@@ -0,0 +1,127 @@
---
name: link-workspace-packages
description: 'Link workspace packages in monorepos (npm, yarn, pnpm, bun). USE WHEN: (1) you just created or generated new packages and need to wire up their dependencies, (2) user imports from a sibling package and needs to add it as a dependency, (3) you get resolution errors for workspace packages (@org/*) like "cannot find module", "failed to resolve import", "TS2307", or "cannot resolve". DO NOT patch around with tsconfig paths or manual package.json edits - use the package manager''s workspace commands to fix actual linking.'
---
# Link Workspace Packages
Add dependencies between packages in a monorepo. All package managers support workspaces but with different syntax.
## Detect Package Manager
Check whether there's a `packageManager` field in the root-level `package.json`.
Alternatively check lockfile in repo root:
- `pnpm-lock.yaml` → pnpm
- `yarn.lock` → yarn
- `bun.lock` / `bun.lockb` → bun
- `package-lock.json` → npm
## Workflow
1. Identify consumer package (the one importing)
2. Identify provider package(s) (being imported)
3. Add dependency using package manager's workspace syntax
4. Verify symlinks created in consumer's `node_modules/`
---
## pnpm
Uses `workspace:` protocol - symlinks only created when explicitly declared.
```bash
# From consumer directory
pnpm add @org/ui --workspace
# Or with --filter from anywhere
pnpm add @org/ui --filter @org/app --workspace
```
Result in `package.json`:
```json
{ "dependencies": { "@org/ui": "workspace:*" } }
```
---
## yarn (v2+/berry)
Also uses `workspace:` protocol.
```bash
yarn workspace @org/app add @org/ui
```
Result in `package.json`:
```json
{ "dependencies": { "@org/ui": "workspace:^" } }
```
---
## npm
No `workspace:` protocol. npm auto-symlinks workspace packages.
```bash
npm install @org/ui --workspace @org/app
```
Result in `package.json`:
```json
{ "dependencies": { "@org/ui": "*" } }
```
npm resolves to local workspace automatically during install.
---
## bun
Supports `workspace:` protocol (pnpm-compatible).
```bash
cd packages/app && bun add @org/ui
```
Result in `package.json`:
```json
{ "dependencies": { "@org/ui": "workspace:*" } }
```
---
## Examples
**Example 1: pnpm - link ui lib to app**
```bash
pnpm add @org/ui --filter @org/app --workspace
```
**Example 2: npm - link multiple packages**
```bash
npm install @org/data-access @org/ui --workspace @org/dashboard
```
**Example 3: Debug "Cannot find module"**
1. Check if dependency is declared in consumer's `package.json`
2. If not, add it using appropriate command above
3. Run install (`pnpm install`, `npm install`, etc.)
## Notes
- Symlinks appear in `<consumer>/node_modules/@org/<package>`
- **Hoisting differs by manager:**
- npm/bun: hoist shared deps to root `node_modules`
- pnpm: no hoisting (strict isolation, prevents phantom deps)
- yarn berry: uses Plug'n'Play by default (no `node_modules`)
- Root `package.json` should have `"private": true` to prevent accidental publish