# Architecture Review

> Use when evaluating whether a proposed change fits the existing architecture. Prevents layer violations, dependency cycles, and accidental coupling.

- Skill: `voidful/architecture-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add voidful/architecture-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/voidful/architecture-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: voidful (https://skillmd.com/u/voidful)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/voidful/architecture-review

---


# Architecture Review

## Core Principle

Every module should have one reason to change. If a proposed change touches three unrelated modules, the architecture has a coupling problem.

## Aixlarity Architecture Rules

These are the rules from AGENTS.md, enforced during architecture review:

1. **aixlarity-core must stay dependency-light.** Every new dependency needs justification.
2. **Command loading, skill loading, and prompt assembly are separate layers.** Never entangle them.
3. **Trust and sandbox decisions must be explicit.** No silent bypasses.
4. **Offline testability is mandatory.** Core logic must work without API keys.

## Dependency Direction

```
aixlarity-cli → aixlarity-core (one-way only)
aixlarity-core never imports from aixlarity-cli
```

Within aixlarity-core:
```
tools/registry.rs ← tools/*.rs ← agent.rs ← prompt.rs ← app.rs
```

A change that reverses any arrow is an architecture violation.

## Review Questions

For any proposed change, ask:

1. Does this change respect the dependency direction?
2. Does this add a new dependency to aixlarity-core? If yes, is it justified?
3. Does this mix concerns across layers (e.g., prompt logic in a tool file)?
4. Can this be tested offline (without API keys)?
5. Is the trust/permission impact explicit in the output?

## When to Use

- Before any PR that adds a new module or significantly changes existing module boundaries.
- When a refactoring plan proposes moving code between crates.
- When adding a new tool that might need special permissions.