/enterprise-architecture-skill

name: enterprise-architecture
description: >-
  Unified enterprise & software architecture skill grounded in four open-source standards —
  C4 + Structurizr DSL, ArchiMate 3.x, TOGAF ADM, and arc42 + ADRs (MADR). Use it whenever the
  user wants to: produce architecture diagrams as code (C4 context/container/component,
  Structurizr, PlantUML, Mermaid); write architecture docs or decision records (arc42,
  ADRs/MADRs, design docs); review or assess a design against quality attributes and EA
  principles; or model an enterprise (capabilities → applications → technology, app landscapes,
  portfolio rationalization). Trigger it even when no framework is named — e.g. "draw the
  architecture of this service", "give me a container diagram", "write an ADR for choosing
  Kafka", "is this design sound?", "map our capabilities to apps", "document my architecture
  in arc42", "create an HLD or LLD", "assess this design against ISO 25010 / quality
  attributes", "produce a solution design". Do NOT trigger it for writing
  application code or REST endpoints, IaC / cloud deployment (Terraform, Kubernetes), database
  or ER schema design, code-level UML or sequence diagrams, reviewing a pull request, or API
  reference docs.

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. If the question is *which framework / how should we approach this* rather than a request for an artifact ("is TOGAF worth it?", "Zachman vs TOGAF?", "how do we structure this effort?"), read `references/choosing-frameworks.md` and answer with a grounded recommendation that routes into the right mode. 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,