architecture-check

name	architecture-check
version	2.7.0
description	Validate module boundaries, check for architectural drift, and suggest fitness function tests. Compares actual code structure against ARCHITECTURE.md.
trigger	conditional
depends-on	[]
references	[]
user-invocable	true
allowed-tools	Read, Glob, Grep, Bash
context	fork
agent	Explore

---

architecture-check

You are a software architect validating that the codebase adheres to its documented architecture.

1. Load Architecture Documentation

Read:

• docs/architecture/ARCHITECTURE.md — documented module boundaries and dependencies
• docs/reference/GROUND_RULES.md — architectural ground rules with enforcement channels (if exists)
• docs/adr/ — architecture decision records (if any exist)
• CLAUDE.md — architecture one-liner

If ARCHITECTURE.md doesn't exist or is a template, inform the user and suggest running /bootstrap or creating one.

2. Validate Module Boundaries

Apply the architectural_impact reasoning tool from .claude/skills/story-cycle/references/reasoning-tools.md to assess module boundaries systematically.

For each documented module/layer:

If the Module Map section contains explicit Dependency Rules (MUST/NEVER statements), use those as the primary validation criteria rather than inferring boundaries from the diagram alone.

Import Analysis

Scan imports to check for violations:

• No cross-layer imports — e.g., presentation layer should not import from data layer directly
• No circular dependencies — module A imports B which imports A
• Dependency direction — imports should flow in the documented direction (e.g., handlers → services → repositories, not reversed)

# Example: Find imports across boundaries
# grep -r "from data_layer" presentation_layer/
# grep -r "import.*handler" repository_layer/

Boundary Check

For each module:

• Does it only depend on modules it's allowed to depend on?
• Are there any "reaching across" imports that skip layers?
• Are shared types/interfaces in the right location?

3. Check for Architectural Drift

Compare the actual code structure against ARCHITECTURE.md:

• New modules — code directories not documented in ARCHITECTURE.md
• Missing modules — documented modules that don't exist (yet or anymore)
• Changed responsibilities — modules doing things outside their documented scope

Read `docs/reference/GROUND_RULES.md`. For each rule: - **`Enforced-by: review:`** — perform the specified check against the codebase, report violations with file:line evidence - **`Enforced-by: auto:`** — verify the referenced tool/test is configured and running (e.g., ArchUnit test exists, dependency-cruiser config present). Flag unconfigured enforcement as "enforcement gap" - **`Enforced-by: ai:`** — check that recent changes don't violate the ai instruction