kit-monorepo-change
Make a change in a monorepo or multi-module workspace (pnpm, npm, or yarn workspaces, Turborepo, Nx, Go workspaces with go.work, uv workspaces, or Cargo workspaces) by finding the package that owns th
SKILL.mdregistry/skills/monorepo-change/SKILL.md
GitHubMonorepo change
1. Map the workspace
- Identify the tool and its configuration:
pnpm-workspace.yaml,workspacesinpackage.json,turbo.json,nx.json,go.work,[tool.uv.workspace]inpyproject.toml, or[workspace]inCargo.toml. Read root and package scripts and project instructions for the documented commands. - Find the package that owns the code to change and the packages that depend on it:
pnpm why/pnpm ls --filter ...<pkg>,nx graphornx show projects --affected,turbo run <task> --filter=...<pkg> --dry, a search for imports of the module path in the othergo.workmodules,uv tree --invert --package <pkg>,cargo tree -i <crate>, or a search for imports of the package name.
2. Change within boundaries
- Change the owning package and import other packages only through their public entry points (
exports, the module path, the published crate API), never by reaching into another package'ssrcor internal directories. - Declare every new cross-package dependency in the consuming package's manifest using the workspace protocol the repo uses (
workspace:*, a path or workspace dependency inpyproject.tomlorCargo.toml; in a Go workspace thego.workuseentry is enough, and arequirewith a real version orreplaceis only needed for builds outside the workspace), then refresh the lockfile with the tool (pnpm install,npm install,uv lock,cargo check); never hand-edit lockfiles. - When a change alters a package's public API, update all dependents in the same change or keep the old API working, and say which packages were affected.
- Put a dependency in the package that uses it, not the workspace root, unless the repo keeps shared dev tooling at the root.
3. Verify what is affected
- Run the build, type check, and tests for the owning package and its dependents with the workspace tool:
pnpm --filter ...<pkg> run test(the package and its dependents),turbo run test --filter=...[origin/main],nx affected -t test,go test ./...in each affected module orgo test example.com/mod/...,uv run --package <member> pytest,cargo test -p <crate>. - Use the repository's own scripts when they exist; package-level commands sometimes only work from the root script. If shared configuration, the lockfile, or a widely used package changed, run the full workspace checks.
4. Report
Summarize the packages changed and why, dependents updated, dependency and lockfile changes, the commands run with results, and anything that needs a release (see kit-monorepo-release).
Examples
- Use: "Add a currency field to the shared money package and use it in billing." "Fix the date bug in packages/utils." "Rename this function used across services."
- Skip: "Create a new packages/notifications package." (kit-monorepo-package) "Bump versions for the release." (kit-monorepo-release)