gs-modularity-maturity-assessor_skill

Overview

This skill assesses a codebase for Clean Architecture compliance and computes a maturity score. It focuses on dependency direction, entity design, repository and use-case patterns, DI usage, and action thinness. The output highlights critical violations, prioritized findings, and concrete recommendations for improvement.

How this skill works

The assessor runs static checks and heuristics against source directories to detect violations of the Dependency Rule, backend-framework coupling, and direct instantiation. It inspects entity files for private constructors and validate() methods, checks use-case shapes (execute()), validates repository interfaces versus implementations, and measures action handler sizes. Scores are weighted by principle importance and auto-fail conditions reduce the final maturity level.

When to use it

• Before merging major architectural changes or refactors
• As part of CI to prevent regression of architectural boundaries
• During technical debt audits to prioritize remediation work
• When onboarding teams to enforce consistent domain/infrastructure separation
• To track progress across releases toward higher architecture maturity

Best practices

• Enforce the Dependency Rule: inner layers must not import outer layers
• Keep entities as behavior-rich domain objects with private constructors and validate() logic
• Register concrete implementations in a DI container instead of direct instantiation
• Keep action/handler functions thin (<15 lines) and push behavior into use cases
• Define repository interfaces in the domain and implement them in infrastructure
• Fail CI on critical violations so regressions are caught early

Example use cases

• CI gate that fails pull requests if domain imports outer layers or backend imports frontend framework
• Automated architecture report that scores each principle and lists P0/P1 violations
• Refactor plan that uses the assessor output to prioritize fixing direct instantiation and repository misplacements
• Developer checklist during feature work to validate use-case classes, DTO mapping, and DI registration
• Sprint-level technical debt tracking showing maturity level changes over time