--- type: Module title: workspace description: The monorepo root — layout, build pipeline, dependency resolution and vendored source. status: stable kind: workspace resource: ../.. tags: - architecture - dx generated: by: "okfit/claude-code" at: 2026-11-12T21:41:04Z integrity: generated: body: 9dc13feea9100a46 --- # workspace ## Purpose The repository root: the `packages/*` layout, the pnpm workspace and Effect catalogs, the turbo/bundler build pipeline, Biome/commitlint/lint-staged/markdownlint presets, and the read-only vendored reference sources under `.repos/`. Every package Module sits underneath this one and inherits its build, lint and dependency-resolution rules. ## Layout - `packages/*` — one directory per `@effected` library. - `packages/pnpm-plugin-effected` — the kit's companion (pnpm catalog/config plugin): published with the kit and installable by consumers, but not a library, so it carries no tier. - `plugin/` — the "effected" agent plugin, `@effected/ai-plugins`: a private tracking package that versions it but never publishes to npm, holding one pluginfinity source built into committed Claude Code and Copilot plugins under `plugin/builds/`. See [ai-plugin](ai-plugin.md). - `.claude/skills/improve` — the project-level self-improvement skill that maintains `plugin/skills/`. - `.repos/` — read-only vendored sources as sparse git submodules; see [Vendored source](#vendored-source). - `website/` — the RSPress docs site, with per-package api-extractor models under `website/lib/models/`; see [website](website.md). - `scratchpad/` — a private agent-probe workspace member, never published and invisible to CI; see [scratchpad](scratchpad.md). Build tooling is `@effected/bundler`, run by the `effected` tool from source, with `@savvy-web/silk` for the Biome, commitlint, lint-staged and markdownlint presets, orchestrated by [Turbo](https://turbo.build/). The bundler's `publishConfig` manifest transform produces the publishable manifest at build time from a `"private": true` source manifest, and `@effected/plugin` ships the tsconfig bases. ## Build pipeline `pnpm build` runs `turbo run build`, leaving out the frozen `docs` site. Each package's `build` script is `effected package build`, and there is one target: `dist/prod//{pkg,meta}`, `dist/prod/targets.json` and `dist/prod/issues.json`. `build` depends on the package's `types:check`, which chains over `^types:check`, and it has no `^build`, because workspace links resolve to each sibling's source. See [one build target](../decisions/one-build-target-from-source-links.md). Config is `effected.toml`, which only six packages need; each build appends to `.cache/effected/build.jsonl` and `issues.jsonl` at the workspace root. `@effected/plugin` is a root devDependency, never a package's dependency, and `effected` runs from source as [the bootstrap decision](../decisions/bundler-bootstraps-from-source.md) describes. Build through `pnpm build --filter `: a direct `effected package build` is allowed but skips the typecheck gate and the cache. A turbo cache hit replays the previous run's output **verbatim** — the same `FULL TURBO` line, the same `suppressed` figure a clean gate prints — so a clean log does not prove a build ran. The tell is `dist/prod/issues.json`'s `generatedAt`, which must postdate the last source edit; a replay against unchanged inputs is legitimate, one predating the edit means the reader is looking at someone else's gate. A hit also adds no line to the build journal. Every package typechecks with `tsc --noEmit` (`types:check`) against `typescript` from `catalog:effected:build`, the kit's build catalog, which `pnpm:export` writes into `pnpm-workspace.yaml` beside `effected` ([the effected build catalog](../decisions/effected-build-catalog.md)). `@effect/tsgo` was removed from every package and survives only as an unused catalog entry; do not reintroduce it as a package's typechecker (see [tsc, not tsgo](../decisions/tsc-not-tsgo.md)). The root `tsconfig.json` sets `skipLibCheck: true` as a deliberate override of the silk preset's default (`false`), because `vitest@5.0.0` ships a broken `.d.ts` (`dist/chunks/plugin.d.ts` imports `MarkOptions` from `vitest/browser`, which `dist/browser.d.ts` does not export) that was the only error in the whole root program and failed the pre-commit hook's `tsc --noEmit` on every commit. Drop the override once vitest ships a consistent declaration; per-package `types:check` is unaffected either way. ## Code quality and hooks Biome, commitlint, lint-staged and markdownlint all take their presets from `@savvy-web/silk` (configs at the repo root and in `lib/configs/`). Never invoke `markdownlint-cli2` directly — it *merges* explicit path arguments with the config's repo-wide `globs` rather than narrowing to them, so "lint just my file" lints the whole repository; run `pnpm lint:md` or `pnpm lint:md:fix` instead. Never run `git checkout` / `git restore` / `git stash` to undo unexpected working-tree changes — other agents and earlier steps may hold uncommitted work there. ## Vendored source `.repos/` holds read-only vendored sources as sparse git submodules, declared in `.gitmodules` and described by the `.repos/config.json` manifest (url, ref, purpose, sparse paths, orientation notes) — see [the vendored-repos manifest interface](../interfaces/vendored-repos-manifest.md). `.repos/effect` is the load-bearing entry, pinned to the release tag matching the lockfile's resolved `effect` rather than tracking `main` — see [vendored Effect is pinned to the catalog tag](../decisions/vendored-effect-pinned-to-catalog-tag.md). `.repos/pnpm` is the read-only pnpm 12 source pinned to the repo's `devEngines` pnpm (`v12.20.0`), sparse to the config, versioning, workspace and lockfile crates plus the settings docs: the authority for `@effected/pnpm`'s settings catalog, versioning schema and lockfile grammar. The rest are port bases and oracles for the `markdown` package. The checkout is **sparse**: for `.repos/effect`, only `packages/effect` (the v4 export authority), `packages/vitest` (the `@effect/vitest` reference implementation) and `migration`, `ai-docs`, `LLMS.md`, `MIGRATION.md` (the rename evidence for the plugin's evidence ladder) are materialized. Submodule content is not stored in the parent tree, so fresh clones, CI runners and new git worktrees start with an **empty** `.repos/` checkout — see [vendored repos are empty on a fresh clone](../gotchas/vendored-repos-empty-on-fresh-clone.md) and [sync the vendored repos](../runbooks/sync-vendored-repos.md). Re-pinning when the lockfile's resolved `effect` moves is one operation, folded into the commit that moves it — see [advance the effect pin](../runbooks/advance-the-effect-pin.md). The vendored tree is **read-only, and enforced rather than trusted**: the silk plugin's PreToolUse guards deny Write, Edit, Bash and MCP-git mutations under `.repos/**`. It also stays outside every build and lint graph — the silk Biome preset centrally excludes `**/.repos`, markdownlint's config keeps `**/.repos` in its ignores, dependabot excludes `.repos/**`, and pnpm, turbo and vitest never matched the directory by glob in the first place. ## Dependency resolution The whole tree resolves to **one** `effect` copy — this workspace and the build toolchain (`@savvy-web/*`, rolldown-pnpm-config, okfit, tsdoctor, vitest-agent) alike, on the exact `effect` the derived pins hold. See [one resolved effect copy](../conventions/one-resolved-effect-copy.md) for why that is a correctness requirement rather than hygiene, and for the toolchain bridge shapes a toolchain still on an older Effect minor or a release candidate may need. No bridge is in place today; the Effect 4.1 `.pnpmfile.cjs` hook was retired on 2026-11-01. The workspace's runtime catalog pair is `effected` and `effected:peers` in `pnpm-workspace.yaml`, the same names a consumer writes ([the one declared effected catalog](../decisions/one-declared-effected-catalog.md)). Its Effect-family entries give `effect` and every satellite a tilde on the current Effect minor under `lock-minor` (and `@effect/tsgo` a caret on its own 0.x line; see [the effect catalog holds one minor](../decisions/effect-catalog-minor-lock.md)), generated by [`pnpm-plugin-effected`](pnpm-plugin-effected.md), and the plugin's derived family pins (`overridesFromCatalogs`) hold the whole graph, transitive satellites included, to the catalog version — see [the effect family is pinned by overrides derived from the catalog](../decisions/effect-overrides-derived-from-catalog.md). No Effect v3 catalog exists: the `effect3` / `effect3:peers` pair and the camelCase `effectPeers` / `effect3Peers` aliases are retired, and a catalog spelled that way is a stale reference to repair, not a surface to restore. The same catalogs also carry the kit's own packages under a `lock-minor` strategy with caret ranges; those entries are unused here, since internal edges stay `workspace:*` or `workspace:^`. Manifests write `catalog:effected` for a dev or runtime dependency and `catalog:effected:peers` for a peer. A consumer sees the same split: the plugin's hook serves `effected` (the Effect family at its exact pins) and its floored `effected:peers` twin, and a consumer spells peers `catalog:effected:peers` ([one declared effected catalog](../decisions/one-declared-effected-catalog.md)). The `effected` catalog is kept current by a workflow triggered on pull requests to `main` and to `changeset-release/main`. The build-tooling versions (`typescript`, `@types/node`, `tsx`, React and its types, the bundler's own stack) come from the second pair, `effected:build` and `effected:build:peers`, also generated by `pnpm-plugin-effected` and exported into `pnpm-workspace.yaml`; manifests write `catalog:effected:build` and `catalog:effected:build:peers`. The catalog sync never moves them; `pnpm:up` does. Silk's other catalogs (`lint`, `test`, `silk`, `docs`) are still injected by the `@savvy-web/pnpm-plugin-silk` config dependency; check the installed plugin under `node_modules/.pnpm-config/` when one of those needs verifying. `pnpm peers check` carries one expected, rotating occupant: a downstream package pinning an older `@effected/*` caret than the kit's current release, always in the *toolchain* graph rather than this workspace, always clearing when that tool republishes against the current release. Any other warning is a genuine closure defect to fix upstream, not a second expected residual. Always check the lockfile diff after an install — a plain `pnpm install` has once stripped the turbo, biome and tsgo platform binaries from it. After renaming a workspace package, install deliberately and review that diff before running any script: pnpm's pre-run dependency check otherwise installs on the next `pnpm run` ([the verify-deps gotcha](../gotchas/verify-deps-before-run.md)). **User-run only:** `pnpm pnpm:up`, `pnpm pnpm:preview` and `pnpm pnpm:export` advance and export the Effect catalogs, mutating the lockfile and the root `pnpm-workspace.yaml`. Agents must not invoke them — surface the command and let the user run it. Agents may run `pnpm catalog:check` (a read-only drift gate) and `pnpm catalog:sync`, which write nothing but `packages/pnpm-plugin-effected/lib/build/pnpm-config.plugin.ts` and one fixed-name changeset. ## Testing Vitest with the `@vitest-agent/plugin` `AgentPlugin`; tests live in each package's `__test__/` directory, never co-located in `src/`. Effect code is tested with `@effect/vitest`, asserting with `assert.*` rather than `expect`. A test needing `FileSystem` provides `memfs`, never a hand-rolled `FileSystem.layerNoop` double, because `layerNoop` is deny-by-default and a stub encodes only what its author remembered. Full rules and riders → [testing standards](../conventions/testing-standards.md). The root `globalSetup` (`vitest.setup.ts`) runs `pnpm exec turbo run build` for the packages whose tests read their own `dist` (`@effected/plugin...`, `@effected/pnpm-plugin-effected`, `@effected/cli-kit`, `@effected/config-file`, `@effected/kit`, `@effected/commands`) via `AgentPlugin.runScript` before **every** vitest run — CLI and the MCP `run_tests` tool alike, whichever project; turbo's cache makes it a fast no-op when nothing changed. Everything else reads siblings' source over the workspace links. The filter is named because `@effected/ai-plugins`'s `build` regenerates the committed `plugin/builds/` trees, and the setup pins `runScript`'s recently-built window to 1 ms, because at its 30 s default a run inside the window skips the build and reads a stale `dist` — see [testing standards](../conventions/testing-standards.md). `vitest.config.ts` clears `NODE_OPTIONS` and sets `__PACKAGE_VERSION__` for every project: a test that runs sibling source in a child process loads tsx itself. Run vitest from the repo root: from inside a package directory vitest does not load the root config, so `--project @effected/` fails with `No projects matched the filter` and the repo's setup, plugins and reporter are all absent. From the root, prefer `vitest run --project @effected/`. A bare positional filter is matched as a substring against each test file's path, not as a path selector — see [a vitest positional filter is a substring match, and a package-dir run never loads the root config](../gotchas/vitest-positional-filter-is-cwd-relative.md) for the measured comparison and the `Tests: 0/0 passed` / exit 1 shape a miss produces. `pnpm ci:test` sets `CI=true`. The global coverage thresholds in `vitest.config.ts` are set unconditionally. They measure the whole repository, so a filtered run cannot meet them — but `@vitest-agent/plugin` (4.x) detects a partial run (positional filter, `--project`, `--tags-filter`, `--changed`, `--related`, `--shard`, `-t`) and skips them, printing `Coverage thresholds skipped: partial run`. A filtered run's exit code is therefore a real signal; do not reintroduce a CI-only gate around the thresholds. Coverage is measured on our own sources only (`coverage.include`: `packages/*/src/**` and `lib/scripts/**`), so dependency files never reach the report. Under `CI` the config sets `persist: false` on `AgentPlugin`, skipping the SQLite history an ephemeral runner discards; `VITEST_AGENT_PERSIST` overrides it either way. The BATS construct-index positive control skips under `CI` (it would run a cold `pnpm build`; the pre-push gate proves it). Three of this repository's gates — the `suppressed:` count in `issues.json`, the `Tests:` line, and `packages.length`-style fixture assertions — work by asserting a number did not change unexpectedly; state which count moved and why whenever one does, per [state the reason when a gate count moves](../conventions/state-the-reason-when-a-gate-count-moves.md).