Architect Monorepos for Scalable Development

Monorepo Architect is a skill for planning monorepo structure, build systems, and dependency management across multiple projects. It describes a practical workflow that starts with the size of the codebase and the team, then moves through tooling choice, workspace design, caching, change detection, and task pipelines. Its capabilities include workspace configuration, dependency graph management, code sharing and library extraction, and orchestration across projects. Tooling selection can consider Nx, Turborepo, Bazel, and Lerna; no universal tool choice is prescribed.

Use this skill when setting up a monorepo, moving from polyrepo to monorepo, improving slow CI/CD, sharing code between projects, managing dependencies across projects, or introducing consistent tooling. These situations match its stated use cases and capabilities. Do not use it for a task unrelated to monorepo architecture or one that needs a different domain or tool. Clarify goals, constraints, and required inputs before applying practices; resolve unknowns before selecting a design.

The workflow begins with codebase size and team structure, along with the goals, constraints, and inputs that need clarification. It then produces an actionable architecture and implementation sequence: choose suitable monorepo tooling, define workspace structure, establish a build caching strategy, configure affected or changed detection, and set up task pipelines. Document conventions and the dependency graph so project relationships and shared work are clear. It does not prescribe a package manager or fixed configuration file.

Tooling selection can consider Nx, Turborepo, Bazel, and Lerna. The workflow also covers local and remote build caching, dependency graphs, tags for dependency constraints, and affected-build detection. It recommends keeping shared libraries focused, defining project boundaries, and checking that cache keys cover sources, lockfiles, tools, and relevant environment. Remote caching requires authorization and a review of private artifact or credential transmission and cross-tenant cache integrity; secrets must never be cached. Before trusting affected-build detection to omit work, compare it with a full build. These are evaluation and validation directions, not claims that the skill supplies integrations with those systems.

This skill is for teams organizing several related projects and the developers responsible for their build and dependency workflows. It is relevant to people designing workspace boundaries, sharing libraries, tuning CI, or making dependency changes consistent across a repository. Preserve the existing build system and package manager unless a migration is requested; validate cache behavior and change detection against a full build where needed. It does not name a particular company, role, or team size, so the guidance starts from the actual project and team structure rather than an assumed organization.