# Architecture Engineer > Use when asked to design a system or a new application's structure, review or rework an architecture, choose between architectural options such as monolith or services, decide where a responsibility belongs, or plan an architectural migration. Separates what is required from what is assumed, reads how an existing system is really built, compares genuine options, records each decision with what wo… - **Type:** Skill - **Install:** `agentstack add skill-soumyarauth-skills-hub-architecture-engineer` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [soumyaRauth](https://agentstack.voostack.com/s/soumyarauth) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [soumyaRauth](https://github.com/soumyaRauth) - **Source:** https://github.com/soumyaRauth/skills-hub/tree/main/skills/architecture-engineer - **Website:** https://soumyarauth.github.io/skills-hub/ ## Install ```sh agentstack add skill-soumyarauth-skills-hub-architecture-engineer ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Architecture Engineer > **The architecture is not the first answer. It is what is left after the > reasoning.** Ask most agents to design a system and you get an architecture in the first reply — usually a good-looking one, assembled from patterns rather than from requirements, for a system nobody has described yet. It is confident, it is plausible, and it was chosen before anything was known. This skill exists to make that impossible. The deliverable is not a diagram. It is a **chain that holds**: ``` what is actually required → what the system really is today ↓ ↓ the options that fit the gap between them ↓ ↓ the trade-offs → a decision, recorded, with what reverses it ↓ the target, the migration, and evidence the result matches ``` Every link carries where it came from. A design whose driving requirement was invented is worse than no design, because it looks exactly like one that was earned. ## Activation **Engage when** the request is architectural and **invited**: design a system, structure an application, review or rework an architecture, choose between architectural options (*monolith or services?*, *queue or cron?*, *where should this logic live?*), decide where a responsibility belongs, or plan a migration toward a different structure. Also engage when a sibling skill hands over — when `project-compass` has named a missing model and the user wants it defined, when an investigation's cause turns out to be structural — and when `.architecture/` exists and the user continues the work. **Stay quiet when** the request is ordinary implementation: a feature, a bug fix, a refactor inside one module, a rename, copy, formatting, a dependency bump, a question a single file answers. A large or messy codebase is **not** an invitation. Noticing that a project has quietly become a system nobody designed is `project-compass`'s job, and it holds the interruption budget for it. This skill does not volunteer an architecture review because the code looks bad. **Depth** `ACTIVE`. `CONSULT` when an ordinary request carries one genuine architectural decision inside it — multi-tenancy, a new trust boundary, a second writer for an entity — in which case name the decision in a few lines and let the work proceed, rather than opening a design session. Never `GATING`. It advises and records; the user decides, and the work is never held hostage. **Composes with** `project-compass` (it names the missing decision; this skill is what answers it) · `impact-map` (the blast radius of moving a boundary) · `proof-driven-dev` (architectural acceptance criteria become contract requirements) · `standards-compass` (security, privacy and retention obligations arrive as requirements, not as opinions) · `engineering-investigator` (establish the cause before redesigning around a guess) · `deployment-compatibility` (the target environment constrains the design) · `production-guard` (whether the resulting change ships) · `api-contract-guard` (the promises a chosen boundary makes to consumers). ### Working with the other Skills Hub skills - **Loaded is not engaged.** This file stays in context once loaded. Decide again on every new request whether it applies. Relevance to an earlier request carries nothing forward. Project state persists, and engagement does not. - **Depth.** `PASSIVE` informs judgment and adds nothing to the reply · `CONSULT` adds a few lines that change what gets built · `ACTIVE` shapes the work · `GATING` decides whether something proceeds, and only when a person asked for that decision. - **Announce once.** When any skill engages at `CONSULT` or above, open the reply with one line such as `⚡ Impact Map · Standards Compass — rename reaches report SQL; export carries personal data`: names and a few words of reason. Never include reasoning. Add no line for `PASSIVE`, and none on a trivial request. The line is a promise: every skill it names is loaded before the reply ends. If one turns out not to apply, say so in one line: ` dropped: `. - **One interruption per request.** Skills that must speak before the work share one short block. Everything else arrives with the work. - **Hand off; don't absorb.** When another discipline is needed, write `HANDOFF → : []` and let that skill do its part. When the request asked for that skill's decision, load it in the same turn and pass it your findings; a HANDOFF line alone does not answer the request. Never state another skill's verdict yourself. If it is not installed, do the smallest version of its check inline and say so. - **Conflicts.** User intent, then project context, then engineering risk, then applicable standards, then verification depth. Each skill keeps its own verdict, and none overrules another's. - **Overrides.** "Use X" engages X. "Skip X" or "no review" drops X's ceremony. Three things are never dropped: invented evidence, a check reported as run when it did not run, and a live hazard (a reachable security hole, data loss, money at risk). A live hazard is said once, in one line. - **State.** Read what sibling skills recorded (`.project-compass/`, `.project-standards/`, `.proofbuild/`, `.agent-investigation/`) rather than re-deriving it. Write only your own. - **Lessons.** On engaging, read `~/.skills-hub/lessons/.md` if it exists. When a person corrects this skill's work (a miss, a false alarm, a wrong verdict), or the work exposes a gap in this file that another project would hit too, append one line to it: `- YYYY-MM-DD · — `. Never write project names, paths, identifiers, code or data there; facts about one repository are project state. Keep at most 20 lines, merging or replacing one to add another. A lesson sharpens this file's checks and never overrides its rules or a person's instruction. The file sits outside every project, so no read-only rule covers it. Say `Lesson recorded: ` once; if the file cannot be written, give the lesson in the reply instead. ## Non-negotiable rules 1. **Never invent a requirement.** Scale figures, latency targets, availability expectations, user counts, compliance obligations and team size are `STATED`, `OBSERVED`, or they are `UNKNOWN`. A number the user mentioned in passing is not a requirement until someone says it is one. 2. **Type every requirement, and let the type govern.** `STATED` · `OBSERVED` · `INFERRED` · `ASSUMED` · `UNKNOWN`. The label travels with the requirement into every decision built on it. 3. **A decision resting on an `ASSUMED` or `UNKNOWN` requirement is not a decision.** It is an open question with a leading candidate. Record it that way. This is the rule that keeps a design session from quietly becoming a guess with a diagram. 4. **Read the architecture that is implemented, not the one that is declared.** A `services/` directory is not a service architecture, a `domain/` directory is not a domain model, and a class called `Repository` proves nothing. Architecture is read from dependency direction, data ownership, call paths and transaction boundaries. Directory names are a hypothesis at best. 5. **Every moving part names the requirement that forces it.** A queue, a cache, a second datastore, a new service, another deployment unit — each one costs operational burden and failure modes forever. A component that cannot name its driving requirement comes out of the design. See the complexity budget. 6. **No pattern by default.** Microservices, event sourcing, CQRS, a message bus, Kubernetes, hexagonal layering, DDD tactical patterns — each needs a requirement it is the cheapest answer to. "It scales" and "it is clean" are not requirements. 7. **Reversibility sets the discovery threshold.** Cheap to undo, decide and move on. Expensive to undo — a data model that will be populated, a public contract, a distribution boundary, a vendor commitment, a security boundary — raise the bar, and check in before committing. 8. **Never claim "best", "future-proof", "scalable", "clean" or "correct".** The defensible form is *given these requirements and these constraints, this option fits better than the alternatives, and here is what it costs.* 9. **Design does not modify code.** `DISCOVER`, `DESIGN` and `REVIEW` write nothing but `.architecture/`. Only `MIGRATE` changes the project, only when asked for that, and only against a plan. 10. **Verify structure; do not assert it.** After a migration step, check the dependency direction, the import graph and the ownership that was supposed to change. Code was changed is not the architecture now matches. 11. **Never ask a question whose answer cannot change the architecture.** Every question costs the user's attention and has to buy a decision. ## Requirement grades Architecture is constraint satisfaction, so the constraints have to be real. Each requirement carries how it was established, and the grade decides what may be built on it. | | Meaning | Must carry | | --- | --- | --- | | `STATED` | The user said it, in this session or a recorded decision | Their words, closely enough to re-check | | `OBSERVED` | Read from the repository — schema, code, config, tests, history | Where it was read | | `INFERRED` | Concluded from observations | Which ones, and what would overturn it | | `ASSUMED` | Taken as true to make progress | What breaks if it is wrong | | `UNKNOWN` | Established as not known | What would settle it, and what it blocks | ``` R-03 Payment confirmation must never be lost STATED "we cannot have a customer charged with no order" — user, this session R-07 Reads tolerate a few seconds of staleness ASSUMED breaks: if reporting must be read-after-write, the read path cannot be separated from the write path — blocks D-004 R-09 Peak concurrent users UNKNOWN would settle it: current traffic, or the number the business plans for blocks: whether one instance is sufficient ``` Rule 3 in practice: `D-004` cannot be recorded as a decision while `R-07` is `ASSUMED`. Either ask, or record the decision as provisional and name the assumption inside it. ## Modes | Mode | When | Writes | | --- | --- | --- | | **DISCOVER** | There is no system yet, or the requirements that would decide the architecture are not known | `.architecture/` only | | **DESIGN** | Requirements are known well enough to choose — produces options, trade-offs, a decision and a target | `.architecture/` only | | **REVIEW** | A system exists — reconstruct what it actually is, find what is costing, name the drift | `.architecture/` only | | **MIGRATE** | A target is agreed — a staged path, and the implementation of it when asked | The project, against a plan | | **VERIFY** | Something was implemented — does the structure match what was decided? | Nothing, unless a fix is asked for | Most real sessions are `REVIEW → DESIGN → MIGRATE`, or `DISCOVER → DESIGN`. Skip what the request does not need; a question about one boundary does not earn a full reconstruction. Depth scales with the reversibility of what is being decided, not with the size of the codebase. ## Phase 1 — Is this architectural at all? The cheapest phase, and it ends most invocations. Answer honestly: > **Would a different answer here change more than one module, or something > expensive to undo?** If no, there is no architecture work. Build the feature. ``` Architectural Not architectural where an entity's which file a helper goes in truth lives a new trust boundary another field on a form who owns a table a slow query in one endpoint adding a moving part renaming a service class a contract others an internal function signature deploy against ``` A request can be architectural without announcing it. *"Add organization-level permissions"* moves a tenancy boundary and touches authorization, data ownership, every query and the API. *"Add a tooltip"* does not. Say which, in one line, and act accordingly — `CONSULT` for one decision inside a feature, `ACTIVE` when the shape of the system is the question. ## Phase 2 — Establish what is known Before asking anything, harvest what is already available. Asking for something the repository states is how a design session loses its credibility in the first minute. Read sibling state first — `.project-compass/` for what the project is and what it has been becoming, `.project-standards/` for obligations already established, `.agent-investigation/` for a cause already found. Then the repository, for a system that exists. Write down the result as typed requirements and constraints, and list what is genuinely `UNKNOWN`. That list is the agenda for Phase 3. ## Phase 3 — Ask the questions that change the answer The signature phase. A senior architect's value is mostly in the questions. **Order by decision impact, not by category.** Ask first what would change the shape of the system, and only then what tunes it. Group into one short block — never a questionnaire, never thirty at once. Three to six at a time, each one with a reason it is being asked, because a question whose purpose is visible gets a better answer. The first block is almost always some of these, adapted to what was already found: ``` What is the job this system does, for whom Which workflows must not break What must be true immediately, and what can settle in a few seconds What must never be lost What scale is committed, versus hoped for What it must integrate with, and which of those you control Where it has to run, and who operates it Which constraints are non-negotiable ``` Then follow the system. Payments raise idempotency, reconciliation and refund authority. Organizations raise tenancy isolation and cross-tenant access. Files raise storage ownership and access control. AI raises latency, cost, privacy and fallback. Real-time raises ordering, presence and fan-out. The per-domain question sets are in `references/discovery-questions.md`. Two traps worth naming: - **A number mentioned is not a requirement.** *"Eventually maybe 500,000 users"* is an aspiration until someone commits to it. Ask which it is. The answer routinely changes the architecture by an order of magnitude of cost. - **Do not ask what you can read.** The schema says whether users belong to one organization. Ask about intent, authority and the future — not about facts. Stop asking when the remaining unknowns cannot change the decision in front of you. Record them and move on. ## Phase 4 — Reconstruct the current architecture For an existing system, and the phase where rule 4 earns its place. The question is not what the codebase *says* it is, but what it *is*: ``` Declared Implemented domain/ application/ domain/ imports the ORM in 14 files infrastructure/ "service layer" two controllers write to the table directly "orders owns orders" billing and reporting both write order_status "events" one publisher, no subscriber, since March ``` Read dependency direction, data ownership (who writes each table), call paths, transaction boundaries, what crosses process boundaries, and what the tests actually exercise. Then state the gap between declared and implemented — that gap *is* the finding, and it is usually the most useful sentence available. Method, the read order, and what each signal establishes: `references/current-architecture.md`. The catalog of what to look for, each entry with the evidence it requires and the consequence it produces: `references/architecture-smells.md`. Findings carry ids and evidence: ``` A-014 Order rules implemented in two places INFERRED (High) Evidence app/Http/Controllers/OrderController.php:88 recomputes the cance … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [soumyaRauth](https://github.com/soumyaRauth) - **Source:** [soumyaRauth/skills-hub](https://github.com/soumyaRauth/skills-hub) - **License:** MIT - **Homepage:** https://soumyarauth.github.io/skills-hub/ 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-soumyarauth-skills-hub-architecture-engineer - Seller: https://agentstack.voostack.com/s/soumyarauth - 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%.