corp-v1-channel-architecture/SKILL.md

---
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 seven channels."
version: 1.8.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [corp-v1, discord, channel, architecture, c4, adr, requirements]
    related_skills: [corp-v1-main, home-v1-discord, diagrams-drawio, documentation-docusaurus, corp-v1-glossary]
---

# 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`, `ui-ux`, `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 `diagrams-drawio` skill from:

```text
https://gitea.lego-cloud.eu/home-v1-skills-code-agent/diagrams-drawio
```

Do not duplicate `diagrams-drawio` 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
```

Load the global `corp-v1-glossary` skill from `https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1-glossary` whenever project documentation needs to define or explain a reusable term. Maintain one canonical definition in the project's final top-level **Glossary** area and link to it from the owning domain page; do not duplicate glossary-style explanations across channel documentation.

## Shared Corp v1 System Login

When an authorized task requires login to a Corp v1 system being built or operated, follow the shared policy in `corp-v1-main` and use only the Bitwarden-injected runtime secrets named:

```text
HL_V1_SSO_EMAIL
HL_V1_SSO_PASSWORD
```

Secret availability is capability, not authorization. Verify the destination origin and task purpose before login. Never print, inspect, log, hash, serialize, paste, screenshot, or persist either value; never place a value in a command line, URL, file, repository, prompt, Discord message, browser console, test fixture, CI output, or generated artifact. Never ask a human to paste a value into chat. If a variable is unavailable, report only its missing name and request Bitwarden/gateway injection. Login does not authorize account recovery, MFA or credential changes, permission changes, billing, spending, destructive operations, or access outside the approved project task.

## When to Use

Use this skill when:

- 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;
- 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-<code>-general
corp-v1-<code>-scope
corp-v1-<code>-architecture
corp-v1-<code>-ui-ux
corp-v1-<code>-kanban
corp-v1-<code>-delivery
corp-v1-<code>-releases
```

Use mapped-channel history to avoid duplicate work and new relevant activity from the other six 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
Container Registry
Requirements - Functional
  Registry
  <FR-ID>
Requirements - Non-Functional
  Registry
  <NFR-ID>
```

Do not add unrelated first-level items or rename these entries. In particular, Architecture has no `Features` menu, Feature reader pages, task registry page, or task reader navigation. Architecture decisions, implementation-task derivation, dependencies, readiness, and version evidence remain authoritative Architecture semantics but are linked from Context, Overview, the applicable Container Registry entry, or FR/NFR pages rather than expanding this sidebar. Scope hosts canonical Epic, Feature, and task reader pages.

### 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` maps to the C4 **Container** level (C2). It shows the deployable or runnable applications, services, data stores, queues, major technologies, responsibilities, interfaces, and material relationships that make up the project. It must not be an aggregate Component view. Include an editable Draw.io C2 Container diagram and link to the Container Registry for deeper per-container views.

### Container Registry

`Container Registry` indexes the C2 containers from Overview. It is an information-architecture registry, not another C4 level. Each entry links to a dedicated C3 **Component view** whose subject remains that container. The C3 page opens the selected container to show relevant internals and surrounding relationships.

### Requirements - Functional

`Requirements - Functional` contains a registry plus one separate reader page per stable `FR-*` requirement. Architecture derives and maintains FRs from approved Scope Features and preserves reciprocal traceability to the exact source Feature, acceptance outcome, related ADR/C4 element, implementation tasks, status, and evidence. The registry is an index, not a substitute for the reader pages.

### Requirements - Non-Functional

`Requirements - Non-Functional` contains a registry plus one separate reader page per stable `NFR-*` requirement. Architecture derives and maintains measurable NFRs from approved Scope Features and cross-cutting constraints, preserving reciprocal traceability to exact source Features, acceptance outcomes, related ADR/C4 elements, implementation tasks, verification methods, status, and evidence.

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. Do not recreate Scope Feature prose or task reader content inside Architecture.

## Epic and Feature Transition

For each human-approved Feature from canonical Scope:

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 `diagrams-drawio` 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 `diagrams-drawio` 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, Container Registry entries, and FR/NFR 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 and one separate reader page for every requirement. Derive both classes from canonical Scope Features while keeping Architecture as the requirement owner.

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 to exact Scope Features and acceptance outcomes, and preserved historically when superseded. Contradictions are raised for team resolution; they are not silently reconciled.

