Manage a monorepo through explicit contracts

Accept a repository and a concrete outcome. Inspect before prescribing a layout or tool. A monorepo shares a Git history; it does not require one language, one dependency version, one build system, or synchronized releases.

Use only the phases relevant to the request. Investigation permits inspection; implementation requires edit authorization. Installing dependencies, migrating tools, importing repositories, publishing packages, and deploying services must fit the explicitly authorized scope.

1. Discover the workspace and requested change

1. Read repository state, existing architecture decisions, and relevant CI workflows. Preserve unrelated local work.
2. Identify actual workspace roots and members from manifests and tool discovery, not folder names alone. Record package/project identifiers, paths, owners, deployable applications, reusable libraries, tooling, and generated artifacts.
3. Inspect package managers, runtime/compiler versions, lockfiles, scripts, task-runner configuration, shared configuration, and release tooling. Multiple ecosystems can legitimately have separate roots and lockfiles. Inspect discovery and dry-run side effects first: tools can update guidance files or contact remote services. Use file inspection or an approved isolated copy when the investigation must remain read-only.
4. Trace the target's dependencies and consumers, including generated schemas, shared configuration, native bindings, and files outside its directory.
5. Establish the requested result, allowed writes, behavior to preserve, and acceptance checks. For a performance request, measure representative baseline tasks and separate cold execution, warm execution, and cache restoration.

Done: the affected projects, installed toolchain, change boundary, and verification commands are known. Missing access or tools: report the unavailable evidence; continue safe inspection without installing a replacement or inventing a project graph.

2. Choose the smallest coherent structure

Retain the existing toolchain unless the request or observed limitations justify a change. Package management, task orchestration, and release management are different responsibilities; one tool need not own all three.

This is a decision aid, not a performance ranking. Compare the current approach with credible alternatives using actual tasks, platform support, maintenance cost, and acceptance checks before recommending adoption.

For new repositories, define deployable units and public library contracts first. Use ecosystem-compatible membership patterns; apps/, packages/, and tools/ are optional conventions. Extract shared code only for demonstrated consumers or a required independently owned contract, not hypothetical reuse. Share configuration where semantics match, preserving necessary project-specific compiler, framework, test, and runtime settings.

For migration, agree on history preservation, access restrictions, package-name conflicts, import rewrites, CI/release changes, and rollback before moving files. A shared repository is not a package-level access-control boundary.

Done: the proposed structure has a concrete reason, preserved contracts, and an authorized implementation path. If no structural change is needed, keep the current layout.

3. Make dependency and package boundaries explicit

1. Declare each project's runtime and build dependencies in the owning manifest or supported project graph. Hoisting, root installation, editor aliases, and incidental filesystem access are not evidence of a declared dependency.
2. Match local dependency syntax to the installed package manager. Where a local workspace package is required, enforce local resolution using supported configuration; do not assume workspace: works across all managers.
3. Import another package through its declared public API rather than relative paths into its source tree. For JS/TS, align exports, type entry points, module formats, and runtime conditions with actual consumer support. TypeScript path aliases alone do not establish runtime package resolution.
4. Choose whether consumers use source directly or consume built artifacts. Source consumption requires compatible consumer tooling; produced-file consumption requires explicit prerequisites satisfied by execution or valid restoration, with emitted files matching the package contract. Match distributed contents to the ecosystem: Cargo packages normally ship source, while a JS library may ship compiled modules, types, and assets.
5. Inspect transitive edges and detect cycles. Resolve new cycles at the owning boundary rather than hiding them with aliases, undeclared edges, or exclusions.
6. Preserve intentional dependency-version differences and peer constraints. Centralize compatible versions with existing mechanisms only when useful; do not force every project onto an incompatible shared version.
7. In mixed-language repositories, keep each ecosystem's native manifests, lockfiles, and validation. Represent cross-language generation and packaging edges explicitly; sharing a Git tree does not make JS tooling validate Rust, Python, or other language contracts.

When changing workspace resolution, consult the installed manager's documentation: pnpm workspaces (select the installed major), npm workspaces, or Yarn workspaces. For Rust workspace membership and inheritance, use Cargo workspaces.

Done: dependency edges are declared, public imports resolve through the intended local or published contract, and affected consumers are identified.

4. Make task execution and caching correct

Distinguish the project graph from the task graph. A project dependency identifies a relationship; a task dependency determines execution order.

For each changed task, establish its command, working directory, prerequisites, inputs, outputs, environment/runtime constraints, and side effects. Schedule upstream builds or generators when their artifacts are consumed. Source-only consumers may need upstream input tracking without an upstream build. Parallelize only independent tasks and keep concurrent writers out of the same output path.

