improve-architecture

Installation
SKILL.md

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 tdd and write-design 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.

Installs
51
GitHub Stars
1
First Seen
Jul 7, 2026
improve-architecture — jayden-dang/skills