## Task and Dependency Breakdown

Architecture derives and maintains implementation-task semantics, dependencies, sequencing, and readiness from the FR/NFR solution. Scope hosts the canonical task records and reader pages under their owning Feature; Architecture must not create a competing task registry page or task navigation.

Architecture owns complete Task decomposition for every Feature allocated to the release.

Before reporting a release planning-ready, Architecture must:

1. Architecture creates missing Tasks, reviews existing Tasks, and retains, revises, supersedes, or removes them according to the current Feature outcomes and Architecture boundaries. Architecture may freely revise or remove only draft Tasks with no implementation approval, Kanban admission, execution, or completion evidence;
2. define between two and six independently executable Tasks per Feature; permit one Task only when a recorded Architecture rationale proves it is the smallest atomic, independently verifiable boundary;
3. map the Feature's Tasks collectively, exactly, and reciprocally to every acceptance-outcome ID and every applicable active `FR-*` and `NFR-*` record;
4. encode acyclic within-Feature sequencing and require every entry Task to depend on all terminal Tasks of every prerequisite Feature;
5. give each Task one specific outcome, repository/component owner, canonical/display identity, task-specific implementation artifacts, concrete inputs and outputs, failure boundaries, exclusions, verification steps, and future acceptance-evidence requirements;
6. keep draft Tasks separate from implementation approval and Kanban Focus admission.

Architecture must not report planning readiness while any Feature allocated to the release lacks this complete Task breakdown. A Feature-shaped placeholder Task, a generated empty Task group, or requirement coverage without executable Tasks does not satisfy the gate.

Approved, Kanban-admitted, in-progress, or completed Tasks must not be deleted or silently rewritten. Retain an obsolete Task with a terminal Superseded or Cancelled status, its prior evidence and history, and explicit replacement links.

A material change to Task scope, outcome, dependency, repository, or component invalidates the Task's existing implementation approval, returns the Task to its pre-approval state, and always requires renewed human `Approved for Implementation` before implementation can resume. After renewed approval, execution still requires a separate exact-task Kanban Focus admission.

```text
canonical_id | display_id | feature | outcome | scope | dependencies | owner | status | acceptance evidence | affected repository/component
```

Use canonical Task IDs `TASK-<ZERO_PADDED_NUMBER>` and separate project-scoped display IDs `<UPPERCASE_PROJECT_CODE>-TS-<NUMBER>`. Both fields are mandatory for every Task. Bind dependencies, links, event histories, evidence, and append-only hashes to `canonical_id`; use `display_id` only for reader-facing navigation and labels. Never infer or rewrite canonical identity from a display ID. Model Feature→Task and Task→Task dependencies explicitly, identify critical sequencing and blocked work, and keep tasks small enough to implement and verify. During migration, preserve historic canonical identities, aliases, event evidence, and append-only hashes; do not rewrite prior records or hashes solely to adopt the display convention. Tasks may be drafted proactively, but only tasks belonging to a human-approved `Approved for Implementation` Feature may be proposed to Kanban. Focus admission requires a separate human decision.

## 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.

## Delivery Readiness State

Architecture uses the task flow `IN_DESIGN → READY_FOR_DELIVERY → IN_PROGRESS`. `READY_FOR_DELIVERY` is a fail-closed, pre-execution readiness state: Architecture may emit it for an exact Task only when all of the following evidence is durable and linked to that Task:

1. an exact item-specific `Approved for Implementation` decision from a human team member;
2. complete task inputs, including implementation artifacts, concrete inputs and outputs, failure boundaries, exclusions, verification steps, and future acceptance-evidence requirements;
3. evidence that all entry dependencies are satisfied; and
4. for a Task that affects the user interface or user experience, exact approved UI/UX implementation-handoff evidence; otherwise the readiness record explicitly records UI/UX as not applicable with a rationale.

`READY_FOR_DELIVERY` does not mean Focus admission, assignment, claim, implementation start, `delivery_started`, or `IN_PROGRESS`. Architecture records the satisfied gate and sends a handoff to Kanban for a separate exact-task Focus-admission decision; only the authorized delivery-flow owner may subsequently record `IN_PROGRESS` when implementation actually starts.

