--- name: enterprise-architecture description: >- Unified enterprise & software architecture skill grounded in four open-source standards — the C4 model + Structurizr DSL, ArchiMate 3.x, TOGAF ADM, and arc42 + ADRs (MADR). Use it whenever the user wants to: produce software or enterprise architecture diagrams as code (C4 context/container/component, Structurizr, PlantUML, or Mermaid); write architecture documentation or decision records (arc42 sections, ADRs/MADRs, design docs); review or assess an existing architecture or design against quality attributes and EA principles; or model an enterprise (business capabilities → applications → technology, application landscapes, portfolio rationalization, TOGAF engagements). Trigger it even when no framework is named — e.g. "draw the architecture of this service", "give me a container diagram", "document how this system is built", "write an ADR for choosing Kafka", "is this design sound?", "map our capabilities to our apps", "create a Structurizr workspace". This is about system- and enterprise-level structure and decisions — do NOT trigger it for writing application code or REST endpoints, infrastructure provisioning / IaC / cloud deployment (Terraform, Kubernetes manifests), database or ER schema design, code-level UML or sequence diagrams of functions/classes, reviewing a pull request for code bugs, or API reference docs and project-management/Gantt charts. --- # 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 ``` 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`.