---

name: architecture-validate-layer-boundaries description: Validates Clean Architecture layer boundaries by checking that domain has no external imports, application doesn't import from interfaces, and infrastructure implements repository interfaces correctly. Use before architectural changes or as part of quality gates. allowed-tools:

• Read
• Grep
• Bash

---

Validate Clean Architecture Layer Boundaries

Purpose

Validates that all layers respect Clean Architecture dependency rules by checking that domain has no external imports, application doesn't import from interfaces, and infrastructure implements repository interfaces correctly. Ensures architectural integrity before commits and during quality gates.

Table of Contents

Core Sections

• Purpose - What this skill validates
• When to Use This Skill - Triggers and use cases
• What This Skill Does - Layer dependency rules and validation process
• Quick Start - Immediate validation workflow
• Usage Examples - Real-world scenarios
• Supporting Files - References, examples, and scripts

Detailed Sections

• Validation Process - Step-by-step validation workflow
• Expected Outcomes - Success and failure scenarios
• Detection Patterns - Grep patterns for violations
• Integration Points - Hooks, quality gates, and agents
• Expected Benefits - Performance metrics
• Success Metrics - Measurement criteria

When to Use This Skill

Use this skill when:

• Making changes to files in domain/application/infrastructure/interface layers
• Adding new dependencies to any layer
• Reviewing code for architecture compliance
• Running pre-commit quality gates
• User asks "Does this follow Clean Architecture?"

What This Skill Does

Validates that all layers respect Clean Architecture dependency rules:

Layer Dependency Rules

Domain Layer (src/project_watch_mcp/domain/)

• ❌ CANNOT import from: infrastructure, interfaces, application
• ✅ CAN import from: domain only
• Rationale: Domain is innermost layer, pure business logic

Application Layer (src/project_watch_mcp/application/)

• ❌ CANNOT import from: interfaces
• ✅ CAN import from: domain, application
• Rationale: Application orchestrates domain, but doesn't know about interfaces

Infrastructure Layer (src/project_watch_mcp/infrastructure/)

• ✅ CAN import from: any layer
• ✅ CAN import external dependencies (Neo4j, etc.)
• Must: Implement domain repository interfaces
• Rationale: Infrastructure is outermost layer, connects to external systems

Interface Layer (src/project_watch_mcp/interfaces/)

• ❌ CANNOT import from: infrastructure, domain directly
• ✅ CAN import from: application
• Rationale: Interfaces depend on application use cases only

Validation Process

1. Identify Layer: Determine which layer the file belongs to based on path
2. Extract Imports: Parse all import and from ... import statements
3. Check Rules: Validate imports against layer-specific rules
4. Report Violations: List violations with file:line references

Quick Start

User: "Validate my architecture changes"

What happens:

1. Skill identifies which layer each file belongs to
2. Checks imports against Clean Architecture rules
3. Reports violations with specific fixes

Result: ✅ Pass (boundaries respected) or ❌ Fail (violations with fixes)

Example output:

Copy✅ Clean Architecture Validation: PASSED - 15 files, 0 violations

or

Copy❌ Domain Layer Violation
   File: src/domain/models/entity.py:12
   Issue: Importing from infrastructure
   Fix: Use repository interface instead

Supporting Files

• references/layer-rules.md - Complete layer dependency matrix with examples
• references/violation-fixes.md - Common violations and how to fix them
• scripts/validate.sh - Executable validation script for Clean Architecture layer boundaries

Usage Examples

Example 1: Validate Single File

CopyUser: "Is this domain model valid?"

Claude invokes skill by reading file and checking imports:
- Identify layer from path
- Extract all imports using Grep
- Check each import against layer rules
- Report violations

Example 2: Validate All Changes

CopyUser: "Check if my changes follow Clean Architecture"

Claude invokes skill for all modified files:
1. Run: git diff --name-only
2. Filter Python files
3. Validate each file's imports
4. Report summary of violations

Example 3: Pre-Commit Gate

CopyInvoked automatically by pre-commit hook:
1. Get staged files
2. Validate layer boundaries
3. Block commit if violations found

Expected Outcomes

Success (No Violations)

Copy✅ Clean Architecture Validation: PASSED

Files checked: 15
Violations: 0

All layer boundaries respected.

Failure (Violations Found)

Copy❌ Clean Architecture Validation: FAILED

Violations found:

1. Domain Layer Violation
   File: src/project_watch_mcp/domain/models/entity.py:12
   Issue: Importing from infrastructure layer
   Code: from infrastructure.neo4j import Neo4jDriver
   Fix: Remove direct infrastructure dependency. Use repository interface instead.

2. Application Layer Violation
   File: src/project_watch_mcp/application/services/search.py:8
   Issue: Importing from interfaces layer
   Code: from interfaces.mcp.tools import search_code
   Fix: Application should not know about interfaces. Use application-level handler instead.

Total Violations: 2
Exit Code: 1

Detection Patterns

Use these Grep patterns to detect violations:

Domain layer violations:

Copy# Domain importing from application/infrastructure/interfaces
grep -rn "from.*\.\(application\|infrastructure\|interfaces\)" src/project_watch_mcp/domain/
grep -rn "from project_watch_mcp\.\(application\|infrastructure\|interfaces\)" src/project_watch_mcp/domain/

Application layer violations:

Copy# Application importing from interfaces
grep -rn "from.*\.interfaces" src/project_watch_mcp/application/
grep -rn "from project_watch_mcp\.interfaces" src/project_watch_mcp/application/

Interface layer violations:

Copy# Interfaces importing from domain directly (should use application)
grep -rn "from.*\.domain\.models" src/project_watch_mcp/interfaces/
grep -rn "from project_watch_mcp\.infrastructure" src/project_watch_mcp/interfaces/

Integration Points

With Pre-Flight Validation Hook

The pre-flight validation hook in .claude/scripts/pre_flight_validation.py can invoke this skill to validate architectural boundaries before allowing tool execution.

With Quality Gates

Quality gate scripts in ./scripts/check_all.sh can run the validation script to ensure Clean Architecture compliance as part of CI/CD.

With @architecture-guardian

The architecture guardian agent can delegate boundary validation to this skill rather than implementing validation inline, reducing context load by 96%.

Expected Benefits

Success Metrics

After implementation, measure:

• Invocation Rate: Skill invoked in 80%+ of architecture validation tasks
• Context Reduction: 90%+ reduction vs agent approach
• Violation Detection: 95%+ recall (catches all major violations)
• False Positives: <5% (no incorrect violations)