improve-codebase-architecture

Scan codebases for architectural friction and generate HTML reports with before/after diagrams.

3|1|Updated Nov 5, 2015
One-click install
npx skills add https://github.com/Flowm/dotfiles --skill improve-codebase-architecture-flowm
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/Flowm/dotfiles/tree/main/home/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/Flowm/dotfiles --skill improve-codebase-architecture-flowm

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill eliminates the guesswork of improving codebase architecture by automatically identifying shallow modules, cross-seam leakage, and other friction points that reduce testability, maintainability, and AI navigability of software projects.

Core Features & Use Cases

  • Architectural Friction Scanning: Organically explores codebases to flag shallow modules, untested hard-to-test components, and tightly coupled code that leaks across seams.
  • Visual HTML Report Generation: Creates a self-contained, styled HTML report with before/after diagrams of proposed deepening refactors, including Mermaid flowcharts, mass diagrams, and cross-sections to illustrate changes clearly.
  • Guided Refinement Loop: Walks users through a structured grilling process to refine their chosen refactor, integrates with domain modeling to update project context, and respects existing ADRs to avoid re-litigating settled decisions.
  • Use Case: A software team struggling with a hard-to-test order processing module can use this skill to get a prioritized list of refactors, visual explanations of each change, and guided support to implement the highest-impact improvement.

Quick Start

Use the improve-codebase-architecture skill to scan your current project's codebase and generate a visual report of prioritized architecture improvement opportunities.

Frequently Asked Questions about improve-codebase-architecture

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

FAQPage Schema
How do I identify shallow modules and cross-seam leakage in my codebase?

To identify shallow modules and cross-seam leakage, scan your codebase to detect architectural friction that reduces testability and AI navigability. This process organically explores your project structure to flag tightly coupled code leaking across seams, outputting a prioritized list of low-effort, high-impact refactors.

What is the best way to visualize codebase architecture refactoring before and after changes?

Visualize codebase architecture refactoring by generating a self-contained HTML report with before and after diagrams. This report includes styled Mermaid flowcharts, mass diagrams, and cross-sections to illustrate proposed deepening refactors and clearly explain structural changes.

How do I prioritize refactoring tasks to improve codebase maintainability?

Prioritize refactoring tasks to improve maintainability by scanning for architectural friction and applying a guided grilling loop. This loop walks you through structured refinement to select and implement low-effort, high-impact changes that deepen module structure and long-term testability.

Can I scan any software engineering project size for architectural improvements?

Yes, you can scan software engineering projects of any size for architectural improvements. The scanning process organically explores the codebase without rigid size constraints, effectively identifying shallow modules and hard-to-test components regardless of total project scale.

Does codebase architecture scanning respect existing Architecture Decision Records?

Yes, codebase architecture scanning respects existing Architecture Decision Records to avoid re-litigating settled decisions. It integrates domain modeling to update project context while ensuring identified refactoring candidates align with established technical constraints.