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: <Skill> dropped: <reason>.
• 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 → <skill>: <reason> [<ids>] 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/<this skill's name>.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 · <the rule, stated for any project> — <what went wrong>. 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: <rule> 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.

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

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 an id, a label, evidence, consequence, question and direction — format and a sample in references/current-architecture.md.

Do not report every smell. Report what has evidence and is costing something.

Phase 5 — Generate options, then compare them

At least two genuine options whenever the decision is not forced, and never a strawman pair. If only one option is viable, say why the others are excluded — that is a shorter and more useful answer than a fake comparison.

Compare on the dimensions the requirements make relevant, not on a fixed list: complexity, operational burden, failure modes, consistency, latency, cost, team capability, testing, deployment, and reversibility. No scores. A weighted total invents precision that nothing here supports; the repository forbids invented numbers and this is exactly the place they appear.

The complexity budget is the discipline that makes this honest. Every moving part is a permanent cost — another thing to deploy, monitor, secure, back up, and be woken by. Each one names its driving requirement, or it does not survive the design:

Component       Driving requirement              Grade
Queue + worker  R-03 payment confirmation must   STATED
                not be lost
Redis cache     —                                none — removed from the design
Second service  R-09 unknown scale               UNKNOWN — deferred, not adopted

Method, dimension selection, and worked comparisons: references/options-and-tradeoffs.md.

Phase 6 — Decide, and record why

A decision is recorded when its driving requirements are STATED or OBSERVED (rule 3). Use an ADR — one file per decision, because rewriting a whole architecture document on every change is how architecture documentation dies.

D-004 — Asynchronous payment confirmation

Status      Accepted · 2026-09-20
Drivers     R-03 payment confirmation must not be lost        STATED
            R-05 provider webhooks may arrive twice, or late  OBSERVED
Options     A synchronous in-request · B durable queue + idempotent consumer
            · C event-sourced ledger
Chosen      B
Why         A loses confirmations whenever the browser or the process dies,
            which R-03 forbids. C satisfies R-03 and costs a consistency model
            and a rebuild path the team has no requirement for
Trade-off   One more moving part to run and monitor, and confirmation becomes
            eventually consistent — the UI must show pending
Reverses by Deleting the consumer and calling the handler inline. Cheap while
            the queue holds only this message type
Open        R-07 reporting staleness tolerance is still ASSUMED

Before committing to anything expensive to reverse, summarize and check in (rule 7). One short paragraph: the direction, the main trade-off, its reversibility, and a direct question. Not for every detail — for the ones that will still be true in two years.

Format, statuses, supersession and the reversibility gate: references/decision-records.md.

Phase 7 — The target, and failure before the happy path

Describe the target only to the depth the decisions support, covering only the sections this system actually has: context and trust boundaries, components and what each owns, data ownership and consistency, the API surface, asynchronous work and its guarantees, failure and recovery, security boundaries, and what operating it requires.

Mermaid where a picture carries something prose does not, never as decoration, and every edge labeled with the relationship it represents.

Then, for each important workflow, the part that is usually skipped:

Failure → Detection → Immediate behavior → Recovery → Data consistency
        → What the user sees

An architecture that only describes success is a sketch. Dependencies fail, messages arrive twice, workers die mid-job, caches go stale, deploys land half-finished — and what the system does then is a property of the architecture, not of the code.

Record what must not be violated: the invariants, the dependency directions, the ownership rules. Those become the fitness checks in Phase 9.

Phase 8 — Migrate, in states that each work

For an existing system, never rewrite it. Produce transition states, each one shippable and each one leaving the system working:

Current  →  Transition 1  →  Transition 2  →  Target

Each step names its objective, what it touches, its risk, how it is validated, how it rolls back, and whether production keeps running during it. Strangler routing, an anti-corruption boundary, dual-write with a read cutover, a compatibility shim removed last — use them when the situation calls for one, not because they have names.

Before a step that moves a boundary, get the blast radius from the skill that owns it:

HANDOFF → impact-map: moving order-status writes behind OrderService touches
          every current writer [A-014]

MIGRATE implements only when asked for implementation, one transition state at a time, running the project's own checks after each. Patterns, sequencing and the rules for data migrations: references/migration.md.

Phase 9 — Verify the structure, not the intention

After implementation, check that the thing decided is the thing that exists. Prefer a check that can be re-run over a claim that cannot:

dependency direction     no import from domain into infrastructure
ownership                one writer for order_status
boundary                 nothing outside billing imports billing/internal
cycles                   none among the top-level modules
contract                 the published schema matches the handler

Where the ecosystem supports it, make the important ones executable — an import linter rule, a dependency-cruiser config, an architecture test. Add a check only where a violation would actually matter; brittle checks that exist to be green get disabled, and then nothing is verified. What survives, what does not, and how to write the few that earn their place: references/fitness-checks.md.

Anything that cannot be checked is stated as unverified, with what would settle it. Proof that behavior still holds is proof-driven-dev's job, and readiness to ship is production-guard's:

HANDOFF → proof-driven-dev: the extracted OrderService must preserve the
          cancellation-window behavior at the 15-minute boundary [D-006]

State

Read references/state.md before creating or updating .architecture/. The repository outranks the file: re-verify a recorded claim before building on it, and never write a secret or customer data into it.

What this skill is not

• Not Project Compass. That skill notices, unprompted, that a project has become something nobody designed, and names the one decision that would settle it. This skill is what answers that decision once someone asks. It does not volunteer an architecture review.
• Not Impact Map. That maps what a specific change touches. This decides where the boundaries should be, then asks Impact Map what moving one costs.
• Not a pattern catalog. Patterns are answers to requirements. A design that names the pattern before the requirement has the reasoning backwards.
• Not a rewrite generator. The default for an existing system is an evolutionary path where every state ships.
• Not the ship decision. production-guard owns that, proof-driven-dev owns VERIFIED, and deployment-compatibility owns whether a target environment can run the result.

References

• references/discovery-questions.md — ordering questions by decision impact, and the per-domain sets
• references/current-architecture.md — reconstructing implemented architecture from evidence
• references/architecture-smells.md — the catalog, each with required evidence and consequence
• references/options-and-tradeoffs.md — generating alternatives, comparison dimensions, the complexity budget
• references/decision-records.md — ADR format, statuses, the reversibility gate
• references/migration.md — transition states, strangler routing, data migration rules
• references/fitness-checks.md — verifying implemented structure against decided structure

Worked examples

examples/greenfield-discovery.md — an idea with no system yet, taken from vague to a decided architecture through questions · examples/existing-review.md — a codebase whose declared architecture and real one disagree · examples/monolith-or-services.md — the trade-off question, answered without fashion and without a lecture · examples/quiet-feature.md — the request that sounds architectural, is not, and gets the work instead.