monorepo-workspace-governance

Enforces workspace dependency ownership and root orchestration rules in npm monorepos.

Updated Dec 24, 2025
One-click install
npx skills add https://github.com/JoyJoin-Tech-Limited/JoyJoin_app_v0.1 --skill monorepo-workspace-governance-joyjoin-tech-limited
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: monorepo-workspace-governance
Source: https://github.com/JoyJoin-Tech-Limited/JoyJoin_app_v0.1/tree/main/.github/skills/monorepo-workspace-governance
Command: npx skills add https://github.com/JoyJoin-Tech-Limited/JoyJoin_app_v0.1 --skill monorepo-workspace-governance-joyjoin-tech-limited

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? In an npm workspaces monorepo, dependencies often get installed to the wrong package.json, root scripts get renamed and break guardrail checks, and code leaks across workspace boundaries. This Skill defines and enforces the ownership rules that keep the monorepo structure consistent. ## Core Features & Use Cases - Dependency Ownership Enforcement: Ensures each dependency is installed to the workspace that uses it (via npm install <pkg> -w @joyjoin/<workspace>), never to the orchestration-only root package.json. - Guardrail Compliance: Keeps required root scripts (check, check:clients, check:server, check:full, set-admin) aligned with scripts/check/check-guardrails.mjs, plus secret/env and legacy-identifier rules. - tsconfig Normalization: Maintains the solution-style root tsconfig with per-workspace references extending tsconfig.base.json. - Use Case: When asked to "add date-fns to the server", the Skill scopes the install to @joyjoin/server, verifies the root package.json stays clean, and runs npm run guardrails to confirm compliance. ## Quick Start Ask the assistant to add a dependency to a specific workspace or fix a failing guardrails check, and it will apply the workspace ownership rules and verify with npm run guardrails.

Frequently Asked Questions about monorepo-workspace-governance

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a dependency to a specific workspace in an npm monorepo?▼

Run npm install <package> -w @joyjoin/<workspace> from the repo root so the dependency lands in that workspace's package.json, not the root. Then run npm run guardrails to verify ownership rules still pass.

Why does npm run guardrails fail with a missing required script error?▼

A required root script such as check, check:clients, check:server, check:full, or set-admin was renamed or removed. Check scripts/check/check-guardrails.mjs for the exact expected names and commands, then restore the matching entry in the root package.json.

Can the root package.json own runtime dependencies in npm workspaces?▼

No. The root package.json is orchestration-only and must not own runtime code or dependencies. Each workspace declares its own dependencies and devDependencies, and cross-workspace shared code lives in packages/shared.

Why do TypeScript errors appear after changing tsconfig in a monorepo?▼

The workspace tsconfig.json may have lost its extends reference to tsconfig.base.json, or a new workspace is missing from the root tsconfig.json references array. Restore the extends chain and add the workspace path to the solution-style root config.

When should I not use workspace governance rules?▼

Skip this Skill for route placement inside the server workspace, tasks that only add a regression test, or purely UI-level changes with no package.json or config impact. Those belong to server architecture, testing, or UI-focused workflows instead.