Audit architecture and map module dependencies
An architecture-audit skill mapping module dependencies, layering integrity, and structural decay, with a codebase-onboarding mode.
Why it matters
Perform comprehensive architecture audits that map module dependencies, verify layering integrity, detect circular imports, and identify structural decay patterns across your codebase using principles from twelve classic software engineering books.
Outcomes
What it gets done
Draw module dependency graphs with color-coded health indicators
Scan for architectural decay risks like circular dependencies and layer violations
Assess testability seams and identify hard-to-test components
Check Conway's Law alignment between code structure and team organization
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/ag-brooks-audit | bash Overview
Brooks-Lint - Architecture Audit
This skill audits codebase architecture: mapping module dependencies as a Mermaid graph, checking layering integrity and testability, and running a Conway's Law check, with a separate onboarding mode for explaining a codebase to new developers. Use it to audit architecture, review module structure, or check for circular imports. Use onboarding mode instead when explaining a codebase to a new developer.
What it does
This skill runs an architecture audit that maps module dependency graphs, checks layering integrity, and flags structural decay across a codebase, drawing on twelve classic software-engineering books referenced in shared framework files - a common rules file defining an Iron Law and Health Score, a source-coverage file attributing findings to specific books, a decay-risks file defining symptom taxonomy, and this skill's own architecture guide. It also supports an onboarding mode, triggered by requests to explain the codebase to a new developer or give a codebase tour, which walks through the structure explanatorily rather than diagnostically, skipping the Health Score and Iron Law findings entirely.
When to use - and when NOT to
Use it when asked to audit architecture, review folder or module structure, check for circular imports, or understand how a codebase is organized. If the user hasn't specified files or a directory, the skill applies its own automatic scope detection to determine what to audit before proceeding.
Inputs and outputs
Given a codebase, or an auto-detected scope within it, it produces a Mermaid module-dependency graph with nodes colored red, yellow, or green based on findings, a testability seam assessment, a Conway's Law check comparing module structure to team structure, and a findings report following a shared report template - the Mermaid graph first, then findings - labeled Architecture Audit as its report mode.
Integrations
Depends on companion reference files in this skill's directory and a shared folder defining the audit rules, book sourcing, and decay symptom taxonomy; renders results as Mermaid diagrams.
Who it's for
Developers and tech leads who want a structured, book-grounded architecture health check covering dependency mapping, layering violations, testability gaps, and Conway's Law mismatches, or, in onboarding mode, a guided explanatory tour of an unfamiliar codebase for a new team member.
Source README
Brooks-Lint - Architecture Audit
When to Use
Use this skill when you need architecture audit that maps module dependencies, checks layering integrity, and flags structural decay across a codebase, drawing on twelve classic engineering books. Triggers when: user asks to audit architecture, review folder/module structure, check for circular imports, understand...
Setup
- Read
../_shared/common.mdfor the Iron Law, Project Config, Report Template, and Health Score rules - Read
../_shared/source-coverage.mdfor book-level coverage, exceptions, and tradeoffs - Read
../_shared/decay-risks.mdfor symptom definitions and source attributions - Read
architecture-guide.mdin this directory for the audit framework
Process
Onboarding mode: If the user asks for an onboarding report, codebase tour, or
"explain this codebase to a new developer", read onboarding-guide.md from this
directory and follow it instead of architecture-guide.md. This mode explains rather
than diagnoses - no Health Score, no Iron Law findings.
If the user has not specified files or a directory to audit: apply Auto Scope
Detection from ../_shared/common.md to determine the audit scope before proceeding.
- Gather codebase context and draw the module dependency graph as Mermaid (Steps 0-1 of the guide)
- Scan for each decay risk in the order specified (Steps 2-4 of the guide)
- Assign node colors in the Mermaid diagram based on findings (red/yellow/green) - after Step 4
- Run the Testability Seam Assessment (Step 5 of the guide)
- Run the Conway's Law check (Step 6 of the guide)
- Output using the Report Template from common.md - Mermaid graph FIRST, then Findings
Mode line in report: Architecture Audit
Limitations
- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.