improve-codebase-architecture

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

Updated Jul 31, 2026
One-click install
npx skills add https://github.com/julianckt/adoptarun --skill improve-codebase-architecture-julianckt
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/julianckt/adoptarun/tree/main/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/julianckt/adoptarun --skill improve-codebase-architecture-julianckt

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 instead of leaving them buried in the code. ## Core Features & Use Cases - Hot-spot exploration: Scopes the review using git history and user direction, then explores the codebase for shallow modules, seam leakage, and poor locality. - Visual HTML report: Renders each candidate refactor as a self-contained HTML file with Tailwind and Mermaid before/after diagrams, recommendation-strength badges, and ADR conflict callouts, written to the OS temp directory. - Grilling loop: After the user picks a candidate, walks the decision tree on constraints, seams, and tests, updating CONTEXT.md and offering ADRs as decisions crystallize. - Use Case: A team notices their order intake flow is spread across six thin wrappers. Run this Skill to get a visual report of deepening candidates, pick one, and grill through the design before writing any code. ## Quick Start Ask the assistant to review this codebase for architecture improvements and show the deepening candidates 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 explore the codebase for modules whose interfaces are nearly as complex as their implementations. It scopes the search using recent git history hot spots, then applies the deletion test to confirm which modules are genuinely shallow.

How to visualize architecture refactoring candidates?

The Skill writes a self-contained HTML report to the OS temp directory and opens it in your browser. Each candidate gets a before/after diagram built with Mermaid or hand-crafted SVG, plus problem, solution, benefits, and a recommendation-strength badge.

Does the architecture review respect existing ADRs?

Yes, it reads ADRs in docs/adr/ before proposing changes and avoids re-litigating recorded decisions. If a candidate contradicts an ADR, it is only surfaced with a clear warning callout when the friction justifies reopening the decision.

What happens after I pick a refactoring candidate?

The Skill runs a grilling loop that walks the decision tree: constraints, dependencies, the shape of the deepened module, and which tests survive. It updates CONTEXT.md with new domain terms and offers to record load-bearing rejections as ADRs.

Where does the architecture report get saved?

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