Skip to content

fix(contracts): tighten Architecture Documentation diagram and format rules #486

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rdmueller merged 1 commit into from
May 15, 2026
Merged

fix(contracts): tighten Architecture Documentation diagram and format rules #486

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions website/public/data/contracts.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@
"description": "How we document architecture with diagrams, ADRs, and decision evaluation",
"descriptionDe": "Wie wir Architektur mit Diagrammen, ADRs und Entscheidungsbewertung dokumentieren",
"anchors": ["arc42", "c4-diagrams", "adr-according-to-nygard", "pugh-matrix"],
"template": "Architecture documentation follows arc42 with all 12 sections.\n\nDiagrams are required per section:\n- §3.1 Business context: business-process / value-flow diagram\n- §3.2 Technical context: classical context diagram (PlantUML/Mermaid)\n- §5 Building blocks: C4 Level 1 (System Context), Level 2 (Container), and Level 3 (Component) where decomposition adds clarity\n- §6 Runtime view: sequence or activity diagram per named scenario\n\nDecisions:\n- Every architecture decision documented as an ADR according to Nygard (Context, Decision, Status, Consequences).\n- Each ADR includes a Pugh Matrix with 3-point scale (-1, 0, +1) evaluating alternatives against quality goals.\n- When the rationale cannot be confirmed by a stakeholder, ADR Status is \"Accepted (inferred)\" and Pugh cells requiring team judgment are marked `?` rather than filled with assumptions.\n\nCrosscutting concepts (§8) are listed in the separate \"Crosscutting Concepts\" contract.",
"templateDe": "Architekturdokumentation folgt arc42 mit allen 12 Abschnitten.\n\nDiagramme sind pro Abschnitt verpflichtend:\n- §3.1 Fachlicher Kontext: Geschäftsprozess- / Wertfluss-Diagramm\n- §3.2 Technischer Kontext: klassisches Kontextdiagramm (PlantUML/Mermaid)\n- §5 Bausteinsicht: C4 Level 1 (System Context), Level 2 (Container) und Level 3 (Component), wo Zerlegung Klarheit bringt\n- §6 Laufzeitsicht: Sequenz- oder Aktivitätsdiagramm pro benanntem Szenario\n\nEntscheidungen:\n- Jede Architekturentscheidung als ADR nach Nygard dokumentiert (Kontext, Entscheidung, Status, Konsequenzen).\n- Jedes ADR enthält eine Pugh-Matrix mit 3-Punkt-Skala (-1, 0, +1) zur Bewertung von Alternativen gegen Qualitätsziele.\n- Wenn die Begründung nicht von einem Stakeholder bestätigt werden kann, lautet der ADR-Status \"Accepted (inferred)\", und Pugh-Zellen, die Team-Urteil erfordern, werden mit `?` markiert statt mit Annahmen gefüllt.\n\nQuerschnittliche Konzepte (§8) sind im separaten Contract \"Crosscutting Concepts\" beschrieben.",
"template": "Architecture documentation follows arc42 with all 12 sections.\n\nSections are numbered as in arc42 itself: `1.`, `1.1`, `2.`, … No `§` prefix in the output (the `§` symbol is used in this contract only to reference arc42 sections, not as the prescribed notation).\n\nFile formats:\n- arc42, ADRs, PRD, specification documents: AsciiDoc (.adoc), per the Docs-as-Code contract.\n- Use-case files and entity model retain whatever format the AIUP-reverse-engineer skill produces (Markdown today).\n- Question Tree and Open Questions: AsciiDoc (.adoc).\n\nDiagrams are required per section, all as PlantUML:\n- 3.1 Business context: business-process / value-flow diagram (BPMN or annotated sequence).\n- 3.2 Technical context: classical context diagram showing the system as a black box with all external systems and protocols labelled.\n- 5.1 / 5.2 / 5.3 Building blocks: C4 model using the C4-PlantUML standard library (`!include` C4_Context / C4_Container / C4_Component) with the proper stereotypes (`Person`, `System`, `Container`, `Component`, `Rel`). Generic `box`/`rectangle` shapes do not satisfy this requirement.\n- 6 Runtime view: PlantUML sequence diagram per named scenario.\n\nDecisions:\n- Every architecture decision documented as an ADR according to Nygard (Context, Decision, Status, Consequences).\n- Each ADR includes a Pugh Matrix with 3-point scale (-1, 0, +1) evaluating alternatives against quality goals.\n- When the rationale cannot be confirmed by a stakeholder, ADR Status is \"Accepted (inferred)\" and Pugh cells requiring team judgment are marked `?` rather than filled with assumptions.\n\nCrosscutting concepts (§8) are listed in the separate \"Crosscutting Concepts\" contract.",
"templateDe": "Architekturdokumentation folgt arc42 mit allen 12 Abschnitten.\n\nAbschnitte werden wie in arc42 selbst nummeriert: `1.`, `1.1`, `2.`, … Kein `§`-Präfix in der Ausgabe (das `§`-Zeichen wird in diesem Contract nur zur Referenzierung von arc42-Abschnitten verwendet, nicht als vorgeschriebene Notation).\n\nDateiformate:\n- arc42, ADRs, PRD, Spezifikationsdokumente: AsciiDoc (.adoc), gemäß Docs-as-Code-Contract.\n- Use-Case-Dateien und Entity Model behalten das Format, das die AIUP-reverse-engineer-Skill erzeugt (heute Markdown).\n- Question Tree und Open Questions: AsciiDoc (.adoc).\n\nDiagramme sind pro Abschnitt verpflichtend, alle als PlantUML:\n- 3.1 Fachlicher Kontext: Geschäftsprozess- / Wertfluss-Diagramm (BPMN oder annotierte Sequenz).\n- 3.2 Technischer Kontext: klassisches Kontextdiagramm, das das System als Black Box zeigt, mit allen externen Systemen und beschrifteten Protokollen.\n- 5.1 / 5.2 / 5.3 Bausteinsicht: C4-Modell mit der C4-PlantUML-Standardbibliothek (`!include` C4_Context / C4_Container / C4_Component) und den korrekten Stereotypen (`Person`, `System`, `Container`, `Component`, `Rel`). Generische `box`/`rectangle`-Formen erfüllen diese Anforderung nicht.\n- 6 Laufzeitsicht: PlantUML-Sequenzdiagramm pro benanntem Szenario.\n\nEntscheidungen:\n- Jede Architekturentscheidung als ADR nach Nygard dokumentiert (Kontext, Entscheidung, Status, Konsequenzen).\n- Jedes ADR enthält eine Pugh-Matrix mit 3-Punkt-Skala (-1, 0, +1) zur Bewertung von Alternativen gegen Qualitätsziele.\n- Wenn die Begründung nicht von einem Stakeholder bestätigt werden kann, lautet der ADR-Status \"Accepted (inferred)\", und Pugh-Zellen, die Team-Urteil erfordern, werden mit `?` markiert statt mit Annahmen gefüllt.\n\nQuerschnittliche Konzepte (§8) sind im separaten Contract \"Crosscutting Concepts\" beschrieben.",
"category": "architecture"
},
{
Expand Down Expand Up @@ -116,8 +116,8 @@
"description": "How we write and build documentation",
"descriptionDe": "Wie wir Dokumentation schreiben und bauen",
"anchors": ["docs-as-code", "plain-english-strunk-white", "gutes-deutsch-wolf-schneider"],
"template": "Documentation follows Docs-as-Code according to Ralf D. Müller:\n- AsciiDoc as format, PlantUML for inline diagrams, built by docToolchain\n- Version-controlled, peer-reviewed, and built automatically\n- Plain English according to Strunk & White (or Gutes Deutsch nach Wolf Schneider)",
"templateDe": "Dokumentation folgt Docs-as-Code nach Ralf D. Müller:\n- AsciiDoc als Format, PlantUML für Inline-Diagramme, gebaut von docToolchain\n- Versioniert, reviewt und automatisch gebaut\n- Gutes Deutsch nach Wolf Schneider (oder Plain English nach Strunk & White)",
"template": "Documentation follows Docs-as-Code according to Ralf D. Müller:\n- AsciiDoc as format, PlantUML for inline diagrams, built by docToolchain\n- Version-controlled, peer-reviewed, and built automatically\n- Plain English according to Strunk & White (or Gutes Deutsch nach Wolf Schneider)\n- Projects following this contract include the `dtcw` wrapper and `docToolchainConfig.groovy` so PlantUML / AsciiDoc actually render.",
"templateDe": "Dokumentation folgt Docs-as-Code nach Ralf D. Müller:\n- AsciiDoc als Format, PlantUML für Inline-Diagramme, gebaut von docToolchain\n- Versioniert, reviewt und automatisch gebaut\n- Gutes Deutsch nach Wolf Schneider (oder Plain English nach Strunk & White)\n- Projekte, die diesem Contract folgen, enthalten den `dtcw`-Wrapper und `docToolchainConfig.groovy`, damit PlantUML / AsciiDoc tatsächlich gerendert werden.",
"category": "documentation"
},
{
Expand Down
18 changes: 13 additions & 5 deletions website/public/llms.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5659,11 +5659,18 @@ Clarify requirements using the Socratic Method:

Architecture documentation follows arc42 with all 12 sections.

Diagrams are required per section:
- §3.1 Business context: business-process / value-flow diagram
- §3.2 Technical context: classical context diagram (PlantUML/Mermaid)
- §5 Building blocks: C4 Level 1 (System Context), Level 2 (Container), and Level 3 (Component) where decomposition adds clarity
- §6 Runtime view: sequence or activity diagram per named scenario
Sections are numbered as in arc42 itself: `1.`, `1.1`, `2.`, … No `§` prefix in the output (the `§` symbol is used in this contract only to reference arc42 sections, not as the prescribed notation).

File formats:
- arc42, ADRs, PRD, specification documents: AsciiDoc (.adoc), per the Docs-as-Code contract.
- Use-case files and entity model retain whatever format the AIUP-reverse-engineer skill produces (Markdown today).
- Question Tree and Open Questions: AsciiDoc (.adoc).

Diagrams are required per section, all as PlantUML:
- 3.1 Business context: business-process / value-flow diagram (BPMN or annotated sequence).
- 3.2 Technical context: classical context diagram showing the system as a black box with all external systems and protocols labelled.
- 5.1 / 5.2 / 5.3 Building blocks: C4 model using the C4-PlantUML standard library (`!include` C4_Context / C4_Container / C4_Component) with the proper stereotypes (`Person`, `System`, `Container`, `Component`, `Rel`). Generic `box`/`rectangle` shapes do not satisfy this requirement.
- 6 Runtime view: PlantUML sequence diagram per named scenario.

Decisions:
- Every architecture decision documented as an ADR according to Nygard (Context, Decision, Status, Consequences).
Expand Down Expand Up @@ -5747,6 +5754,7 @@ Documentation follows Docs-as-Code according to Ralf D. Müller:
- AsciiDoc as format, PlantUML for inline diagrams, built by docToolchain
- Version-controlled, peer-reviewed, and built automatically
- Plain English according to Strunk & White (or Gutes Deutsch nach Wolf Schneider)
- Projects following this contract include the `dtcw` wrapper and `docToolchainConfig.groovy` so PlantUML / AsciiDoc actually render.

*Referenced anchors: docs-as-code, plain-english-strunk-white, gutes-deutsch-wolf-schneider*

Expand Down
Loading