Architecture Audit — Where The Structure Is Wrong

Your codebase is growing, and you no longer know if your module boundaries are holding or if circular dependencies are slowing down your builds. This skill performs a cold, structural audit of your repository to map the dependency graph, identify layering violations, and surface god modules.

What it does

• Detects cycles by identifying recursive dependency loops that break modularity.
• Finds layering violations by checking if infrastructure or UI modules are reaching into domain logic.
• Maps reach and coupling to identify which modules are too large or act as critical contract hubs.
• Identifies disconnected modules to surface dead code or isolated subsystems that are no longer in use.
• Calculates fix order by ranking structural issues based on their reach and severity.

How it works

1. Frame the audit by defining whether to scan the whole repository or a specific subsystem against documented architectural intent.
2. Collect structural signals using the agent-context CLI to generate a module map and dependency graph.
3. Apply eight specific checks to score issues like unresolved imports, coupling depth, and layering non-conformance.
4. Generate the remediation report including a ranked table of findings and a step-by-step order for fixing them.

Frameworks & tools

Works with any language or framework. It integrates with the ai-agent-context CLI for deterministic graph analysis but falls back to git grep and manual file inspection for environments without Node.js.

Why this beats prompting it yourself

Standard prompts often miss deep circular dependencies or subtle layering violations across large file trees. This skill uses a standardized scoring system and remediation sequence to ensure the audit is reproducible and objective.

Use cases

• Auditing a legacy repository before starting a major refactor.
• Reviewing module boundaries before moving to a monorepo or microservices.
• Verifying that a team is following the layering rules defined in their docs.
• Identifying dead code and unreachable modules in aging projects.

Known limitations

The audit is read-only and does not modify code. Role detection is name-based, so repositories without standard directory names (like /domain or /infra) may yield limited layering analysis.