improve-codebase-architecture

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

3|Updated Jan 10, 2026
One-click install
npx skills add https://github.com/MaxWolf-01/agents --skill improve-codebase-architecture-maxwolf-01
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/MaxWolf-01/agents/tree/main/mx/skills/improve-codebase-architecture
Command: npx skills add https://github.com/MaxWolf-01/agents --skill improve-codebase-architecture-maxwolf-01

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 that architectural friction and proposes concrete deepening refactors instead of leaving the analysis as vague intuition. ## Core Features & Use Cases - Scoped exploration: Uses recent commit history to find hot spots, then spawns an Explore subagent to detect shallow modules, seam leakage, and untestable entry points. - Visual HTML report: Renders each refactor candidate as a self-contained HTML file with Tailwind and Mermaid before/after diagrams, recommendation-strength badges, and ADR conflict callouts. - Grilling loop: After the user picks a candidate, walks the decision tree on constraints, seams, and tests, updating CONTEXT.md and offering ADRs for load-bearing rejections. - Use Case: Point it at a service where pricing logic leaks across modules; it produces a report showing the leakage in red on a dependency graph and proposes collapsing the pipeline into one deep module. ## Quick Start Ask the agent to review the architecture of the order intake subsystem 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 commit history for hot spots, then explore for modules whose interface is nearly as complex as their implementation. It applies the deletion test: if deleting a module would concentrate complexity rather than move it, that module is a deepening candidate.

How to visualize architecture refactoring proposals?

The Skill writes a self-contained HTML report using Tailwind and Mermaid from CDNs. Each candidate gets a before/after diagram, a recommendation-strength badge, and a one-sentence problem and solution, saved outside the repo in a temp directory.

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 nearly matches its implementation. The Skill uses this vocabulary from its companion codebase-design command and applies it consistently in every suggestion.

Does the architecture review respect existing ADRs?

Yes, it reads ADRs in the decisions directory before proposing changes. A candidate that contradicts an ADR is only surfaced when the friction justifies reopening it, and the card is marked with a warning callout referencing the ADR.

When should I not run an architecture deepening review?

Skip it for parts of the codebase that rarely change, since deepening pays off by easing future modifications. The Skill scopes by recent commit activity for this reason, and purely speculative refactors with no real friction are filtered out.