> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/monorepo-infrastructure/monorepo/09-implementation.md).

# Implementation

> **Part of**: [Monorepo Infrastructure PRD](/docs/monorepo-infrastructure/monorepo.md) | **Last Updated**: 2026-02-19

***

## Overview

The monorepo infrastructure rolls out in four phases. Each phase is independently useful and shippable — later phases build on earlier ones but are not blocked by them.

## Phase 1 — Foundation

**Goal**: Working pnpm + Turborepo monorepo with TypeScript compilation and basic scripts.

| Task                                      | Files                                                | Dependencies      |
| ----------------------------------------- | ---------------------------------------------------- | ----------------- |
| Initialize pnpm workspace                 | `pnpm-workspace.yaml`, `.npmrc`, root `package.json` | None              |
| Configure Turborepo                       | `turbo.json`                                         | pnpm workspace    |
| Create `@gotts.ai/typescript-config`      | `packages/typescript-config/`                        | None              |
| Configure root `tsconfig.json`            | `tsconfig.json`                                      | typescript-config |
| Set up `packages/safe` skeleton           | `packages/safe/package.json`, `tsconfig.json`        | typescript-config |
| Set up `packages/vault` skeleton          | `packages/vault/package.json`, `tsconfig.json`       | typescript-config |
| Set up `packages/agent-proxy` skeleton    | `packages/agent-proxy/package.json`, `tsconfig.json` | typescript-config |
| Verify `pnpm install && pnpm build` works | —                                                    | All above         |

**Success criteria:**

* `pnpm install` completes without errors
* `pnpm build` compiles all packages
* `pnpm check-types` passes across all packages
* Turborepo caching works (second `pnpm build` is instant)

**Estimated effort**: 1–2 hours

## Phase 2 — Quality

**Goal**: Linting, formatting, testing, and pre-commit hooks enforced.

| Task                                  | Files                                             | Dependencies      |
| ------------------------------------- | ------------------------------------------------- | ----------------- |
| Create `@gotts.ai/eslint-config`      | `packages/eslint-config/`                         | typescript-config |
| Configure root ESLint                 | `eslint.config.ts`                                | eslint-config     |
| Configure per-package ESLint          | `packages/*/eslint.config.ts`                     | eslint-config     |
| Add Prettier config                   | `.prettierrc`, `.prettierignore`                  | None              |
| Configure Vitest (root + per-package) | `vitest.config.ts`, `packages/*/vitest.config.ts` | Phase 1           |
| Set up Husky + lint-staged            | `.husky/`, `lint-staged.config.mjs`               | ESLint, Prettier  |
| Set up commitlint                     | `commitlint.config.ts`                            | Husky             |
| Verify `pnpm lint && pnpm test` works | —                                                 | All above         |

**Success criteria:**

* `pnpm lint` passes on all packages
* `pnpm format:check` passes
* `pnpm test` runs Vitest across all packages
* Pre-commit hook runs lint-staged on staged files
* Commit with bad format (e.g., `asdf`) is rejected by commitlint

**Estimated effort**: 2–3 hours

## Phase 3 — CI & Publishing

**Goal**: GitHub Actions CI pipeline and Changesets publishing workflow.

| Task                                     | Files                                                | Dependencies   |
| ---------------------------------------- | ---------------------------------------------------- | -------------- |
| Create CI workflow                       | `.github/workflows/ci.yml`                           | Phase 2        |
| Create release workflow                  | `.github/workflows/release.yml`                      | Phase 2        |
| Initialize Changesets                    | `.changeset/config.json`                             | None           |
| Configure published package.json exports | `packages/{safe,vault,agent-proxy}/package.json`     | Phase 1        |
| Add tsdown configs                       | `packages/{safe,vault,agent-proxy}/tsdown.config.ts` | Phase 1        |
| Add publint check to CI                  | CI workflow                                          | tsdown configs |
| Configure Knip                           | `knip.config.ts`                                     | Phase 1        |
| Configure Syncpack                       | `syncpack.config.ts`                                 | Phase 1        |
| Set up Renovate                          | `.github/renovate.json5`                             | None           |

**Success criteria:**

