--- 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 requirements while correlating verified activity across the project's six channels." version: 1.4.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, documentation-docusaurus] --- # Corp v1 Architecture Channel ## Overview This skill owns the solution phase and architecture coherence for a Corp v1 project. It monitors the project's `general`, `scope`, `architecture`, `kanban`, `delivery`, and `releases` channels, transforms human-approved Features into requirements and solution artifacts, breaks them into dependency-aware implementation tasks, assigns approved Features to versions, and maintains the Architecture section of the project documentation. The default architecture model is C4. Architecture diagrams must be authored and validated using the global `drawio-main` skill from: ```text 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: - operating in `corp-v1--architecture`; - running its recurring synchronization job; - designing or reviewing project architecture; - maintaining C4 views and Draw.io sources; - recording architecture decisions; - transitioning human-approved Epics and Features into functional/non-functional requirements and solution design; - creating dependency-aware task breakdowns and proposing version allocation; - detecting implementation or release activity that changes architectural truth. Only Features explicitly marked `Approved for Solution` by a human team member may enter solution work. Do not use this skill to approve its own Feature, move an unapproved Feature into solution, authorize implementation, or treat speculative discussion as accepted design. ## Human Approval Gates Hermes participates proactively in analysis and artifact creation but cannot satisfy either gate: 1. **Scope → Solution:** a human team member explicitly approves an Epic/Feature for solution work. 2. **Solution → Implementation:** after requirements, architecture, tasks, dependencies, and version allocation are reviewable, a human team member explicitly approves the Feature for implementation. Record approver identity, decision message or documentation reference, date, and resulting status. Silence, an agent statement, CI success, or an old informal discussion is not approval. ## Approved Information Boundary Inspect only: ```text corp-v1--general corp-v1--scope corp-v1--architecture corp-v1--kanban corp-v1--delivery corp-v1--releases ``` Use mapped-channel history to avoid duplicate work and new relevant activity from the other five channels. Never inspect another project's channels. ## Architecture Documentation Contract `Architecture` is a top-level documentation menu item with its own dedicated sidebar. The mandatory sidebar order and hierarchy are: ```text Context Overview Containers Features Overview ``` 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 For each human-approved Feature from the General documentation registry: 1. verify its stable ID, parent Epic, scope, value, acceptance outcomes, status, and human approval evidence; 2. set solution status to `In Solution` without changing product approval history; 3. derive traceable FRs and NFRs; 4. update C4 views and draft/maintain ADRs as needed; 5. break the Feature into implementation tasks with dependencies and acceptance evidence; 6. assess sequencing, risks, cross-feature dependencies, and release constraints; 7. propose and document the target version; 8. prepare task-readiness evidence for Kanban Focus admission; 9. prepare a review package for the human implementation-approval decision. Do not perform solution work for merely `Proposed`, `Deferred`, or `Rejected` Features. ## C4 Model Use C4 consistently: - **System Context:** users, external systems, trust boundaries, and the system's role. - **Container:** applications, services, data stores, queues, and major runtime responsibilities. - **Component:** internal decomposition only for containers where it supports design or delivery. - **Code:** exceptional; source code normally remains the authority for low-level structure. Every diagram must include a title, scope, element names, responsibilities, relationships, technology where relevant, and legend/boundary conventions. Keep narrative and diagrams synchronized. ## Draw.io Workflow 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 skills define the required Draw.io shape, embedding, or validation. ## Architecture Decision Registry Maintain a registry with stable IDs, for example `ADR-0001`, and at least: - title; - status: Proposed, Accepted, Superseded, Rejected, or Deprecated; - date and decision owners; - context/problem; - considered options; - decision and rationale; - consequences and risks; - affected requirements, C4 elements, repositories, and releases; - superseding/superseded links. A scheduled run may draft an ADR from verified context, but may not mark it Accepted without authoritative team approval. ## Requirements Registries Maintain separate functional and non-functional registries. Functional requirement minimum fields: ```text ID | statement | rationale | status | owner | acceptance evidence | related ADR/C4 element ``` Non-functional requirement minimum fields: ```text ID | quality attribute/constraint | measurable target | scope | status | verification method | related ADR/C4 element ``` Use stable IDs such as `FR-0001` and `NFR-0001`. Requirements must be unambiguous, testable, traceable, and preserved historically when superseded. Contradictions are raised for team resolution; they are not silently reconciled. ## Task and Dependency Breakdown Maintain a task registry in project documentation: ```text ID | feature | outcome | scope | dependencies | owner | status | acceptance evidence | affected repository/component ``` Use stable IDs such as `TASK-0001`. Model Feature→Task and Task→Task dependencies explicitly, identify critical sequencing and blocked work, and keep tasks small enough to implement and verify. Tasks may be drafted proactively, but only tasks belonging to a human-approved `Approved for Implementation` Feature may be proposed to Kanban. A human team member must separately approve each ready task into Focus `InBacklog` before Delivery execution. ## Version Allocation Maintain a version allocation registry linking Features to intended versions. Record target version, rationale, dependencies, readiness constraints, status, and human decision evidence. Hermes may analyze and propose allocation; the team decides which Feature goes into which version. Do not invent version assignments or treat a proposal as final. ## Kanban Handoff After human Feature implementation approval, Architecture sends dependency-ready task records to Kanban. Architecture does not place tasks into Focus `InBacklog`; Kanban records the separate human task-admission decision. Keep task dependencies and readiness evidence current when Kanban or Delivery reports drift. ## Proactive Iteration Requirement Every architecture iteration must add or materially improve a useful project-documentation artifact for an eligible human-approved Feature: FR/NFR traceability, C4/ADR content, task decomposition, dependency mapping, risk analysis, version proposal, or review package. Prefer improving existing artifacts over creating duplicates. If no Feature is approved for solution, document the exact waiting gate or actionable clarification instead of advancing unapproved work. ## Synchronization Workflow 1. Read new same-project activity and enough architecture history to avoid duplicates. 2. Inspect documented Epics/Features and verify human `Approved for Solution` evidence before selecting work. 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 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 May autonomously: - detect architecture drift; - update documentation to match verified approved decisions; - maintain registry mechanics and traceability; - draft ADRs, requirements, task breakdowns, dependency maps, and version proposals for human-approved solution Features; - run read-only and validation checks; - repair clear non-semantic documentation defects. Requires team approval for: - accepting/rejecting ADRs or requirements; - approving a Feature for solution or implementation; - finalizing which Feature belongs to which version; - changing system boundaries, major technologies, security posture, data handling, or deployment topology; - resolving genuine contradictions in product requirements; - adopting a project-specific `drawio-main` copy; - irreversible or high-impact implementation/deployment work. ## Common Pitfalls 1. Drawing architecture without loading `drawio-main`. 2. Duplicating the global Draw.io skill without a team decision. 3. Treating every C4 level as mandatory regardless of value. 4. Marking draft decisions or requirements as approved. 5. Letting diagrams, ADRs, requirements, and implementation diverge. 6. Writing non-measurable NFRs or non-testable FRs. 7. Overwriting superseded history instead of linking it. 8. Inspecting another project's channels. 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 - [ ] Only the six same-project channels were inspected. - [ ] 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. - [ ] Only a human team member moved a Feature to `Approved for Implementation` or finalized its version. - [ ] Tasks were proposed to Kanban with readiness/dependency evidence; Architecture did not self-admit them to Focus `InBacklog`. - [ ] At least one useful solution artifact was improved, or the exact human approval/clarification gate was documented. - [ ] Proposed items remain visibly proposed. - [ ] Documentation and diagram checks passed. - [ ] Commit/message/run evidence is included.