From 6b51f71f5266bce7ac406d30e6772e6b4b66309b Mon Sep 17 00:00:00 2001 From: Jarvis Jr Hermes Date: Thu, 13 Aug 2026 12:57:32 +0000 Subject: [PATCH] feat: define architecture channel operations --- SKILL.md | 168 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 145 insertions(+), 23 deletions(-) diff --git a/SKILL.md b/SKILL.md index 4c32de3..bbb7dd7 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,50 +1,172 @@ --- name: corp-v1-channel-architecture -description: "Use as the central reference when defining or adopting project-scoped operating guidance for a Corp v1 architecture channel. This repository is initial setup only; detailed purpose and procedures remain pending steering walkthrough." -version: 0.1.0 +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 four channels." +version: 1.0.0 author: Hermes Agent license: MIT metadata: hermes: - tags: [corp-v1, discord, channel, architecture, reference] - related_skills: [corp-v1-steering-committee, home-v1-discord] + tags: [corp-v1, discord, channel, architecture, c4, adr, requirements] + related_skills: [corp-v1-steering-committee, home-v1-discord, drawio-main] --- -# Corp v1 Architecture Channel Reference +# Corp v1 Architecture Channel ## Overview -This is the central source skill for the `architecture` channel created for each Corp v1 project. +This skill owns architecture coherence for a Corp v1 project. It monitors the project's `general`, `architecture`, `delivery`, and `releases` channels, identifies architectural implications, and maintains the Architecture section of the project documentation. -**Current status: setup only.** Its detailed purpose, responsibilities, procedures, artifacts, authority boundaries, and verification rules are intentionally not defined yet. They will be agreed in a separate walkthrough before promotion beyond version `0.1.0`. +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. ## When to Use -Use this source when walking through the future `architecture` channel skill, creating a reviewed project copy after finalization, or comparing an adopted copy with its source. +Use this skill when: -Do not use this version as complete operating guidance for a live project channel. +- 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; +- maintaining functional and non-functional requirement registries; +- detecting implementation or release activity that changes architectural truth. -## Adoption Contract +Do not use it to approve architecture decisions without the team's authority, or to treat speculative discussion as an accepted design. -After finalization, `corp-v1-steering-committee` requires a project copy named `corp-v1-channel-architecture--` under `corp-v1--skills-code-agent`. Adoption preserves source history and attribution, applies project context, validates the result, and records the source branch and commit. +## Approved Information Boundary -Creating existing-project copies is explicitly deferred until separately requested. +Inspect only: -## Purpose Definition Pending +```text +corp-v1--general +corp-v1--architecture +corp-v1--delivery +corp-v1--releases +``` -The walkthrough must define channel outcomes, responsibilities, activities, artifacts, cross-channel relationships, applicable engineering skills, synchronization behavior, approval boundaries, and verification criteria. +Use mapped-channel history to avoid duplicate work and new relevant activity from the other three channels. Never inspect another project's channels. + +## Architecture Documentation Contract + +Maintain the project documentation's `Architecture` area with at least: + +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. + +Documentation must reflect approved/current truth. Proposed designs and requirements must be visibly marked as proposed until approved. + +## 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 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. + +Do not hand-author substitutes when the global skill defines the required Draw.io shape 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. + +## Synchronization Workflow + +1. Read new same-project activity and enough architecture history to avoid duplicates. +2. Identify changed assumptions, requirements, interfaces, constraints, infrastructure, deployment topology, or runtime behavior. +3. Compare evidence with C4 views, ADRs, and requirement registries. +4. Safely update documentation for already-approved facts, or prepare clearly marked proposals/drafts. +5. Use `drawio-main` for every diagram change. +6. Run documentation, link, diagram, and repository validation. +7. Post a concise architecture update with changed artifacts, implications, unresolved decisions, and exact evidence; otherwise stay silent. + +## Authority and Escalation + +May autonomously: + +- detect architecture drift; +- update documentation to match verified approved decisions; +- maintain registry mechanics and traceability; +- draft ADRs and requirements; +- run read-only and validation checks; +- repair clear non-semantic documentation defects. + +Requires team approval for: + +- accepting/rejecting ADRs or requirements; +- 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. Treating this setup scaffold as finalized policy. -2. Creating project copies before the requested migration. -3. Defining behavior indirectly instead of completing the walkthrough. -4. Losing source history or attribution during adoption. +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. ## Verification Checklist -- [ ] Repository exists under `home-v1-skills-code-agent`. -- [ ] Default branch is `test`. -- [ ] Skill name is `corp-v1-channel-architecture`. -- [ ] Version remains `0.1.0` until purpose is finalized. -- [ ] No project-scoped copy was created during setup. +- [ ] Only the four same-project channels were inspected. +- [ ] Architecture documentation reflects verified status. +- [ ] C4 scope and level are appropriate. +- [ ] `drawio-main` governed every diagram change. +- [ ] ADR, FR, and NFR entries have stable IDs and traceability. +- [ ] Proposed items remain visibly proposed. +- [ ] Documentation and diagram checks passed. +- [ ] Commit/message/run evidence is included.