docs: add real Corp v1 architecture and skill context

2026-08-25 20:11:54 +00:00
parent 661bcde0f2
commit 382a9cc670
10 changed files with 265 additions and 111 deletions
@@ -0,0 +1,74 @@
+---
+id: overview-skills
+title: "Overview Skills"
+description: "Understand Corp v1 governance and channel skills, project-adopted copies, mandatory engineering skills, and useful shared Hermes skills."
+---
+
+import Drawio from '@theme/Drawio';
+import skillsDiagram from '!!raw-loader!./diagrams/skills.drawio';
+
+# Overview Skills
+
+Skills are the operating instructions loaded by Hermes for a task. They are **versioned guidance**, not autonomous workers and not substitutes for human approval. Corp v1 combines a central governance layer, channel-specific references, deliberate project adoptions, and useful generic execution skills.
+
+<Drawio content={skillsDiagram} title="Corp v1 central, adopted, and shared skill model" toolbar="zoom layers lightbox" responsive maxHeight={720} />
+
+## Central `corp-v1-*` skills
+
+The central sources live in [`home-v1-skills-code-agent`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent):
+
+| Skill | Purpose |
+|---|---|
+| [`corp-v1--main`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1--main) | Board authority, project lifecycle, resource model, membership, adoption, publication, and verification rules. |
+| [`corp-v1--glossary`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1--glossary) | Shared terminology and rules for keeping canonical definitions in project documentation. |
+| [`corp-v1-channel-general`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1-channel-general) | Onboarding, coordination, questions, and outcome broadcasts. |
+| [`corp-v1-channel-scope`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1-channel-scope) | Ideas, Epics, Features, value, acceptance outcomes, and human solution approval. |
+| [`corp-v1-channel-architecture`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1-channel-architecture) | Requirements, ADRs, interfaces, constraints, system design, and implementation Tasks. |
+| [`corp-v1-channel-ui-ux`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1-channel-ui-ux) | Journeys, information architecture, Penpot, accessibility, prototypes, and implementation handoff. |
+| [`corp-v1-channel-kanban`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1-channel-kanban) | Board/Focus visibility, dependencies, flow, blockers, and explicit Task admission. |
+| [`corp-v1-channel-delivery`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1-channel-delivery) | Planning, implementation, reviews, exact-head CI, blockers, and delivery evidence. |
+| [`corp-v1-channel-releases`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1-channel-releases) | Readiness, versioning, deployment, rollback, acceptance, and post-release outcomes. |
+
+## Project-adopted skills
+
+Every project owns fourteen adopted repositories in `corp-v1-<code>-skills-code-agent`:
+
+- seven channel skills named `corp-v1-channel-<channel>--<code>`;
+- seven engineering skills named `<source-skill>--<code>`.
+
+A project adoption records the central source branch and commit, then adds the project code, repository links, environment namespace, approved authority, and operating lessons. Central updates are compared and adopted semantically; they never silently overwrite project-specific decisions or authorization overrides.
+
+At runtime, a focused channel session loads its mapped project channel skill plus only the engineering or global skills needed for the current work.
+
+## Mandatory engineering skills
+
+These generic sources become project-owned copies during kickoff:
+
+| Source skill | Used for |
+|---|---|
+| [`development-branching-strategy`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/development-branching-strategy) | Branches, pull requests, integration, and release branching. |
+| [`development-gitops-argo-cd`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/development-gitops-argo-cd) | GitOps repositories, environments, Argo CD applications, and reconciliation evidence. |
+| [`development-monorepo-pnpm`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/development-monorepo-pnpm) | pnpm/TypeScript monorepo structure, applications, packages, and workspace validation. |
+| [`development-scripts`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/development-scripts) | Taskfiles, `.scripts`, environment handling, logging, and Devbox. |
+| [`devsecops-ci-cd-gitea`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/devsecops-ci-cd-gitea) | Gitea Actions, validation, Harbor publication, and delivery gates. |
+| [`documentation-docusaurus`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/documentation-docusaurus) | Docusaurus structure, content quality, diagrams, build, and Pages publication. |
+| [`template-engine-copier`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/template-engine-copier) | Copier/Jinja templates and reusable project scaffolding. |
+
+## Useful shared generic skills
+
+These are loaded globally when relevant; they are not additional mandatory project repositories:
+
+| Skill | Useful when |
+|---|---|
+| [`drawio-main`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/drawio-main) | Creating and validating editable architecture diagrams with layout and connector quality gates. |
+| [`home-v1-discord`](https://gitea.lego-cloud.eu/home-v1-skills-code-agent/home-v1-discord) | Discovering and operating Discord channels, permissions, messages, pins, and effective access. |
+| `gitea-repository-operations` | Discovering, creating, changing, and independently reading back Gitea organizations, teams, repositories, PRs, and refs. |
+| `systematic-debugging` | Investigating a defect from evidence and root cause before applying a fix. |
+| `test-driven-development` | Building behavior through RED, GREEN, and refactoring. |
+| `requesting-code-review` | Applying pre-commit security and quality gates and resolving findings. |
+| `dogfood` | Performing evidence-backed exploratory QA of deployed web applications. |
+| `gondor-v1-nodes` | Inspecting Argo CD, MicroK8s workloads, images, routes, and runtime evidence on Gondor v1. |
+
+## Selection rule
+
+The channel skill defines **why the work belongs here and which approvals and artifacts are required**. Engineering and generic skills define **how to execute the work safely**. If instructions conflict, explicit Corp v1 governance and preserved project authority win. No skill grants a human approval that has not actually been given.