improve-codebase-architecture

Detects shallow modules and proposes surgical architecture-deepening refactors grounded in project documentation.

Updated Jun 2, 2026
One-click install
npx skills add https://github.com/MohamedSayedK/omnigrid --skill improve-codebase-architecture-mohamedsayedk
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/MohamedSayedK/omnigrid/tree/main/assets/core/skills/improve-codebase-architecture
Command: npx skills add https://github.com/MohamedSayedK/omnigrid --skill improve-codebase-architecture-mohamedsayedk

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules, tight coupling, and leaky boundaries that make them hard to test and navigate, and generic refactoring advice often ignores the project's own documented decisions. This Skill finds architecture-deepening opportunities that are grounded in the project's own domain language and ADRs. ## Core Features & Use Cases - Documented-model grounding: Reads OMNIGRID-CONTEXT.md and omnigrid/artifacts/adrs/ so every proposal uses the project's glossary terms and respects locked architectural decisions. - Shallowness scanning: Detects tight coupling, leaky boundaries, shallow modules, test resistance, and AI-navigation friction, each anchored to a concrete file:line location. - Surgical deepening proposals: Produces a prioritized list of minimal, independently shippable refactors with the signal removed, the payoff, and the ADR relationship. - Use Case: After a codebase grows organically, run this Skill to get a prioritized list of consolidation and extraction moves that feed directly into the grill-with-docs → to-prd → to-issues feature flow. ## Quick Start Ask the agent to analyze this repository for architecture-deepening opportunities using the documented domain model and ADRs, and produce a prioritized refactoring list.

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 refactoring opportunities in a large codebase?▼

Scan for shallowness signals: tight coupling between modules, leaky boundaries, wide interfaces over thin implementations, and units that resist testing. This Skill anchors each finding to a file:line location and proposes the smallest change that deepens the module.

What is a deep module versus a shallow module?▼

A deep module hides complexity behind a narrow interface, while a shallow module has a wide interface over little implementation, often many small pass-through functions. The Skill hunts shallow modules and proposes deepenings that move complexity behind a seam.

How does this Skill use ADRs when proposing refactors?▼

Every proposal must respect decisions recorded in omnigrid/artifacts/adrs/ or explicitly argue for reopening one. A refactor that silently contradicts a locked decision is rejected before it is proposed.

Can I use this without OMNIGRID-CONTEXT.md documentation?▼

The method is designed to ground proposals in the project's documented glossary and ADRs, so it expects those files to exist. Without them, proposals lose the documented-model grounding that distinguishes this from generic best-practice advice.

What are the limitations of automated architecture review?▼

The Skill proposes surgical, independently shippable deepenings rather than large rewrites, so it will not produce whole-system redesigns. Proposals still require human judgment on prioritization and on whether an ADR should be reopened.