Architecture Guard

Validates that new files and modules are placed correctly according to .context/architecture.md . Prevents architectural drift by catching misplacements before code is written.

When to Use This Skill

• Before creating a new file or directory

• When moving or renaming files

• When a user asks "where should I put this?"

• During code review to validate file placement

Validation Process

Step 1: Read Architecture Definition

Read .context/architecture.md to understand:

• The directory structure

• Module boundaries and responsibilities

• Import rules between modules

Step 2: Classify the New File

Determine which module the new file belongs to based on its purpose:

File Purpose Likely Module Examples

Business logic, domain models core/

validators, services, entities

API calls, DB queries, file I/O adapters/

repositories, clients, providers

UI components, pages, layouts ui/

components, screens, hooks

Shared utilities, types, constants shared/

helpers, types, config

Tests tests/

mirrors the module being tested

Step 3: Validate Placement

Check if the proposed path matches the architecture:

✅ Valid placement:

Creating: src/core/auth/validate-token.ts Module: core/ (business logic → correct) Result: APPROVED

❌ Invalid placement:

Creating: src/utils/auth-service.ts Module: utils/ (not defined in architecture.md) Expected: src/core/auth/ (services belong in core/) Result: REJECTED — suggest correct path

Step 4: Check Import Rules

If the new file imports from other modules, validate against the "May Import From" rules:

File: src/core/auth/validate-token.ts Imports: from '../../adapters/db/user-repo' Rule: core/ may only import from shared/ Result: ❌ VIOLATION — core/ cannot import from adapters/ Fix: Inject the dependency via interface in core/, implement in adapters/

Response Format

Approval

✅ ARCHITECTURE CHECK PASSED File: src/adapters/api/payment-client.ts Module: adapters/ — External integrations ✓ Imports: shared/types ✓

Rejection with Guidance

❌ ARCHITECTURE CHECK FAILED

File: src/helpers/format-date.ts Issue: "helpers/" is not a defined module

Recommended path: src/shared/format-date.ts Reason: Utility functions belong in shared/ per architecture.md

Should I create the file at the recommended path instead?

Edge Cases

New Module Needed

If the file doesn't fit any existing module, propose updating architecture.md :

⚠️ NO MATCHING MODULE

File: src/workers/email-queue.ts Analysis: Background workers are not covered in architecture.md

Proposal: Add "workers/" module to architecture.md: | workers/ | Background jobs, queues, scheduled tasks | core/, shared/, adapters/ |

Proceed with creating the module? [Y/N]

Test File Placement

Test files should mirror the source structure:

• Source: src/core/auth/validate-token.ts

• Test: tests/core/auth/validate-token.test.ts

Integration

• Triggers context-sync when a new module is proposed

• Works alongside spec-lifecycle to validate that spec-related files go in the right place