/architecture

name: architecture
description: Use when reviewing architecture in any codebase — module boundaries, stated design contracts, abstraction depth, error-handling design. Assess by default, apply changes on request; complexity is dependencies plus obscurity, and deep modules win.

Architecture Review

**Runtime syntax:** in Codex, invoke the plugin copy with the owner-qualified `$genie:<skill>` selector; use bare `$<skill>` only when intentionally selecting a user-tier copy (a separately installed personal copy; Genie no longer seeds this tier). Claude Code and Hermes use `/<skill>`. Cross-skill prose below uses bare names as portable semantic routes; the orchestrator resolves the selector for the active tier.

Lens

This lane treats complexity as anything that makes a system hard to understand or modify — it accumulates as dependencies and obscurity. KISS comes first: begin with the simplest complete design that satisfies current user stories, and make every added mechanism earn its carrying cost with a present contractual need or measurement. Hypothetical future scale is not evidence. The unit of judgment is the module: deep modules (simple interface, substantial implementation) are good; shallow modules (interface as complicated as what they hide) are architecture debt. Information leakage, pass-through methods, temporal decomposition, and speculative optimization are the smells to hunt. Prize "define errors out of existence" and design-it-twice thinking.

This lane's lens is inspired by the work of John Ousterhout, author of *A Philosophy of Software Design*.

Mandate

Assess and report by default. Apply changes only when the invocation explicitly asks. Every finding must cite the concrete interface, import, or branch that embodies it — no vibes. Findings outside this lane (failing gates, security holes, missing tests) get a one-line handoff to the relevant lane skill under `skills/`. When you have enough information to judge, judge; recommend one design, not a survey.

Discover the Ground Truth First

Architecture is judged against the repo's own stated intent, then against first principles. Before scoring anything, collect: `CLAUDE.md` / `AGENTS.md` architecture sections, ADRs or design docs, any documented invariants ("X must never import Y", "state lives in Z"), and the real module graph traced from the entry points via imports. A repo's deliberate constraints (zero-daemon designs, intentionally-duplicated modules, forbidden cross-imports) are the design under review — the defect is a *violated* contract or a contract the code has outgrown, not the contract's existence.

**Genie-framework repos**: `.genie/` documents (wishes, brainstorms) often record the intended design and its acceptance criteria — read the relevant wish before judging the code it produced.

**Repo profile — recall, verify, persist.** Before deriving from scratch, recall a stored profile for this repo: a memory/brain store if one is available this session, else a well-known file (in genie-framework repos, `.genie/repo-profile.md`). For this lane the profile records the module map, documented invariants, key interfaces and their depth verdicts. Recalled anchors are hypotheses — re-verify each invariant you rely on against current code and report drift as a finding. After the audit, persist what discovery learned: update rather than duplicate, delete what proved wrong.

**Profile write boundary.** During assess-only and pull-request runs, return proposed profile changes as a `profile_delta`; do not write memory or repository files. Persist a profile only when the user explicitly asks.

Workflow

1. **Establish the simplicity baseline.** State the current user stories, realistic scale, and smallest complete design. For every cache, delta, shard, queue, retry state machine, abstraction, or configuration surface, name the present evidence that requires it and the simpler alternative it displaces. Prefer bounding current state and moving history behind pagination before distributing synchronization. Done when speculative machinery is deleted, deferred behind a measurable trigger, or justified. 2. **Map the module graph.** Trace imports from the entry points; identify layers, cycles, and upward imports. Done when you have the real dependency picture, not the README's. 3. **Verify the stated contracts.** For each documented invariant found in discovery, read the code that must uphold it. Done when each is confirmed intact or broken with file:line evidence. 4. **Depth-score the key interfaces.** For the repo's central abstractions: interface surface vs implementation hidden, leakage of internals to callers, pass-throughs. Done when each has a deep/shallow verdict with the specific signature that decides it. 5. **Hunt the classic smells**: information leakage (two modules that must change together), temporal decomposition (modules named after steps, not capabilities), exceptions where errors could be defined away, configuration knobs exporting decisions the module should make, and optimizations without measurements or present requirements. Done when each smell has a concrete instance or the category is declared clean. 6. **Rank by change amplification** — how many places must be touched when the underlying decision changes — and report.

Grounded Reporting

Every structural claim traces to code read this session, cited file:line. A design opinion is only a defect if you can name the modification scenario it makes expensive; interfaces judged without reading their implementation are labeled as such. Conversely, added machinery without a current user story, contract, or measurement is itself a grounded complexity finding: the evidence is the absent requirement plus the concrete states and failure modes the machinery introduces.

Output Format

Lead with a one-sentence verdict on architectural health and name the simplest viable design. Then findings ranked by change-amplification risk, each with e