improve-codebase-architecture

Scan a codebase for module deepening opportunities and present them as a visual HTML report.

Updated Jul 3, 2026
One-click install
npx skills add https://github.com/alex-jordan547/agent-setup --skill improve-codebase-architecture-alex-jordan547
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/alex-jordan547/agent-setup/tree/main/archive/2026-09-10/improve-codebase-architecture
Command: npx skills add https://github.com/alex-jordan547/agent-setup --skill improve-codebase-architecture-alex-jordan547

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, presented visually rather than as a wall of text. ## Core Features & Use Cases - Architecture exploration: Delegates a read-only codebase walk to find shallow modules, seam leakage, poor locality, and untestable areas, applying the deletion test to validate candidates. - 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. - Guided design grilling: After the user picks a candidate, runs a grilling loop to walk the design tree, updating CONTEXT.md and offering ADRs as decisions crystallize. - Use Case: Point it at a service codebase where order handling is scattered across six thin wrappers; it produces an HTML report showing how to collapse them into one deep module with a single testable interface. ## Quick Start Ask the agent to review this repository's architecture 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 delegate a read-only exploration of the codebase that flags modules whose interface is nearly as complex as their implementation. It applies the deletion test to confirm whether removing a module would concentrate complexity rather than just move it.

How to visualize architecture refactoring proposals?

The Skill writes a self-contained HTML report to the OS temp directory using Tailwind and Mermaid from CDNs. Each candidate gets a card with files, problem, solution, benefits, a before/after diagram, and a recommendation-strength badge.

Does the architecture review modify my repository files?

The HTML report is written to the OS temp directory, not the repo, so nothing lands in your project. During the grilling phase it may update CONTEXT.md or offer to record an ADR, but only as explicit side effects of design decisions.

What happens if a proposal contradicts an existing ADR?

Candidates that contradict an ADR are only surfaced when the friction is real enough to warrant revisiting the decision. The card is marked with a warning callout referencing the ADR, and theoretical refactors an ADR forbids are not listed.

When should I not use this architecture review approach?

It is not suited for greenfield design with no existing code to explore, since it depends on reading CONTEXT.md, ADRs, and actual module structure. It also deliberately avoids proposing interfaces before the user picks a candidate from the report.