Scope owns the canonical Task lifecycle schema. Architecture must not silently mutate or outrun Scope-owned canonical lifecycle schema: when the schema cannot represent `READY_FOR_DELIVERY`, return the handoff to Scope for canonicalization and keep the Task in its prior state. Never infer this state from solution-package completeness, UI/UX discussion, dependency expectations, CI success, or implementation activity.

## Kanban Handoff

After human Feature implementation approval, Architecture applies the `READY_FOR_DELIVERY` gate to each exact Task and sends only qualifying 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.

## UI/UX Coordination

Architecture supplies UI/UX with system boundaries, interfaces, data availability, security/privacy constraints, and affected containers/components. UI/UX owns the frontend experience, Penpot design source, design-system decisions, accessibility evidence, and implementation handoff. Neither channel silently changes the other channel’s approved constraints.

## 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 the required Architecture information architecture, C4 views, ADRs, FR/NFR registries and pages, Scope-hosted task records, dependencies, readiness, and version evidence.
5. Add or materially improve at least one useful solution artifact for an eligible Feature.
6. Use `diagrams-drawio` for every diagram change and `documentation-docusaurus` for every documentation, navigation, MDX, plugin, or embedding change.
7. Validate the exact Architecture sidebar, FR/NFR registries and reader pages, absence of Architecture Feature/task navigation, reciprocal Scope traceability, 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 `diagrams-drawio` copy;
- irreversible or high-impact implementation/deployment work.

## Common Pitfalls

1. Drawing architecture without loading `diagrams-drawio`.
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, Container Registry, Requirements - Functional, and Requirements - Non-Functional.
13. Treating Overview as a Component map instead of the project-wide C2 Container view.
14. Publishing static diagram exports without onboarding the editable `.drawio` source into Docusaurus.
15. Reintroducing Architecture Feature pages or task reader navigation instead of linking canonical Scope pages.
16. Renaming task display IDs by rewriting historic canonical identities, evidence, or append-only hashes.
17. Treating `READY_FOR_DELIVERY` as automatic Focus admission or `IN_PROGRESS`, or emitting it without exact implementation approval, complete task inputs, satisfied entry dependencies, and applicable approved UI/UX handoff evidence.

## Verification Checklist

- [ ] Only the seven same-project channels were inspected.
- [ ] Architecture documentation reflects verified status.
- [ ] C4 scope and level are appropriate.
- [ ] `diagrams-drawio` governed every diagram change.
- [ ] `documentation-docusaurus` governed navigation, MDX, plugin, and source embedding changes.
- [ ] Architecture has its dedicated sidebar ordered Context, Overview, Container Registry, Requirements - Functional → Registry + FR pages, Requirements - Non-Functional → Registry + NFR pages.
- [ ] Architecture has no Features menu/pages and no task registry/reader navigation.
- [ ] Context maps to C4 System Context; Overview maps to C2 Container; Container Registry entries open per-container C3 Component views.
- [ ] Every FR/NFR has its own reader page and reciprocal traceability to exact canonical Scope Features and acceptance outcomes.
- [ ] 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 derivation and version proposals, with canonical task reader pages under their Scope Feature.
- [ ] Every Feature allocated to the planned release has a reviewed, non-placeholder Task breakdown covering every acceptance outcome and applicable requirement, with acyclic within-Feature and cross-Feature dependencies.
- [ ] Task display IDs use `<UPPERCASE_PROJECT_CODE>-TS-<NUMBER>` without rewriting historic canonical identities, evidence, or append-only hashes.
- [ ] Only a human team member moved a Feature to `Approved for Implementation` or finalized its version.
- [ ] Every emitted `READY_FOR_DELIVERY` Task has exact implementation approval, complete task inputs, satisfied entry dependencies, and applicable approved UI/UX handoff evidence (or an explicit not-applicable rationale).
- [ ] `READY_FOR_DELIVERY` remained distinct from Focus admission, assignment, claim, `delivery_started`, and `IN_PROGRESS`; Architecture did not self-admit Tasks 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.