scan-architecture
Improve the Architecture
Scan the codebase for accumulated friction, present deepening candidates as a visual report, and carry the one the user picks into the normal spec cycle. The goal is testability and navigability — modules deep enough that their interface is the test surface.
Vocabulary is strict throughout: module, interface, implementation, seam, adapter (plus depth/locality/leverage as qualities) — a seam is a public surface where behavior is both observable and substitutable (the same seam test-first and design-solution name). Never drift into "component", "service", "layer", or "boundary" — precision in the nouns is what keeps the findings comparable run over run.
1. Explore for friction
Read CONTEXT.md (the domain names good seams) and docs/adr/ (decisions not to re-litigate) first. Then dispatch an explore subagent to walk the codebase organically — no rigid checklist, just note where work hurts:
- Shallow modules — an interface nearly as complex as the implementation behind it
- Poor locality — one conceptual change fans out across many files
- Missing or weak seams — places substitution is needed but impossible, or a seam exists with only one hypothetical adapter
- Untested-through-interface — code only testable by reaching past its interface into internals
Apply the deletion test to anything suspect: if this module vanished, how much would its callers need to know to rebuild the behavior? "Almost everything" means the module was shallow — deleting it would concentrate complexity rather than lose it. That concentration point is your candidate.
Done when: you hold 3–7 candidates, each tied to specific modules and a named kind of friction.