From 6f52c2763d635567188a996097ff717c11ccf807 Mon Sep 17 00:00:00 2001 From: Jarvis Jr Hermes Date: Thu, 13 Aug 2026 17:48:10 +0000 Subject: [PATCH] feat: define Architecture documentation hierarchy --- SKILL.md | 82 +++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 63 insertions(+), 19 deletions(-) diff --git a/SKILL.md b/SKILL.md index 4b660f3..da696bd 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,13 +1,13 @@ --- name: corp-v1-channel-architecture description: "Use when operating or synchronizing a Corp v1 project's architecture channel. Maintains C4-based architecture documentation, Draw.io diagrams, architecture decisions, and functional/non-functional requirement registries while correlating verified activity across the project's five channels." -version: 1.2.0 +version: 1.3.0 author: Hermes Agent license: MIT metadata: hermes: tags: [corp-v1, discord, channel, architecture, c4, adr, requirements] - related_skills: [corp-v1-steering-committee, home-v1-discord, drawio-main] + related_skills: [corp-v1-steering-committee, home-v1-discord, drawio-main, documentation-docusaurus] --- # Corp v1 Architecture Channel @@ -24,6 +24,12 @@ https://gitea.lego-cloud.eu/home-v1-skills-code-agent/drawio-main Do not duplicate `drawio-main` into each project by default. A project team may explicitly decide to adopt its own copy; that decision must also update the project's channel skills and steering record. +Load the global `documentation-docusaurus` skill before changing project documentation structure, navigation, MDX, Draw.io embedding, or Docusaurus configuration. Its authoritative source is: + +```text +https://gitea.lego-cloud.eu/home-v1-skills-code-agent/documentation-docusaurus +``` + ## When to Use Use this skill when: @@ -64,15 +70,42 @@ Use mapped-channel history to avoid duplicate work and new relevant activity fro ## Architecture Documentation Contract -Maintain the project documentation's `Architecture` area with at least: +`Architecture` is a top-level documentation menu item with its own dedicated sidebar. The mandatory sidebar order and hierarchy are: -1. **Architecture overview** — scope, goals, constraints, principles, and links to authoritative registries. -2. **C4 model** — System Context, Container, Component where justified, and Code only when it adds durable value. -3. **Architecture decisions** — indexed ADR registry and individual decisions. -4. **Functional requirements** — uniquely identified, testable requirements with status and traceability. -5. **Non-functional requirements** — measurable quality attributes, constraints, status, and verification method. +```text +Context +Overview +Containers +Features + + Overview +``` -Documentation must reflect approved/current truth. Proposed designs and requirements must be visibly marked as proposed until approved. +Do not add unrelated first-level items or rename these entries. Architecture decisions, requirements, tasks, dependencies, and version evidence remain authoritative Architecture records but are linked from the applicable Context, Overview, Container, or Feature Overview page rather than expanding the required first-level sidebar. + +### Context + +`Context` documents the project architecture context and maps to C4 **System Context**: people, external systems, the project system, trust/organization boundaries, principal relationships, goals, constraints, and material assumptions. It must contain an editable Draw.io context diagram unless a diagram is genuinely inapplicable and the page records why. + +### Overview + +`Overview` is the project-wide component map and maps to C4 **Component**. It summarizes significant logical components, responsibilities, dependencies, interfaces, and links to owning containers and Features. Use one or more editable Draw.io component diagrams; for many containers, provide a readable cross-container overview and link detailed views rather than creating one unreadable canvas. + +### Containers + +`Containers` is the C4 **Container** registry and view. It documents deployable/runnable applications, services, data stores, queues, major technologies, responsibilities, interfaces, and relationships. Include an editable Draw.io container diagram and a linked table of containers. Detailed views may be nested in-page without changing the mandatory first-level sidebar. + +### Features + +`Features` contains a table of all Architecture-eligible Features, using stable IDs owned by Scope/General: + +```text +Feature ID | title | parent Epic | solution status | implementation status | target version | dependencies | Overview link +``` + +Each Feature ID is nested under `Features` and contains an `Overview` page. Feature Overview consolidates its approved problem/outcome, FRs/NFRs, affected Context/Containers/Components, ADRs, interfaces/data flows, task/dependency breakdown, risks, target version, implementation approval evidence, and Kanban handoff. Add editable Draw.io diagrams wherever they materially clarify the Feature—normally at least an affected-component, interaction, sequence, data-flow, or deployment-impact view. If no Feature-specific diagram adds value, record why and link the relevant shared Context, Overview, or Containers diagram. + +Documentation and diagrams must reflect approved/current truth. Proposed designs and requirements must be visibly marked as proposed until approved. Every registry row and diagram element must link to authoritative records where Docusaurus permits. ## Epic and Feature Transition @@ -103,15 +136,17 @@ Every diagram must include a title, scope, element names, responsibilities, rela ## Draw.io Workflow -1. Load the global `drawio-main` skill before creating or modifying a diagram. -2. Store editable `.drawio` source in the documentation repository. -3. Export the required review/publishing format according to `drawio-main`. -4. Validate the source and exports. -5. Link diagrams from the relevant C4 documentation page. -6. Commit source and rendered output together when the project convention requires both. -7. Record exact paths and commit evidence. +1. Load global `drawio-main` before creating or modifying a diagram. +2. Load global `documentation-docusaurus` before changing the site or embedding a diagram. +3. Store editable `.drawio` source in the documentation repository. +4. Onboard the source through `docusaurus-plugin-drawio` using the MDX source-import workflow from `documentation-docusaurus`; do not publish only a static export. +5. Export an additional review format only when `drawio-main` or project policy requires it. +6. Validate Draw.io source, Docusaurus build, source import, selected page/pageId, browser rendering, and console/network output. +7. Link diagrams from Context, Overview, Containers, and Feature Overview pages as applicable. +8. Commit source, MDX/configuration, lockfile, and any required rendered output together. +9. Record exact paths and commit evidence. -Do not hand-author substitutes when the global skill defines the required Draw.io shape or validation. +Do not hand-author substitutes when the global skills define the required Draw.io shape, embedding, or validation. ## Architecture Decision Registry @@ -176,8 +211,8 @@ Every architecture iteration must add or materially improve a useful project-doc 3. Identify changed assumptions, requirements, interfaces, constraints, infrastructure, deployment topology, or runtime behavior. 4. Compare evidence with C4 views, ADRs, requirement, task/dependency, and version registries. 5. Add or materially improve at least one useful solution artifact for an eligible Feature. -6. Use `drawio-main` for every diagram change. -7. Run documentation, link, diagram, and repository validation and perform remote readback. +6. Use `drawio-main` for every diagram change and `documentation-docusaurus` for every documentation, navigation, MDX, plugin, or embedding change. +7. Validate the exact Architecture sidebar, Features hierarchy/table, links, Draw.io source embedding, Docusaurus build, and browser rendering; then perform remote readback. 8. Post a concise update with changed artifacts, implications, unresolved decisions, approval gate, and exact evidence. ## Authority and Escalation @@ -214,6 +249,9 @@ Requires team approval for: 9. Starting solution work for a Feature without explicit human approval. 10. Moving a Feature into implementation or assigning a final version based on Hermes's own judgment. 11. Creating task lists without explicit dependencies and traceability. +12. Adding first-level Architecture sidebar items outside Context, Overview, Containers, and Features. +13. Treating Overview as System Context instead of the project-wide C4 Component map. +14. Publishing static diagram exports without onboarding the editable `.drawio` source into Docusaurus. ## Verification Checklist @@ -221,6 +259,12 @@ Requires team approval for: - [ ] Architecture documentation reflects verified status. - [ ] C4 scope and level are appropriate. - [ ] `drawio-main` governed every diagram change. +- [ ] `documentation-docusaurus` governed navigation, MDX, plugin, and source embedding changes. +- [ ] Architecture has its dedicated sidebar ordered Context, Overview, Containers, Features → Feature ID → Overview. +- [ ] Context maps to C4 System Context, Overview maps to C4 Component, and Containers maps to C4 Container. +- [ ] Features table and every Feature Overview use stable linked IDs and current approval/version/dependency evidence. +- [ ] Draw.io diagrams exist wherever materially useful; any omission is justified and links to the applicable shared diagram. +- [ ] Editable `.drawio` sources render through Docusaurus and pass build plus browser verification. - [ ] ADR, FR, and NFR entries have stable IDs and traceability. - [ ] Every solution Feature has explicit human `Approved for Solution` evidence. - [ ] Eligible Features have dependency-aware task breakdowns and version proposals.