corp-v1-3darch-skills-code-agent/corp-v1-channel-architecture-3darch
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: define architecture channel operations

Browse Source
This commit is contained in:
jarvis-at-skic
2026-08-13 12:57:32 +00:00
parent a1e47c1487
commit 6b51f71f52
1 changed files with 145 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
SKILL.md
+145 -23
View File
@@ -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-<code>-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--<code>` under `corp-v1-<code>-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-<code>-general
corp-v1-<code>-architecture
corp-v1-<code>-delivery
corp-v1-<code>-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.