Cache only results that are reproducible from tracked inputs. Include relevant source, shared configuration, dependency resolution, generated inputs, command options, environment values, and toolchain/platform differences. Inspect existing defaults before overriding input/output lists; configuration merging and automatic tracking differ by tool and version.

Separate dependency-download caches from task-result caches. Passing an environment variable to a process does not necessarily include it in the result's cache key. Keep publication, deployment, database mutations, and other external side effects outside result caching. Give long-running servers an explicit lifecycle rather than treating them as finite prerequisites.

For task or cache changes, use an isolated fixture or disposable output directory. Isolate cache storage and disable unapproved remote access/uploads; a force-run flag can bypass reads while still writing cache entries. Check the actual mode:

• Run with result-cache reads disabled and fresh owned outputs; inspect the files.
• Repeat unchanged inputs and observe the expected hit.
• Remove only owned disposable outputs and verify that a hit restores required files.
• Change relevant local, upstream, and environment inputs independently; require the expected invalidation and new result, restoring each mutation before the next.
• Introduce a failing assertion when changing test caching; require failure rather than replay of an earlier passing result, then restore the fixture.

These checks establish the exercised cases, not exhaustive cache correctness. Test remote restoration separately if remote reuse is part of the requested outcome.

For Turborepo configuration, read its task reference. For Nx hashing and restore behavior, read cache task results. For Vite+ projects, use the available vite-plus skill for installed command and tracking semantics; if unavailable, inspect installed help and owning documentation.

Done: task ordering and cache invalidation/restoration are observed, not inferred from a green cached log. If safe execution is unavailable, report the untested boundary and retain the proposed checks.

5. Select CI work and prepare releases safely

When changing CI:

1. Use the repository's pinned toolchain and supported locked/immutable install mode. Preserve ecosystem-specific checks and platform requirements.
2. Resolve and record the intended Git base/head and ensure the needed history is available. Select changed projects and affected downstream consumers; include prerequisite tasks needed to execute that selected work.
3. Check shared configuration, lockfile changes, generated contracts, and implicit dependencies. A folder-only filter can omit consumers outside that folder. Inspect the selected project/task list before treating the command as coverage.
4. If history, graph data, or selection is incomplete, repair it or use the required broader checks. An empty selection is acceptable only when explained by the diff.
5. Enforce remote-cache read/write trust boundaries. Untrusted contributions must not write artifacts consumed by trusted jobs or receive privileged credentials. Review cached outputs and logs for secrets and private data.

For affected-selection semantics, consult Nx affected execution or the installed runner's equivalent; do not translate filter syntax by analogy.

When package delivery is in scope, distinguish non-publishable units from libraries intended for a registry. Restricted registry access is not a non-publication flag. Preserve the established independent or coordinated versioning policy. Review API compatibility, dependent version ranges, changelogs, registry targets, and publication order. Inspect the installed release-tool major and configuration before selecting commands or defaults. Use existing release tooling; Changesets is an option, not a prerequisite.

Inspect packed artifacts and exercise relevant imports/types in an isolated consumer outside the workspace's dependency tree, with declared runtime/peer requirements and no source aliases or links back to the working tree masking defects. Review lifecycle scripts before packing or installing artifacts. Deployment bundles likewise need their actual runtime files and dependencies, not merely a successful workspace build.

Done: selected CI work covers the affected contracts and any release artifacts are verified. After partial publication, inspect actual registry state before retrying.

6. Verify and hand over

Run the project's required checks for the changed area, including affected consumers and the relevant build, type, boundary, package, or integration checks. Establish a failing regression first for a requested fix when safely reproducible. Run fresh execution where cache behavior could conceal the change.

For graph/CI-selection changes, exercise a leaf-only change, a shared dependency change, and a relevant root configuration or lockfile change. Require the expected project set and prerequisites, not just a successful command. For performance changes, compare the same workload and environment against the baseline; report execution time and cache behavior without equating hits with faster compilation.

Inspect the final scoped diff and untracked outputs. Return:

• Changed contracts and affected projects.
• Exact commands, tool versions, selected scope, results, and cache mode.
• Artifact/consumer evidence, remaining failures, and untested platforms or remote CI.
• Pending approvals or operations, with the next safe action.

Complete: the authorized outcome and required checks are satisfied. Incomplete: identify the missing evidence or operation; a valid configuration, cache hit, or local build alone does not establish end-to-end correctness.