Skill · Workflow
Monorepo Boundary Auditor
Audit a monorepo's package boundaries, dependency direction, public entry points, ownership, build graph, and affected-test rules, then report cycles and cross-layer imports with a staged repair plan. Use when packages are tightly coupled, builds invalidate too much, teams import internals, dependency cycles appear, or a monorepo migration needs enforceable architecture boundaries.
User-invocablev1.0.0
Updated Aug 4, 2026npx agentscamp add skills/monorepo-boundary-auditorInstall to ~/.claude/skills/monorepo-boundary-auditor/SKILL.md
Audits workspace packages as an architecture graph: discovers declared and source-level dependencies, checks allowed layer direction and public entry points, finds cycles and deep imports, evaluates ownership and affected-build accuracy, and proposes a staged boundary repair with automated lint or graph rules. It reports evidence without performing a risky repository-wide rewrite.
Audit structure and recommend repairs without editing the repository. Treat declared manifests and real source imports as separate evidence because either can be stale.
Workflow
- Discover workspaces. Read root and package manifests, workspace configuration, task runner files, path aliases, project references, ownership files, and package entry points. Build a package inventory with purpose and owner.
- Construct the dependency graph. Combine declared dependencies with actual imports, code generation, build-time inputs, and task dependencies. Distinguish runtime, development, type-only, and optional edges.
- Infer or read intended layers. Identify applications, features, domain packages, platform/infrastructure, shared libraries, tooling, and generated code. Record allowed dependency direction and flag places where no intended architecture is documented.
- Check public interfaces. Find deep imports into another package's source or private paths, undeclared dependencies, duplicate aliases, barrel files that expose internals, and packages with unstable or oversized public surfaces.
- Find cycles and coupling hotspots. Report strongly connected components, packages with high fan-in or fan-out, and changes that invalidate unrelated builds. Explain the runtime and ownership consequence of each.
- Audit task and cache boundaries. Verify build inputs, outputs, environment variables, generated files, and affected-test calculation. Flag tasks that miss dependencies or invalidate the whole graph unnecessarily.
- Check ownership alignment. Identify packages with no owner, several teams changing the same internal surface, or a boundary that contradicts deployment and support responsibility.
- Design staged repairs. Prefer public entry points, dependency inversion, interface packages, moved shared types, or extracted modules. Sequence changes so the graph remains buildable and avoid a repository-wide flag day.
- Propose enforcement. Recommend import lint rules, workspace constraints, dependency-cruiser or graph checks, ownership rules, and affected-build tests appropriate to the existing toolchain.
WARNING
Do not recommend moving code into shared merely to break a cycle. A shared dumping ground erases ownership and often creates a larger cycle. Place abstractions with the domain that owns the contract.
Output
Return:
- package inventory with layer, owner, entry point, and dependency types
- dependency graph or Mermaid diagram
- findings ordered by architectural and build impact, with concrete import paths
- cycles and coupling hotspots with runtime versus type-only classification
- staged repair plan preserving buildability
- enforcement rules and affected-build verification
- unresolved ownership or intended-layer questions
Frequently asked questions
- What is a monorepo boundary?
- It is an enforceable rule about which package or layer may depend on another and through which public interface. Boundaries keep shared code reusable without allowing every workspace to reach into every other's internals.
- Are all dependency cycles equally harmful?
- No. A type-only development cycle may be less urgent than a runtime cycle that changes initialization order or forces broad rebuilds. Prioritize cycles by runtime impact, change coupling, ownership, and how many packages they pull into affected builds.
Related
- 9 Best Claude Skills for Code ReviewChoose Claude skills for security, correctness, maintainability, and focused pull request review without relying on one vague review prompt.
- Circular Dependency BreakerDetect and break a circular import — map the exact cycle with a real tool, then break the right edge by extracting the shared piece into a leaf module, inverting a layering dependency, merging two falsely-split modules, or (last resort) deferring an import. Use when you hit an import cycle error, an undefined-on-import or 'cannot access before initialization' bug, or a bundler/linter flags a cycle.
- Extract ModuleSplit an overgrown file into cohesive, well-bounded modules — find the natural seams, design each new module's public interface before moving a line, then relocate one unit at a time keeping tests green. Use when a file has grown too large, mixes unrelated responsibilities, or every change to it forces unrelated diffs and merge conflicts.
- GitHub Actions OptimizerMake a GitHub Actions workflow faster, cheaper, and harder to attack — by profiling where wall-clock and billed minutes actually go, then adding content-keyed caching, matrix/job parallelism, run-cancellation, and path filters, and hardening the supply chain (SHA-pinned actions, least-privilege GITHUB_TOKEN, safe fork-PR handling). Use when CI is slow or queues, when a repo burns Actions minutes, or before trusting a workflow that runs on untrusted pull requests.
- Dependency Upgrade PlannerPlan and de-risk a major dependency, framework, or runtime upgrade — map the full version path, read every intermediate migration guide, and pin the breaking changes to your actual call sites instead of bumping the number and hoping. Use when a key dependency is several majors behind, when a security advisory forces an upgrade, or before a framework migration.
- System ArchitectUse this agent for high-level system design — service boundaries, data flow, scaling, trade-offs. Examples — designing a new system, evaluating a monolith-to-services split, a scalability review.