diff --git a/docs/architecture-high-level/context.mdx b/docs/architecture-high-level/context.mdx
index f5483f7..19d07ef 100644
--- a/docs/architecture-high-level/context.mdx
+++ b/docs/architecture-high-level/context.mdx
@@ -1,7 +1,7 @@
---
id: context
title: "Context"
-description: "See the people, collaboration systems, repositories, and delivery platforms around the Corp v1 operating model."
+description: "See the governance channel, project sessions, repositories, and delivery platforms around the Corp v1 operating model."
---
import Drawio from '@theme/Drawio';
@@ -9,7 +9,7 @@ import contextDiagram from '!!raw-loader!./diagrams/context.drawio';
# Context
-Corp v1 is the **governed operating model for project delivery**. It is not an application runtime architecture. The Board supplies lifecycle authority and shared guardrails; project teams retain ownership of their scope, architecture, implementation, and release outcomes.
+Corp v1 is the **governed operating model for project delivery**. It is not an application runtime architecture. The Board supplies lifecycle authority and shared guardrails; project teams retain ownership of their scope, architecture, user experience, implementation, and release outcomes.
@@ -17,9 +17,11 @@ Corp v1 is the **governed operating model for project delivery**. It is not an a
The operating model joins four evidence-bearing environments:
-- **Discord** routes work into six project channels with distinct concerns.
+- **Discord** provides one `corp-v1-board` governance channel and seven focused channels per project.
- **Gitea** preserves decisions, documentation, application source, adopted skills, pull requests, and CI evidence.
- **Delivery platforms** publish documentation through LEGO Cloud Pages and applications through Harbor plus GitOps/Argo CD.
- **This Board portal** records project, team, member, repository, lifecycle, and verification state.
-The model does not approve a project's target solution architecture. Each project must separately record its approved context, containers, requirements, decisions, and implementation Tasks.
+One Hermes agent operates across multiple channel sessions. Project-adopted skills define each session's concern, approval rules, evidence requirements, and handoffs while preventing one project's decisions from silently changing another.
+
+The model does not approve a project's target solution architecture. Each project must separately record its approved context, containers, requirements, decisions, UI/UX evidence, and implementation Tasks.
diff --git a/docs/architecture-high-level/diagrams/channels.drawio b/docs/architecture-high-level/diagrams/channels.drawio
index ccbb901..c9d1fb3 100644
--- a/docs/architecture-high-level/diagrams/channels.drawio
+++ b/docs/architecture-high-level/diagrams/channels.drawio
@@ -1,65 +1,62 @@
-
-
-
+
+
+
-
-
-
-
+
+
+
+
-
-
+
+
-
-
+
+
-
-
+
+
-
-
+
+
+
-
-
+
+
-
-
+
+
-
-
+
+
-
-
+
+
-
-
+
+
-
-
-
-
-
-
-
-
+
+
-
-
+
+
-
-
+
+
+
+
+
+
+
+
-
-
-
-
-
-
-
-
-
+
+
+
+
+
-
\ No newline at end of file
+
diff --git a/docs/architecture-high-level/diagrams/context.drawio b/docs/architecture-high-level/diagrams/context.drawio
index 649472e..0107204 100644
--- a/docs/architecture-high-level/diagrams/context.drawio
+++ b/docs/architecture-high-level/diagrams/context.drawio
@@ -19,7 +19,7 @@
-
+
@@ -28,10 +28,10 @@
-
+
-
+
@@ -40,7 +40,7 @@
-
+
@@ -48,7 +48,7 @@
-
+
@@ -57,10 +57,10 @@
-
+
-
+
diff --git a/docs/architecture-high-level/diagrams/overview.drawio b/docs/architecture-high-level/diagrams/overview.drawio
index 1550f8f..cdd0681 100644
--- a/docs/architecture-high-level/diagrams/overview.drawio
+++ b/docs/architecture-high-level/diagrams/overview.drawio
@@ -1,94 +1,33 @@
-
-
-
+
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
\ No newline at end of file
+
diff --git a/docs/architecture-high-level/diagrams/repositories.drawio b/docs/architecture-high-level/diagrams/repositories.drawio
index 8c06d0e..8ddd0c8 100644
--- a/docs/architecture-high-level/diagrams/repositories.drawio
+++ b/docs/architecture-high-level/diagrams/repositories.drawio
@@ -22,7 +22,7 @@
-
+
@@ -37,13 +37,13 @@
-
+
-
+
-
+
@@ -52,7 +52,7 @@
-
+
@@ -61,10 +61,10 @@
-
+
-
+
diff --git a/docs/architecture-high-level/overview-channels.mdx b/docs/architecture-high-level/overview-channels.mdx
index fd69031..f8d38a9 100644
--- a/docs/architecture-high-level/overview-channels.mdx
+++ b/docs/architecture-high-level/overview-channels.mdx
@@ -1,7 +1,7 @@
---
id: overview-channels
title: "Overview Channels"
-description: "Understand how the six Corp v1 project channels divide responsibilities and hand work to one another."
+description: "Understand the Corp v1 Board channel, seven project workspaces, session boundaries, skills, and SDLC handoffs."
---
import Drawio from '@theme/Drawio';
@@ -9,17 +9,48 @@ import channelsDiagram from '!!raw-loader!./diagrams/channels.drawio';
# Overview Channels
-A project receives exactly six purpose-specific Discord channels. The channels are concern boundaries, not isolated teams: evidence and decisions move forward through explicit handoffs.
+Corp v1 uses **one portfolio-governance channel** and **seven purpose-specific channels per project**. These are operating boundaries for one AI agent and the human team—not separate delivery teams.
-
+
-| Channel | Owns | Typical handoff |
+## Portfolio governance: `corp-v1-board`
+
+`corp-v1-board` exists once for the whole Corp v1 pilot. It is the authoritative Discord workspace for decisions that change the portfolio operating model:
+
+- approve project kickoffs, closures, and membership changes;
+- approve changes to the global `corp-v1--main` governance skill;
+- approve central `corp-v1-channel-*` reference-skill changes;
+- resolve conflicts that cannot be decided inside one project;
+- review portfolio-level evidence and remaining gates.
+
+A Board message is evidence only when approval is explicit and attributable to a listed Board member. The Board channel does **not** replace project Scope, Architecture, UI/UX, Delivery, or Releases decisions.
+
+## Project workspaces
+
+Every active project receives these seven channels in this exact order:
+
+| Channel | Owns | Sends forward |
|---|---|---|
-| General | Announcements, questions, shared coordination | Routes product intent to Scope and broadcasts outcomes |
-| Scope | Ideas, Epics, Features, value, acceptance outcomes, solution approval | Sends an approved Feature to Architecture |
-| Architecture | Requirements, ADRs, Draw.io views, technical design, implementation Tasks | Sends prepared Tasks to Kanban |
-| Kanban | Board, Focus, flow visibility, explicit human Task admission | Sends admitted work to Delivery |
-| Delivery | Planning, implementation, pull requests, CI evidence, blockers | Sends a validated release candidate to Releases |
-| Releases | Readiness, versions, deployment, rollback, post-release outcomes | Reports deployment state and outcomes to the project |
+| **General** | Project announcements, questions, onboarding, shared coordination, and outcome broadcasts | Product intent and questions to Scope; cross-cutting needs to the owning channel |
+| **Scope** | Ideas, Epics, Features, value, acceptance outcomes, roadmap, and human approval for solution work | An exact approved Feature to Architecture |
+| **Architecture** | Requirements, ADRs, system design, interfaces, constraints, and implementation Tasks | Design intent to UI/UX and prepared technical work toward Kanban |
+| **UI/UX** | User journeys, information architecture, interaction and visual design, accessibility, Penpot sources, prototypes, and design handoff | Reviewed design evidence and implementation-ready UX decisions to Kanban and Delivery |
+| **Kanban** | Board and Focus visibility, dependencies, sequencing, blockers, and explicit human Task admission | An exact admitted Task to Delivery |
+| **Delivery** | Implementation planning, branches, pull requests, reviews, exact-head CI, and engineering blockers | A validated immutable candidate to Releases |
+| **Releases** | Readiness, version decisions, deployment, rollback, acceptance evidence, and post-release outcomes | Verified status and outcomes back to General and durable records |
-Each channel loads its mapped project-adopted channel skill. Relevant engineering skills are loaded alongside it for branching, monorepo structure, scripts, CI/CD, GitOps, documentation, and templates. A green build or agent statement never substitutes for a required human approval or deployed readback.
+## One agent, multiple sessions, specialised skills
+
+The same Hermes agent operates across the pilot, but each Discord channel has its own focused session and mapped channel skill. This gives the pilot:
+
+1. **Shared identity and governance** — one agent follows the same Board-approved operating model.
+2. **Focused context** — Scope discussion does not become Delivery execution, and one project's decisions do not silently become another project's decisions.
+3. **Specialised behavior** — the mapped `corp-v1-channel---` skill defines the channel's responsibilities, approvals, evidence, and handoffs.
+4. **Engineering depth on demand** — relevant project engineering skills are loaded alongside the channel skill for documentation, branching, monorepo work, CI/CD, GitOps, scripts, and templates.
+5. **Durable evidence** — decisions and current state are written to Discord, Gitea, project documentation, and the Board portal rather than existing only in an agent session.
+
+## Handoff rule
+
+A handoff is not “continue the conversation elsewhere.” It carries an exact governed artifact: an approved Feature, requirement set, ADR, Penpot design, admitted Task, reviewed commit, immutable release candidate, or deployed readback.
+
+Green CI, a merge, an agent statement, or silence never substitutes for required human approval. Corp v1 currently uses no project cronjobs or scheduler jobs; coordination is human- or event-driven.
diff --git a/docs/architecture-high-level/overview-repositories.mdx b/docs/architecture-high-level/overview-repositories.mdx
index bc48dab..89d1f29 100644
--- a/docs/architecture-high-level/overview-repositories.mdx
+++ b/docs/architecture-high-level/overview-repositories.mdx
@@ -9,7 +9,7 @@ import repositoriesDiagram from '!!raw-loader!./diagrams/repositories.drawio';
# Overview Repositories
-Each project has two Gitea organization boundaries and fifteen required repositories: two project repositories plus thirteen adopted skill repositories.
+Each project has two Gitea organization boundaries and sixteen required repositories: two project repositories plus fourteen adopted skill repositories.
@@ -26,7 +26,7 @@ A project team grants access to both repositories. Project-specific environment
The corresponding skills team grants access to:
-- six adopted channel-skill repositories;
+- seven adopted channel-skill repositories—General, Scope, Architecture, UI/UX, Kanban, Delivery, and Releases;
- seven adopted engineering-skill repositories;
- their complete supporting assets, scripts, templates, references, and preserved adoption history.
@@ -34,4 +34,4 @@ The global `drawio-main` and `corp-v1--glossary` remain shared references unless
## Delivery evidence
-Documentation commits are validated and published to LEGO Cloud Pages. Deployable application commits produce immutable Harbor images and update GitOps/Argo CD desired state. Completion requires exact-commit CI plus deployed page or runtime readback; a local build or accepted push alone is not delivery evidence.
+Documentation commits are validated by Gitea Actions and published to LEGO Cloud Pages. Deployable application commits produce immutable Harbor images and update GitOps/Argo CD desired state. Completion requires exact-commit CI plus deployed page or runtime readback; a local build or accepted push alone is not delivery evidence.
diff --git a/docs/architecture-high-level/overview.mdx b/docs/architecture-high-level/overview.mdx
index d650f42..e4f8fbc 100644
--- a/docs/architecture-high-level/overview.mdx
+++ b/docs/architecture-high-level/overview.mdx
@@ -1,7 +1,7 @@
---
id: overview
title: "Overview"
-description: "Follow a Corp v1 project from Board approval through governed scope, delivery, deployment, and verified evidence."
+description: "Follow the single-agent, multi-session Corp v1 pilot from Board governance through design, delivery, release, and verified evidence."
---
import Drawio from '@theme/Drawio';
@@ -9,22 +9,28 @@ import overviewDiagram from '!!raw-loader!./diagrams/overview.drawio';
# Overview
-Every approved Corp v1 project repeats the same high-level operating flow while keeping its own decisions and delivery boundary.
+Corp v1 is an SDLC operating-model pilot: **one AI agent works across multiple focused Discord sessions, each governed by specialised project skills and explicit human decision rights**. Every approved project repeats the same flow while keeping its decisions, repositories, and delivery evidence isolated.
-
+
-## How projects operate
+## How the setup fits together
-1. **Board approval** establishes the project purpose, code, lead, members, visibility, initial deliverable, and required resources.
-2. **Scope** turns evidence-backed intent into Ideas, Epics, and Features. A human project member approves a Feature for solution work.
-3. **Architecture** defines requirements, decisions, diagrams, and implementation Tasks without treating documentation scaffolding as an approved target design.
-4. **Kanban** exposes unfinished work. A human project member explicitly admits an exact Task to Focus before Delivery may execute it.
-5. **Delivery** implements through reviewable branches and pull requests; Gitea Actions validates the exact candidate.
-6. **Releases** assess immutable artifacts, risk, rollback, deployment, and acceptance evidence.
-7. **Verification** reads the deployed page or runtime back and updates durable project and governance records.
+1. **`corp-v1-board` governs the portfolio.** Listed Board members approve project kickoffs, closures, membership changes, and changes to the global operating model.
+2. **General establishes the project workspace.** It handles onboarding, shared coordination, questions, and broadcasts verified outcomes.
+3. **Scope decides what creates value.** Ideas become Epics and Features; a human project member approves an exact Feature for solution work.
+4. **Architecture decides how the system should work.** Requirements, ADRs, interfaces, constraints, and implementation Tasks become durable project evidence.
+5. **UI/UX makes the frontend experience implementable.** User journeys, information architecture, accessibility, Penpot designs, prototypes, and handoff evidence bridge Architecture and execution.
+6. **Kanban controls admission and flow.** A human project member admits an exact Task to Focus before Delivery may execute it.
+7. **Delivery produces a reviewed candidate.** Work proceeds through branches, pull requests, exact-head validation, and reviewable implementation evidence.
+8. **Releases control deployment and outcomes.** Immutable artifacts, risk, rollback, deployment, acceptance, and post-release evidence are assessed explicitly.
+9. **Verification closes the evidence loop.** Hermes reads the deployed page or runtime back, updates project documentation and the Board portal, and reports remaining gates honestly.
-## Project-owned operating guidance
+## Why sessions and skills are separated
-Each project adopts six channel skills and seven engineering skills into its dedicated skills/code-agent organization. Those copies preserve project naming, environment namespaces, repository links, authority decisions, and operating lessons. Central changes are compared and deliberately synchronized; they never silently overwrite project decisions.
+Each channel is a concern boundary with its own session. The same agent can coordinate the whole project, while the loaded project-adopted channel skill prevents responsibilities and approval rules from blurring together. The project uses seven channel skills to define the workspaces and seven engineering skills to provide reusable execution practices.
-Corp v1 projects and channels do **not** use cronjobs or scheduler jobs under the current approved model. Coordination is human- or event-driven.
+Project copies preserve project-specific authority, terminology, repository links, environment namespaces, and operating lessons. Central skill changes are compared and deliberately adopted; they never silently overwrite project decisions.
+
+## Automation boundary
+
+Corp v1 projects and channels do **not** use cronjobs or scheduler jobs under the current approved model. Work advances through explicit human decisions, Discord events, reviewed repository changes, exact-commit CI, and deployed readback.
diff --git a/scripts/verify-portal.mjs b/scripts/verify-portal.mjs
index 290554c..19cd08d 100644
--- a/scripts/verify-portal.mjs
+++ b/scripts/verify-portal.mjs
@@ -99,20 +99,24 @@ const architecturePages = {
for (const [name, page] of Object.entries(architecturePages)) {
assert.match(page, /!!raw-loader!\.\/diagrams\/.+\.drawio/, `${name} page must render an editable Draw.io source`);
}
-for (const term of ['six channel skills', 'seven engineering skills', 'Gitea Actions', 'scheduler jobs']) {
+for (const term of ['seven channel skills', 'seven engineering skills', 'Gitea Actions', 'scheduler jobs', 'corp-v1-board', 'UI/UX', 'one AI agent']) {
assert.ok(Object.values(architecturePages).some((page) => page.includes(term)), `architecture explanation is missing: ${term}`);
}
+for (const [name, page] of Object.entries(architecturePages)) {
+ assert.doesNotMatch(page, /exactly six|six project channels|six channel skills|thirteen adopted skill/i, `${name} retains the superseded six-channel model`);
+}
for (const [name, markers] of Object.entries({
'context.drawio': ['CORP V1 — OPERATING CONTEXT', 'Corp v1 Board', 'Gitea organizations and repositories', 'Delivery platform'],
- 'overview.drawio': ['CORP V1 — PROJECT OPERATING FLOW', 'BOARD APPROVAL', 'KANBAN / FOCUS', 'VERIFY & RECORD'],
- 'channels.drawio': ['CORP V1 — PROJECT CHANNELS', 'GENERAL', 'ARCHITECTURE', 'RELEASES'],
- 'repositories.drawio': ['CORP V1 — ORGANIZATIONS, REPOSITORIES & DELIVERY', 'PROJECT ORGANIZATION', 'SKILLS ORGANIZATION', 'GITEA ACTIONS'],
+ 'overview.drawio': ['CORP V1 — PROJECT OPERATING FLOW', 'CORP-V1-BOARD', 'BOARD APPROVAL', 'UI/UX', 'KANBAN / FOCUS', 'VERIFY & RECORD'],
+ 'channels.drawio': ['CORP V1 — BOARD & PROJECT CHANNELS', 'CORP-V1-BOARD', 'GENERAL', 'ARCHITECTURE', 'UI/UX', 'RELEASES', 'MULTIPLE FOCUSED SESSIONS'],
+ 'repositories.drawio': ['CORP V1 — ORGANIZATIONS, REPOSITORIES & DELIVERY', 'PROJECT ORGANIZATION', 'SKILLS ORGANIZATION', '7 adopted channel-skill repos', 'GITEA ACTIONS'],
})) {
const diagram = read(`docs/architecture-high-level/diagrams/${name}`);
const xmlResult = XMLValidator.validate(diagram);
assert.equal(xmlResult, true, `${name} is malformed XML: ${JSON.stringify(xmlResult)}`);
assert.match(diagram, /]/, `${name} is not a Draw.io source file`);
for (const marker of markers) assert.ok(diagram.includes(marker), `${name} is missing: ${marker}`);
+ assert.doesNotMatch(diagram, /Six purpose-specific|6 channel skills|6 adopted channel-skill repos/i, `${name} retains the superseded six-channel model`);
}
if (existsSync(join(root, 'build'))) {