improve-architecturelisted
Install: claude install-skill svyatov/agent-toolkit
# Improve Codebase Architecture
Explore a codebase, surface architectural friction, and propose module-deepening refactors with mandatory cohesion checks and test writing. Starts with an assessment — if the architecture is already healthy, say so and stop.
**Architecture vs Refactoring:** This skill handles structural changes — module boundaries, interfaces, testability. If the problem is code-level (complexity, duplication, naming, dead code within a well-bounded module), that's refactoring, not architecture — recommend handling it separately (via the `refactor` skill if installed). The same applies after completing an architectural change: cleaning up the new module's internals is a separate refactoring pass.
## What is a deep module?
A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside.
**Shallow** (before): `UserValidator` calls `isEmail()`, `isStrongPassword()`, `isUniqueUsername()` — each in its own file. The interface (3 functions) is as complex as the implementation. Tests mock the database to test `isUniqueUsername` in isolation, but the real bugs live in how these are composed during registration.
**Deep** (after): `UserRegistration` exposes `register(credentials) → Session | Error`. Internally it delegates to focused collaborators (validator, password hasher, session store), but callers do