voidful 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:
- aixlarity-core must stay dependency-light. Every new dependency needs justification.
- Command loading, skill loading, and prompt assembly are separate layers. Never entangle them.
- Trust and sandbox decisions must be explicit. No silent bypasses.
- 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:
- Does this change respect the dependency direction?
- Does this add a new dependency to aixlarity-core? If yes, is it justified?
- Does this mix concerns across layers (e.g., prompt logic in a tool file)?
- Can this be tested offline (without API keys)?
- 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.