arch3rPro/dsh-skills / skills/architecture/module-layering
module-layering
VerifiedKnow and enforce your module dependency graph — derive inter-module edges from the canonical dependency signal, catch circular dependencies, and enforce intended layering with tooling. Use when a codebase has many modules or packages and layering is a real concern.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.8 KB |
| agents/openai.yaml | config | 305 B |
SKILL.md
View on GitHub---
name: module-layering
status: beta
description: "Know and enforce your module dependency graph — derive inter-module edges from the canonical dependency signal, catch circular dependencies, and enforce intended layering with tooling. Use when a codebase has many modules or packages and layering is a real concern."
---
# Module Layering
A discipline for **knowing and enforcing the dependency graph** of a multi-module or multi-package codebase. It keeps the intended layering explicit, surfaces circular dependencies, and makes a violation fail instead of silently drifting.
**The defining constraint:** derive the graph from the **canonical dependency signal** — the single authoritative statement of what each module depends on (a package manifest's peer dependencies, a module's declared imports) — rather than from ad hoc inspection. Enforce intended direction with tooling, not memory.
## Know the graph
- **Identify the canonical dependency signal** for each module: the declared peer/regular dependency for packages, or the module imports for in-repo modules.
- **Derive the inter-module edges** from that signal, grouped by the package or module hierarchy, so the graph is reproducible rather than hand-maintained.
- **Keep the graph as a documented artifact** (a module-graph page or generated report) so it is the single home for dependency facts.
## Enforce layering
- **Decide the intended layering** — which modules may depend on which. State it explicitly (a layering rule per layer), not implicitly.
- **Detect circular dependencies** — a cycle means no clear layer boundary and is a signal to re-examine ownership.
- **Enforce with tooling** (e.g. a dependency-cruiser or graph analyzer), running in the check gate so a new edge that violates the intended direction fails rather than silently drifting.
## When it applies
Reach for this when a codebase has enough modules or packages that dependency relationships are non-trivial — multiple packages, a plugin ecosystem, or a layered architecture where the direction of dependencies matters. A single small module does not need a graph.
## Workflow
1. **Confirm the concern** — enough modules that layering matters; if not, skip.
2. **Identify the canonical dependency signal** and derive the edges.
3. **State the intended layering** explicitly, per layer.
4. **Enforce with tooling** in the check gate; treat a circular dependency or an edge against the intended direction as a failure.
5. **Keep the graph as a documented artifact**, updated with the code.
## Completion criteria
- Edges are derived from the canonical dependency signal, not ad hoc inspection.
- Intended layering is explicit; circular dependencies are surfaced.
- Layering is enforced by tooling in the check gate, so violations fail.
- The graph is a documented artifact and the single home for dependency facts.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |