I

improve-codebase-architecture

bymattpocock·#7 trending

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

183,100stars
First seenMar 13, 2026

Installation

Send this command to your AI agent:

npx skills add https://github.com/mattpocock/skills --skill improve-codebase-architecture

Documentation

Analyze codebases for architectural friction and propose module-deepening refactors as testability improvements.

  • Explores codebases organically to surface shallow modules, tightly-coupled components, and untested seams rather than following rigid heuristics
  • Applies John Ousterhout's "deep module" principle: small interfaces hiding large implementations for better testability and AI navigability
  • Generates multiple radically different interface designs (minimalist, flexible, caller-optimized, ports & adapters) via parallel sub-agents, then recommends the strongest approach
  • Creates GitHub issue RFCs documenting the problem space, design trade-offs, and refactoring rationale