c4-architecture

# C4 Architecture Skill ## Goal Produce audience-appropriate C4 diagrams for existing systems from code or planned systems from requirements. Create new diagrams with the selected [renderer](#supported-renderers), or update existing diagrams when their renderer is supported. ## Supported Diagrams These defaults apply when creating new diagrams. Updates change only what the request targets. | Diagram | Generated by default | User selection | Answers | |-------------------------|------------------------|---------------------------------------|---------------------------------------------------------------| | Level 1: System Context | Yes | Which system when several qualify | Who uses the system and what does it interact with | | Level 2: Container | Yes | None | What separately deployable or runnable units make up a system | | Level 3: Component | Yes | Which containers when several qualify | What major building blocks sit inside one container | | Level 4: Code | On request only | Which component to detail | How one component maps to code structures | | Deployment | Offered when evidenced | Opt-in and which environment | Where container instances run in one named environment | ## Supported Renderers Read the selected renderer reference in full before generating or modifying diagrams. Apply every relevant rule. | Renderer | Reference | Status | |-----------|------------------------------------------------------------------|---------| | `mermaid` | [references/renderer-mermaid.md](references/renderer-mermaid.md) | Default | ## Process Follow these steps when activating this skill: 1. Ensure the [renderer](#supported-renderers) required by the user is available. 2. Inspect the relevant code and documentation to identify architecture elements, boundaries, relationships, and deployment evidence. 3. Read and apply the [C4 modelling instructions](references/c4-modelling-instructions.md), including its modelling-uncertainty decision. 4. When creating new diagrams, identify which diagrams, systems, and levels are required. Ask the user to clarify if unclear from context. 5. When updating an existing diagram document, read the complete document first and apply only the requested model delta. Preserve existing nodes, relationships, comments, layout controls, and stable identifiers unless the requested change affects them. Ask the user before removing content whose relevance is uncertain. 6. Before responding, validate each created/edited diagram rule by rule against the selected renderer reference and correct every violation. ## Success Criteria Complete the run when the agreed diagrams are produced or updated, their content is supported by the available evidence, and each diagram passes rule-by-rule source validation against the selected renderer reference. Report renderer-specific validation using the statuses defined by that reference, including the reason when validation was not run. ## Constraints Preserve the agreed system boundary, diagram levels, and renderer. Do not infer architecture, deployment topology, ownership, or relationship technology that the provided evidence does not support. Follow the selected renderer reference in full. ## Stop Rules Stop and ask for clarification when unresolved modelling uncertainty materially affects the diagrams. Stop and report the limitation when required evidence is missing or the requested renderer is unsupported or unavailable. Do not substitute an unrequested renderer or fabricate unsupported elements to complete a diagram. ## Final Response When diagrams are produced or updated, report the diagrams, selected renderer, source-validation result, renderer-specific validation status, assumptions or limitations, and unresolved decisions. For a clarification stop, state the evidence found, each specific modelling decision blocking the diagrams, the plausible options for each decision, and that no diagrams were produced. Do not report validation status during a clarification stop because no diagram source has been produced yet. ## Attribution and licensing Each source is paraphrased with attribution; none is reproduced verbatim. - C4 model concepts and abstractions (System Context, Container, Component, Code) are based on the [C4 Model](https://c4model.com/) by Simon Brown, licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). - Mermaid syntax conventions in the [Mermaid renderer](references/renderer-mermaid.md) are derived from the [Mermaid documentation](https://mermaid.js.org/), licensed under [MIT](https://github.com/mermaid-js/mermaid/blob/develop/LICENSE). Derived and original material share files here, so the boundary is marked inline in each file rather than split by file. The frontmatter expression is the conjunction of every license present in the package. | Path | License | Origin | |-------------------------------------------|-------------------|------------------------------------------------------------------------------------------------| | `references/renderer-mermaid.md` | CC-BY-4.0 AND MIT | Repository renderer rules, paraphrased C4 concepts, and MIT-derived Mermaid syntax conventions | | `references/c4-modelling-instructions.md` | CC-BY-4.0 | Repository modelling rules with paraphrased C4 concepts | | `SKILL.md` and remaining package content | CC-BY-4.0 | Repository-original with paraphrased C4 concepts |