architecture-audit

Audits TypeScript codebase architecture using a Graphify knowledge graph to detect boundary, coupling, and convention violations.

3|5|Updated Apr 26, 2026
One-click install
npx skills add https://github.com/BenSheridanEdwards/ArchitectPlaybook --skill architecture-audit-bensheridanedwards
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: architecture-audit
Source: https://github.com/BenSheridanEdwards/ArchitectPlaybook/tree/main/architecture-audit
Command: npx skills add https://github.com/BenSheridanEdwards/ArchitectPlaybook --skill architecture-audit-bensheridanedwards

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Large TypeScript codebases drift into tangled imports, god modules, circular dependencies, and inconsistent conventions that are hard to see from inside the code. This Skill audits the repository against an opinionated architectural baseline and produces an evidence-backed findings report plus an optional implementation plan. ## Core Features & Use Cases - Graph-powered structural analysis: Reads the Graphify knowledge graph to detect circular dependencies, god modules, god components, orphaned files, and fan-in/fan-out threshold violations. - Four-layer audit model: Covers module boundaries, coupling and complexity, state and data flow, and convention adherence, preceded by a diagnostic snapshot of the codebase's actual shape. - Pattern-aware checks: Detects Next.js, Remix, Vite-React, and architectural patterns (feature-folders, layered, atomic-design, monorepo workspaces) and applies the matching boundary rules. - Use Case: Run the audit on a React monorepo to discover that a shared api-client module has 87 inbound edges, two features import each other through deep paths, and half the components are marked 'use client' — then generate an ordered implementation plan to fix each gap. ## Quick Start Run /architecture-audit in the project root after running /pre-audit-setup to build the knowledge graph, then review the findings report written to .architect-audits/architecture-audit/.

Frequently Asked Questions about architecture-audit

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit TypeScript codebase architecture automatically?

Run /architecture-audit from the project root after generating the Graphify knowledge graph with /pre-audit-setup. The audit writes findings.md, findings.json, snapshot.md, and metadata.json to .architect-audits/architecture-audit/ and offers an implementation plan.

How to detect circular dependencies and god modules in a React project?

The audit reads graphify-out/graph.json to find dependency cycles, modules with fan-in above 30, components rendered by more than 25 parents, and files over 400 lines. All thresholds are overridable via --threshold flags.

Does the architecture audit work without the Graphify knowledge graph?

No. The graph is a hard requirement because cycle detection, community analysis, and fan-in/fan-out checks are unimplementable without it. If missing, the audit writes a canonical not-evaluated result and instructs you to run /pre-audit-setup first.

Can I use this audit on a JavaScript-only or non-TypeScript project?

No. The audit requires tsconfig.json and a typescript dependency in package.json. On JavaScript-only projects it writes a canonical not-applicable result rather than guessing findings.

Does the architecture audit modify my code or files?

No. The audit is fully static and read-only; it never runs code, rewrites imports, or deletes orphans. It only writes reports inside .architect-audits/architecture-audit/, and the implementation plan is descriptive Markdown.

Why does the audit report not-evaluated for some checks?

Checks become not-evaluated when the knowledge graph is missing or a filter excludes them, and not-applicable when a structural prerequisite is absent, such as monorepo checks in a single-package project. Null statuses prevent misleading scores.