* CI passes on a PR to `main`
* `pnpm changeset` creates a changeset file
* `pnpm release` builds and publishes (dry-run) without errors
* `pnpm knip` reports no false positives
* `pnpm syncpack:check` passes

**Estimated effort**: 2–3 hours

## Phase 4 — Frontend & DX

**Goal**: Next.js app, shared UI package, VS Code configuration, and polish.

| Task                                   | Files                                              | Dependencies      |
| -------------------------------------- | -------------------------------------------------- | ----------------- |
| Create `apps/web` Next.js app          | `apps/web/`                                        | Phase 1           |
| Configure Tailwind v4                  | `apps/web/tailwind.css`                            | Next.js app       |
| Initialize shadcn/ui                   | `apps/web/components.json`                         | Tailwind v4       |
| Create `packages/ui` shared components | `packages/ui/`                                     | typescript-config |
| Add VS Code config                     | `.vscode/settings.json`, `.vscode/extensions.json` | None              |
| Update CLAUDE.md                       | `CLAUDE.md`                                        | All phases        |
| Update root README                     | `README.md`                                        | All phases        |

**Success criteria:**

* `pnpm dev --filter=web` starts the Next.js dev server
* Tailwind v4 classes work without a JS config file
* `@gotts.ai/ui` components render correctly in `apps/web`
* VS Code shows recommended extensions on first open
* CLAUDE.md reflects pnpm commands (not yarn)

**Estimated effort**: 2–3 hours

## Total Estimated Effort

| Phase                     | Effort    | Cumulative |
| ------------------------- | --------- | ---------- |
| Phase 1 — Foundation      | 1–2 hours | 1–2 hours  |
| Phase 2 — Quality         | 2–3 hours | 3–5 hours  |
| Phase 3 — CI & Publishing | 2–3 hours | 5–8 hours  |
| Phase 4 — Frontend & DX   | 2–3 hours | 7–11 hours |

## Success Metrics

| Metric              | Target  | How to Measure                  |
| ------------------- | ------- | ------------------------------- |
| Cold install time   | < 30s   | `time pnpm install` on CI       |
| Cached build time   | < 2s    | `time pnpm build` (second run)  |
| CI pipeline time    | < 5 min | GitHub Actions timing           |
| Type errors         | 0       | `pnpm check-types` exit code    |
| Lint errors         | 0       | `pnpm lint` exit code           |
| Test pass rate      | 100%    | `pnpm test` exit code           |
| Unused dependencies | 0       | `pnpm knip` exit code           |
| Version mismatches  | 0       | `pnpm syncpack:check` exit code |

## Risks & Mitigations

| Risk                                      | Impact                 | Likelihood | Mitigation                                                                        |
| ----------------------------------------- | ---------------------- | ---------- | --------------------------------------------------------------------------------- |
| ESLint 10 plugin incompatibility          | Lint rules unavailable | Medium     | Fall back to ESLint 9 with flat config; most plugins already support flat config  |
| Tailwind v4 breaking changes              | CSS issues             | Low        | v4 is stable as of Feb 2026; pin version if needed                                |
| tsdown regression (new tool)              | Build failures         | Medium     | tsdown is a thin wrapper over Rolldown; can temporarily use `unbuild` or `rollup` |
| Turborepo cache corruption                | Stale builds           | Low        | `pnpm clean:turbo` clears cache; CI always starts fresh                           |
| pnpm strict isolation breaks a dependency | Install failure        | Medium     | Use `.npmrc` `public-hoist-pattern` for specific packages                         |
| Vitest 4.0 migration issues               | Test failures          | Low        | Vitest 4.0 is stable; `projects` config is well-documented                        |
| Changesets version conflicts              | Release failures       | Low        | `linked` and `fixed` groups in Changesets config resolve conflicts                |

## Migration Checklist

When implementing, update these external references:

* [ ] `CLAUDE.md` — Change all `yarn` references to `pnpm`, update package manager version
* [ ] `prd/README.md` — Add monorepo PRD to index
* [ ] `.gitignore` — Add pnpm-specific entries (`.pnpm-store/`, `node_modules/`)
* [ ] Remove `yarn.lock` if present
* [ ] Remove `.yarnrc.yml` if present
* [ ] Remove `.yarn/` directory if present