# Architecture > Use for architecture decisions, module boundaries, coupling, layering, and system shape. - **Type:** Skill - **Install:** `agentstack add skill-kreek-consult-architecture` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [kreek](https://agentstack.voostack.com/s/kreek) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [kreek](https://github.com/kreek) - **Source:** https://github.com/kreek/consult/tree/main/consult/skills/architecture ## Install ```sh agentstack add skill-kreek-consult-architecture ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Architecture ## Iron Law `ORGANIZE BY WHAT CHANGES TOGETHER. BOUNDARIES EXPOSE CONTRACTS, NOT INTERNAL STEPS.` ## When to Use - Choosing between domain/feature-oriented organization and horizontal controller/service/repository/DTO layers. - Choosing shared project/package/module boundaries, bounded contexts, and public surfaces. - Defining internal boundary contracts: what shape crosses a module/component boundary, what assumptions are guaranteed, and what details stay hidden. - Choosing API style or data store family before a specialist skill owns the detailed shape. - Mapping data flow inside a component from external/service payloads through parsed internal shapes to output/render shapes. - Deciding whether DDD tactical patterns (aggregates, repositories, factories, domain services) earn their keep. - Reviewing code where one behavior is scattered across many files for no technical reason. ## When NOT to Use - Data shape, invariant, and effect discipline; use `domain-modeling`. - Public HTTP contract details; use `api`. - Database physical schema, indexes, or migrations; use `database`. - Reshaping existing code while preserving behavior; use `refactoring`. - Local file moves or private helper extraction that do not create shared boundaries; explain the choice and proceed. ## Core Ideas 1. Organize by what changes together. Feature behavior, data shapes, invariants, and tests should live close enough to change together. Keep production files and their matching test files small enough that one focused behavior can be run without invoking the whole suite. 2. Functions should do one thing well. Keep them around 25-30 lines, and keep conditionals and loops under three nesting levels. Use guard clauses, extraction, or composition before adding another nested branch. 3. Use layers only for real boundaries. Horizontal layers are useful for process, deploy, trust, persistence, transport, or proven duplication. They are harmful when they scatter one behavior by default. 4. Expose contracts and hide internal shape. A module boundary should say what crosses it, what assumptions hold, and what details callers must not depend on. 5. Keep domain meaning local. Use bounded contexts when the same word means different things in different parts of the system. Do not force subtly different meanings into one shared model. 6. Use architecture patterns only when they carry behavior. DDD patterns like aggregates, repositories, factories, and domain services must protect a real invariant, workflow, or boundary. 7. Make data flow explicit. Name where external data enters, where it becomes trusted, where domain work happens, and what output shape leaves. These are roles, not required folders. 8. Shared structure is user-owned. Ask before creating project layout, package/module boundaries, public library shape, or cross-component ownership that future work will depend on. ## Workflow 1. Name the business capability and its transitions before drawing modules. 2. Sketch the module surface from the caller's view: what it accepts, what it returns, what it must never expose. 3. If the surface is caller-facing or the structure is shared, recommend one option and route to `contract-first` before implementation. An approving `specify` design or RFC approves the direction, not the concrete module boundaries, shared structure, or project layout. Get sign-off on those before code locks them in. 4. Sketch the internal data path: where external data enters, where it is parsed into a trusted shape, where domain work happens, where output data is shaped, and what the renderer/presenter receives. 5. Group code by capability first; introduce horizontal layers only where a real technical boundary justifies them. 6. For each cross-module call, ask whether the caller depends on a stable contract or on internal shape. Stabilize the contract; hide the shape. 7. Record the decisions that future readers can't recover from the code: why this boundary, why this shape, what alternative was rejected. ## Verification - [ ] One feature can be edited and its matching proof run without traversing more directories or test files than the change deserves. - [ ] Functions do one thing well, stay roughly 25-30 lines, and avoid a fourth nesting level. - [ ] Horizontal controller/service/repository/DTO layers, where present, correspond to real technical boundaries, not default ceremony. - [ ] DDD tactical patterns are applied where they earn their keep, not as decoration. - [ ] Component data flow has named ingress, parse, domain, output-shaping, and render/presentation roles; raw external payloads do not leak past the parse boundary. - [ ] Module surfaces hide volatile decisions; callers depend on the contract, not the internal shape. - [ ] Caller-facing interfaces and shared structure were routed through user-approved contract/API/architecture design before implementation. - [ ] An approving design or RFC approved the architectural direction, not the concrete module boundaries, shared structure, or project layout. Those got sign-off before implementation. - [ ] Boundaries separate concerns that change independently; they are not merely steps in a flowchart. - [ ] Bounded contexts are explicit where the same word means different things in different parts of the system. - [ ] Architectural decisions whose rationale isn't recoverable from the code are recorded (ADR, comment, or commit message). ## Tripwires Use these when the shortcut thought appears: - Group by capability before adding controller/service/repository/DTO layers. - Share code only when the reused value has the same meaning and rules in both contexts. - Add repositories, factories, services, or aggregates only when they protect a real domain rule or boundary. - Keep feature-specific business rules at the handler/domain boundary; use middleware for transport-wide concerns. - Decide the boundary before using `refactoring` to move files. - Ask before locking in shared package/module/project structure; do not ask for private file moves that do not establish a boundary. - Add a layer only when it separates an independent change axis, process, deploy, trust, persistence, transport, or proven duplication. ## Handoffs - `specify`: compare current and proposed contracts before boundary decisions. - `domain-modeling`: module data shapes, invariants, effects, parsed/output shapes. - `refactoring`: move existing code toward the chosen structure. - `api`: public HTTP contract details. - `database`: physical schema, migrations, indexes, query behavior. - `documentation`: ADRs that capture rationale. - `proof`: handoff tests at each module boundary the architecture defines; a clean module boundary is a clean place to assert. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [kreek](https://github.com/kreek) - **Source:** [kreek/consult](https://github.com/kreek/consult) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-kreek-consult-architecture - Seller: https://agentstack.voostack.com/s/kreek - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.