Module Boundary Design

module-boundary-design

Registry Trigger

Use when

• Module ownership, public/private surface, dependency direction, cycles, shared state, or a module split, merge, or move changes.

Do not use when

• The change stays inside one established module without changing its consumers, state authority, exports, or dependency edges.

Skill Role

Define cross-module responsibility, state ownership, contractual surface, dependency direction, cycles, and split or merge decisions. Exclude system style, fixed-layer rules, model translation, and owner-internal placement.

Task-agent owner-internal placement belongs to implementation-structure-design.

High-Value Rules

• boundary-kind is plain directory | language package/module | build target/package | distributable SDK/library | runtime/service, and its decision record names the authoritative mechanism and enforcement owner. A directory name is insufficient evidence of ownership.
• Anchor the boundary in one coherent responsibility with an accountable owner, invariant or policy authority, source of truth, and state lifecycle; folder names and team charts are selectors, not the boundary.
• Derive the public surface from verified consumers and their semantics, failures, compatibility, and versioning needs; keep repositories, persistence shapes, helpers, and mutable internals private without a proven contract.
• This capability owns in-repository responsibility, state authority, dependency direction, and public/private surface selection. For a distributable SDK/library, sdk-library-contract-design owns compatibility, migration, and external consumer proof while this capability retains state and dependency direction.
• Draw allowed and forbidden dependency edges before moving code. Resolve a cycle by relocating authority, introducing an owner-controlled contract, or changing coordination; a shared type does not remove the runtime cycle.
• Assign mutation and consistency authority for state crossing the boundary. Reject shared mutable state, direct reads of another module's storage, and writes that bypass the owning contract.
• Split when responsibility, invariant lifecycle, release/change reason, or consumer contract can vary independently without a cycle; merge when separation creates pass-through ownership or hidden coordination.
• Enforce the selected surface and edges with the authoritative language, build, package, or runtime mechanism; name the enforcement owner and expose unproved generated, dynamic, plugin, and runtime edges.

Anti-Patterns

• Treating a framework, layer name, directory layout, file count, or coupling score as sufficient boundary proof.
• Moving business policy into shared, common, or utils to avoid choosing its owner.
• Publishing a facade that re-exports internals or mirrors another module without owning semantics.
• Renaming a cycle as a callback or event while state, ordering, failure, or retry ownership stays circular.

Stop Conditions

Stop when state or source authority is unresolved, a required edge creates a cycle, a breaking surface has unknown consumers, or owners dispute mutation, compatibility, migration, or incident responsibility.

Output Contract

• Module boundary decision with boundary-kind, authoritative mechanism, enforcement owner, responsibility and state authority, public/private surface, consumers, allowed/forbidden edges, cycle result, split/merge rationale, migration, evidence, proof limits, and residual risks.

Targeted References