# Monorepo Ops

> Use for monorepo-level work — running pnpm and turbo scripts, adding dependencies, changing shared packages, or cross-app changes. Covers workspace layout, filters, and build and validation order.

- Skill: `yosemitecrew/monorepo-ops` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add yosemitecrew/monorepo-ops`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yosemitecrew/monorepo-ops/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yosemitecrew (https://skillmd.com/u/yosemitecrew)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yosemitecrew/monorepo-ops

---


# Monorepo Operations — Yosemite Crew

## Description

Use this skill for any task involving monorepo-level operations: running scripts, adding dependencies, managing shared packages, understanding workspace relationships, or cross-app work.

TRIGGER: tasks spanning multiple apps, dependency changes, turbo commands, pnpm workspace operations, or shared package changes.

---

## Workspace Layout

```
apps/
  frontend/       frontend
  backend/        backend
  desktop/        @yosemite-crew/desktop
  mobileAppYC/    mobileAppYC
  dev-docs/       dev-docs
packages/
  auth/           @yosemite-crew/auth
  database/       @yosemite-crew/database
  design-tokens/  @yosemite-crew/design-tokens (DEAD - never built, zero consumers; live tokens: apps/frontend/src/app/globals.css)
  fhir/           @yosemite-crew/fhir
  fhirtypes/      @yosemite-crew/fhirtypes
  lib/            @yosemite-crew/lib
  types/          @yosemite-crew/types
```

Tooling: **pnpm workspaces** + **Turbo**. Package manager: `pnpm@8.15.6`.

---

## Project Architecture Reference

For architecture decisions, technical narratives, or product-engineering context, read `.agents/skills/monorepo-ops/project-baseline.md`.

## Running Commands

Always use `--filter` to scope to the relevant workspace. Never run commands at root without `--filter` unless intentionally affecting all packages.

When the touched workspace is `apps/frontend`, apply Sonar rules from `.agents/skills/frontend-sonar/SKILL.md` and run the mandatory frontend check order (`tsc` -> `lint` -> targeted tests).

```bash
# Dev
pnpm --filter frontend dev
pnpm --filter backend dev

# Build
pnpm --filter frontend build
pnpm turbo build --filter=frontend...   # build frontend + its deps

# Lint
pnpm --filter frontend run lint
pnpm --filter backend run lint

# Type check
pnpm --filter frontend run type-check
# or from within the app:
npx tsc --noemit

# Tests (targeted)
pnpm --filter frontend run test -- --testPathPatterns="ComponentName"
pnpm --filter mobileAppYC run test -- --testPathPatterns="ScreenName"
```

---

## Adding Dependencies

```bash
# Add to a specific app
pnpm --filter frontend add <package>
pnpm --filter backend add <package>
pnpm --filter mobileAppYC add <package>

# Add as devDependency
pnpm --filter frontend add -D <package>

# Add to a shared package
pnpm --filter @yosemite-crew/types add <package>

# Add root devDependency (tooling only)
pnpm add -D -w <package>
```

---

## Shared Packages

Two packages deserve special care: `@yosemite-crew/database` holds the Prisma schema, migrations, and generated client (the schema source of truth), and `@yosemite-crew/auth` holds the SuperTokens session helpers used by the backend.

When changing `packages/types` or `packages/fhirtypes`:

1. Update the type definitions.
2. Build the package you changed: `pnpm --filter @yosemite-crew/types build` or `pnpm --filter @yosemite-crew/fhirtypes build` (both have a `build` script).
3. All consumers (frontend, backend, mobile) pick up changes automatically via workspace links.
4. Run type-check in each affected app.

---

## Build Pipeline (Turbo)

`turbo.json` defines the task graph. Tasks run in dependency order automatically.

```bash
pnpm turbo build           # builds all apps in correct order
pnpm turbo build --filter=frontend...  # builds frontend + its dependencies
```

---

## Pre-commit Hooks

Husky + commitlint are configured. Pre-commit runs a staged-secret scan + lint-staged (eslint --fix, prettier, secretlint on staged files); the full monorepo lint + type-check run at pre-push. Commit messages must follow conventional commits:

```
<type>(<scope>): <subject>
Types: feat | fix | chore | refactor | test | docs | style | perf | ci
```

Scope allowlist is defined centrally in root `AGENTS.md` and enforced by `commitlint.config.cjs`.

Never skip hooks with `--no-verify`.

---

## Secrets Check

`secretlint` runs on commit. Never commit `.env` files, API keys, tokens, or private keys.

```bash
pnpm run check:secrets   # manual check
```

---

## Gotchas

- `pnpm install` at the root installs all workspaces. Never run `npm install` or `yarn` — pnpm only.
- Hoisting: some packages are hoisted to root `node_modules`, others are not. If you see resolution errors, check `pnpm-workspace.yaml`.
- Lock file: always commit `pnpm-lock.yaml` changes. Never ignore it.
- If turbo cache causes stale output: `pnpm turbo build --force` to bypass cache.