git:20260618.1cf9152 to git:20260618.25a13e6

---

name: enterprise-architecture

description: >-

---

# Enterprise Architecture

A practical toolkit for doing real architecture work the way open-source EA standards

intend it — diagrams as code, documentation as code, decisions as records, and a single

traceable model underneath. It unifies four complementary frameworks so you reach for the

right tool at the right altitude instead of forcing everything into one notation.

## The mental model: four frameworks, four altitudes

These frameworks are not competitors — they answer different questions. Knowing which one

fits the question is most of the skill.

| Framework | Question it answers | Altitude | When to reach for it |

|---|---|---|---|

| **C4 model** | "How is *this software system* structured?" | System → code | A single system/service: context, containers, components |

| **ArchiMate** | "How does the *whole enterprise* hang together?" | Business → app → tech | Capabilities, app landscapes, cross-system flows |

| **TOGAF ADM** | "How do we *deliver* an architecture change?" | Process/governance | Running an architecture engagement end-to-end |

| **arc42 + ADRs** | "How do we *write it down* so others understand & decisions stick?" | Documentation | Documenting a system; recording a decision |

A useful rule of thumb: **C4 zooms into one system, ArchiMate zooms out to the

enterprise, TOGAF is the *method* for changing it, and arc42/ADR is how you *narrate* it.**

They compose: an arc42 doc embeds C4 diagrams and links ADRs; a TOGAF engagement produces

ArchiMate models and ADRs as deliverables.

## How to use this skill

1. **Pick the mode** (below) from what the user is asking for. If ambiguous, ask one

short clarifying question rather than guessing — architecture work is expensive to redo.

2. **Read the matching reference file(s)** in `references/` before producing output. They

contain the real notation, element catalogs, templates, and gotchas. Do not work from

memory of the standards — load the reference so the output is correct and idiomatic.

3. **Produce diagrams/docs as code**, default to text formats that live in Git and render

anywhere. Save artifacts to files when the user has a repo/workspace; otherwise emit

inline.

4. **Keep one source of truth.** When elements recur across diagrams/docs, give them

stable IDs and reuse them (see *Traceability* below). Don't redraw the same box with a

different name in two places.

## The four modes

### Mode 1 — Diagram (diagrams as code)

*Triggers: "draw / diagram / visualize the architecture", "C4 container diagram",

"Structurizr workspace", "show the components".*

- For a **single software system**, use **C4** → read `references/c4-structurizr.md`.

- Default output: **Structurizr DSL** when the user wants a reusable model that

generates multiple views; **Mermaid** when they want something that renders inline

immediately (chat, GitHub, Markdown docs); **PlantUML (C4-PlantUML)** when they're

already in a PlantUML/Kroki toolchain.

