ahtishamshahzad 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-strategychose 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 (
pnpmvsnpm)?
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
- Inventory packages + their build/test tasks + interdependencies.
- Pick the workspace manager (pnpm vs npm) with reason.
- Decide Turborepo yes/no on build-graph + CI-caching payoff.
- Record the decision + trade-offs.
- 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.