validate-architecture

Validate Architecture

ℹ️ First, set expectations: before anything else, print one short line with this skill's version and its most recent change — the top entry of metadata.changelog above — e.g. validate-architecture vX.Y — recent: <summary>. Then proceed.

Validate the live codebase against the architectural invariants documented in docs/memory/architecture.md. Produces a violations report. Run weekly or before any major release.

State Dependencies

Source	Location	Read	Write	Description
Architecture	docs/memory/architecture.md	✅		Invariants and patterns
Source code	src/	✅		Implementation to validate
Validation report	docs/reports/architecture-{date}.md		✅	Saved output

Process

Step 1: Read Architecture Invariants

Read docs/memory/architecture.md and extract:

• Layer boundaries (what can import what)
• Naming conventions (file names, class names, function names)
• API pattern requirements (auth, versioning, error format)
• Database access rules (which layers can query directly)
• Any explicitly documented invariants or constraints

Step 2: Naming Conventions

Check that files, classes, functions, and modules follow documented naming patterns.

# Example: check for files that violate snake_case convention in Python
find src/ -name "*.py" | grep -E '[A-Z]' | grep -v '__pycache__'

# Example: check route handler naming
grep -rn "def [A-Z]" src/api/ 2>/dev/null

Flag deviations from documented conventions.

Severity: INFORMATIONAL (unless architecture.md marks as REQUIRED)

Step 3: Layer Dependency Directions

Verify that imports respect documented layer boundaries. For example, if architecture specifies "routers never import from other routers directly":

# Check for cross-imports between router modules
grep -rn "from.*router import\|import.*router" src/api/routers/ | grep -v "^.*#"

Adapt the checks to the actual layer boundaries defined in architecture.md.