Architecture decisions: *.archify-decision files, decisions: keys in diagrams
- parse, merge and validate decisions (ids, status, elements, diagrams, supersedes); strip decisions keys from diagrams and check the ids - model:validate counts decisions; model:list lists them with status and the diagrams that reference them; examples carry decisions - formats.md and SKILL.md describe the format and when an agent writes one
This commit is contained in:
1 parent
90a0c0d109
commit
b169034b4f
15 files changed
+276
-11
No files matched your search
@@ -100,3 +100,42 @@ For each diagram file under the root (and a single file outside a model):
|
||||
5. Hand the result to `archify validate <kind> <json> --json` (or `render`).
|
||||
|
||||
`task model:resolve -- --file=… --out=x.json` writes step 4's result.
|
||||
|
||||
## `name.archify-decision`
|
||||
|
||||
One architecture decision of the model, anywhere under the root (`decisions/` by convention):
|
||||
|
||||
```yaml
|
||||
schema_version: 1
|
||||
decision:
|
||||
id: queue-between-api-and-worker # unique in the model; words, or a quoted number
|
||||
title: A queue between the API and the worker
|
||||
status: accepted # proposed | accepted | superseded | rejected
|
||||
date: 2026-09-16
|
||||
elements: [api, queue, worker] # registry ids
|
||||
diagrams: [0200-containers/online-shop.archify]
|
||||
supersedes: [] # ids of older decisions this one replaces
|
||||
context: >
|
||||
Why a decision was needed.
|
||||
decision: >
|
||||
What was decided.
|
||||
consequences: >
|
||||
What becomes easier, harder, or must change.
|
||||
```
|
||||
|
||||
Checks (`model:validate`): id present and not a bare number, status known, every element in a registry, every diagram present, every superseded id present. A decision that another one supersedes is shown as superseded whatever its own status says.
|
||||
|
||||
Diagrams point back with a `decisions` list on the diagram itself, on a node (component, node, participant, state) and on an edge (connection, edge, flow, transition, message):
|
||||
|
||||
```yaml
|
||||
decisions: [postgres-as-source-of-truth]
|
||||
components:
|
||||
- ref: queue
|
||||
pos: [460, 360]
|
||||
size: [130, 60]
|
||||
decisions: [queue-between-api-and-worker]
|
||||
connections:
|
||||
- { from: api, to: queue, label: enqueue, decisions: [queue-between-api-and-worker] }
|
||||
```
|
||||
|
||||
The resolver strips the key before Archify sees the diagram and reports an unknown id at its line. Outside a model the key is an error, like `ref`. The extension shows decisions on the `main.archify` page, in a Decisions panel under each diagram, on element cards, and opens a decision file as its own page.
|
||||
Reference in new issue
Block a user