architect git:20261017.0423cdeA

Immutable. This exact content never changes and is served at /api/v1/blob/28bccab7a0b6ca7a.

---
name: architect
description: "Place one slice in the C4 model (LikeC4) by interviewing the driver on each design decision: layer by layer in arc42's views, and a runtime view only for a complex sequence. A short MADR only for a cross-cutting decision. Use after the spec, before code."
---

# Architect

**In:** the Gherkin spec at `features/<domain>/<feature>.feature`.
**Out:** the slice placed in the **LikeC4 model** at `docs/architecture/` — plus one terse ADR in
`docs/adrs/`, only when a crucial cross-cutting decision was made.

**Write only the model** — no code, no diagram files.

1. **Read the model** — none yet? This slice starts it, in the layout below, with just enough to
   place the slice.
2. **Grill the design into the model, layer by layer** — in arc42's order: context and scope, then
   the building blocks level by level, each box before its parts, then deployment. A runtime view
   only for a complex sequence — many elements, an order that matters, an asynchronous hand-off,
   what happens when one part fails — never one per scenario: the feature file already tells the
   story. Ask in rounds: every question the model lets you ask yet, each with your recommendation;
   write each answer into the model before the next round.

   **Ask with `AskUserQuestion`** — up to four questions a call, so a bigger round takes several
   calls in a row; your recommendation is the first option, marked *(Recommended)*. A question
   with nothing to choose between goes in plain text. No such tool in this session? Number the
   questions and put your recommendation under each.

   **Facts are yours, decisions are the driver's** — look up what the code and the model can tell
   you; ask everything someone could have decided differently. A question about behaviour is the
   spec's: hand it back to the requirements step, never settle it in the model.
3. **ADR only if warranted** — an integration pattern, a security boundary, build versus reuse,
   repo structure: a decision that binds features not yet written. Default to none; never
   package a feature as an ADR. A choice the driver made for this slice is answered in the model,
   not recorded again; what a scenario already says is not an ADR decision either. A decision that
   is cross-cutting? Recommend the ADR and ask the driver first. Then plain
   [MADR](https://adr.github.io/madr/), kept short, next number in `docs/adrs/`.
4. **Push** — once no question is open and the driver agrees: commit as `arch: …` to the slice's
   branch and push.

## Rules for the model

- Views follow [arc42](https://arc42.org/overview/); its goals and quality live in `features/`,
  its cross-cutting decisions in `docs/adrs/`.
- A box with parts of its own gets a view at the next level.
- A building-block view holds its subject's children and their direct neighbours. No element
  appears at two levels in one view.
- A runtime view holds only the elements that take a step.
- **Say a fact once.** A description says what an element is, in one sentence. What it does to
  another element is a relation. How a story runs is the feature file; a runtime view shows only
  a sequence too complex to read from it. Why one feature is built this way needs no record; why
  every feature must be is an ADR.
- An ADR names the views it shaped, by view id; the model never names an ADR.
- Applications share no storage; one reaches another only through its API.
- Model your own parts. A library you use is a technology line; a package you write is a
  `library`.
- Where the system is headed is a view on this model, never a second model.
- **Names come from the field's standard** — offer two or three candidate terms with their
  source and ask; never pick silently. Prefer one source, but meaning beats source.

## Layout

- `likec4.config.mjs` (`defineConfig`, never JSON): the project, its summary in
  `metadata.description`.
- `models/base-model.c4`: element kinds, people, externals, the system and its applications.
- `models/<part>.c4`: one per container or package, each `extend`ing its parent.
- `models/deployment.c4`: where each part runs.
- `views/views.c4`: every view.

## Done when

No question is open, the driver agrees the model places the slice, and an ADR exists only if a
crucial decision was made — often none.