diff --git a/website/public/data/contracts.json b/website/public/data/contracts.json index fef40cf..78f7e5d 100644 --- a/website/public/data/contracts.json +++ b/website/public/data/contracts.json @@ -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" }, { @@ -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" }, { diff --git a/website/public/llms.txt b/website/public/llms.txt index 9748ae1..5377743 100644 --- a/website/public/llms.txt +++ b/website/public/llms.txt @@ -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). @@ -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*