- Produce views in order of altitude: System Context → Container → Component (→ Code

only if explicitly asked; it's usually noise). Stop at the level that answers the

question.

- For **cross-system / enterprise** views, use **ArchiMate** → read `references/archimate.md`.

- Respect good-diagram hygiene from the reference: 5–20 elements per view, every external

dependency shown, consistent naming, a title and a legend.

### Mode 2 — Document (docs & decisions as code)

*Triggers: "document this system", "write an ADR / decision record", "arc42 docs",

"design doc / RFC for X".*

- **Whole-system documentation** → arc42. Read `references/arc42.md`. Use the

discover → generate → validate loop and the detail-level knob (LEAN / ESSENTIAL /

THOROUGH) so you write the right amount, not a 40-page tome nobody reads.

- **A single decision** → ADR/MADR. Read `references/adr-madr.md`. Capture the context and

the *options considered with trade-offs*, not just the chosen answer — the value of an

ADR is the reasoning a future reader can't reconstruct.

- Embed diagrams (Mode 1) rather than describing visuals in prose. Link ADRs from the

relevant arc42 section (§9 Decisions).

### Mode 3 — Review / assess

*Triggers: "review my architecture", "is this design sound?", "assess this against best

practice", "what are the risks in this design?".*

- Read `references/review-rubric.md`. Assess against **quality attributes** (the ISO/IEC

25010 set: performance, security, reliability, maintainability, etc.) and EA principles,

not personal taste.

- Output **severity-categorized findings** (Critical / Major / Minor / Suggestion), each

with *evidence* and a *concrete remediation*, then a **verdict**

(Approved / Approved-with-changes / Needs-revision). Avoid vague praise; an unhelpful

"looks good" is worse than nothing.

- Where a finding implies a fix, hand off to the right mode (e.g. "record this as an ADR",

"redraw the container diagram to show the queue").

### Mode 4 — Model the enterprise

*Triggers: "map our business capabilities", "application landscape", "capability → app →

technology", "enterprise architecture model", "rationalize our app portfolio".*

- This is the big-picture mode. Use **ArchiMate** for the model

(`references/archimate.md`) and **TOGAF ADM** for the method/structure of the engagement

(`references/togaf-adm.md`).

- Work top-down through the layers: **Strategy/Motivation → Business (capabilities,

processes, services) → Application (apps, services, data) → Technology (nodes,

platforms)**, then draw the *realization* links between layers (which app realizes which

capability; which node hosts which app). The cross-layer links are the whole point — a

capability map with no realization links is just a list.

- For portfolio rationalization, add a TIME / quality assessment per application

(Tolerate / Invest / Migrate / Eliminate) — see the TOGAF reference.

## Traceability — keep one model under everything

Give every architectural element a **stable, human-readable ID** and reuse it across

diagrams, docs, and ADRs. This is what turns a pile of pictures into an actual model.

- Recommended ID scheme (URN-style): `ea:{org}:{system}:{kind}:{name}`

- e.g. `ea:acme:checkout:container:payment-api`, `ea:acme:enterprise:capability:billing`

- `kind` ∈ person, system, external, container, component, capability, app, node,

decision …

- When a repo/workspace exists, persist these in an `architecture/` folder (one file per

significant artifact, or a Structurizr workspace as the model-of-record) so they're

diff-able and greppable. Reference the same ID from the arc42 doc and the ADRs.

- Before inventing a new element, check whether it already exists under another name and

reuse the ID. Two names for one thing is the most common EA documentation defect.

## Validation

After generating diagrams or docs, sanity-check them. For cross-artifact consistency

(IDs referenced but never defined, building blocks named in prose but missing from

diagrams, quality goals with no scenario, ADRs not linked from any doc), run:

```

python scripts/ea_lint.py <path-to-architecture-dir-or-file>

```

It reports issues grouped by severity. Treat its output as advisory review feedback, not a

hard gate — explain findings to the user rather than silently "fixing" their intent.

## Output conventions

- **Diagrams**: fenced code blocks with the right language tag (` ```mermaid `,

` ```plantuml `, or Structurizr DSL in ` ```text `/a `.dsl` file). One view per block,

each with a one-line caption stating what it shows and for whom.

- **Docs**: Markdown, headings matching the standard's section structure. Diagrams as

separate `.puml`/`.dsl` files referenced from the doc when a repo exists; inlined

otherwise.

- **Always state which framework and view** you're producing, so the user learns the map.

Part of this skill's job is to make the user fluent in the frameworks, not just hand them

artifacts.

## Reference files (load as needed)

| File | Load when |

|---|---|

| `references/c4-structurizr.md` | Any C4 diagram; Structurizr DSL; Mermaid/PlantUML C4 |

| `references/archimate.md` | ArchiMate views; enterprise/cross-system modeling (Modes 1 & 4) |

| `references/togaf-adm.md` | Running/structuring an architecture engagement; portfolio (Mode 4) |

| `references/arc42.md` | Whole-system documentation (Mode 2) |

| `references/adr-madr.md` | Writing a decision record (Mode 2) |

| `references/review-rubric.md` | Reviewing/assessing an architecture (Mode 3) |

Templates live in `assets/templates/`; the consistency linter in `scripts/ea_lint.py`.