Architecture Engineer

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.

1. 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.

1. **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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.