Skip to content
TilloTech Docs

Use Turborepo for the EOS monorepo

Date: 2026-07-08

Status

Accepted

Context

EOS is being created as a new monorepo for shared engineering and AI enablement assets. The repo is expected to bring together the current agent workbench-style assets, shared skills, engineering standards, documentation, ADRs, and deterministic CLI tooling that supports engineering workflows.

The team agreed that the existing repo would be significantly reworked and that starting fresh in a new repo would be cleaner than trying to reshape the current structure in place. The repo will contain multiple related but distinct areas, such as skills, CLI tooling, documentation, and future review tooling.

The repo is expected to be TypeScript-first where possible. This aligns with the surrounding AI tooling ecosystem, internal engineering familiarity, and the likely need to integrate with Node-based tools. The decision does not prevent other languages being used where they are the right fit, but TypeScript should be the default for EOS packages and tooling.

We need monorepo tooling that:

  • has low cognitive overhead;
  • works well for a small-to-medium internal tooling repo;
  • supports TypeScript-first packages naturally;
  • sits cleanly on top of pnpm workspaces;
  • gives us useful task running and caching without imposing too much structure;
  • does not over-optimise for governance before the repo shape has stabilised;
  • leaves room to move to something more opinionated later if the repo grows into needing it.

Nx was discussed as another credible option, but it was considered a step up in complexity. For EOS, the immediate need is coherence, caching, and simple package orchestration rather than strict boundary enforcement.

Decision

We will use Turborepo as the monorepo task runner for EOS, with pnpm workspaces as the underlying workspace mechanism.

Turborepo will be used to coordinate common package tasks such as build, test, lint, format, typecheck, and any repo-specific generation or validation commands.

EOS should start with a simple structure and avoid introducing more monorepo machinery than is needed. If EOS later grows to need stronger project graph enforcement, dependency constraints, or richer workspace governance, we can revisit the tooling choice.

Consequences

Positive

  • The repo starts with a simple monorepo setup that most contributors can understand quickly.
  • TypeScript packages work naturally without extra wrapper conventions.
  • pnpm workspaces remain the foundation, so the repo is not tightly locked into Turborepo.
  • Turborepo provides useful caching and task orchestration without forcing a heavy project model.
  • Moving from Turborepo to a more opinionated tool later should be easier than starting with a more complex tool and trying to simplify it.

Negative

  • Turborepo does not provide the same level of built-in boundary enforcement as Nx.
  • We may need to add our own conventions, validation, or documentation if package boundaries become unclear.
  • If EOS grows significantly, Turborepo may eventually feel too lightweight for the repo’s needs.

Neutral

  • This decision is scoped to EOS. It is not a company-wide decision that all future monorepos must use Turborepo.
  • This ADR should not block a future organisation-wide ADR about monorepo standards.

Alternatives considered

Nx

Nx provides richer monorepo features, stronger project graph awareness, and more built-in governance. It may be a good fit for larger or more complex monorepos.

We are not choosing Nx for EOS at this stage because it adds more structure and complexity than we currently need. EOS is an internal tooling and standards repo, not yet a large application monorepo with many independently owned product packages.

Separate repositories

Keeping skills, CLI tooling, docs, ADRs, and review tooling in separate repositories would reduce the need for monorepo tooling.

We are not choosing separate repositories because these areas are closely related. The CLI exists to support deterministic engineering workflows, the skills need to wrap and call that deterministic tooling, and the standards/docs need to be available as shared context. Keeping them together gives EOS a clearer operating model.