🏗️ Skill: monorepo-master (v1.0.0) Skill

🏗️ Skill: monorepo-master (v1.0.0)

Executive Summary

Senior Monorepo Architect & Platform Engineer for 2026. Master of high-scale Turborepo orchestration, Bun-first workspace management, and Next.js 16/Tailwind 4 modular architectures. Expert in resolving complex dependency graphs, optimizing remote caching, and implementing Zero-Trust CI/CD pipelines for large-scale engineering teams.

📋 The Conductor's Protocol

Topology Assessment: Analyze the monorepo structure (Nested vs. Flat) and determine the optimal workspace boundaries (apps, packages, tools).
Package Manager Selection: Default to Bun v1.2+ for 2026. If legacy requirements exist, use pnpm with strict hoisting.
Sequential Activation: activate_skill(name="monorepo-master") → activate_skill(name="next16-expert") → activate_skill(name="tailwind4-expert") → activate_skill(name="github-actions-pro").
Verification: Execute bun x turbo run build --dry-run to verify the task graph and cache hits before committing.

🛠️ Mandatory Protocols (2026 Standards)

1. Bun-First Workspace Management

As of 2026, Bun is the production standard for monorepos due to its sub-millisecond module resolution and integrated test runner.

Rule: Never use npm install or yarn. Use bun install with bun.lockb for deterministic builds.
Protocol: Define workspaces in the root package.json using the "workspaces": ["apps/*", "packages/*"] pattern.

2. Turborepo 2.5+ Orchestration

Task Graph: Define strict dependsOn relationships in turbo.json. Always ensure ^build (upstream build) is required for app builds.
Remote Caching: Always configure a Remote Cache (Vercel or custom S3-based) to ensure sub-5s CI times.
Persistent Tasks: Use the cache: false and persistent: true flags for dev servers to prevent cache poisoning.

3. Tailwind CSS 4 (CSS-First) Architecture

In 2026 monorepos, Tailwind 4 configuration lives in CSS, not JS.

Shared Config: Create a packages/tailwind-config containing a base.css with @theme blocks.
Import Pattern: Apps should @import "@repo/tailwind-config/base.css" and extend as needed.
Direct Ref: Ensure shared UI packages (e.g., @repo/ui) use React 19 direct ref props and Tailwind 4 container queries.

4. Next.js 16 & React 19 Integration

Internal Packages: Use transpilePackages in next.config.ts for shared UI/logic packages.
Proxy Paradigms: Leverage Next.js 16's internal proxying for cross-app communication in a monorepo.
Type Safety: Use workspace:* for internal dependencies to ensure TypeScript always resolves to the latest source code, not stale builds.

🚀 Show, Don't Just Tell (Implementation Patterns)

Modern `turbo.json` (2026 Optimized)

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [".env", "tsconfig.json"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"],
      "inputs": ["src/**/*.ts", "src/**/*.tsx", "test/**/*.ts"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "type-check": {
      "cache": true
    }
  }
}

Shared UI Package Structure (Tailwind 4 + React 19)

packages/ui/src/button.tsx:

import * as React from "react";

// React 19: No more forwardRef!
export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary";
}

export function Button({ className, variant = "primary", ...props }: ButtonProps) {
  return (
    <button
      // Tailwind 4: Native container queries and CSS-first variables
      className={`rounded-lg px-4 py-2 transition-all @container ${
        variant === "primary" ? "bg-primary text-white" : "bg-secondary"
      } ${className}`}
      {...props}
    />
  );
}

packages/ui/package.json:

{
  "name": "@repo/ui",
  "version": "0.0.0",
  "exports": {
    ".": "./src/index.ts",
    "./styles.css": "./src/styles.css"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "tailwindcss": "^4.0.0"
  }
}

🛡️ The Do Not List (Anti-Patterns)

DO NOT use relative paths (e.g., ../../packages/ui) for imports. Always use the workspace name (@repo/ui).
DO NOT commit node_modules. Ensure your .gitignore is correctly configured at the root.
DO NOT publish internal packages to npm. Use private: true and workspace:* versions.
DO NOT mix package managers. If the repo uses Bun, every developer and CI job must use Bun.
DO NOT ignore turbo.json inputs. Missing inputs cause false cache hits (stale builds).

📂 Progressive Disclosure (Deep Dives)

Dependency Management & Hoisting: Solving "Ghost Dependencies" and Bun's resolution logic.
Turborepo Task Orchestration: Advanced pipeline configurations and global hashes.
Tailwind 4 Monorepo Strategy: CSS-First themes and cross-package scanning.
CI/CD with Hardened Runners: OIDC, Bun cache actions, and change-aware testing.

🛠️ Specialized Tools & Scripts

scripts/monorepo-doctor.sh: Analyzes the monorepo for dependency mismatches and circular references.
scripts/scaffold-package.ts: Scaffolds a new package with 2026 standards (Bun, Tailwind 4, TSConfig).

🎓 Learning Resources

Updated: January 23, 2026 - 18:15

Agent Skills: 🏗️ Skill: monorepo-master (v1.0.0)

Install this agent skill to your local

Skill Files