Monorepo selection

Monorepo Selection

Purpose

Choose the monorepo tooling once a monorepo is decided (repository-strategy): the package manager's workspaces alone, or workspaces plus a task orchestrator (Turborepo) for caching and affected-only builds — sized to the repo's actual complexity.

When to Use

• After repository-strategy chose a monorepo.
• When an existing monorepo's tooling is being reconsidered.
• Not for single/multi-repo projects, or before the monorepo decision.

Inputs

• The apps/packages in the monorepo and their build/test tasks.
• CI needs (build times, how often unaffected apps rebuild), team size.

Discovery Questions

• How many packages/apps, and how interdependent are their build/test tasks?
• Are CI times already hurting from rebuilding everything on every change (caching payoff)?
• Which package manager is in use or preferred (pnpm vs npm)?

Responsibilities

• Decide the workspace manager: pnpm workspaces (efficient disk/install via content-addressable store, strict dependency isolation — strong default for monorepos — pnpm-workspaces) vs npm workspaces (already present, simpler, fewer moving parts — npm-workspaces).
• Decide whether to add Turborepo on top: worth it when there are multiple buildable packages, dependency graphs, and CI that benefits from task caching + affected-only runs; unnecessary overhead for a two-package repo where plain workspace scripts suffice (turborepo-foundation).
• Record the decision + trade-offs; start light and add orchestration when build/CI pain is real, not speculative.
• Feed the choice to ci-cd (affected-only jobs) and the foundation skills.

Required Workflow

1. Inventory packages + their build/test tasks + interdependencies.
2. Pick the workspace manager (pnpm vs npm) with reason.
3. Decide Turborepo yes/no on build-graph + CI-caching payoff.
4. Record the decision + trade-offs.
5. Hand off to the foundation skill(s) + ci-cd.

Decision Rules

• pnpm workspaces is the efficient default for new monorepos; npm workspaces is fine when already standardized on npm and simplicity is valued.
• Add Turborepo when multiple buildable packages + CI caching payoff justify it — not reflexively.
• Start with workspaces-only; introduce the orchestrator when rebuild-everything CI actually hurts.
• Tooling that changes install/CI is a decision worth recording (Gate 2 if it shifts the stack).

Rules

• Decision recorded and tied to the package inventory.
• No installation/scaffolding before approval.
• Keep tooling proportional to repo complexity.

Anti-Patterns

• Turborepo on a trivial two-package repo.
• Mixing package managers within one monorepo.
• Adopting orchestration for speculative future scale.
• Choosing tooling before knowing the package graph.

Validation Checklist

• Packages + tasks + interdependencies inventoried.
• Workspace manager chosen (pnpm/npm) with reason.
• Turborepo decision made on real payoff.
• Trade-offs recorded; foundation skill selected.

Definition of Done

A recorded monorepo-tooling decision — workspace manager and whether to add Turborepo — sized to the package graph and CI needs, with trade-offs noted and the foundation skill selected.

Related Skills

repository-strategy, turborepo-foundation, pnpm-workspaces, npm-workspaces, ci-cd, ../../stack-recommendation.

Related Knowledge

../../../knowledge/ (package graph, CI pain points).

Related References

../../../references/devops/ (monorepo tooling notes, when populated).

Context Loading Guidance

• Requires: package inventory + tasks, CI/build pain, package-manager preference.
• Does not require: app source, unrelated infra.
• May load: one foundation skill after deciding, ci-cd.
• Stop when: the tooling decision is recorded.

Token Efficiency Guidance

The package graph + a yes/no on caching payoff decides it; don't survey every tool feature.