module-craft

The architecture sibling of ui-craft: where the craft rules attach themselves to anything a user sees, these attach themselves to anything another module sees — a new module, a moved seam, a changed export, a public interface gaining or losing a promise.

When it loads

Model-invoked, on its own, whenever work touches a module boundary: creating a module, moving code across one, changing a public interface's shape or promises, deciding where a seam goes or what a layer owns. It stays loaded for the whole task. The user never has to ask.

The vocabulary

• A deep module is a small interface hiding a large commitment: lots of functionality behind few, stable promises. A shallow module is the smell — a wide interface over thin logic, forcing every caller to know everything. Depth is the aim; surface is the cost.
• A seam is where two parts are allowed to know about each other. Seams go where change actually accumulates, not where a diagram looks balanced; a seam placed over a rumor of future need is a shallow module waiting to happen.
• An interface promises — every public surface is a promise someone else's code now depends on. Widening is easy and permanent; narrowing is a breaking change. Default to the narrowest promise that today's callers need.
• A module owns its data and the operations on it. When callers reach in to operate on a module's data themselves, the boundary has leaked — move the operation inside and export the verb.

Precedence

The repo's own architecture conventions lead — where the target repo has pinned patterns, layering rules, or an ADR about structure, they replace these defaults wherever the two disagree, and code extends the repo's conventions rather than inventing beside them. This skill informs; the repo decides. A conflict between a ticket and a recorded architecture decision goes in front of the user, never silently around.