Improve Codebase Architecture

Surface architectural friction and propose deepening opportunities: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

Load and apply codebase-design for the architecture vocabulary and principles this command is built on. If it is not installed, tell the user and use the deep-module vocabulary it draws on: Ousterhout's module, interface, depth, deep, and shallow; Feathers's seam; adapter, leverage, and locality; the deletion test below; the dependency categories in-process, local-substitutable, ports & adapters, and mock; and, for design-it-twice, sketching two contrasting interfaces before choosing one. Name everything in two vocabularies: codebase-design's terms, used exactly, for the architecture, and the selected domain glossary's terms for the domain. If the glossary defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."

Process

1. Explore

Scope before you scan, taking the scope from what the invocation names:

• Direction: the user named a module, a subsystem, or a pain point. Take it. The scan is complete when every module it involves has been checked.
• Change set: the user named a PR, a commit or commit range, a branch, or their current changes. Start from the diff and read outward, looking for friction the change ran into as well as friction it introduced: one concept forcing edits across many modules (no locality), a new caller repeating setup around a shallow module, a change routing around an existing seam because its interface did not fit. The scan is complete when every module the change touches, its callers, and sibling modules that solve the same problem have been checked.
• Whole codebase: the user named nothing. A working tree with uncommitted edits still gets this scope. Split the codebase into areas (top-level packages or directories) and scan every one. Deepening a module pays off by making future changes to it easier (YAGNI), so walk back a good stretch of the commit history (git log --oneline) to find the hot spots, the files and areas that keep coming up: scan them first, and count their churn toward their candidates' recommendation strength. The scan is complete when every area has been checked.

Scan in the current agent. When the scope is too large to read in one context, split it into areas and delegate each area to a subagent with a fresh context window. Give it the area, the selected scope's bullet with what the user named, the rest of this step, and the codebase-design vocabulary. Each subagent returns the candidates in its area that pass the deletion test, with their files, the friction, and the proposed deepening, and lists any friction that crosses into another area. Follow up each cross-area friction in the current agent before presenting candidates.

Read the File structure section of the installed domain-modeling/SKILL.md (without that skill, use the paths docs/agents/domain.md records, else the root GLOSSARY-MAP.md or GLOSSARY.md, or legacy CONTEXT-MAP.md or CONTEXT.md) to select the glossary, map, and ADR paths. Read the selected glossary and the area's ADRs as read-only context before exploring. References to GLOSSARY.md below mean the selected glossary.