From 17e09ee8ec59e85d17b3e3ede81bbffb421cb5d2 Mon Sep 17 00:00:00 2001 From: Jarvis Jr Hermes Date: Tue, 25 Aug 2026 19:45:33 +0000 Subject: [PATCH] docs: explain Corp v1 SDLC and rebuild diagrams --- docs/architecture-high-level/context.mdx | 10 +- .../diagrams/channels.drawio | 91 +++++++------- .../diagrams/context.drawio | 14 +-- .../diagrams/overview.drawio | 117 +++++------------- .../diagrams/repositories.drawio | 14 +-- .../overview-channels.mdx | 53 ++++++-- .../overview-repositories.mdx | 6 +- docs/architecture-high-level/overview.mdx | 34 ++--- scripts/verify-portal.mjs | 12 +- 9 files changed, 165 insertions(+), 186 deletions(-) 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'))) {