architecture-check

---

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
• Undocumented dependencies — imports between modules not shown in the architecture