Skip to content

Commit 98c10eb

Browse files
chore: add monorepo doctor skill (#243)
Adds the monorepo-doctor agent skill, which audits package boundaries, dependency cycles, caching, CI coverage and test code in production, with a sample report.
1 parent 418f3d2 commit 98c10eb

12 files changed

Lines changed: 1065 additions & 0 deletions

File tree

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: monorepo-doctor
3+
description: Use when a user asks for a JS/TS monorepo audit, monorepo health check, Nx/Turborepo cache issues, affected tests not running, circular dependencies, package boundary drift, or test code shipped to production. Read-only; writes Markdown and JSON reports.
4+
---
5+
6+
# Monorepo Doctor
7+
8+
Audit a JS/TS monorepo for five classes of problems that teams routinely miss, and produce an evidence-backed report.
9+
10+
Prerequisites: Node ≥ 22.5. The work dir is `$W` = `$(node -p 'require("os").tmpdir()')/monorepo-doctor` (see detection.md).
11+
12+
## Rules
13+
14+
- **Read-only.** Never install dependencies, build, run tests, or edit project files. Allowed writes: `monorepo-doctor-report.md`, `monorepo-doctor-report.json` (workspace root or a user-given dir) and `$W`.
15+
- Allowed commands: the snippets in the reference files, `npx --yes [email protected]`, `npm_config_ignore_scripts=true npx --yes [email protected]` (exact pinned versions — never unpinned or `@latest`; bump only after review), `npm pack --dry-run --json --ignore-scripts`, and `npx nx` / `npx turbo` **only if** detection reports them `installed` (graph / `--dry=json` / `boundaries` only — never real task runs, with read-only env vars from the references).
16+
- **Never abort a check.** If a tool fails, mark the check `partial` or `skipped` with a reason and continue.
17+
- **Every finding needs evidence** (config snippet, file:line, or command output). No evidence → no finding.
18+
- Use only the finding ids defined in the reference files.
19+
20+
## Workflow
21+
22+
1. **Detect** — follow [references/detection.md](references/detection.md). Stop if `NO_WORKSPACE`.
23+
2. **Scan** — follow [references/scan.md](references/scan.md).
24+
3. **Check** — run all five unless the user asked for a subset (write `{"status":"not-run","reason":"not requested","findings":[]}` to `$W/findings/<check>.json` for the others):
25+
- [references/boundaries.md](references/boundaries.md) — package split & public API
26+
- [references/circular-deps.md](references/circular-deps.md) — package and file cycles
27+
- [references/caching.md](references/caching.md) — Nx / Turborepo cache correctness
28+
- [references/ci-coverage.md](references/ci-coverage.md) — tests that silently don't run in CI
29+
- [references/prod-leakage.md](references/prod-leakage.md) — test code shipped to production
30+
The checks are independent; if you can run sub-agents, run them in parallel.
31+
4. **Report** — follow [references/report-format.md](references/report-format.md): validate each `findings/<check>.json`, render, then show the user the summary line and the top 5 findings.
32+
5. **CI mode** (only if asked, or when invoked non-interactively with a threshold) — run the exit-code snippet from report-format.md.
33+
34+
## Tracking
35+
36+
Create a todo per phase/check and mark each done as its findings file is written.
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Check 1 — Package boundaries
2+
3+
Question: are packages split along real seams, and is each package's public API respected?
4+
Inputs: `workspace.json`, `scan.json`. Output: `findings/boundaries.json`.
5+
6+
## Rules
7+
8+
| id | severity | detect | evidence |
9+
| ---------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
10+
| `boundaries/oversized-package` | low | `scan.packages[p].sourceFiles > 500` or `loc > 50000` | counts |
11+
| `boundaries/deep-import` | medium | each `scan.imports` entry with `deep && (declared \|\| fromSource === "project.json")` (undeclared package.json importers are reported by ci-coverage instead) | file:line + import specifier + target's `exports` keys |
12+
| `boundaries/unlisted-dependency` | medium | knip `unlisted` entries | knip output line |
13+
| `boundaries/unused-dependency` | low | knip `dependencies` / `devDependencies` entries | knip output line |
14+
| `boundaries/nx-missing-module-boundaries-rule` | medium | Nx detected and no ESLint config in the root mentions `@nx/enforce-module-boundaries` | list of ESLint config files checked |
15+
| `boundaries/nx-permissive-module-boundaries` | low | the rule exists but `depConstraints` contains `{ sourceTag: '*', onlyDependOnLibsWithTags: ['*'] }` | the config snippet |
16+
| `boundaries/nx-untagged-project` | low | Nx detected, rule absent or permissive, and a project has empty `tags` | project.json path |
17+
| `boundaries/turbo-boundaries-violation` | medium | each violation printed by `turbo boundaries` | output line |
18+
19+
Group `deep-import` findings: one finding per (from, target) pair, listing up to 5 locations in `evidence`; `location` is the first occurrence.
20+
21+
## Steps
22+
23+
1. Load `workspace.json` and `scan.json`. Apply the size and deep-import rules directly.
24+
2. **knip** — only if `hasNodeModules`:
25+
```bash
26+
W="$(node -p 'require("os").tmpdir()')/monorepo-doctor"
27+
npx --yes [email protected] --reporter json --include dependencies,unlisted --no-progress --no-exit-code
28+
```
29+
Parse stdout as JSON. Its shape varies by version; look for per-file `dependencies`, `devDependencies` and `unlisted` arrays of `{ name }`. Map the file to its package via `workspace.json`. If knip fails or the output can't be parsed, mark the check `partial` with reason `knip unavailable: <first line of error>`. Do **not** report `unused-dependency` for `@types/*` packages or for tools only referenced in scripts.
30+
3. **Nx** — only if Nx is an orchestrator: read ESLint configs in the root (`eslint.config.{js,mjs,cjs,ts}`, `.eslintrc{,.json,.js,.cjs}`) and every package dir. Apply the three `nx-*` rules. A config that contains `@nx/enforce-module-boundaries` or legacy `@nrwl/nx/enforce-module-boundaries` anywhere counts as present. Group `nx-untagged-project` consistently as one finding per untagged project found from the root and package-dir project configs.
31+
4. **Turborepo** — only if turbo is an orchestrator **and installed**:
32+
```bash
33+
W="$(node -p 'require("os").tmpdir()')/monorepo-doctor"
34+
TURBO_TELEMETRY_DISABLED=1 npx turbo boundaries
35+
```
36+
One finding per reported violation. If the command errors with an unknown-command message (turbo < 2.4), skip this sub-step and note it in `reason`.
37+
5. Write `findings/boundaries.json`.
38+
39+
## Fix guidance
40+
41+
- deep-import: add the subpath to the target's `exports`, or re-export from its entry point, then import from the package root.
42+
- oversized-package: identify clusters by directory and by which consumers import which files (`scan.imports` subpaths); propose 2–3 candidate splits.
43+
- nx-missing-module-boundaries-rule: add `@nx/enforce-module-boundaries` with `depConstraints` based on `scope:*`/`type:*` tags.

0 commit comments

Comments
 (0)