| name | architecture-audit |
| version | 1.0.0 |
| description | Audit a codebase for shallow modules — places where the interface is nearly as complex
as the implementation, where understanding one concept requires bouncing between many
small files, where pure functions were extracted just for testability but the real bugs
hide in how they're called, or where tightly-coupled modules leak across their seams.
Surface them as deepening opportunities (refactors that turn shallow modules into deep
ones), apply the deletion test, and walk the design tree with the user. Supports
parallel sub-agent fanout for 'Design It Twice'-style interface exploration. Use
whenever the user wants to improve architecture, find refactoring opportunities,
consolidate tightly-coupled modules, identify shallow abstractions, make a codebase more
testable, or hits you with phrases like 'where can we refactor', 'find architecture
friction', 'this code feels over-abstracted', 'help me deepen modules', or 'audit my
codebase'.
|
| license | MIT |
| compatibility | claude-code opencode |
| allowed-tools | ["Read","Write","Edit","Grep","Glob","Bash","Agent","AskUserQuestion"] |
| metadata | {"author":"MKAbuMattar"} |
Architecture audit
Surface architectural friction in a codebase and propose deepening opportunities — refactors that turn shallow modules into deep ones by relocating their seams. The aim is testability, locality, and AI/human navigability.
When to use
- The user asked to audit a codebase, find refactor opportunities, consolidate tightly-coupled modules, or identify shallow abstractions.
- A codebase has grown organically and now feels harder to navigate or change than it should.
- Pure functions were extracted for testability, but bugs still hide in how they're called — the unit tests pass and the real behaviour breaks.
- A test suite has 80% coverage but tells you nothing about whether the real flow works.
- The user wants to know where modules leak across seams that aren't real seams.
Skip this skill for: pure code review of a single PR (use qa or a code-review pattern), greenfield architecture design (use deep-discovery or information-architecture), or formatting/linting (use pre-commit-setup).
The vocabulary is the point
Use the terms from references/language.md exactly. Do not substitute "component", "service", "API", "boundary". Consistent vocabulary is what makes audits comparable across modules and across sessions.
The seven core terms: Module, Interface, Implementation, Depth, Seam, Adapter, Leverage, Locality. The three core principles: the deletion test, the interface is the test surface, and one adapter = hypothetical seam, two = real.
Workflow
- Read the optional context. If the project has a domain glossary (commonly
CONTEXT.md, GLOSSARY.md, or similar) and/or architectural decision records (docs/adr/, architecture/decisions/), read them first. These name the good seams and record decisions that the audit should not re-litigate. Load references/optional-context.md for the heuristic. If no such files exist, continue without them — do not stop the audit.
- Explore the codebase. Walk it with whatever exploration mechanism the harness offers (sub-agent / search tools / direct reads). Don't follow a rigid checklist — feel for friction. Load
references/exploration.md for the friction signals to look for.
