Improve Codebase Architecture

Improve Codebase Architecture surfaces architectural friction and proposes "deepening opportunities" - refactors that turn shallow modules (interface nearly as complex as the implementation) into deep ones, aimed at testability and AI-navigability. It is built on the /codebase-design skill's shared vocabulary - module, interface, depth, seam, adapter, leverage, locality - and its principles, including the deletion test (would deleting a piece concentrate complexity elsewhere, or just move it?) and "one adapter is a hypothetical seam, two is a real one." It uses these exact terms in every suggestion rather than drifting into generic words like "component" or "service."

Use it when the request matches scanning a codebase for deepening opportunities and presenting them visually before discussing any one in depth. It is informed by the project's actual domain model and existing decisions - it reads CONTEXT.md and relevant ADRs in docs/adr/ first and will not re-litigate decisions already recorded there, only surfacing an ADR conflict when the friction is real enough to genuinely warrant reopening it.

Exploration uses the Agent tool's Explore subagent type to walk the codebase organically - not against rigid heuristics - looking for concepts requiring bouncing between many small modules, shallow interfaces, pure functions extracted for testability while real bugs hide in their call sites (a locality failure), and untested or hard-to-test seams. Findings are written as a self-contained HTML file to the OS temp directory (never the repo), at <tmpdir>/architecture-review-<timestamp>.html, opened automatically (xdg-open/open/start per OS) using Tailwind and Mermaid via CDN plus hand-crafted CSS/SVG for editorial visuals. Each candidate renders as a card: affected files, the problem, the plain-English solution, benefits framed in terms of locality and leverage, a before/after diagram, and a recommendation-strength badge (Strong, Worth exploring, Speculative), with a CONTEXT.md-named domain concept ("the Order intake module," not "FooBarHandler") throughout. The report ends with a top recommendation and a question - it deliberately does not propose actual interfaces yet.

<tmpdir>/architecture-review-<timestamp>.html

Once the user picks a candidate, it hands off to the /grilling skill to walk the design tree (constraints, dependencies, the deepened module's shape, what sits behind the seam, which tests survive), while /domain-modeling keeps CONTEXT.md current inline - adding newly-named concepts, sharpening fuzzy terms as they're resolved, and offering to record a rejected candidate as an ADR only when the rejection reason would genuinely help a future architecture review avoid re-suggesting it. Exploring alternative interfaces for the chosen module can invoke /codebase-design's "design-it-twice" parallel sub-agent pattern.

Engineers and teams who want a visual, before/after-illustrated architecture review that identifies where a codebase is shallow rather than deep, then walks the chosen refactor through a structured design conversation that keeps the project's glossary and decision log current as it happens.