monorepo-manager

What this skill does

# Monorepo Manager

## Overview

Analyze, maintain, and optimize monorepo dependency graphs. Detect version mismatches across packages, sync shared dependencies, configure build pipelines, and resolve workspace conflicts that slow teams down.

## Instructions

### 1. Detect monorepo structure

Identify the monorepo tool in use:
- Check for `pnpm-workspace.yaml` → pnpm workspaces
- Check `package.json` for `"workspaces"` → npm/yarn workspaces
- Check for `turbo.json` → Turborepo
- Check for `nx.json` → Nx
- Check for `lerna.json` → Lerna (legacy)

Map all packages:
```
Monorepo: pnpm workspaces + Turborepo
Packages (14):
  apps/
    web          → Next.js 14 app
    api          → Express server
    admin        → React admin panel
  packages/
    ui           → Shared component library
    config       → ESLint/TS configs
    database     → Prisma schema + client
    utils        → Shared utilities
    types        → TypeScript type definitions
```

### 2. Audit dependency versions

Scan all package.json files and flag mismatches:
```
## Dependency Version Mismatches

| Package    | apps/web | apps/api | apps/admin | packages/ui |
|------------|----------|----------|------------|-------------|
| react      | 18.3.1   | —        | 18.2.0 ⚠️  | 18.3.1      |
| typescript | 5.4.2    | 5.3.3 ⚠️ | 5.4.2      | 5.4.2       |
| zod        | 3.22.4   | 3.21.1 ⚠️| —          | —           |

3 mismatches found across 14 packages.
```

### 3. Resolve conflicts

For each mismatch, recommend and apply fixes:
- Identify which version to standardize on (usually latest)
- Check for breaking changes between versions
- Update all package.json files
- Run the appropriate install command
- Verify build still passes

### 4. Analyze internal dependency graph

Map which packages depend on which:
```
packages/types ← packages/utils ← packages/ui ← apps/web
                                                ← apps/admin
               ← packages/database ← apps/api
```

Flag circular dependencies and suggest extraction points.

### 5. Optimize build configuration

For Turborepo/Nx, ensure:
- Build tasks declare correct `dependsOn` relationships
- Caching is configured for all cacheable tasks
- Only affected packages rebuild on changes
- CI pipeline uses remote caching

## Examples

### Example 1: Sync React versions

**Input:** "Our monorepo has 6 apps using different React versions. Sync them all."

**Output:**
```
Found React version mismatches:

| Package       | Current | Target |
|---------------|---------|--------|
| apps/web      | 18.3.1  | 18.3.1 ✅ |
| apps/admin    | 18.2.0  | 18.3.1 ⬆️ |
| apps/mobile   | 18.2.0  | 18.3.1 ⬆️ |
| packages/ui   | 18.3.1  | 18.3.1 ✅ |

Updated 2 package.json files. Run `pnpm install` to apply.

Breaking changes in 18.2→18.3: None (patch release).
Recommend running `pnpm turbo build` to verify all packages compile.
```

### Example 2: Add shared dependency

**Input:** "Add date-fns to packages/utils and make sure all apps use the same version"

**Output:**
```
Current date-fns usage:
- apps/web: [email protected]
- apps/api: [email protected] (major version behind!)
- apps/admin: not installed

Plan:
1. Add [email protected] to packages/utils
2. Upgrade apps/web from 3.3.1 → 3.6.0
3. Upgrade apps/api from 2.30.0 → 3.6.0 (breaking changes — see migration notes)
4. Remove direct date-fns deps from apps, import via packages/utils

⚠️ date-fns v2→v3 breaking changes:
- Named exports only (no default import)
- `format` tokens changed: `DD` → `dd`, `YY` → `yy`

Updated 4 package.json files. Review the v3 migration in apps/api.
```

## Guidelines

- Always map the full dependency graph before making changes
- Check for breaking changes before bumping major versions
- Prefer hoisting shared deps to the root when possible
- Use `catalog:` protocol in pnpm or `resolutions` in yarn for version pinning
- After any dependency change, verify builds across all affected packages
- Circular dependencies between packages are a code smell — suggest extraction
- For large monorepos (50+ packages), prioritize the most impactful mismatches first
- Internal packages should use `workspace:*` protocol, not pinned versions