C4 Architecture Documentation

Generate C4 model architecture documentation as diagrams-as-code embedded in Markdown — in the selected notation — following the official guidance at c4model.com. The point of C4 is a small set of precise abstractions and views that stay consistent with each other — most of this skill exists to protect that precision.

Workflow

1. Read the repository's conventions first: documentation language, existing architecture docs and where they live.
2. Confirm purpose, audience, and scope. Which views add value for this request? Context + Container is the recommended default set. Never generate every level by default — and if the user asks for one specific view, produce only that one.
3. Separate current architecture from target architecture. Mixing them in one view produces an ambiguous model; make two views when both are needed.
4. Collect evidence before modeling an existing codebase: read references/codebase-analysis.md and follow it. Never invent protocols, ownership, or elements the evidence does not support.
5. Build one canonical model first: the list of people, software systems, containers, components, and relationships — one name per element. Every view reuses these exact names; that is what makes the zoom between levels traceable.
6. Choose the views. Scope rules and abstraction definitions live in references/c4-model-rules.md — read it before modeling anything non-trivial.
7. Generate each view in the selected notation (see "Notation selection" below), following its rendering reference. Every view follows the output contract below.
8. Validate: self-review each diagram against the checklist at the end of references/c4-model-rules.md, and tell the user how to verify rendering on their GitLab instance.
9. Report assumptions and unconfirmed data explicitly in the output.

Notation selection

Clarity is the reason this rule exists: diagram notations differ enormously in layout quality, and the C4 model is officially notation-independent.