improve-codebase-architecture

Scan a codebase for shallow modules and present deepening refactors as a visual HTML report.

Updated May 31, 2026
One-click install
npx skills add https://github.com/AlexanderNarbaev/agi --skill improve-codebase-architecture-alexandernarbaev
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/AlexanderNarbaev/agi/tree/main/.opencode/skills/matt-pocock/improve-codebase-architecture
Command: npx skills add https://github.com/AlexanderNarbaev/agi --skill improve-codebase-architecture-alexandernarbaev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, making them hard to test and navigate. This Skill surfaces those architectural friction points and proposes concrete deepening refactors, presented as a visual before/after report instead of a wall of prose. ## Core Features & Use Cases - Hot-spot-driven exploration: Scopes the scan using git history and user direction, then applies the deletion test to identify shallow modules, seam leakage, and poor locality. - Visual HTML report: Generates a self-contained HTML file in the OS temp directory using Tailwind and Mermaid via CDN, with before/after diagrams, recommendation-strength badges, and ADR conflict callouts for each candidate. - Grilling loop: After the user picks a candidate, walks the decision tree on constraints, dependencies, and module shape, updating CONTEXT.md and offering ADRs as decisions crystallize. - Use Case: Point it at a subsystem where changes keep hurting; it returns a report showing, for example, how collapsing a six-layer call pipeline into one deep module shrinks the test surface to a single interface. ## Quick Start Ask the assistant to review the architecture of the current repository and show deepening opportunities as an HTML report.

Frequently Asked Questions about improve-codebase-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find shallow modules in my codebase?

Run this Skill to scan recent git history for hot spots, then apply the deletion test: if deleting a module would concentrate complexity rather than move it, the module is shallow. Candidates are presented with before/after diagrams in an HTML report.

What is a deep module versus a shallow module?

A deep module has a small interface hiding a substantial implementation, while a shallow module's interface is nearly as complex as its implementation. The Skill uses this vocabulary from the codebase-design glossary to evaluate every candidate refactor.

Where does the architecture review report get saved?

The report is written as a self-contained HTML file to the OS temp directory, resolved from $TMPDIR with fallback to /tmp or %TEMP%, named architecture-review-<timestamp>.html. Nothing is written into the repository itself.

Does the review respect existing ADRs?

Yes, ADRs in docs/adr/ are read before scanning and candidates that contradict them are normally suppressed. A conflicting candidate is only surfaced with a warning callout when the friction is real enough to warrant reopening the decision.

What happens after I pick a candidate from the report?

The Skill enters a grilling loop that walks constraints, dependencies, and the shape of the deepened module. It updates CONTEXT.md with new domain terms and offers to record an ADR when a candidate is rejected for a load-bearing reason.